Your end-user, or their accountant, makes the accounting choices: which journal, VAT code and ledger account each invoice uses. You build the mapping screen where they make these choices, and the logic that sends the invoices.
1. Fetch the mapping data
Fetch these lists when the end-user connects their accounting software. Show them in your mapping screen. Store the selections of the end-user for each consumer.Journals
Every invoice belongs to a journal. Call Get journals.- Store the
id. You send it asjournal_idon the invoice. - Show the
nameand thecode. - Filter on
journal_type. Your end-user selects one journal for each invoice type:customer_invoice,customer_refund,supplier_invoiceandsupplier_refund. - Hide the journals where
blockedistrue. Entries cannot be created in a blocked journal.
VAT codes
Accounting software does not record a VAT rate directly. It uses a VAT code. Call Get VAT codes.- Store the
id. You send it astax_codeon each invoice line. - Show the
labeland therate. - Filter on
type. Show the codes of typesaleorbothfor customer invoices, and the codes of typepurchaseorbothfor supplier invoices. - Hide the codes where
activeisfalse.
Ledger accounts
Each invoice line books on a ledger account: a revenue account for a sale, an expense account for a purchase. Call Get chart of accounts with thetype filter:
type=incomefor the revenue accounts.type=expensefor the expense accounts.
number. You send it as account_number on each invoice line. Hide the accounts where active is false.
Your end-user selects at least one default revenue account and one default expense account. They can also map each of your product or expense categories to its own account.
Rounding correction
Your end-user also selects the data that Chift uses to correct a rounding difference of 0.01 (see Amounts):- a credit account and a debit account, from the chart of accounts;
- a 0% VAT code of type
saleand a 0% VAT code of typepurchase.
2. Link your customers and suppliers
Each invoice references its client or supplier in the accounting software withpartner_id. Chift uses this partner to book the receivable or payable line. So get the partner_id before you book an invoice:
- Match your customer or supplier with an existing partner of the accounting software.
- When no partner matches, create it.
Some accounting software cannot create partners through the API. For these connectors, send
partner_info on the invoice, with the account_number and the account_name of the partner. The accounting software then creates the partner. See for example the Tiime connector.3. Create the invoice
Create one invoice for each invoice of your software. Call Create sale/purchase entry (Multiple plans):POST /consumers/{consumer_id}/accounting/invoices/multi-analytic-plans?regroup_lines=false
Invoice fields
invoice_type:customer_invoice,customer_refund,supplier_invoiceorsupplier_refund.journal_id: the journal mapped for this invoice type. If you leave it empty, Chift selects the journal only when one journal exists. Otherwise, the request fails.partner_id: the client or the supplier (see step 2).invoice_dateanddue_date: the accounting date and the due date (YYYY-MM-DD).currency: the ISO 4217 code, for exampleEUR. For another currency than the one of the folder, see Multi-currency.untaxed_amount,tax_amountandtotal: the totals of the invoice.pdfandpdf_name: the PDF of the invoice in base64, and its file name. The file name accepts letters, digits,-,_and spaces, and can end with.pdf. See Attachments.
Invoice number and reference
invoice_number: the number of the entry in the accounting software. It does not need to match the number printed on the invoice. Each accounting software has its own format and length rules. See Number restrictions.reference: a free-text reference. For a supplier invoice, put the number that the supplier printed on the invoice here, not ininvoice_number.
invoice_number and use it as your idempotency key, to avoid booking the same invoice twice.
Lines
Each line has:account_number: the revenue or expense account mapped for this line. It is always a general account, never the account of the partner. See Accounts in invoices.tax_code: the VAT code mapped for the rate of this line.tax_rate: the VAT rate, for example21.0. Send it even when the VAT code already defines it.unit_price,quantity,untaxed_amount,tax_amountandtotal: the amounts of the line (see Amounts).description: the text of the line.
Amounts
Your invoice is the original document: you know the untaxed amount of each line. Compute the amounts of each line as follows:- Set the header
totalto the total printed on your invoice. - Set
regroup_lines=false. Withtrue, Chift checks that thetax_amountof each line equalsuntaxed_amount × tax_rate / 100at 4 decimals. Atax_amountrounded to 2 decimals then fails. - Always send
invoice_correction, with both accounts and both VAT codes from Rounding correction. Your invoice can compute its VAT on the whole invoice instead of each line. Then its total can differ by 0.01 from the sum of the line totals. In that case, Chift adds a 0% VAT correction line that keeps the entry on the total of your invoice.
Example: customer invoice
POST /consumers/{consumer_id}/accounting/invoices/multi-analytic-plans?regroup_lines=false
regroup_lines=false.
Example: supplier invoice
POST /consumers/{consumer_id}/accounting/invoices/multi-analytic-plans?regroup_lines=false
< and > come from the mapping data of step 1 and from step 2. Account numbers and VAT codes differ per country and per chart of accounts.
Refunds
For a credit note, setinvoice_type to customer_refund or supplier_refund, and send the journal mapped for this type. The other fields follow the same rules.
Specific cases
- Analytical accounting: split the lines across cost centers, projects or other dimensions with
analytic_distribution. - Multi-currency: invoices in another currency than the one of the folder.
- Reversed VAT: reverse-charge invoices.
- Spanish withholding taxes: withholding taxes on Spanish invoices.
- Multi-folder: when one connection gives access to several folders.
4. Follow the invoice status
To follow the invoices you created (for example, to know which ones are paid), call Get invoices by type (Multiple analytic plans). Each call returns one invoice type.updated_after: returns only the invoices created or updated after this UTC date and time. Pass the date of your last successful call. See Incremental synchronization.payment_status:all(default),paidorunpaid.
status field of each invoice gives its state: draft, posted, paid or cancelled.
Not every connector supports updated_after. Without it, filter on date_from and date_to, and compare the result with the invoices you stored. A changed status shows an update. Check the coverage matrix.
To read one invoice, call Get one invoice (Multiple analytic plans) with its id.