Sintropix Invoices API: Create, Book, and Link DTEs

Invoices are Sintropix’s model for both AR (issued to customers) and AP (received from suppliers). Each Invoice can be booked to a Ledger Entry and, in Chile, linked to a Documento Tributario Electrónico (DTE) issued through the SII. This page covers listing, creating, editing, booking, and DTE-linking Invoices, individually or in bulk.

Status

Invoices carry two derived, read-only status values on the listing rows:

Field	Values	Meaning
Booking status	`unbooked`, `booked`, `excluded`	An Invoice is `booked` when a Ledger Entry backs it (`bookingEntryId` is set), `excluded` when someone excluded it from the books, and `unbooked` otherwise. Only an `unbooked` Invoice is pending work.
`paymentStatus`	`paid`, `partial`, `unpaid`, `null`	Derived from the open amount of the Control Line (ADR 0018) in the Entity’s functional currency. `null` means the Invoice is not booked and settles nothing yet. A `tax_only` document owes nothing, so its `paymentStatus` is always `null`, even when booked.

The GET /invoices/pages listing accepts a combined filter statusFilter with values all, notPaid, paid, unbooked, booked, excluded, and notExcluded, and supports groupBy=bookingStatus and groupBy=paymentStatus. all lists every document, excluded ones included. notExcluded lists every document still headed for the books, and excluded lists only the excluded ones. notPaid is the filter a payment run works from. Amounts are integers in the minor units of their currency (1190000 is CLP 1,190,000; 125050 is USD 1,250.50). Dates are YYYY-MM-DD strings, tax periods are YYYY-MM, and timestamps are ISO 8601.

Open in the app. This resource has a page in the Sintropix web app at https://app.sintropix.com/{entityId}/invoices?open={invoiceId}, where each id in braces is the same UUID as in the API route or response. That page is for direction receivable. For direction payable use /{entityId}/bills?open={invoiceId}, and for an Expense Rendition use /{entityId}/expense-renditions?open={invoiceId}. When you mention a record to a user, include that link. See Link to the App for the full URL grammar.

Document kinds

Every Invoice has a documentKind. It says what the booking does with the Invoice’s total:

`documentKind`	What its booking does	What it owes
`invoice`	Books the claim or obligation on its Control Line: a debit on a receivable account, or a credit on a payable account.	Its total, until the Control Line is settled.
`credit_note`	Books the opposite side of an `invoice`, such as a Chilean DTE `61`. You apply it to an invoice with an ordinary Match.	It settles an invoice once matched.
`tax_only`	Books tax only, with no Control Line and no claim or obligation.	Nothing.

Tax-only documents

Use tax_only for a document that only declares tax. The usual case is a factura de compra (DTE 46) for a purchase abroad. The foreign vendor’s own Invoice already holds the payable, so the 46 books only the IVA: a debit to IVA Crédito Fiscal and a credit to IVA Retenido. A tax_only document:

Books a balanced Ledger Entry with no Control Line. Send controlLineId: null when you book it. Its controlLineId and controlAccountId stay null, so read bookingEntryId to tell whether it’s booked.
Can’t have a line on an account whose sub-type is payable, expense_rendition_payable, or receivable. A claim there would be an open item that no Invoice owns. The booking is refused with 409 and TAX_ONLY_LINE_ON_CONTROL_ACCOUNT_ERROR, and Reclassify refuses to move a line of its booking onto such an account the same way.
Owes nothing, booked or not. Its paymentStatus, paymentDate, and openAmount are null. It never appears in Payables to Plan, a Payment Order can’t name it, and it adds nothing to the amounts of customer status.
Can’t be deferred.
Is never a match candidate for a Bank Movement.
Is pending work while it’s unbooked, like any other document, and you can exclude it.

Both directions accept tax_only. A vendor’s Booking Template can also book its new 46s as tax_only automatically.

Switch the kind

To make an unbooked Invoice tax_only, send { "documentKind": "tax_only" } to PATCH /invoices/:invoiceId. Send "invoice" to switch it back. In the app, open the document and pick Solo impuesto in Clase de documento. The listing then shows the document as, for example, 46 · solo impuesto, with no payment status. The switch is refused when:

Case	Status	Code
The Invoice is booked. Unbook it, switch the kind, and book it again.	`409`	`INVOICE_BOOKED_FIELDS_LOCKED_ERROR`
The Invoice is a credit note. A credit note never switches, and nothing switches to `credit_note`.	`409`	`INVOICE_DOCUMENT_KIND_FIXED_ERROR`
A Payment Order names the Invoice. Remove the orders first.	`409`	`INVOICE_PAYMENT_ORDERS_PIN_ERROR`
The Invoice lands a Sales Summary. The SII sets its kind.	`409`	`DTE_HELD_BY_SALES_SUMMARY_ERROR`

A Source Feed sync never changes the kind of an Invoice that already landed. Documents booked as invoice before tax_only existed keep their kind. To correct one, unbook it, switch it to tax_only, and book it again.

Ontop invoices

Ontop pays a company’s foreign contractors from a prepaid USD wallet, and bills the company for each payment. Erwin can load those invoices, book them, and match each payment to its invoices. Ask him in a Slack channel bound to the Entity’s Organization through an Agent Channel, for example “carga las facturas de Ontop”. To load the wallet’s movements first, ask “carga Ontop”. See Ontop wallet. Ontop issues three kinds of invoice:

Prefix	What it bills	Paid from
`ONTW`	One contractor in one payment	The wallet or a card
`ONTF`	The fee of a payment charged to a card	A card
`OMF`	The monthly membership	A card

Before the first load

Erwin reads the facts below from the Ontop page of his wiki. Ask him to note them there before the first load. If the page is missing or lacks a fact, he stops and asks. He never creates a Partner, a Source, a Bank Account, or an account.

The Partner of Ontop, the Source of its invoices, and the Bank Account of the wallet.
The control account of the invoices, and the account for the exchange difference.
The expense account of each category of contractor, and the category of each contractor.
The expense account for Ontop’s fees (ONTF and OMF).

The Entity also needs a login Credential for Ontop.

What a load does

Each load reads from 3 days before the newest issue date among the Partner of Ontop’s Invoices to today. On the first load, Erwin asks from which date to start.

Create. Erwin creates each invoice whose number no Invoice of the Partner of Ontop has yet, as an AP Invoice in USD:

Field	Value
`partnerId`, `sourceId`	The Partner and the Source of Ontop
`direction`, `documentKind`, `currency`	`payable`, `invoice`, `USD`
`documentNumber`	The Ontop number, for example `ONTW650770`
`total`	The invoice’s total in USD, in cents
`issueDate`	The date of the payment the invoice belongs to. For an `OMF`, its issue date
`memo`	`Ontop <number> · <contractor>`, or `Ontop <number> · Membresía` for an `OMF`
`metadata`	In this order, when Ontop shows them: `Tipo Ontop`, `Worker ID`, `Contratista`, `Fecha pago contratista`, and each part of the pay that isn’t zero (`Compensation`, `Bonus`, `Commissions`, `Reimbursements`, `Total compensation`, `Ontop fees`)

Book. Erwin books each new ONTW to the account of its contractor’s category, and each ONTF and OMF to the fee account. The entry credits the control account and debits the expense account, on the issue date, at the FX rate of USD for that date, or of the last earlier date with a rate. When the wiki has no category for a contractor, Erwin leaves the invoice unbooked with a question Follow-up that offers one option per category. He never guesses a category from the contractor’s role.
Match. Erwin matches each payment to its invoices once all of them are booked and open:
- A PAYMENT of the wallet pairs with the Ontop payment made from the wallet, with the same amount and a date at most 3 days away.
- A card charge whose description names Ontop pairs with the Ontop payment made by card, or with an OMF, with the same amount and a date at most 3 days away.
He matches the Movement to the first invoice, assigns the others from the Suspense Account, and books what’s left to the exchange difference account on the last invoice. If an invoice of the payment isn’t booked yet, the Movement waits unbooked with a waiting Follow-up that names the invoices. If two payments fit, he pairs none and leaves a question Follow-up.

The other wallet movements get their own treatment:

