create_sales_document
Generate sales documents like invoices or credit notes with line items. Choose finalize=true to issue immediately (fiscally binding) or finalize=false to save as a draft.
Instructions
Create a sales document with line items.
Two code paths depending on finalize:
finalize=True— uses the v1 endpoint (POST /api/v1/commercial_sales_documents), which takes a flat body, embeds lines inline, and issues the document immediately (fiscally binding, irreversible). Customer identity fields are denormalized by fetching/api/customers/{customer_id}first.finalize=False(default) — uses the legacy JSON:API endpoint multi-step: POST the header to/api/commercial_sales_documents, then POST each line to/api/commercial_sales_document_lineswithdocument_idlinking. The document stays as a draft (status 0) — editable, not yet fiscally valid. To issue later, callfinalize_sales_document(id).
v1 ignores finalize=0 (the documented field), so the legacy path is
the only way to actually leave a doc in draft state via this API.
Customer identity (name, tax number, address) is denormalized onto the
header by TOCOnline server-side, on both paths — but only from the
customer's main address. If the header comes back with an empty
customer_address_detail, the customer has no main_address_id set;
fix the customer's address rather than passing address fields here.
Date: on a certified series the date cannot precede the series' last issued document. The API enforces this; we don't pre-check it (a type can have multiple series, so a client-side guess would risk blocking valid emissions).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | ISO date, e.g. 2025-01-15. On a certified series the date cannot precede the last issued document's date — TOCOnline rejects back-dating before the most recent document in the series. | |
| lines | Yes | At least one line item. | |
| notes | No | Customer-visible notes on the document. | |
| due_date | No | Payment due date (YYYY-MM-DD). | |
| finalize | No | If true, the document is issued immediately (fiscally binding). If false, it stays as a draft. | |
| customer_id | Yes | TOCOnline customer id. | |
| document_type | Yes | Document type code. Common: FT (invoice), FR (invoice-receipt), NC (credit note / rectificative), ND (debit note / rectificative), FT-FA (simplified invoice). | |
| payment_mechanism | No | TOCOnline payment mechanism code (e.g. MO, NUM, TRA, CC). | |
| external_reference | No | External reference id (e.g. PO number). | |
| parent_document_id | No | For rectificative documents (NC / ND): id of the original sales document this rectifies. Included via the `parent_documents_ids` attribute. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||