Invoice API

Published changes for Invoice API.

13 August 2026

Area	Change type	Description
Faturação	Change	Comment lines normalised Comment lines are normalised: `taxId = 0` and `quantity = 1`. A document cannot be issued with comment lines only — returns `Invoice.Details.OnlyComments`. POST /gateway/invoice/invoices How to upgrade Ensure at least one valued line on the document. Do not rely on tax or quantity on comment lines.
Faturação	Fix	Stable document line ordering Document line ordering is now guaranteed by `Id`, fixing swapped lines when reopening a document from Issued Documents. GET /gateway/invoice/invoices/{id}
Faturação	Addition	Cashier selection when creating documents Sales document create accepts the optional `businessAccountId` field to select the cashier. If omitted or `0`, the API picks the cashier in this order: payment type, document type, user and terminal. Password-protected cashiers require prior authorization (`POST /gateway/business-account/{id}/authorize`) or the `X-BA-Auth-Token` header. Re-authorizing the same cashier no longer fails. POST /gateway/invoice/invoices
SAT	Breaking change	Removed the legacy SAT invoicing endpoint The `POST /gateway/intervention/invoice` endpoint no longer exists. SAT invoicing now uses a dedicated preview and the generic create-document endpoint. POST /gateway/intervention/invoice How to upgrade Stop calling `POST /gateway/intervention/invoice`. Use `POST /gateway/service-order/invoice/preview` or `POST /gateway/intervention/invoice/preview`, then `POST /gateway/invoice/invoices` with `serviceOrderGuid` or `interventionGuid`.
SAT	Addition	Service order invoice preview New endpoint to compute invoice lines for a service order without persisting. Accepts `documentTypeKeyId` and `hoursBillingMode` (`Full`, `ExtraOnly`, `None`). POST /gateway/service-order/invoice/preview
SAT	Addition	Intervention invoice preview New endpoint to compute invoice lines for a standalone intervention without persisting. Accepts `interventionGuid`, `documentTypeKeyId` and `hoursBillingMode`. POST /gateway/intervention/invoice/preview
SAT	Change	SAT issuing via the generic create-document endpoint Document creation accepts `serviceOrderGuid` or `interventionGuid` to declare the SAT origin. Reference lines use `originBodyGuid` and `relationType` (e.g. `ServiceOrderInterventionHours`). Sending both GUIDs returns `SatOrigin.Ambiguous`. POST /gateway/invoice/invoices How to upgrade Declare the SAT origin on the header and reuse the lines returned by preview (including `originBodyGuid` and `relationType`).
SAT	Change	hoursBillingMode only on preview `hoursBillingMode` is used only on preview to compute lines. On issue (`POST /gateway/invoice/invoices`) the backend validates quantities against recorded hours. POST /gateway/service-order/invoice/preview How to upgrade Stop sending `hoursBillingMode` on issue. Compute lines with preview and send the adjusted result to `POST /gateway/invoice/invoices`.

6 August 2026

Area	Change type	Description
Contratos	Addition	Covenant agreement debit Covenant debit: list (`GET /gateway/debit-agreement` on Core API), process (`POST .../save`) and skip occurrence (`POST .../ignore`). Save/ignore require `Idempotency-Key`. POST /gateway/debit-agreement/save
Faturação	Breaking change	Payments and discounts on document create Document creation payload changed: `paymentType` is replaced by `payments[]` ({ paymentTypeId, amount }) and `discountValue` by `discountPercentage`. Header fields `currencyId`, `guid` and `saleZoneAreaObjectId` were removed. New fields: `documentDate`, `emissionReason`, `creationUserId` and `allowCreditLimitOverride`. On lines, `discountValue` becomes `discountPercentage`; `paymentType`, `headerDiscountAmount`, `stockFlow` and `stockBehavior` were removed. Stock movement is now driven by document type and item configuration. POST /gateway/invoice/invoices How to upgrade Send `payments` as a list (split payments and change) and express discounts as percentages on header and lines. Stop sending `currencyId`, `guid`, `saleZoneAreaObjectId`, `stockFlow` and `stockBehavior`. Use line `guid` / `parentGuid` / `relationType` only for menus and conversions.
Faturação	Breaking change	Retail price includes VAT Line `retailPrice` is now the public final price **including VAT**. The engine derives net amount and tax internally. The response exposes `hasTaxIncludedPrices` to indicate the pricing regime. POST /gateway/invoice/invoices How to upgrade If you previously sent a net price in `retailPrice`, send the VAT-inclusive public price instead. Confirm totals using `hasTaxIncludedPrices` in the response.
Faturação	Breaking change	Stricter fiscal validation The new fiscal engine rejects requests that used to succeed: VAT/NIF validation (including VIES for EU customers), simplified invoice rules, credit/debit notes (PT/AO) and checking-account rules. Allowed payment mechanisms on create: NU, CC, CD and OU only. TB, CH, MB and MW are rejected even if enabled in the database. Unsupported document natures return `DocumentType.NotSupported`. POST /gateway/invoice/invoices How to upgrade Validate NIF and simplified-invoice limits before POST. Use only NU/CC/CD/OU mechanisms. Do not mix checking-account with immediate payments, and do not use checking-account on FR. On `DocumentType.NotSupported`, confirm the nature in sandbox or with R&D.
Faturação	Addition	Document PDF New document PDF endpoint. Returns `application/pdf`. Optional query `layout=Slip|Standard` (receipt roll vs A4/A5). 400 for invalid layout; 404 `Document.NotFound` if the document does not exist. GET /gateway/invoice/invoices/{id}/pdf
Faturação	Addition	Structured printing data Structured printing data so integrators can render the document: fiscal header (atcud, qrCode, fiscalData), entity, lines, taxes, payments (including `isChange` for cash change) and print counts. GET /gateway/invoice/invoices/{id}/printing-data
Faturação	Addition	Print registration with Idempotency-Key Registers a print and increments the copy counter. Response `{ numberCopies }`. The `Idempotency-Key` header is required (400 without it). The same key does not increment twice. POST /gateway/invoice/invoices/{id}/register-print
Faturação	Addition	Suggested next document number Returns the suggested next number `{ number, createDate }` without reserving the counter. GET /gateway/invoice/invoices/next-number/{documentTypeId}/{serieId}
Faturação	Addition	Temporary documents Temporary documents (parked sale): create, list, get, check existence and delete. This is a data parking area with no fiscal validation — it does not issue a document or series number. Endpoints: `POST/GET /temp-documents`, `GET /has`, `GET/DELETE /{id}`. POST /gateway/invoice/temp-documents
Faturação	Change	serieId and excludeFullyConverted filters The list now accepts `serieId` and `excludeFullyConverted`. Each document includes `documentIdentifier` (e.g. FT FAC1/7223). GET /gateway/invoice/invoices
Faturação	Change	documentIdentifier, entityBalance and ATCUD The header now exposes `documentIdentifier` and `entityBalance` (customer current-account balance). ATCUD is stamped on the document (`atcud`). Numbering uses a per-terminal lock with integrity checks (PT/AO) and automatic number release on failure. GET /gateway/invoice/invoices/{id}
Faturação	Addition	Menus and document conversion Menu / composite products: the menu line has a `guid`; each component is a line with `parentGuid` and `relationType`. Document conversion: `originBodyGuid` + `relationType` link lines to the source document (order → invoice). POST /gateway/invoice/invoices