A top-up by wire is recorded as an internal transfer from the company’s bank account.
A top-up by card isn’t booked. Erwin leaves a question Follow-up.
A cashback gets a proposal Follow-up that books it to the account the wiki gives, or a question one when the wiki gives none.

Erwin never changes or books again an Invoice that was already in Sintropix, and never deletes an Invoice or a Movement. He reports the invoices he created and booked, the payments he matched, each Follow-up he left, the contractors the wiki doesn’t have yet, and the wallet’s balance in Ontop next to its Bank Account’s balance.

Erwin loads the invoices as Ontop issues them. The Chilean tax treatment of these payments, such as Impuesto Adicional or a factura de compra, is out of scope.

Expense renditions

A rendition (rendición) is an expense that a person paid with their own money for the company, which the company pays back. Sintropix records each rendition as a payable Invoice whose Partner is the person who paid, never the merchant. Erwin loads renditions from Rindegastos and books them. People can also submit a rendition in Sintropix itself, as an Expense Claim, or report it to Erwin, who submits the claim for them. When the Approver approves it, Sintropix creates its Invoice already booked. Mark the Source of the renditions, such as Rindegastos, as one that holds Expense Renditions. Its Invoices are then listed in Rendiciones instead of Compras, and GET /invoices/pages tells them apart with isExpenseRendition.

Load Rindegastos

Ask Erwin in a Slack channel bound to the Entity’s Organization through an Agent Channel, for example “carga Rindegastos”. Before the first load:

Add a login Credential for Rindegastos to the Entity in Integraciones. Erwin only reads Rindegastos. He never approves, rejects, closes, or edits anything there.
If a person’s name in Rindegastos differs from the name of their Partner, note the pair on the Rindegastos page of Erwin’s wiki.

The Rindegastos company must keep its accounts in the Entity’s functional currency. If it doesn’t, Erwin stops. Every Invoice of a load is in that currency. Each load reads every report, because a report can close months after it was sent. Erwin loads each approved expense of a closed report that isn’t in Sintropix yet. He skips rejected expenses and the expenses of reports still in process. For each new expense, Erwin creates one Invoice and attaches its receipt:

Field	Value
`partnerId`	The person who reported the expense, found by RUT, then by the wiki, then by name. Erwin creates the Partner when none fits, and asks when two fit.
`sourceId`	The Source named `Rindegastos`. Erwin creates it on the first load if the Entity has none.
`direction`, `documentKind`	`payable`, `invoice`
`documentNumber`	`RG-<expense id>`, the key that keeps a load from adding an expense twice
`currency`, `total`	The currency of the Rindegastos company, and the amount the person is paid back, as Rindegastos states it. An expense paid in another currency is loaded at that amount too.
`issueDate`	The date of the expense
`memo`	`Informe <folio> · <report title> · <merchant>`
`metadata`	In this order, when Rindegastos shows them: `Informe`, `Título informe`, `ID informe`, `ID gasto`, `Comercio`, `Categoría`, `Cuenta contable Rindegastos`, `Nota`, `Nota informe`, `Moneda original`, `Total original`, and `Tasa de cambio` for an expense paid in another currency, `Reembolsable: No`, `Fondo`, `Tipo de documento (OCR)`, `RUT comercio (OCR)`, `Folio (OCR)`, then each custom field of the expense, and each custom field of the report as `<name> (informe)`. A value longer than 500 characters is split into numbered labels, such as `Nota (1)` and `Nota (2)`.

For an expense paid in another currency, such as a USD hotel, the Invoice holds the amount the person is paid back. The currency they paid in, the amount in that currency, and the rate Rindegastos applied are only in Moneda original, Total original, and Tasa de cambio, as Rindegastos shows them. A load books nothing. An expense without a receipt, or whose receipt fails to download, is still loaded, and Erwin reports it. Cuenta contable Rindegastos is information only: it doesn’t follow your chart of accounts, so Erwin never books to it. Erwin also ignores the Pagado status of Rindegastos, because Sintropix learns what’s paid from the bank. Erwin never changes or deletes an Invoice that’s already in Sintropix. If Rindegastos changes an expense after it was loaded, so that it’s no longer approved, its report reopens, or its currency or amount changes, Erwin leaves a question Follow-up on the Invoice that states what changed. He reports the Invoices he created by report with their totals, the receipts that are missing or failed, the Partners he created, and each Follow-up he left.

Book renditions

Ask Erwin, for example “contabiliza las rendiciones”. He books each unbooked Invoice of the Rindegastos Source. He skips an Invoice that has a question Follow-up until a person answers it. The Entity needs a control account for renditions, such as Rendiciones por pagar. If it has none, Erwin stops and asks. Each entry is dated on the Invoice’s issue date, and its Control Line credits that account with the person as Partner. The debit depends on the expense’s document:

Document	Debit	Why
A boleta, or no document	The expense account	The expense is only in the rendition.
A factura issued to the company	The supplier’s payable account, with the supplier as Partner	The expense is already in the supplier’s factura, which comes from the SII. The person paid that factura for the company, so debiting an expense account would book it twice.

Expense account. Erwin uses the account the wiki gives for the expense’s category. Otherwise, he uses the one expense account that clearly fits. When none clearly fits, he leaves the Invoice unbooked with a question Follow-up that offers one option per account that fits.
Factura. Erwin reads the receipt to tell a factura from a boleta. A factura of a supplier with the same RUT and total, within 10 days of the expense, also confirms it. He finds the supplier by the RUT on the receipt, and creates its Partner when there is none. When the receipt shows no RUT, he leaves a question Follow-up that asks for the supplier. He never creates the supplier’s factura from a receipt.
Other currency. An Invoice of a Rindegastos load is already in the functional currency, so Erwin books its total as it is.
Not reimbursable, or a fund. When the expense is marked Reembolsable: No or spends a Fondo, Erwin leaves it unbooked with a question Follow-up that asks how to book it.

The debit to a supplier’s payable is an advance until the supplier’s factura is booked. On each run, Erwin matches each open advance to the Control Line of a booked factura of the same supplier, with the same total, within 10 days of the expense. When two facturas fit, he matches neither and reports both. When the amounts differ, the smaller one settles and the rest stays open. He reports each advance still without a factura 30 days after the expense. Erwin never changes or books again an Invoice that was already booked. He reports how many renditions he booked to an expense account and how many against a factura, the advances he matched and any rest that stayed open, the advances without a factura after 30 days, and each Follow-up he left.

GET `/invoices`

List every Invoice for the Entity, filtered by direction and document kind. Pass ids instead to read the full detail of up to 100 specific Invoices in one request. Query parameters

Field	Type	Required	Description
`ids`	uuid[]	No	1 to 100 Invoice ids. Repeat the parameter for each id (`?ids=A&ids=B`). Cannot be combined with any other query parameter. See Reading several Invoices by id.
`direction`	string	No	`receivable` (AR, issued to a customer) or `payable` (AP, received from a supplier). Omit to list both.
`documentKind`	string	No	`invoice`, `credit_note`, or `tax_only`. Omit to list every kind.

Response: an array of Invoice objects.

Field	Type	Description
`id`	uuid	Invoice id.
`entityId`	uuid	Owning Entity.
`partnerId`	uuid	Counterparty Partner.
`direction`	string	`receivable` or `payable`.
`documentKind`	string	`invoice`, `credit_note`, or `tax_only`. See Document kinds.
`documentNumber`	string	The number printed on the document.
`currency`	string	ISO 4217 code the document is denominated in.
`total`	integer	Gross total in minor units of `currency`.
`issueDate`	string	`YYYY-MM-DD`.
`dueDate`	string or null	`YYYY-MM-DD`.
`memo`	string or null	Free text.
`metadata`	array	Additional Information lines, each `{ "label": string, "value": string }`. Empty array when none.
`sourceId`	uuid or null	The Source the document came from. Null when it was entered directly.
`bookingEntryId`	uuid or null	The Ledger Entry that books the Invoice. Null means the Invoice is not booked.
`controlLineId`	uuid or null	The Ledger Entry Line that carries the receivable or payable. Null while the Invoice is not booked, and always null on a `tax_only` document.
`controlAccountId`	uuid or null	The Ledger Account the control line sits on. Null exactly when `controlLineId` is null.
`followUp`	object or null	The Follow-up on this Invoice, which marks its pending work. Null when there is none.
`excludedAt`	timestamp or null	When the Invoice was excluded from the books. Null when it isn’t excluded.
`exclusionReason`	string or null	Why it was excluded. Null exactly when `excludedAt` is null.
`createdAt`	timestamp	Creation time.
`updatedAt`	timestamp	Last update time.

