API de Facturação — Referência de Erros

Todos os erros devolvidos pela API de Facturação seguem um envelope consistente:

{
    "status": 400,
    "title": "Bad Request",
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "errors": [
        {
            "code": "Payment.InsufficientValue",
            "description": "Delivered value (0.00) is less than the amount to pay (100.00).",
            "type": 1,
            "furtherInformations": {
                "deliveredValue": 0.0,
                "totalToPay": 100.0
            }
        }
    ]
}

Os erros estão agrupados por categoria. Salvo indicação contrária, todos os erros de validação mapeiam para HTTP 400 Bad Request; os erros de infra-estrutura mapeiam para HTTP 500 Internal Server Error.

Tipo de Documento

Código	HTTP	Condição	Resolução
`DocumentType.NotSupported`	400	A natureza de facturação do tipo de documento não é suportada pelo motor (ex.: recibo RE, ou natureza desconhecida).	Utilize um tipo de documento suportado — ver Tipos de Documento.
`DocumentType.InactiveOrMissing`	400	O `documentTypeId` refere-se a um tipo de documento inactivo ou inexistente.	Confirme que o tipo de documento está activo no back-office.
`DocumentType.NotFound`	404	Nenhum tipo de documento encontrado com o `documentTypeId` fornecido.	Forneça um `documentTypeId` válido.
`DocumentSeries.NotFound`	404	Nenhuma série encontrada com o `serieId` fornecido.	Forneça um `serieId` válido.
`DocumentSeries.InactiveOrMissing`	400	O `serieId` refere-se a uma série inactiva ou inexistente.	Confirme que a série está activa no back-office.

Pagamento

Código	HTTP	Condição	Resolução
`Payment.InsufficientValue`	400	O valor total entregue é inferior ao total do documento.	Aumente o valor entregue ou adicione entradas de pagamento adicionais para cobrir o total.
`Payment.DeliveredMustMatchTotal`	400	O tipo de documento exige correspondência exacta entre o valor entregue e o total (sem troco nem pagamento parcial).	Garanta que o `amount` da entrada de pagamento coincide exactamente com o total do documento.
`Payment.MultipleEntriesNotAllowed`	400	Foi fornecida mais de uma entrada de pagamento num tipo de documento com pagamentos opcionais (sem fluxo de caixa nem de conta-corrente activo).	Forneça no máximo uma entrada de pagamento.
`Payment.MechanismNotAllowed`	400	Uma entrada de pagamento usa um mecanismo (NU, OU, CC, CD) não permitido pela configuração do tipo de documento.	Use apenas os mecanismos listados no campo `allowedMechanisms` do erro.
`Payment.ExceedsAmountWithoutChangeAllowed`	400	O valor entregue excede o total do documento e o tipo de pagamento não permite troco.	Use um tipo de pagamento que permita troco, ou reduza o valor entregue para o total.
`Payment.CheckingAccountType.RequiredForMoveSetting`	400	O tipo de documento está configurado para lançar na conta-corrente mas o tipo de pagamento fornecido não.	Use um tipo de pagamento configurado para lançamento em conta-corrente.
`Payment.CheckingAccountType.RequiredForDeferredMode`	400	O modo de pagamento seleccionado tem condições diferidas mas o tipo de pagamento não lança em conta-corrente.	Use um tipo de pagamento com lançamento em conta-corrente, ou escolha um modo de pagamento não diferido.
`Payment.CheckingAccountType.RequiredForDocumentFlow`	400	O fluxo do tipo de documento lança em conta-corrente mas o tipo de pagamento não.	Use um tipo de pagamento configurado para lançamento em conta-corrente.
`Payment.CheckingAccount.NotSupported`	400	Foi fornecido um tipo de pagamento de conta-corrente; esta API suporta apenas pagamentos imediatos.	Use um tipo de pagamento imediato (numerário, cartão, cheque, etc.).
`PaymentType.NotFound`	404	Nenhum tipo de pagamento encontrado com o `paymentTypeId` fornecido.	Forneça um `paymentTypeId` válido.
`PaymentMode.NotFound`	404	Nenhum modo de pagamento encontrado com o `paymentModeId` fornecido.	Forneça um `paymentModeId` válido.

Pagamentos opcionais

payments é opcional quando o tipo de documento não tem fluxo de caixa nem fluxo de conta-corrente activo (CashierFlow = NoAction, CheckingAccountFlow = None). As guias de transporte (GT…GD), encomendas (NE) e orçamentos (ORC) são tipicamente configurados desta forma. Quando opcional, omita payments na totalidade ou inclua no máximo uma entrada cujo amount seja igual ao total do documento.

Cliente / Entidade

