n8n: a quote, an invoice and a receipt

• Job details holds one job: who is selling, who is buying, the work, the amounts and the three document numbers. The nodes "Make the quote", "Make the invoice" and "Make the receipt" each send one request to the API.
• The invoice prints the number of the quote: its related_document is the quote_number column.
• The receipt prints the number of the invoice: its related_document is the invoice_number column.
• All 3 documents get the job_id column as their reference, your own label that is never printed. GET /api/v1/documents?reference=… finds all three.
• So job_id is stored with each document's record for 90 days, sent back in a response header, and can appear in our hosting provider's request logs. Don't put personal information in it, such as a client's name or an email address: use a job number. It may hold 1 to 128 visible ASCII characters (! to ~): no spaces and no accented letters, because it is also the start of each Idempotency-Key (at most 255 visible ASCII characters).
• After the last node, one item carries the 3 PDFs as files in the fields "quote", "invoice" and "receipt". Add your own nodes after it to save or send them. Koutei itself never sends a document to anyone.

Download koutei-quote-invoice-receipt.json (the workflow "Koutei: quote, invoice and receipt for one job"). It holds no key and no real person's details: you add your key as an n8n credential.

If you only need invoices, use the smaller workflow: one row of invoice details, one request, one PDF. Download koutei-one-invoice.json (the workflow "Koutei: one invoice from one row"). Set it up as below, with the credential in the one node Make the invoice.

• Invoice details holds the invoice. Make the invoice sends it and gets the PDF back as the file invoice, within 60 seconds.
• Totals then holds the figures the invoice prints, read from the answer's Koutei-Totals- headers, with the PDF still attached: write them back to your sheet, or use the balance due to make a payment link. You don't have to work the numbers out yourself.
• Its Idempotency-Key is the job ID, invoice and revision: JOB-0042-invoice-r1 for the example row, JOB-0042-invoice-r1-preview in preview mode. It is the same key the chain gives that job's invoice. So job_id may hold 1 to 128 visible ASCII characters (! to ~): no spaces and no accented letters. It is also each invoice's reference, so use a job number, never personal information. To correct an invoice after it was made, edit the row and add 1 to revision: the corrected invoice is a new document, and in final mode it uses 1 credit.

1. In Koutei, open Settings and create an API key. A Preview only key can make previews only, which is enough to try the workflow; final documents need a Full access key.
2. In n8n, create a Header Auth credential. Name: Authorization. Value: Bearer kt_live_…, with your whole key after the space.
3. Import the file into a new workflow (n8n's import from file, or paste its contents onto the canvas).
4. Open each of the 3 Koutei nodes and select that credential.
5. Edit Job details with your own job, or replace it with a sheet (below). Leave mode as preview for a first run: the PDFs are watermarked and no credit is used.
6. Run the workflow. When the previews look right, set mode to final and run it again.

These are the fields of Job details, with the example values in the file. An optional column can be left blank: the document then leaves that line out.

• items holds one line item per line: a description, the quantity and the unit price, separated by |. The API reference has the rules for each value.
• Dates are YYYY-MM-DD. Amounts use . for the decimal point and may use , between thousands, with no currency symbol.
• quote_revision, invoice_revision and receipt_revision start at 1: each is the revision of its own document (see corrections). mode is preview or final.

To make the documents from a spreadsheet, put a Google Sheets node (or any node that reads rows) in place of Job details and name it Job details, so the Koutei nodes still find it. Use the column names above as the sheet's first row, one job per row. Format the date columns as plain text, so the sheet sends YYYY-MM-DD and not a number.

Each Koutei node sends POST https://kouteisystems.com/api/v1/documents with the Header Auth credential and these headers:

• The Idempotency-Key of a final document is the job ID, the document and that document's own revision: for the example row JOB-0017-quote-r1, JOB-0017-invoice-r1 and JOB-0017-receipt-r1. A preview adds -preview, so trying a row first never blocks its final documents.
• The body is JSON: the template, the mode, the reference and the fields, built from the row.
• The answer is read as a file, with the response headers included, so the item also holds the receipt headers such as koutei-document-id and koutei-credit-used. Each request may take up to 60 seconds.

• preview: watermarked PDFs, no credit. final: the real documents, 1 credit each, so 3 credits for one job.
• Running the same row again within 24 hours sends the same keys and the same details: you get the same documents back and no credit is used. After 24 hours the keys are forgotten, and running the row again makes new documents, and a final uses credits again.
• Re-runs have limits too. In final mode a key may replay 60 final documents a minute, and an account 120 a minute and 600 an hour on the Free plan; over that the API answers 429 rate_limited with the detail replay_limit. In preview mode every preview counts: a key may make 30 previews an hour and 200 a day, and an account 60 an hour and 300 a day, across every key and the web app; previews repeated with the same key count against a second allowance of the same size. A run makes 3 previews, so a key's hourly previews cover 10 runs, and the same again for repeated runs.
• To correct a document after it was made, edit the row and raise that document's revision by 1: quote_revision, invoice_revision or receipt_revision. Only that document gets a new key, so only it is made again, as a new document; in final mode that uses 1 credit, and the other documents come back unchanged at no charge. For example, raising invoice_revision from 1 to 2 changes the invoice's key from JOB-0017-invoice-r1 to JOB-0017-invoice-r2, while the quote keeps JOB-0017-quote-r1 and the receipt keeps JOB-0017-receipt-r1.
• A column that several documents print needs each of their revisions raised: the last column of the table above lists them, and so does the note under Job details in the workflow. A new client address, for example, changes all 3 documents.
• If you edit a row within 24 hours and leave a revision it needs as it was, the API refuses that document with 422 idempotency_key_reused instead of making a second, different document under the same key. That stops the workflow at that node: raise that document's revision and run it again.

A request the API refuses stops the workflow at that node, and n8n shows the API's message. The message has a code, and Errors explains each one. Most often:

• 422 validation_failed: a column is missing or has a value the template does not accept. The message lists every problem at once.
• 401 unauthorized: the credential's value is not Bearer, a space and a working key.
• 403 forbidden_scope: mode is final and the key is a Preview only key.
• 402 insufficient_credits: no credits are left for a final document this month.
• 429 rate_limited: a limit was reached. The answer's Retry-After says how long to wait: seconds for a limit per minute, up to an hour for an hourly one, or until 00:00 UTC for a daily one.

You supply every fact, including the three document numbers. Koutei never allocates or checks a document number.