curl "https://api.sintropix.com/api/entities/$ENTITY_ID/invoices?direction=receivable" \
  -H "x-api-key: $SINTROPIX_API_KEY"

Reading several Invoices by id

When you pass ids, the response is an array of Invoice detail objects instead of plain Invoice objects. Each element has the same shape as the response of GET /invoices/:invoiceId, including dte, attachmentCount, and bookingEntry. Use this when you already hold a set of Invoice ids and need their full detail without one request per Invoice.

Results follow the order of ids. A repeated id is returned once, at its first position.
Ids the Entity does not hold are left out of the array rather than refused. Compare the returned id values against the ids you sent.
Combining ids with direction, documentKind, or any other query parameter returns 400.
Sintropix reads every element from one consistent snapshot.

curl "https://api.sintropix.com/api/entities/$ENTITY_ID/invoices?ids=$INVOICE_ID_1&ids=$INVOICE_ID_2" \
  -H "x-api-key: $SINTROPIX_API_KEY"

GET `/invoices/pages`

Paginated Invoice listing with richer filters. Use this instead of GET /invoices for UI-style pagination. Query parameters

Field	Type	Required	Description
`direction`	string	No	`receivable` or `payable`. Omit to page over both.
`documentKind`	string	No	`invoice`, `credit_note`, or `tax_only`. Keep only documents of this kind. Omit to page over every kind.
`cursor`	uuid	No	The `nextCursor` returned by the previous page. Omit for the first page.
`limit`	integer	No	Rows per page, 1 to 100. Default `50`.
`statusFilter`	string	No	`all`, `notPaid`, `paid`, `unbooked`, `booked`, `excluded`, or `notExcluded`. Default `all`, which lists excluded documents too. `notExcluded` leaves them out.
`dteType`	string	No	Keep only documents whose DTE has this type code (`33`, `61`, …). Repeat the parameter to allow several codes. Use `none` for documents with no DTE.
`sourceId`	string	No	A Source id, or `none` for documents that came from no Source. Also scopes the totals in the response.
`isExpenseRendition`	boolean	No	`true` keeps only Expense Renditions, the payable documents of a Source that holds them, as Rendiciones lists. `false` leaves them out, as Compras does. Omit to return both. A `receivable` document is never an Expense Rendition. Also scopes the totals in the response.
`partnerId`	uuid	No	Keep only documents of this Partner.
`currency`	string	No	ISO 4217 code.
`paymentStatus`	string	No	`paid`, `partial`, or `unpaid`.
`standing`	string	No	`accepted`, `pending`, `claimed`, `annulment_requested`, `annulled`, or `observed` keeps documents whose DTE the SII holds in that Standing. `incompatible` keeps the booked documents with an Incompatible Standing.
`followUpKind`	string	No	`proposal`, `question`, `waiting`, or `none`. Filters by the kind of the document’s Follow-up. `none` keeps documents with no Follow-up.
`issueDateFrom`	string	No	`YYYY-MM-DD`, inclusive.
`issueDateTo`	string	No	`YYYY-MM-DD`, inclusive.
`dueDateFrom`	string	No	`YYYY-MM-DD`, inclusive. Documents without a due date are excluded.
`dueDateTo`	string	No	`YYYY-MM-DD`, inclusive. Documents without a due date are excluded.
`taxPeriodFrom`	string	No	`YYYY-MM`, inclusive. Read from the DTE; documents without one are excluded.
`taxPeriodTo`	string	No	`YYYY-MM`, inclusive.
`totalMin`	integer	No	Minimum `total`, in minor units.
`totalMax`	integer	No	Maximum `total`, in minor units.
`groupBy`	string	No	`none`, `partner`, `currency`, `dteType`, `bookingStatus`, `paymentStatus`, `issueMonth`, `dueMonth`, or `taxPeriod`. Default `none`.
`search`	string	No	Case-insensitive contains-match on `documentNumber`, `partnerName`, and `memo`. A search that reads as an amount also matches `total` and the Open Amount; see Search by amount. At most 100 characters; blank is ignored.
`erpThread`	string	No	`with` keeps only documents that have an ERP Thread, the conversation about the record in its Thread tab; `without` keeps only documents with none. Omit to return both. Group counts follow this filter; `totalCount`, `unbookedCount`, and `outstandingTotal` do not.
`sort`	string	No	`documentNumber`, `partnerName`, `currency`, `total`, `issueDate`, `dueDate`, `memo`, `dteTypeCode`, `bookingStatus`, `paymentStatus`, `openAmount`, or `taxPeriod`. Default `issueDate`. Sorting by `openAmount` places unbooked documents (null `openAmount`) before every value in both directions.
`sortDirection`	string	No	`asc` or `desc`. Default `desc`.

Response

Field	Type	Description
`invoices`	array	The Invoice rows on this page (see below).
`nextCursor`	uuid or null	Pass as `cursor` to fetch the next page. Null on the last page.
`totalCount`	integer	Documents in scope: the direction, Source, and `isExpenseRendition` requested, ignoring every other filter.
`unbookedCount`	integer	How many of those are not yet booked. Excluded documents don’t count.
`outstandingTotal`	integer	Sum of the unbooked documents’ totals, in the Entity’s functional currency. Excluded documents don’t count.

Each element of invoices is an Invoice row: every field of the Invoice object above, plus:

Field	Type	Description
`dte`	object or null	The DTE behind the document (fields listed under `PUT /invoices/:invoiceId/dte`). Null when none.
`partnerName`	string	Name of the Partner.
`partnerWebsite`	string or null	Website of the Partner, as a bare domain (`acme.cl`); null when it has none. The Partner’s logo is read from it.
`sourceName`	string or null	Name of the Source, null when the document came from none.
`isExpenseRendition`	boolean	Whether the document is an Expense Rendition: a `payable` Invoice whose Source holds Expense Renditions. Read from the Source, so marking or unmarking the Source changes it on every row at once.
`paymentStatus`	string or null	`paid`, `partial`, or `unpaid`. Null while the document is not booked, and always null on a `tax_only` document.
`paymentDate`	string or null	`YYYY-MM-DD`. For a `paid` document, the latest entry date of the entries that settled its Control Line, whatever settled it: a payment, a credit note, or a manual offset. Null while the document is unpaid, partially paid, or not booked, and always null on a `tax_only` document.
`openAmount`	integer or null	Remaining amount left to settle on the control line, in minor units of the Entity’s functional currency (regardless of the document’s own `currency`). Null while the document is not booked, and always null on a `tax_only` document; `0` once it is fully paid.
`bookingAccountLabel`	string or null	The counterpart account that received the largest amount when the document was booked. Null while unbooked.
`bookingExtraLineCount`	integer	How many further counterpart lines the booking has beyond the one named by `bookingAccountLabel`.
`attachmentCount`	integer	Number of attachments on the Invoice.
`hasErpThread`	boolean	Whether the Invoice has an ERP Thread, the conversation about it.
`group`	object or null	Null unless `groupBy` was requested. Contains `by` (the grouping), `value`, `key` (string), `invoiceCount` (integer, size of the whole group), and `startsGroup` (boolean, true on the first row of each group).

The type of group.value depends on group.by:

`by`	`value`
`partner`	string (Partner name). The group also carries `partnerId` (uuid) and `partnerWebsite` (string or null).
`currency`	string
`dteType`	string or null
`bookingStatus`	`unbooked`, `booked`, or `excluded`
`paymentStatus`	`paid`, `partial`, `unpaid`, or null
`issueMonth`	`YYYY-MM`
`dueMonth`	`YYYY-MM` or null
`taxPeriod`	`YYYY-MM` or null

