Invoice API
Alterações publicadas na Invoice API.
16 de setembro de 2026
| Área | Tipo | Descrição |
|---|---|---|
| Compras | Adição | Emissão de documentos de compra a fornecedor Novo endpoint `POST /gateway/invoice/purchases` para emitir documentos de compra a fornecedor. Preços de linha: `taxIncludedUnitPrice` / `netUnitPrice`. Naturezas suportadas nesta versão: FTF, FSF, FRF, NEF, ORF, FFF, DIF, GRF, GTF, GAF e GCF. Ainda não disponíveis neste endpoint: NCF, NDF, GDF, NGT, FCF (nem VDF ou outras naturezas fora desta lista). Pagamentos: NU, OU, CC, CD, CS, TB e CH. TB e CH continuam a exigir `payments[].paymentBankDetail`. Quando o tipo de documento não tem fluxo de caixa nem de conta-corrente activos, `payments` pode ser omitido (típico em documentos de trabalho e guias). Nas linhas, o preço segue: valor explícito no pedido → catálogo do fornecedor → custo do artigo. Artigos com custo fixo ignoram o catálogo. Campo opcional de linha `supplierItemId` para a referência do artigo no fornecedor; se omitido, a API resolve a partir do catálogo. Após a emissão, a API actualiza o catálogo fornecedor/artigo e o histórico de custos quando aplicável. Entre as naturezas aceites, apenas FTF, FRF e FSF podem actualizar o preço líquido de compra global do artigo. Erros específicos: `Purchase.DocumentType.Required`, `Purchase.DocumentNature.NotSupported`, `Purchase.Supplier.Required`, `Purchase.Supplier.Invalid`, `Purchase.ItemSync.Failed`. A resposta `201` inclui `Location` para `GET /gateway/invoice/invoices/{id}`. |
| Faturação | Adição | Emissão de Documento Interno (DI) `POST /gateway/invoice/invoices` passa a aceitar a natureza DI (Documento Interno). O tipo de entidade é configurável no tipo de documento (`defaultEntityType`). Se a entidade do pedido não corresponder, a API devolve `Entity.TypeMismatch`. Os pagamentos são opcionais quando o tipo não tem fluxo de caixa nem de conta-corrente (como ORC, NE e FPF). A natureza equivalente de compra DIF continua disponível em `POST /gateway/invoice/purchases`. |
| Faturação | Adição | Transferência bancária e cheque A criação de documentos aceita os mecanismos TB (transferência bancária) e CH (cheque), além de NU, OU, CC e CD. Pagamentos TB e CH exigem o objecto `payments[].paymentBankDetail` (`accountNumber` em TB; `checkSequenceNumber` em CH). Nos outros mecanismos o objecto é rejeitado. `paymentBankDetail.businessAccountId` com valor `0` significa nenhuma conta; valores maiores têm de existir. |
| Faturação | Alteração | Persistência do ATCUD só com o código da série O ATCUD passou a ser persistido apenas com o código de validação da série AT (ex.: `AAAA7C8`) em `DocumentsHeaders.ATCUD`. Gravar o valor completo (`AAAA7C8-4559`) estava incorrecto. Nas consultas, `atcud` é o valor de apresentação (`código-número`, ex.: `AAAA7C8-4559`), alinhado entre listagem, GET por id e GET por tipo/série/número. Antes, a concatenação na emissão/formatação duplicava o número (`AAAA7C8-4559-4559`) no QR (campo H) e na exibição; e os GET por id e por tipo/série/número devolviam só o código da série enquanto a listagem já devolveva o ATCUD completo. Aplica-se às naturezas elegíveis para ATCUD em licença portuguesa (não demo): FT, FS, FR, ND, NC, ORC, NE, GT, GR e restantes documentos suportados pela Invoice API elegíveis para ATCUD em licença portuguesa (não demo). Registos já emitidos com o ATCUD completo na BD estão incorrectos nesse campo; a formatação é idempotente para esses casos não quebrarem nem duplicarem o número na API, no QR e na impressão. Também alinhado: `GET /gateway/invoice/invoices/{id}/flat`, `GET /gateway/invoice/invoices/{documentTypeId}/{serieId}/{number}` e o equivalente `/flat`. |
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` nas linhas apenas para menus; `originBodyGuid` / `relationType` apenas em notas de crédito/débito. |
| 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 produtos compostos Suporte a menus/produtos compostos: a linha do menu leva um `guid`; cada componente é uma linha com `parentGuid` a apontar para esse `guid`. As linhas componentes são informativas e ficam fora do total fiscal. |