Código	HTTP	Condição	Resolução
`Entity.KeyId.NotFound`	404	`entityKeyId` foi fornecido mas não existe nenhuma entidade com essa chave na base de dados.	Corrija o `entityKeyId`, ou omita-o e use `entityVat` para identificar o cliente.
`Customer.Inactive`	400	O cliente resolvido está inactivo.	Reactive o cliente no back-office ou utilize um cliente diferente.
`Customer.ForbiddenDocuments`	400	A conta do cliente está configurada para impedir a emissão de documentos.	Remova a restrição no back-office ou utilize um cliente diferente.
`Entity.Vat.Invalid`	400	O `entityVat` fornecido falhou a validação de NIF para o país configurado.	Corrija o NIF ou omita `entityVat` para usar os dados do consumidor final por omissão.

Artigos e Taxas

Código	HTTP	Condição	Resolução
`Item.NotFound`	404	Uma linha de `documentBodies` referencia um `itemKeyId` que não existe no catálogo.	Verifique os valores de `itemKeyId` nas linhas do corpo.
`Tax.NotFound`	404	Uma linha de `documentBodies` referencia um `taxId` ou `secondTaxId` que não existe.	Forneça identificadores de taxa válidos — resolva-os com `GET /gateway/tax`.

Regras de Documento

Código	Condição	Resolução
`SaleDocumentRules.Transport.MissingPlaces`	Uma guia de transporte foi submetida sem local de carga, ou sem local de descarga (e o tipo de documento não é global).	Preencha `loadPlaceDescription` e `unloadPlaceDescription` (ou garanta que o cliente tem morada para o fallback).
`SaleDocumentRules.FullInfo.RequiredCustomer`	O tipo de documento exige NIF do cliente mas nenhum foi fornecido.	Forneça `entityVat` (ou um `entityKeyId` resolvido cujo registo tenha NIF).
`SaleDocumentRules.FullInfo.CustomerFiscalData`	O tipo de documento exige dados fiscais completos do cliente (nome, morada, NIF).	Garanta que o registo do cliente ou os campos de substituição contêm informação fiscal completa.
`SaleDocumentRules.Nif.RequiredVat`	O valor do documento excede o limiar acima do qual a lei exige NIF.	Forneça um `entityVat` válido.
`SaleDocumentRules.NCND.MissingReferences`	Uma Nota de Crédito (NC) ou Nota de Débito (ND) foi submetida sem referências de documento em `documentBodies`.	Inclua pelo menos uma `documentReference` em cada linha do corpo a apontar para o documento de origem.
`SaleDocumentRules.NCND.MissingEmissionReason`	Uma NC/ND não tem o campo `emissionReason` obrigatório (requerido para PT e AO).	Forneça `emissionReason` no pedido.
`SaleDocumentRules.LimitExceeded`	O total do documento excede o limite por documento configurado no tipo de documento.	Reduza o valor do documento ou aumente o limite na configuração do back-office.
`SaleDocumentRules.FS.AboveLegal`	Uma Fatura Simplificada (FS) foi emitida acima do limite legal definido no Art.º 40 do CIVA.	Emita uma Fatura (FT) em alternativa.

Referências (NC / ND)

Código	Condição	Resolução
`DocumentReference.OriginBodyNotFound`	Uma referência de linha aponta para um GUID de linha de origem que não existe ou foi eliminado.	Verifique os valores `originBodyGuid` via `GET /gateway/invoice/invoices/{id}`.
`DocumentReference.BalanceExceeded`	A quantidade referenciada mais a já referenciada excede a quantidade da linha de origem.	Reduza a quantidade na linha de referência para não ultrapassar o saldo disponível.
`DocumentReference.ItemMismatch`	O `itemKeyId` fornecido não coincide com o artigo da linha de origem.	Omita `itemKeyId` ou envie o mesmo artigo que a origem.
`DocumentReference.PriceMismatch`	Foi fornecido um preço mas difere do preço derivado da origem num documento rectificativo angolano.	Omita `retailPrice`/`netPrice` ou coincida com o preço originalmente facturado.
`DocumentReference.EntityMismatch`	O cliente da NC/ND não coincide com o cliente do documento de origem.	Use o mesmo `entityKeyId` da factura de origem.

Stock

Código	Condição	Resolução
`Stock.InsufficientQuantity`	Uma linha do corpo do documento refere um artigo com stock insuficiente (quando o tipo de documento deduz stock).	Reduza a quantidade, ou reponha o stock antes de emitir o documento. O `itemKeyId` é incluído nos detalhes do erro.

Transacção (500)

Estes erros indicam uma falha ao nível da base de dados durante a persistência do documento. O documento não foi gravado. Reenviar o pedido é seguro.

Código	Condição
`Transaction.Begin.Failed`	Não foi possível abrir a transacção de base de dados.
`Transaction.Commit.Failed`	O pipeline de documento concluiu com sucesso mas o commit final falhou.

Última actualização: 29 de junho de 2026

Tipo de Documento​

Pagamento​

Cliente / Entidade​

Artigos e Taxas​

Regras de Documento​

Referências (NC / ND)​

Stock​

Transacção (500)​