pages is a fixed path segment, not an Invoice id: GET /invoices/pages always returns a page, never a single Invoice.

curl "https://api.sintropix.com/api/entities/$ENTITY_ID/invoices/pages?direction=payable&statusFilter=unbooked&limit=25" \
  -H "x-api-key: $SINTROPIX_API_KEY"

To list the Expense Renditions still to book, with their own totals, pass isExpenseRendition=true:

curl "https://api.sintropix.com/api/entities/$ENTITY_ID/invoices/pages?direction=payable&isExpenseRendition=true&statusFilter=unbooked" \
  -H "x-api-key: $SINTROPIX_API_KEY"

To find the payable documents that someone has written about in their ERP Thread, pass erpThread=with:

curl "https://api.sintropix.com/api/entities/$ENTITY_ID/invoices/pages?direction=payable&erpThread=with" \
  -H "x-api-key: $SINTROPIX_API_KEY"

POST `/invoices`

Create an Invoice. The same request can also book it (bookingEntryWithLines) and attach the DTE behind it (dte); all three are written together or not at all. Body

Field	Type	Required	Description
`id`	uuid	Yes	Caller-generated id. Retrying with the same id is answered `409`, so a retried request never creates a second Invoice.
`partnerId`	uuid	Yes	Counterparty Partner of the Entity.
`direction`	string	Yes	`receivable` or `payable`.
`documentKind`	string	Yes	`invoice`, `credit_note`, or `tax_only`. See Document kinds. Only an unbooked Invoice can switch between `invoice` and `tax_only` later.
`documentNumber`	string	Yes	Non-empty. The number printed on the document.
`currency`	string	Yes	ISO 4217 code.
`total`	integer	Yes	Gross total in minor units, zero or more.
`issueDate`	string	Yes	`YYYY-MM-DD`.
`dueDate`	string or null	No	`YYYY-MM-DD`.
`memo`	string or null	No	Free text.
`metadata`	array	No	Up to 50 lines of `{ "label": string, "value": string }`. Labels up to 120 characters, values up to 500, both non-blank. Omit for none.
`sourceId`	uuid or null	No	The Source the document came from. Omit or null when entered directly.
`bookingEntryWithLines`	object	No	Book the Invoice in the same request. Same shape and rules as the body of `POST /invoices/:invoiceId/book`.
`dte`	object	No	The Chilean tax document behind the Invoice. Same shape and rules as the body of `PUT /invoices/:invoiceId/dte`. Omit for a document with no DTE.

Response (201)

Field	Type	Description
`invoice`	object	The created Invoice row, as `GET /invoices/pages` would list it.
`bookingEntry`	object or null	The Ledger Entry detail (see `GET /invoices/:invoiceId`). Null unless `bookingEntryWithLines` was sent or the vendor’s Booking Template booked the Invoice.
`partner`	object or null	The Partner with its `openReceivable` and `openPayable` totals after booking. Null unless the Invoice was booked.
`totalCount`, `unbookedCount`, `outstandingTotal`	integer	The direction-wide totals described under `GET /invoices/pages`.

curl -X POST "https://api.sintropix.com/api/entities/$ENTITY_ID/invoices" \
  -H "x-api-key: $SINTROPIX_API_KEY" \
  -H "x-audit-actor: my-agent" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "6f1c2b1e-0d1a-4c7b-9a3e-2b8f5d0e1a11",
    "partnerId": "0b6c0f2e-5a4d-4e8f-b1c3-7d9e2a4f6c88",
    "direction": "payable",
    "documentKind": "invoice",
    "documentNumber": "45210",
    "currency": "CLP",
    "total": 1190000,
    "issueDate": "2026-08-14",
    "dueDate": "2026-09-13",
    "memo": "Hosting agosto 2026",
    "metadata": [{ "label": "Orden de compra", "value": "OC-2026-0193" }]
  }'

Automatic booking. When you omit bookingEntryWithLines, Sintropix books a payable invoice (not a credit note) from its vendor’s Booking Template if the vendor has booksAutomatically on and the Invoice fits the template exactly. A tax_only template also makes the Invoice tax_only as it books it. The same applies to each element of POST /invoices/bulk and to Invoices the source-feed sync creates. An Invoice that does not fit is still created, unbooked, and the request does not fail.

Example response:

{
  "invoice": {
    "id": "6f1c2b1e-0d1a-4c7b-9a3e-2b8f5d0e1a11",
    "entityId": "b2f0c1d4-7e8a-4b9c-8d1e-2f3a4b5c6d7e",
    "partnerId": "0b6c0f2e-5a4d-4e8f-b1c3-7d9e2a4f6c88",
    "direction": "payable",
    "documentKind": "invoice",
    "documentNumber": "45210",
    "currency": "CLP",
    "total": 1190000,
    "issueDate": "2026-08-14",
    "dueDate": "2026-09-13",
    "memo": "Hosting agosto 2026",
    "metadata": [{ "label": "Orden de compra", "value": "OC-2026-0193" }],
    "sourceId": null,
    "bookingEntryId": null,
    "controlLineId": null,
    "controlAccountId": null,
    "followUp": null,
    "excludedAt": null,
    "exclusionReason": null,
    "createdAt": "2026-08-14T15:02:11.482Z",
    "updatedAt": "2026-08-14T15:02:11.482Z",
    "dte": null,
    "partnerName": "Servicios Cloud SpA",
    "partnerWebsite": "servicioscloud.cl",
    "sourceName": null,
    "isExpenseRendition": false,
    "paymentStatus": null,
    "paymentDate": null,
    "openAmount": null,
    "bookingAccountLabel": null,
    "bookingExtraLineCount": 0,
    "hasErpThread": false,
    "attachmentCount": 0
  },
  "bookingEntry": null,
  "partner": null,
  "totalCount": 128,
  "unbookedCount": 7,
  "outstandingTotal": 4820500
}

POST `/invoices/bulk`

Create up to 100 Invoices in a single request and transaction. Each element carries its own client-supplied id (required) so a retry collides on the primary key rather than double-inserting.

Body: BulkCreateInvoicesDto — { invoices: CreateInvoice[] } (1 to 100 elements).
Response: array of createInvoiceResultSchema, in input order.

curl -X POST "https://api.sintropix.com/api/entities/$ENTITY_ID/invoices/bulk" \
  -H "x-api-key: $SINTROPIX_API_KEY" \
  -H "x-audit-actor: my-agent" \
  -H "Content-Type: application/json" \
  -d '{ "invoices": [ /* CreateInvoice, up to 100 */ ] }'

The bulk routes are declared before :invoiceId in the controller so Nest does not read bulk or book as an invoice id. Match that ordering when composing URLs.

POST `/invoices/book`

Book up to 100 already-created Invoices in a single transaction. Each element carries an invoiceId plus the booking instructions used by the single-invoice endpoint, including the optional expectedBookingVersion.

Body: BulkBookInvoicesDto — { bookings: (BookInvoice & { invoiceId })[] } (1 to 100 elements).
Response: array of bookInvoiceResultSchema, in input order.

Bulk endpoints run as one database transaction. If any element fails validation or a domain rule, the whole batch is rejected and the response identifies the offending element by its zero-based elementIndex (bulkElementFailureSchema). An INVOICE_BOOKING_CHANGED_ERROR on one element rolls back the whole request; retry the batch without that element (or with its refreshed expectedBookingVersion) to book its siblings.

GET `/invoices/:invoiceId`

Return the full Invoice detail: the Invoice row (as listed by GET /invoices/pages, including dte), plus the fields below.

Field	Type	Description
`partnerLegalName`	string or null	Legal name of the Partner.
`partnerTaxId`	string or null	Tax id of the Partner.
`bookingEntry`	object or null	The Ledger Entry that booked the Invoice. Null while unbooked.
`bookingVersion`	string	Opaque token that identifies the current state of the Invoice and its DTE for optimistic concurrency. Pass it back as `expectedBookingVersion` on a later booking write to detect concurrent changes. Changes whenever the Invoice or its DTE is edited, replaced, or removed, even if `updatedAt` is preserved.
`deferrals`	array	The Deferrals of the booking entry’s lines, each with its Releases. Empty while the Invoice is unbooked or when no line was deferred.

