Invoice API
Alterações publicadas na Invoice API.
13 de agosto de 2026
| Área | Tipo | Descrição |
|---|---|---|
| Faturação | Alteração | Linhas de comentário normalizadas Linhas de comentário passam a ser normalizadas: `taxId = 0` e `quantity = 1`. Um documento não pode ser emitido apenas com linhas de comentário — devolve `Invoice.Details.OnlyComments`.
Como actualizar Garanta pelo menos uma linha valorizada no documento. Não dependa de imposto ou quantidade em linhas de comentário. |
| Faturação | Correção | Ordenação estável das linhas do documento A ordenação das linhas do documento passou a ser garantida por `Id`, corrigindo linhas trocadas ao reabrir um documento a partir de Documentos Emitidos. |
| Faturação | Adição | Escolha de caixa na criação de documentos A criação de documentos de venda aceita o campo opcional `businessAccountId` para indicar a caixa. Se for omitido ou `0`, a API escolhe a caixa por ordem: tipo de pagamento, tipo de documento, utilizador e terminal. Caixas com palavra-passe exigem autorização prévia (`POST /gateway/business-account/{id}/authorize`) ou o header `X-BA-Auth-Token`. Reautorizar a mesma caixa já não falha. |
| SAT | Breaking | Removido o endpoint de faturação SAT antigo O endpoint `POST /gateway/intervention/invoice` deixou de existir. A faturação SAT passa a usar pré-visualização dedicada e emissão pelo create-document genérico.
Como actualizar Deixe de chamar `POST /gateway/intervention/invoice`. Use `POST /gateway/service-order/invoice/preview` ou `POST /gateway/intervention/invoice/preview` e depois `POST /gateway/invoice/invoices` com `serviceOrderGuid` ou `interventionGuid`. |
| SAT | Adição | Pré-visualização de faturação da ordem de serviço Novo endpoint para calcular as linhas de fatura de uma ordem de serviço sem persistir. Aceita `documentTypeKeyId` e `hoursBillingMode` (`Full`, `ExtraOnly`, `None`). |
| SAT | Adição | Pré-visualização de faturação da intervenção Novo endpoint para calcular as linhas de fatura de uma intervenção isolada sem persistir. Aceita `interventionGuid`, `documentTypeKeyId` e `hoursBillingMode`. |
| SAT | Alteração | Emissão SAT pelo create-document genérico A criação de documentos aceita `serviceOrderGuid` ou `interventionGuid` para declarar a origem SAT. As linhas de referência usam `originBodyGuid` e `relationType` (ex.: `ServiceOrderInterventionHours`). Enviar ambos os GUIDs devolve `SatOrigin.Ambiguous`.
Como actualizar Declare a origem SAT no cabeçalho e reutilize as linhas devolvidas pelo preview (incluindo `originBodyGuid` e `relationType`). |
| SAT | Alteração | hoursBillingMode apenas na pré-visualização `hoursBillingMode` é usado só no preview para calcular as linhas. Na emissão (`POST /gateway/invoice/invoices`) o backend valida as quantidades contra as horas registadas.
Como actualizar Deixe de enviar `hoursBillingMode` na emissão. Calcule as linhas com o preview e envie o resultado ajustado para `POST /gateway/invoice/invoices`. |
6 de agosto de 2026
| Área | Tipo | Descrição |
|---|---|---|
| Contratos | Adição | Débito de avenças Débito de avenças: listar (`GET /gateway/debit-agreement` na Core API), processar (`POST .../save`) e ignorar ocorrência (`POST .../ignore`). Save/ignore exigem `Idempotency-Key`. |
| Faturação | Breaking | Pagamentos e descontos no POST de documentos O payload de criação de documentos mudou: `paymentType` foi substituído por `payments[]` ({ paymentTypeId, amount }) e `discountValue` por `discountPercentage`. No cabeçalho foram removidos `currencyId`, `guid` e `saleZoneAreaObjectId`. Passam a existir `documentDate`, `emissionReason`, `creationUserId` e `allowCreditLimitOverride`. Nas linhas, `discountValue` passa a `discountPercentage`; `paymentType`, `headerDiscountAmount`, `stockFlow` e `stockBehavior` foram removidos. O stock passa a ser determinado pelo tipo de documento e pelo artigo.
Como actualizar Envie `payments` como lista (permite pagamentos divididos e troco) e descontos em percentagem no cabeçalho e nas linhas. Deixe de enviar `currencyId`, `guid`, `saleZoneAreaObjectId`, `stockFlow` e `stockBehavior`. Use `guid` / `parentGuid` / `relationType` nas linhas apenas para menus e conversões. |
| Faturação | Breaking | Preço de venda com IVA incluído `retailPrice` nas linhas passou a ser o preço final ao público **com IVA incluído**. O motor calcula internamente o líquido e o imposto. A resposta inclui `hasTaxIncludedPrices` para indicar o regime usado.
Como actualizar Se enviava preço sem IVA em `retailPrice`, passe a enviar o preço com IVA. Confirme os totais com `hasTaxIncludedPrices` na resposta. |
| Faturação | Breaking | Validação fiscal mais estrita O novo motor fiscal recusa pedidos que antes eram aceites: validação de NIF (incluindo VIES para clientes da UE), regras de fatura simplificada, notas de crédito/débito (PT/AO) e conta corrente. Mecanismos de pagamento permitidos na criação: apenas NU, CC, CD e OU. TB, CH, MB e MW são rejeitados mesmo que estejam ativos na base. Naturezas não suportadas devolvem `DocumentType.NotSupported`.
Como actualizar Valide NIF e limites de fatura simplificada antes do POST. Use apenas mecanismos NU/CC/CD/OU. Para conta corrente não misture com pagamentos imediatos e não use CC em FR. Em caso de `DocumentType.NotSupported`, confirmar a natureza no sandbox ou com o R&D. |
| Faturação | Adição | PDF do documento Novo endpoint de PDF do documento. Devolve `application/pdf`. Query opcional `layout=Slip|Standard` (talão vs A4/A5). 400 se o layout for inválido; 404 `Document.NotFound` se o documento não existir. |
| Faturação | Adição | Dados de impressão estruturados Dados de impressão estruturados para o integrador renderizar o documento: cabeçalho fiscal (atcud, qrCode, fiscalData), entidade, linhas, impostos, pagamentos (incluindo `isChange` para troco) e contagens de impressão. |
| Faturação | Adição | Registo de impressão com Idempotency-Key Regista uma impressão e incrementa o contador de cópias. Resposta `{ numberCopies }`. O cabeçalho `Idempotency-Key` é obrigatório (400 sem ele). A mesma key não incrementa duas vezes. |
| Faturação | Adição | Próximo número de documento Devolve o próximo número sugerido `{ number, createDate }` sem reservar o contador.
|
| Faturação | Adição | Documentos temporários Documentos temporários (venda suspensa): criar, listar, obter, verificar existência e eliminar. É um parking de dados sem validação fiscal — não gera documento nem número de série. Endpoints: `POST/GET /temp-documents`, `GET /has`, `GET/DELETE /{id}`. |
| Faturação | Alteração | Filtros serieId e excludeFullyConverted A listagem aceita `serieId` e `excludeFullyConverted`. Cada documento inclui `documentIdentifier` (ex.: FT FAC1/7223). |
| Faturação | Alteração | documentIdentifier, entityBalance e ATCUD O cabeçalho passou a expor `documentIdentifier` e `entityBalance` (saldo da conta corrente). O ATCUD é carimbado no documento (`atcud`). A numeração tem bloqueio por terminal com verificação de integridade (PT/AO) e libertação automática do número em caso de falha. |
| Faturação | Adição | Menus e conversão de documentos Suporte a menus/produtos compostos: a linha do menu leva um `guid`; cada componente é uma linha com `parentGuid` e `relationType`. Conversão entre documentos: `originBodyGuid` + `relationType` ligam linhas ao documento de origem (encomenda → fatura). |