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.

Your workflow runs any AI you add to it. Koutei runs no AI model, and passes nothing you send it on to an AI provider: it checks the fields, does the arithmetic and makes the PDF.

The values you send in fields and the PDF are never stored, and no document is sent to anyone. A record of each document (for example the template, size, time and your optional reference) is kept for 90 days. The Privacy Policy lists what that record holds, and the one-way hashes we keep for a short time so that a repeated request isn't charged twice and the limits hold.

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.

If you keep your hours in a Google Sheet, this workflow turns them into invoices every week, with no retyping. Download koutei-weekly-timesheet.json (the workflow "Koutei: weekly invoices from a timesheet").

• Every Monday at 07:00, in the workflow's time zone, it reads last week's rows (Monday to Sunday) and makes one invoice per client, with one line per row: the hours are the quantity and the rate is the unit price. Koutei works out each line and the total; the workflow never multiplies. Run now does the same at any time. Each invoice is dated the day it is made, and its notes give the week of the work.
• Check the invoice sends each invoice to POST /api/v1/documents/validate first, which costs nothing. Make the invoice then makes it with POST /api/v1/documents, and Email the invoice sends the PDF with Gmail.
• In preview mode, as the file comes, each PDF is watermarked, uses no credit and is emailed only to you. In final mode it goes to the client, uses 1 credit, and its number is written into invoice_number on every row it covered, so the next run leaves those rows alone.
• In final mode the Idempotency-Key is made from the client and the week, so running the workflow again the same day returns the same invoice and uses no credit. On another day within 24 hours the invoice date has changed, so Koutei refuses it rather than make a second invoice. The key holds no name and no email address.
• If a run fails at Write back to the sheet, fill in invoice_number by hand from your Gmail Sent folder before you run that week again.
• A row with a problem, such as a missing rate or email address, gets a note, and that client is skipped. The other clients still get their invoices. Fix the row and run the workflow again.

To set it up, use the same Header Auth credential as below in Check the invoice and Make the invoice. Select your Google credential and your sheet in Read the timesheet and Write back to the sheet, and your Gmail credential in Email the invoice. Then set the workflow's own time zone in its settings, so the week and the schedule match yours.

Each invoice number is made from the week and the client, such as INV-2026-W43-EXAMPLE-CLIENT-LTD, so a re-run always gives the same number. You are responsible for your invoice numbers, and a correction needs a new number: to re-issue an invoice that was sent, clear its invoice_number cells, set invoice_suffix (such as -2), run that week again, then clear invoice_suffix.

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.