Ledger Entry detail (bookingEntry)

Field	Type	Description
`id`	uuid	Entry id.
`entityId`	uuid	Owning Entity.
`entryDate`	string	`YYYY-MM-DD`.
`memo`	string or null	Entry memo.
`notes`	string or null	Entry notes.
`status`	string	`active`, `deleted`, `reversed`, `scheduled`, or `cancelled`.
`reversalOfEntryId`	uuid or null	Set when this entry reverses another.
`reversedByEntryId`	uuid or null	Set when a live reversal entry points at this one.
`lines`	array	The entry’s lines (below).
`relatedInvoices`	array	Invoice objects linked to this entry, each with a `partnerName`.
`relatedMovements`	array	Bank Movements linked to this entry, each with `bankAccountCurrency`, `bankAccountLedgerAccountId`, and `partnerName`.
`allocations`	array	Settlements against this entry’s lines. Each carries a `counterpart` with `lineId`, `entryId`, `entryDate`, `entryMemo`, `accountId`, `accountCode`, `accountName`, `partnerId`, and `partnerName`.
`deferralRelease`	object or null	Set when this entry is a Release: `{ deferralId, invoiceId, invoiceDocumentNumber }`. Null otherwise, and null once the booking that holds the deferred line is unbooked or reversed.
`deferrals`	array	The Deferrals whose deferred line this entry books, in the shape of `deferrals` above. Unbooking or reversing this entry also undoes their Releases.
`createdAt`, `updatedAt`	timestamp

Each element of lines:

Field	Type	Description
`id`	uuid	Line id.
`entryId`	uuid	Parent entry.
`entityId`	uuid	Owning Entity.
`accountId`	uuid	Ledger Account.
`accountCode`	string	Code of the Ledger Account.
`accountName`	string	Name of the Ledger Account.
`accountType`	string	`asset`, `liability`, `equity`, `income`, `cost_of_goods_sold`, `operating_expense`, `other_income`, or `other_expense`.
`functionalAmount`	integer	Magnitude in the Entity’s functional currency, minor units.
`side`	string	`debit` or `credit`.
`partnerId`	uuid or null	Counterparty Partner.
`partnerName`	string or null	Name of that Partner.
`partnerWebsite`	string or null	Website of that Partner, as a bare domain (`acme.cl`); null when it has none.
`transactionCurrency`	string or null	Set together with the next two fields when the line was booked in a foreign currency.
`transactionAmount`	integer or null	Amount in `transactionCurrency`, minor units.
`transactionFxRate`	string or null	Decimal string.
`lineDimensionValues`	array	Tags on the line: `{ dimensionId, dimensionName, dimensionValueId, dimensionValueCode, dimensionValueName }`.
`createdAt`, `updatedAt`	timestamp

PATCH `/invoices/:invoiceId`

Partial update. Body: any subset of the fields below. At least one is required. A dte key is ignored; use the /dte endpoints for that.

Field	Type	Required	Description
`partnerId`	uuid	No	Counterparty Partner.
`direction`	string	No	`receivable` or `payable`.
`documentKind`	string	No	`invoice` or `tax_only`, on an unbooked Invoice only. See Switch the kind. `credit_note` is refused with `400`.
`documentNumber`	string	No	Non-empty.
`currency`	string	No	ISO 4217 code.
`total`	integer	No	Minor units, zero or more.
`issueDate`	string	No	`YYYY-MM-DD`.
`dueDate`	string or null	No	`YYYY-MM-DD`, or null to clear.
`memo`	string or null	No	Free text, or null to clear.
`metadata`	array	No	Replaces the whole list. Same limits as on create.
`sourceId`	uuid or null	No	Editable whether or not the Invoice is booked.

While a Payment Order names the Invoice, a change to partnerId, currency, or documentKind is refused with 409 and INVOICE_PAYMENT_ORDERS_PIN_ERROR. Remove the orders first. Response: { "invoice": <Invoice row>, "totalCount": integer, "unbookedCount": integer, "outstandingTotal": integer }.

DELETE `/invoices/:invoiceId`

Delete the Invoice. Booked Invoices are refused; unbook first. In the app, open the unbooked or excluded document and click the trash icon in its panel’s footer, then confirm. A booked document’s panel offers no delete. Deleting an Invoice also deletes the DTE behind it, unless another DTE still references that DTE (409). Response: { "deletedInvoice": <Invoice row>, "totalCount": integer, "unbookedCount": integer, "outstandingTotal": integer }.

PUT `/invoices/:invoiceId/dte`

Attach or replace the DTE behind an Invoice. The body states the whole tax document: every field is sent on both a first attach and a correction, with null where the document says nothing. The DTE’s cross-references are managed on the SII page. Body

Field	Type	Required	Description
`dteTypeCode`	string	Yes	SII document type code, from `GET /sii/document-types` (`33`, `34`, `61`, …).
`folio`	integer	Yes	The number the SII assigned, 1 to 9999999999.
`issuerRut`	string	Yes	Issuer RUT in canonical form, digits then hyphen then check digit (`76123456-0`).
`receiverRut`	string or null	Yes	Receiver RUT, same form.
`issuerName`	string or null	Yes	Issuer name as printed.
`receiverName`	string or null	Yes	Receiver name as printed.
`issueDate`	string	Yes	`YYYY-MM-DD`.
`taxPeriod`	string or null	Yes	The F29 / IVA month, `YYYY-MM`. Null when not yet known; it never defaults to the issue month.
`currency`	string	Yes	ISO 4217 code.
`total`	integer	Yes	Gross total printed on the DTE, minor units, zero or more.
`netAmount`	integer or null	No	Net base, minor units. Omit or null when the DTE states none.
`exemptAmount`	integer or null	No	Exempt part of the base, minor units.
`taxAmount`	integer or null	No	Tax amount, minor units. The whole IVA, including any part the buyer withholds.
`withheldIvaAmount`	integer or null	No	The part of `taxAmount` the buyer withholds, minor units. Omit or null when the DTE withholds no IVA.
`externalRef`	string	No	The id an external provider gave the document. Omit when none; must be non-empty if sent.
`metadata`	array	Yes	Additional Information lines, `{ "label": string, "value": string }`. Send `[]` for none.

Withheld IVA. On a factura de compra (type 46), the buyer withholds the IVA and pays it to the SII directly, so total leaves the withheld part out. State the whole IVA in taxAmount and the withheld part in withheldIvaAmount. A total withholding has withheldIvaAmount equal to taxAmount. For example, a 46 with a net of 1.000.000 CLP and a total withholding states "netAmount": 1000000, "taxAmount": 190000, "withheldIvaAmount": 190000, and "total": 1000000. DTEs that a Source Feed lands carry the amount the provider states, and a later Sync reports a changed amount as a divergence. One issuer cannot hold two DTEs of the same type and folio within an Entity, and one Invoice holds at most one DTE; either collision is answered 409. On a Sales Summary Invoice. An Invoice that lands a Sales Summary carries a DTE the SII owns, with no folio. Only a Sync writes it, so a write is refused with 409 and code DTE_HELD_BY_SALES_SUMMARY_ERROR. On a booked Invoice. The write is still accepted, but the block must restate every field of the stored DTE and change only taxPeriod (the F29 / IVA month) and/or metadata (the Additional Information lines). A field the block leaves unstated keeps its stored value and counts as no change. Any other structural difference — dteTypeCode, folio, issuerRut, receiverRut, issuerName, receiverName, issueDate, currency, total, netAmount, exemptAmount, taxAmount, withheldIvaAmount, or externalRef — is answered 409 with code INVOICE_BOOKED_FIELDS_LOCKED_ERROR; unbook the Invoice first if you need to move one of them. The booking entry (its type, figures, and ledger lines) is not touched when only the period or the metadata changes. Response: { "invoice": <Invoice row>, "totalCount": integer, "unbookedCount": integer, "outstandingTotal": integer }. The Invoice row’s dte carries the stored document:

