Code Gl Item

Code one ingested invoice manually — JE + open item + VAT ± payment (accountant).

The human booking path for an uncoded item (doc/pipeline.md §"Invoice coding (phase 2)"): the server composes the control leg + VAT lines from NET amounts and the company's VAT-code rates, posts as the user's entry (origin default, not ai), creates the gl_open_item and records the manual:code: interlock decision so the AI coder never re-codes the item; a held AI proposal is superseded. The optional paid_on/bank_gl_account_id pair records the payment in the same transaction.

⚠️ Send posting_date when the document's own date is known. This paragraph is the description the code_gl_item MCP tool presents to an agent — FastMCP.from_openapi reads the ROUTE description and drops GlItemCodingIn's own — so it is the one place the warning reaches the caller most likely to omit an optional field. Omitted, the server derives item.invoice_date or item.date.date() — and for an item with no extracted invoice date that is the upload timestamp, i.e. the wrong period and, for a late upload, the wrong fiscal year (ZET-310). A dateless document is deliberately still not refused — manual coding is the human override path and ZCT-259's recovery depends on it staying permissive — and its gl_autopost_decision.reason records the substitution.

⚠️ What IS refused, since ZCT-510: omitting posting_date when the date derived from the document falls in no fiscal year the company has books for and is not the ordinary next-year rollover (a prior year, or a gap between two existing years). 409, naming the remedy. Send posting_date explicitly, or open the year with POST /companies/{company_id}/gl/fiscal-years first. fiscal_year_opened on the response names the year when a coding did open one.

Supplier credit note: positive amounts + credit_note: true (ZCT-812).

A deduction on a supplier bill (the Bezugsprovision on a Quellensteuer bill): a line with a NEGATIVE net_amount_cents and no VAT code, booked on the payables side (ZCT-918). Refused (422) with a VAT code, on a control/bank/VAT account, on a sale, on a credit note, or when the lines add up to zero or less.

⚠️ The bank side may already have booked this spend (ZENO-234). When a bank movement of the same counterparty was booked without a receipt and looks like this document's payment (the same amount, or the only such movement within ±35 days), the coding is refused with 409 conflict.documentPaidByBankCoding naming the movement: if the document is its receipt, link it to that movement (POST /bank-entries/{entry_id}/items) instead of coding it; if it is a genuinely different spend, resend with confirm_different_spend: true. A document already linked as a bank booking's receipt is refused (409 conflict.documentIsBankCodingReceipt) whatever the flag.

⚠️ "Already paid" (paid_on) is refused on a bank account fed by imported statements (ZENO-232) — 409 conflict.handPaymentOnFedBankAccount: the statement line books that payment. Code the document without paid_on and settle it from the statement line.

The number is already booked (409 conflict.documentNoAlreadyCoded, ZET-411). If the other booking is a DIFFERENT document that prints the same number, resend with separate_document: true: it books without the number, keeping it as a reference. Refused (409 conflict.separateDocumentIsDuplicate) when that booking has the same counterparty, amount and date — then it is the same document.

A credit-card statement is not a bill (409 conflict.cardStatementOverridable, ZCT-876). Its lines are imported in Payroll → Expenses → Cards. A person who has checked the document is NOT a card statement resends from the Zeno app with confirm_not_card_statement: true; that flag is refused (403) on an API key, so an agent cannot set it.

Errors: 404 missing/cross-tenant item; 409 already booked / payment already on a bank statement / "already paid" on a statement-fed bank account (ZENO-232) / the bank side booked this spend (ZENO-234) / closed period / no bookable fiscal year for the derived date (ZCT-510) / the document number is already live / the linker recognised this as an out-of-order duplicate of a booked payable (the last two ZET-173); 422 bad account or VAT code, missing direction, or unbalanced input.