Field	Type	Description
`id`	uuid	DTE id. Use it with the SII endpoints.
`entityId`	uuid	Owning Entity.
`invoiceId`	uuid or null	The Invoice this DTE backs.
`dteTypeCode`, `folio`, `issuerRut`, `receiverRut`, `issuerName`, `receiverName`, `issueDate`, `taxPeriod`, `currency`, `total`, `netAmount`, `exemptAmount`, `taxAmount`, `withheldIvaAmount`, `externalRef`, `metadata`		As sent in the body.
`createdAt`, `updatedAt`	timestamp

curl -X PUT "https://api.sintropix.com/api/entities/$ENTITY_ID/invoices/$INVOICE_ID/dte" \
  -H "x-api-key: $SINTROPIX_API_KEY" \
  -H "x-audit-actor: my-agent" \
  -H "Content-Type: application/json" \
  -d '{
    "dteTypeCode": "33",
    "folio": 45210,
    "issuerRut": "76123456-0",
    "receiverRut": "77654321-7",
    "issuerName": "Servicios Cloud SpA",
    "receiverName": "Mi Empresa SpA",
    "issueDate": "2026-08-14",
    "taxPeriod": "2026-08",
    "currency": "CLP",
    "total": 1190000,
    "netAmount": 1000000,
    "exemptAmount": 0,
    "taxAmount": 190000,
    "metadata": []
  }'

DELETE `/invoices/:invoiceId/dte`

Remove the DTE from an Invoice. The Invoice stays; the tax document and the references it stated are deleted. Refused with 409 while another DTE still references it. Refused with 409 and code INVOICE_BOOKED_FIELDS_LOCKED_ERROR while the Invoice is booked; unbook first. Refused with 409 and code DTE_HELD_BY_SALES_SUMMARY_ERROR on an Invoice that lands a Sales Summary. Response: { "invoice": <Invoice row>, "totalCount": integer, "unbookedCount": integer, "outstandingTotal": integer }.

POST `/invoices/:invoiceId/book`

Book an existing Invoice to a Ledger Entry using the supplied booking instructions (target counter account, dimensions, partner). Body

Field	Type	Required	Description
`controlLineId`	uuid or null	Yes	The `id` of the line in `entry.newLedgerEntryLines` that carries the claim: the Invoice’s Control Line. Compared without regard to case. Send `null` for a `tax_only` document, which books no claim, and an id for every other kind.
`entry`	object	Yes	The Ledger Entry to post (fields below).
`expectedBookingVersion`	string	No	Opaque `bookingVersion` you read earlier from `GET /invoices/:invoiceId`. When sent, the server acquires the Invoice lock, compares it to the current version, and refuses the booking with `409` and code `INVOICE_BOOKING_CHANGED_ERROR` if the Invoice or its DTE changed in between. No Ledger Entry is written on a mismatch. Omit to skip the check.

Fields of entry:

Field	Type	Required	Description
`id`	uuid	Yes	Caller-generated entry id. A retry with the same id is answered `409`.
`entryDate`	string	Yes	`YYYY-MM-DD`.
`memo`	string or null	Yes	Entry memo.
`notes`	string or null	No	Entry notes.
`bookId`	uuid or null	Conditional	Book the entry counts in; `null` marks it common. Send (as an id or as `null`) when the Entity has at least one Book; omit otherwise.
`newLedgerEntryLines`	array	Yes	2 to 10,000 lines. Total debits must equal total credits.

Each element of newLedgerEntryLines:

Field	Type	Required	Description
`id`	uuid	Yes	Caller-generated line id. Must not already exist. See Ledger Entries.
`accountId`	uuid	Yes	Ledger Account of the Entity.
`functionalAmount`	integer	Yes	Magnitude in the functional currency, minor units, zero or more.
`side`	string	Yes	`debit` or `credit`.
`partnerId`	uuid or null	No	Counterparty. Lines other than the control line default to the Invoice’s Partner when omitted.
`transactionCurrency`	string	No	ISO 4217 code. Send together with the next two fields, or none of the three.
`transactionAmount`	integer	No	Amount in `transactionCurrency`, minor units.
`transactionFxRate`	string	No	Decimal string such as `"945.12"`. No exponent or sign.
`dimensionValueIds`	array of uuid	No	Dimension Values to tag the line with. Default `[]`.
`deferral`	object	No	Spread this line’s whole amount over whole months instead of recognizing it on the entry date: `{ recognitionAccountId, startMonth, monthCount }`. See Deferrals.

The Control Line (the line whose id is controlLineId) must sit on an open-item receivable account for a receivable Invoice or payable account for a payable one, name the Invoice’s Partner, and match the Invoice’s denomination. A regular invoice debits a receivable or credits a payable; a credit note posts the opposite side. Its account becomes the Invoice’s controlAccountId. A tax_only document has no Control Line. Its entry must still balance, and none of its lines may sit on an account whose sub-type is payable, expense_rendition_payable, or receivable. For example, a factura de compra 46 of CLP 190,000 IVA for a purchase abroad:

{
  "controlLineId": null,
  "entry": {
    "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
    "entryDate": "2026-08-20",
    "memo": "Factura de compra 46 1234 Proveedor Extranjero",
    "newLedgerEntryLines": [
      { "id": "3b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d7e", "accountId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "functionalAmount": 190000, "side": "debit" },
      { "id": "4c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e8f", "accountId": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b", "functionalAmount": 190000, "side": "credit" }
    ]
  }
}

Other lines of the entry can post to the same account as the Control Line. For example, net an advance or a retention of the same Partner in the Invoice’s own entry, or split a receivable into one line per due date. Only the Control Line is the Invoice’s: the payment status derives from it alone. Any other line on that account is an ordinary open item of the Partner until an Allocation settles it. Example body for a CLP purchase invoice of 1,190,000 (1,000,000 net plus 19% VAT):

{
  "controlLineId": "6f7a8b9c-0d1e-4f2a-8b3c-4d5e6f7a8b9c",
  "entry": {
    "id": "9c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
    "entryDate": "2026-08-14",
    "memo": "Factura 45210 Servicios Cloud SpA",
    "newLedgerEntryLines": [
      { "id": "4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a", "accountId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "functionalAmount": 1000000, "side": "debit" },
      { "id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "accountId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "functionalAmount": 190000, "side": "debit" },
      { "id": "6f7a8b9c-0d1e-4f2a-8b3c-4d5e6f7a8b9c", "accountId": "3e7a9c1b-2d4f-4a6e-8b0c-1d2e3f4a5b6c", "functionalAmount": 1190000, "side": "credit", "partnerId": "0b6c0f2e-5a4d-4e8f-b1c3-7d9e2a4f6c88" }
    ]
  }
}

Response (200)

Field	Type	Description
`invoice`	object	The Invoice row, now with `bookingEntryId` set. `controlLineId` and `controlAccountId` are set too, except on a `tax_only` document.
`bookingEntry`	object	The Ledger Entry detail described under `GET /invoices/:invoiceId`.
`partner`	object	The Partner (see Partners) with `openReceivable` and `openPayable` after booking.
`totalCount`, `unbookedCount`, `outstandingTotal`	integer	The direction-wide totals described under `GET /invoices/pages`.

Domain errors

Code	Status	Meaning
`INVOICE_BOOKING_CHANGED_ERROR`	`409`	The Invoice or its DTE was edited, replaced, or removed since the `expectedBookingVersion` you sent was read. No Ledger Entry was written. The response carries `params: { invoiceId }`. Re-read the Invoice detail to check whether the change still makes the booking correct, then retry with the new `bookingVersion`.
`CONTROL_LINE_NOT_IN_ENTRY_LINES_ERROR`	`400`	No line of `entry.newLedgerEntryLines` has the `id` sent as `controlLineId`. The response carries `params: { controlLineId }`.
`CONTROL_LINE_CONTRADICTS_DOCUMENT_KIND_ERROR`	`409`	`controlLineId` doesn’t fit the Invoice’s kind: an id was sent for a `tax_only` document, or `null` for any other kind. The response carries `params: { documentKind, controlLineId }`.
`TAX_ONLY_LINE_ON_CONTROL_ACCOUNT_ERROR`	`409`	A line of a `tax_only` booking sits on an account whose sub-type is `payable`, `expense_rendition_payable`, or `receivable`. The response carries `params: { ledgerAccountId, ledgerAccountSubtype }`.
`INVOICE_EXCLUDED_ERROR`	`409`	The Invoice is excluded from the books. Include it first. The bulk `POST /invoices/book` refuses an excluded element the same way. The response carries `params: { invoiceId }`.
`DEFERRAL_DOCUMENT_KIND_NOT_SUPPORTED_ERROR`	`409`	A line of a credit note or a `tax_only` document carries `deferral`. Only an `invoice` can be deferred. The response carries `params: { invoiceId, documentKind }`.
`DEFERRAL_ACCOUNT_SUBTYPE_MISMATCH_ERROR`	`400`	The deferred line’s account does not have the sub-type the Invoice’s direction needs: `prepaid_expense` for `payable`, `deferred_revenue` for `receivable`. The response carries `params: { ledgerEntryLineId, ledgerAccountId, expectedSubtype }`.
`DEFERRAL_LINE_SIDE_MISMATCH_ERROR`	`400`	The deferred line is on the wrong side: a payable Invoice defers a `debit` line, a receivable Invoice a `credit` line. The response carries `params: { ledgerEntryLineId, expectedSide }`.
`DEFERRAL_RECOGNITION_ACCOUNT_INELIGIBLE_ERROR`	`400`	`recognitionAccountId` is not of a type the deferral can release into. The response carries `params: { ledgerEntryLineId, recognitionAccountId, deferredAccountSubtype }`.
`LEDGER_ENTRY_DATE_LOCKED_ERROR`	`409`	A Release of a deferred line falls on or before the ledger lock date. Nothing is booked. The response carries `params: { entryDate, ledgerLockDate }`.

Detecting concurrent changes with `expectedBookingVersion`

Send expectedBookingVersion when the booking decision is derived from state you read earlier and any change to the Invoice or its DTE between the read and the write should abort the booking. Typical cases: a scheduled workflow that batches unbooked Invoices, an integration that classifies an Invoice from its stored DTE amounts, or a UI that stages a booking for review.

GET /invoices/:invoiceId and remember bookingVersion.
Build the entry from the values you just read.
POST /invoices/:invoiceId/book (or POST /invoices/book) with expectedBookingVersion set to that token.
On 409 INVOICE_BOOKING_CHANGED_ERROR, re-read the Invoice and decide whether to rebuild the entry.

The check runs after the server acquires the Invoice lock, so a booking that races a concurrent DTE edit either sees the edit and refuses, or wins the lock and books the pre-edit state without either write being lost. Omit the field when no earlier read exists and any current state is acceptable.

Deferrals

Some invoices cover several months: an annual software subscription paid up front, or a four-month service billed on one sales invoice. A Deferral spreads one line of the booking over whole months, so the result is recognized month by month instead of all in the invoice month.

On a payable Invoice, the deferred line debits a prepaid expense account (an asset with sub-type prepaid_expense).
On a receivable Invoice, the deferred line credits a deferred revenue account (a liability with sub-type deferred_revenue).
Each month, a Release moves that month’s share from the deferral account to the Recognition Account: the expense or income account the line would have posted to had it not been deferred.

Create the two accounts in the Chart of Accounts before you defer a line. In the app, turn on Diferir on a line when you classify the Invoice.

Defer a line when you book

You defer at booking time only. Add deferral to the line in entry.newLedgerEntryLines on POST /invoices/:invoiceId/book. The same field works in POST /invoices/book and in bookingEntryWithLines on POST /invoices. There is no separate endpoint to defer an Invoice that is already booked; unbook it and book it again with the terms. Fields of deferral:

Field	Type	Required	Description
`recognitionAccountId`	uuid	Yes	The account each Release lands in. For a payable Invoice: `cost_of_goods_sold`, `operating_expense`, or `other_expense`. For a receivable Invoice: `income` or `other_income`.
`startMonth`	string	Yes	First month of service, `YYYY-MM`.
`monthCount`	integer	Yes	Number of months, 1 to 600. The last Release must fall in December 9999 at the latest.

These rules apply:

The whole line is deferred. You can’t defer part of a line.
The line’s account must have the sub-type of the Invoice’s direction, on the matching side: a debit on prepaid_expense for a payable Invoice, a credit on deferred_revenue for a receivable one.
Credit notes and tax_only documents can’t be deferred.
Only the functional amount is deferred. A foreign-currency line is released at the amount booked on the Invoice, and the Releases carry no transaction currency.
Defer the net line only. The IVA line and the control line follow the Invoice as usual.
Several lines of the same booking can each carry their own deferral.

The Release schedule

Booking a deferred line creates one Release per month:

Straight-line amounts. Each Release carries an equal share of the line’s functional amount. The last month absorbs the rounding.
Month-end dates. Each Release is dated the last day of its month.
Past and future months. A Release dated today or earlier is booked right away with status active. A later one is a Scheduled Entry with status scheduled, and Sintropix books it on its date.
Closed months. If a Release would fall on or before the ledger lock date, the whole booking is refused with LEDGER_ENTRY_DATE_LOCKED_ERROR.
Partner and Dimensions. Both lines of each Release carry the Invoice’s Partner. The deferred line’s dimensionValueIds go on the recognition line of each Release, not on the deferral account line of the booking.

Each Release has two lines: the Recognition Account and the deferral account. For a prepaid expense the Release debits the Recognition Account and credits the prepaid account. For deferred revenue it debits the deferred revenue account and credits the Recognition Account. A Release keeps the plan it was created with. Changing its date, through PATCH /ledger/entries/:entryId or by rescheduling it, is refused with DEFERRAL_RELEASE_LOCKED_ERROR. Moving one of its lines to another account is refused with LEDGER_ENTRY_LINE_ACCOUNT_PINNED_ERROR. Example: a bill of CLP 1,428,000 (1,200,000 net plus 19% VAT) for a 12-month software subscription starting in July 2026. The net line debits the prepaid expense account and releases 100,000 a month into the software expense account.

{
  "controlLineId": "0e1f2a3b-4c5d-4e6f-8a7b-8c9d0e1f2a3b",
  "entry": {
    "id": "7b8c9d0e-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
    "entryDate": "2026-07-01",
    "memo": "Factura 88120 Software Anual SpA",
    "newLedgerEntryLines": [
      {
        "id": "8c9d0e1f-2a3b-4c4d-8e5f-6a7b8c9d0e1f",
        "accountId": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
        "functionalAmount": 1200000,
        "side": "debit",
        "deferral": {
          "recognitionAccountId": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f7a",
          "startMonth": "2026-07",
          "monthCount": 12
        }
      },
      { "id": "9d0e1f2a-3b4c-4d5e-8f6a-7b8c9d0e1f2a", "accountId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "functionalAmount": 228000, "side": "debit" },
      { "id": "0e1f2a3b-4c5d-4e6f-8a7b-8c9d0e1f2a3b", "accountId": "3e7a9c1b-2d4f-4a6e-8b0c-1d2e3f4a5b6c", "functionalAmount": 1428000, "side": "credit", "partnerId": "0b6c0f2e-5a4d-4e8f-b1c3-7d9e2a4f6c88" }
    ]
  }
}

The booking response doesn’t list the Releases. Read them from deferrals on GET /invoices/:invoiceId.

Reading a Deferral

Each element of deferrals on the Invoice detail:

Field	Type	Description
`id`	uuid	Deferral id.
`deferredLedgerEntryLineId`	uuid	The booking line that was deferred.
`deferredAccount`	object	The prepaid expense or deferred revenue account: `{ id, code, name }`.
`recognitionAccount`	object	The Recognition Account: `{ id, code, name }`.
`startMonth`	string	First month, `YYYY-MM`.
`monthCount`	integer	Number of months.
`releases`	array	The Releases, ordered by date (below).
`recognizedAmount`	integer	Sum of the `active` Releases, in functional minor units.
`pendingAmount`	integer	The deferred line’s amount minus `recognizedAmount`.

Each element of releases:

Field	Type	Description
`ledgerEntryId`	uuid	The Release’s Ledger Entry.
`entryDate`	string	`YYYY-MM-DD`, the last day of its month.
`amount`	integer	Functional amount, minor units.
`status`	string	`active` (booked), `scheduled` (pending), `cancelled`, `deleted` (unbooked), or `reversed`.

A Deferral has no status of its own. Read its state from its Releases.

Undoing a Deferral

A Deferral follows its booking:

Unbook the booking entry (DELETE /ledger/entries/:entryId): the active Releases are unbooked and the scheduled ones are cancelled.
Reverse the booking entry (POST /ledger/entries/:entryId/reverse): the active Releases are reversed on the same reversal date and the scheduled ones are cancelled.
If an active Release sits on or before the ledger lock date, the whole Unbook is refused with LEDGER_ENTRY_UNBOOK_FROZEN_ERROR and the whole Reverse with LEDGER_ENTRY_FROZEN_ERROR.

In the app, the Unbook and Reverse dialogs on the Invoice and on the entry page list these effects before you confirm. To stop a Deferral but keep what’s already recognized, cancel its pending Releases.

POST `/deferrals/:deferralId/cancel`

Cancel every scheduled Release of the Deferral. Releases already booked stay as they are. In the app, this is Cancelar lo pendiente on the Invoice. The call has no body. Response (200): the Deferral, in the shape of an element of deferrals, with the cancelled Releases now cancelled. Domain errors

Code	Status	Meaning
`DEFERRAL_NOT_FOUND_ERROR`	`404`	The Deferral does not exist under this Entity. The response carries `params: { deferralId }`.

curl -X POST "https://api.sintropix.com/api/entities/$ENTITY_ID/deferrals/$DEFERRAL_ID/cancel" \
  -H "x-api-key: $SINTROPIX_API_KEY" \
  -H "x-audit-actor: my-agent"

Exclude an invoice from the books

Some documents land but should never be booked: for example, an annulled boleta or a factura you claimed at the SII. Deleting one doesn’t help, because the next Source Feed sync lands it again. Exclude it instead. An Exclusion records, with a reason, that the Invoice will never be booked. It takes the Invoice out of the pending work, and you can lift it at any time. An excluded Invoice:

Is still listed by statusFilter=all, the default, and the app crosses those rows out. It’s left out of statusFilter=notExcluded and statusFilter=unbooked, of unbookedCount and outstandingTotal, of the home dashboard’s salesToBook, purchasesToBook, and expenseRenditionsToBook, and of match candidates.
Can’t be booked, single or bulk, and can’t hold a Follow-up. Excluding the Invoice clears its Follow-up.
Owes nothing to plan in a Payment Batch.
Stays landed. A sync skips it, but still writes the Standing and Tax Period of its DTE.

A booked Invoice can’t be excluded: unbook it first. Anyone who can book an Invoice can exclude or include it. A viewer is refused with 403. Each Exclusion and Inclusion appears in the Invoice’s audit trail.

PUT `/invoices/:invoiceId/exclusion`

Exclude an unbooked Invoice from the books. Body

Field	Type	Required	Description
`reason`	string	Yes	Why the Invoice will never be booked. Trimmed, non-empty, up to 1,000 characters.

Response: { "invoice": <Invoice row>, "totalCount": integer, "unbookedCount": integer, "outstandingTotal": integer }, with excludedAt and exclusionReason set.

curl -X PUT "https://api.sintropix.com/api/entities/$ENTITY_ID/invoices/$INVOICE_ID/exclusion" \
  -H "x-api-key: $SINTROPIX_API_KEY" \
  -H "x-audit-actor: my-agent" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Boleta anulada en el SII." }'

DELETE `/invoices/:invoiceId/exclusion`

Include an excluded Invoice in the books again. It goes back to unbooked. Response: { "invoice": <Invoice row>, "totalCount": integer, "unbookedCount": integer, "outstandingTotal": integer }, with excludedAt and exclusionReason null.

Exclusion errors

Code	Status	Meaning
`INVOICE_ALREADY_BOOKED_ERROR`	`409`	The Invoice is booked. Unbook it before you exclude it.
`INVOICE_EXCLUDED_ERROR`	`409`	The Invoice is already excluded.
`INVOICE_NOT_EXCLUDED_ERROR`	`409`	The Invoice isn’t excluded, so there’s nothing to include.

A blank reason, or one longer than 1,000 characters, is refused with 400.

Status codes

Status	Meaning
`200`	Success on `GET`, `PATCH`, `PUT`, `DELETE`, `POST /book`, `POST /deferrals/:deferralId/cancel`. `DELETE` answers with the deleted row.
`201`	Invoice created.
`400`	Validation error, or missing `x-audit-actor` on a key-authenticated mutation.
`403`	The caller’s Role can’t write, for example a `viewer` excluding an Invoice.
`404`	Entity, Invoice, or Deferral not found.
`409`	Cannot delete a booked Invoice, structural DTE edit or DTE removal refused on a booked Invoice (`INVOICE_BOOKED_FIELDS_LOCKED_ERROR`), booking refused because the Invoice or DTE changed since the read (`INVOICE_BOOKING_CHANGED_ERROR`), the Invoice is excluded (`INVOICE_EXCLUDED_ERROR`) or not excluded (`INVOICE_NOT_EXCLUDED_ERROR`), a Payment Order pins its Partner, currency, and kind (`INVOICE_PAYMENT_ORDERS_PIN_ERROR`), a DTE write or removal or a kind switch on a Sales Summary Invoice (`DTE_HELD_BY_SALES_SUMMARY_ERROR`), a credit note’s kind can’t switch (`INVOICE_DOCUMENT_KIND_FIXED_ERROR`), `controlLineId` doesn’t fit the kind (`CONTROL_LINE_CONTRADICTS_DOCUMENT_KIND_ERROR`), a `tax_only` line sits on a receivable or payable account (`TAX_ONLY_LINE_ON_CONTROL_ACCOUNT_ERROR`), a credit note or `tax_only` line carries a deferral (`DEFERRAL_DOCUMENT_KIND_NOT_SUPPORTED_ERROR`), Invoice or entry id already exists, DTE already attached, duplicate DTE identity, and so on.

​Status

​Document kinds

​Tax-only documents

​Switch the kind

​Ontop invoices

​Before the first load

​What a load does

​Expense renditions

​Load Rindegastos

​Book renditions

​GET /invoices

​Reading several Invoices by id

​GET /invoices/pages

​POST /invoices

​POST /invoices/bulk

​POST /invoices/book

​GET /invoices/:invoiceId

​PATCH /invoices/:invoiceId

​DELETE /invoices/:invoiceId

​PUT /invoices/:invoiceId/dte

​DELETE /invoices/:invoiceId/dte

​POST /invoices/:invoiceId/book

​Detecting concurrent changes with expectedBookingVersion

​Deferrals

​Defer a line when you book

​The Release schedule

​Reading a Deferral

​Undoing a Deferral

​POST /deferrals/:deferralId/cancel

​Exclude an invoice from the books

​PUT /invoices/:invoiceId/exclusion

​DELETE /invoices/:invoiceId/exclusion

​Exclusion errors

​Status codes

Status

Document kinds

Tax-only documents

Switch the kind

Ontop invoices

Before the first load

What a load does

Expense renditions

Load Rindegastos

Book renditions

GET `/invoices`

Reading several Invoices by id

GET `/invoices/pages`

POST `/invoices`

POST `/invoices/bulk`

POST `/invoices/book`

GET `/invoices/:invoiceId`

PATCH `/invoices/:invoiceId`

DELETE `/invoices/:invoiceId`

PUT `/invoices/:invoiceId/dte`

DELETE `/invoices/:invoiceId/dte`

POST `/invoices/:invoiceId/book`

Detecting concurrent changes with `expectedBookingVersion`

Deferrals

Defer a line when you book

The Release schedule

Reading a Deferral

Undoing a Deferral

POST `/deferrals/:deferralId/cancel`

Exclude an invoice from the books

PUT `/invoices/:invoiceId/exclusion`

DELETE `/invoices/:invoiceId/exclusion`

Exclusion errors

Status codes