Guia de Utilização da API de Facturação

Versão da API: v1.0 Microserviço: XDPeople.Soba.Invoice.WebAPI

Visão geral

A API de Facturação gere o ciclo de vida de documentos de venda e de compra.

Fluxo	Endpoint de criação	Entidade
Vendas	`POST /gateway/invoice/invoices`	Cliente (opcional → NIF / consumidor final)
Compras	`POST /gateway/invoice/purchases`	Fornecedor (`entityKeyId` e/ou `entityVat`)

Após criar, consulte o documento com GET /gateway/invoice/invoices/{id}. Nas linhas de compra use taxIncludedUnitPrice / netUnitPrice. Detalhes: Guia de Compras.

Naturezas de venda suportadas

Natureza	Código	Guia dedicado
Fatura	FT	Guia de Faturas
Fatura simplificada	FS	Guia de Faturas
Fatura-recibo	FR	Guia de Faturas-Recibo
Nota de crédito	NC	Guia de Notas de Crédito
Nota de débito	ND	Guia de Notas de Débito
Encomenda	NE	Guia de Encomendas
Orçamento	ORC	Guia de Orçamentos
Fatura proforma	FPF	—
Documento interno	DI	—
Guias de transporte	GT, GR, GA, GC, GD	Guias de Transporte

Documento interno (DI)

O DI é emitido via POST /gateway/invoice/invoices. O tipo de entidade é configurável no tipo de documento (defaultEntityType): a entidade do pedido tem de pertencer a esse tipo (ou a qualquer tipo, quando configurado como todos). Um desalinhamento devolve Entity.TypeMismatch.

Naturezas de compra suportadas

Natureza	Código	Guia dedicado
Factura / simplificada / factura-recibo de compra	FTF, FSF, FRF	Guia de Compras
Encomenda / orçamento de compra	NEF, ORF	Guia de Compras
Documento interno de compra / outras guias	FFF, DIF, GRF, GTF, GAF, GCF	Guia de Compras

Naturezas como NCF, NDF, GDF, NGT, FCF e VDF não são emitíveis via POST /gateway/invoice/purchases nesta versão. Detalhes: Guia de Compras.

Mecanismos de pagamento permitidos

Qualquer entrada em payments[] deve usar um tipo de pagamento cujo mecanismo (paymentMechanism) pertença à lista abaixo. Esta restrição aplica-se a todos os documentos, independentemente de os pagamentos serem obrigatórios ou opcionais. No pedido envia-se paymentTypeId.

Código	Descrição	Vendas	Compras	`paymentBankDetail`
`NU`	Numerário	✅	✅	Não permitido
`CC`	Cartão de crédito	✅	✅	Não permitido
`CD`	Cartão de débito	✅	✅	Não permitido
`OU`	Outros	✅	✅	Não permitido
`CS`	Crédito / conta de fornecedor	—	✅	Não permitido
`TB`	Transferência bancária	✅	✅	Obrigatório (`accountNumber`)
`CH`	Cheque	✅	✅	Obrigatório (`checkSequenceNumber`)

Obtenha os identificadores válidos com GET /gateway/payment-types e seleccione registos cujo paymentMechanism corresponda a um dos códigos acima.

Validação

A API valida o mecanismo de cada entrada em payments[] na criação do documento. Tipos de pagamento com outros mecanismos (por exemplo MB, MW) são rejeitados, mesmo que estejam activos na base de dados do cliente.

Detalhes de transferência e cheque

Cada entrada em payments[] cujo tipo usa o mecanismo TB ou CH tem de incluir paymentBankDetail. O objecto não é permitido em NU, OU, CC, CD ou CS (incluindo linhas de troco). O motor copia o amount do pagamento para o detalhe bancário persistido; não envie um montante separado dentro de paymentBankDetail.

{
  "payments": [
    {
      "paymentTypeId": 12,
      "amount": 150.00,
      "paymentBankDetail": {
        "accountNumber": "PT50000700000000000000000",
        "bankKeyId": "CGD",
        "bankDescription": "Caixa Geral de Depósitos",
        "businessAccountId": 0,
        "observation": "Liquidação da fatura"
      }
    }
  ]
}

Exemplo de cheque:

{
  "paymentTypeId": 8,
  "amount": 150.00,
  "paymentBankDetail": {
    "checkSequenceNumber": "CHK-001234",
    "bankKeyId": "BPI",
    "bankDescription": "Banco BPI",
    "deferredDate": "2026-09-15T00:00:00",
    "businessAccountId": 0
  }
}

Campo	TB	CH	Notas
`accountNumber`	Obrigatório	Opcional	Máximo 255 caracteres
`checkSequenceNumber`	Opcional	Obrigatório	Máximo 255 caracteres
`bankKeyId`	Opcional	Opcional	Máximo 25 caracteres
`bankDescription`	Opcional	Opcional	Máximo 255 caracteres
`deferredDate`	Opcional	Opcional	Data de vencimento do cheque, quando aplicável. Valores omitidos são gravados como `1900-01-01`
`businessAccountId`	Opcional	Opcional	`0` = nenhum. Valores maiores que `0` têm de existir nas contas da empresa do cliente
`observation`	Opcional	Opcional	Máximo 255 caracteres

payments[].paymentBankDetail.businessAccountId não é a caixa escolhida no cabeçalho do documento (businessAccountId na raiz do pedido).

Regras de tipo de pagamento com conta-corrente

Pagamentos de conta-corrente suportados

A criação de documentos via POST /gateway/invoice/invoices aceita tipos de pagamento com SendToCheckingAccount = true. Quando usados, o motor lança o documento na conta-corrente. Um documento tem de ser liquidado integralmente com pagamentos imediatos ou lançado integralmente na conta-corrente — os dois não podem ser misturados. Documentos fatura-recibo (FR) não podem usar pagamentos de conta-corrente.

Quando o tipo de documento tem requisitos de conta-corrente, o tipo de pagamento fornecido em payments[] tem de os satisfazer. Caso contrário, a entrada de pagamento é rejeitada:

Configuração do tipo de documento	Erro
`MoveSetting = CheckingAccount` e o tipo de pagamento não lança em conta-corrente	`Payment.CheckingAccountType.RequiredForMoveSetting`
Modo de pagamento com `IncrementDays > 0` e o tipo não é de conta-corrente	`Payment.CheckingAccountType.RequiredForDeferredMode`
`CheckingAccountFlow != 0` e o tipo de pagamento não é de conta-corrente	`Payment.CheckingAccountType.RequiredForDocumentFlow`
Pagamento de conta-corrente misturado com pagamentos imediatos no mesmo documento	`Payment.CheckingAccount.CannotMixWithImmediatePayments`
Pagamento de conta-corrente numa fatura-recibo (FR)	`Payment.CheckingAccount.NotAllowedForInvoiceReceipt`
Pagamento de conta-corrente ou diferido sem cliente identificado	`Payment.CheckingAccount.CustomerRequired`

Os recibos (RE) e os pagamentos a fornecedores (PF) emitem-se pela Core API. Consulte o Guia de Recibos e Pagamentos a Fornecedores.

Outras naturezas (CAS, DIS, etc.) não estão disponíveis nesta API e devolvem DocumentType.NotSupported.

Características principais

Criação de documentos de ponta a ponta (validação, totais, pagamentos, persistência)
Criação, atualização e consulta (formatos flat e completo)
Filtros avançados e paginação
Autenticação JWT
Persistência de datas com fuso horário via header X-Timezone

Como funciona a criação de documentos

Quando chama POST /gateway/invoice/invoices, a API:

Validação inicial — natureza suportada, país/licença, mecanismos de pagamento, série, cliente, regras de emissão
Preparação do cabeçalho — resolução de entidade, defaults de transporte, validações fiscais
Cálculos — totais de linha e cabeçalho, impostos, descontos
Pagamentos — multi-pagamento, troco; para tipos com pagamentos opcionais, no máximo uma entrada sem multi-pagamento nem troco
Finalização — ATCUD, assinatura digital, observações legais
Persistência transacional — cabeçalho, linhas, referências, stock, contadores

Movimento de stock

A movimentação de stock segue a configuração do tipo de documento e do artigo.

Informações técnicas

URL base

Ambiente	URL base	Documentação
Produção	`https://api.xdsoba.com/gateway`	Swagger UI

Headers de pedido

Header	Obrigatório	Descrição
`Authorization`	Sim	`Bearer {jwt}`
`Content-Type`	Sim (POST/PUT)	`application/json`
`X-Timezone`	Recomendado	Fuso IANA (ex.: `Europe/Lisbon`). Datas persistidas no fuso local configurado.

Health checks

GET /gateway/invoice/health

Autenticação

POST https://api.xdsoba.com/gateway/auth/combined-login
Content-Type: application/json

{
 "tenantKey": "XDPT.30010",
 "tenantPassword": "your-tenant-password",
 "userKey": "user@example.com",
 "userPassword": "your-user-password"
}

Utilize o token em todos os pedidos:

Authorization: Bearer {token}
X-Timezone: Europe/Lisbon

Resolução dos IDs de tipo de documento

O documentTypeId numérico não é portável entre bases de dados de clientes. Obtenha-o com:

GET /gateway/document-type
Authorization: Bearer {token}

Use o id de cada linha como documentTypeId. Escolha a linha cuja description / keyId corresponda ao processo (orçamento, encomenda, fatura, nota de crédito, etc.).

dica

Chame GET /gateway/document-type antes dos testes de integração. Substitua IDs ilustrativos dos guias pelos valores devolvidos por GET /gateway/document-type.

Ver Criar tipos de documento (API Base) se faltar um tipo de documento.

Criar tipos de documento (API Base)

POST /gateway/document-type
Content-Type: application/json
Authorization: Bearer {token}

{
  "keyId": "ORC",
  "description": "Orçamento",
  "documentType": 0,
  "invoiceType": "ORC",
  "entityType": 0,
  "checkingAccountFlow": 0,
  "stockFlow": 0,
  "stockBehaviour": 0,
  "cashierFlow": 0,
  "defaultEntityType": 0,
  "printSystemType": 0,
  "instances": 1,
  "isValued": true,
  "voucherExpirationDays": 0,
  "voucherDeductibleAfter": 0,
  "isAdvancement": false,
  "forceAskBatches": false,
  "defaultAccountId": 0,
  "reportLayout": "",
  "htmlLayout": ""
}

Endpoints disponíveis

Criar documento

POST /gateway/invoice/invoices
Content-Type: application/json
Authorization: Bearer {token}
X-Timezone: Europe/Lisbon

Cria um documento de venda (natureza definida por documentTypeId).

Atualizar documento

PUT /gateway/invoice/invoices/{id}

Obter documento por ID

GET /gateway/invoice/invoices/{id}
GET /gateway/invoice/invoices/{id}/flat

/flat — formato plano retrocompatível
Sem /flat — cabeçalho com corpos do documento
A resposta estruturada do cabeçalho inclui entityBalance: o saldo atual da conta corrente da entidade (valor em tempo real, não histórico). É null quando a chave da entidade está em falta ou o saldo não pode ser resolvido.

Obter por tipo, série e número

GET /gateway/invoice/invoices/{documentTypeId}/{serieId}/{number}
GET /gateway/invoice/invoices/{documentTypeId}/{serieId}/{number}/flat

A resposta estruturada (não flat) também inclui entityBalance no cabeçalho do documento, com o mesmo significado acima.

Listar documentos

GET /gateway/invoice/invoices?page=1&pageSize=20&status=Open&startDate=2025-01-01&endDate=2025-12-31
Authorization: Bearer {token}

Parâmetro	Descrição
`page`	Número da página (predefinido: 1)
`pageSize`	Tamanho da página (predefinido: 20)
`status`	`Open` / `Closed`
`startDate`	Documentos criados a partir desta data
`endDate`	Documentos criados até esta data
`entityKeyId`	Filtrar por cliente/fornecedor
`documentTypeId`	Filtrar por tipo de documento
`sortBy`	`CreationDate`, `DocumentNumber`, `Total`, `EntityDescription`
`sortDescending`	Ordem decrescente (predefinido: false)

Modelo de dados (criar documento)

Campos obrigatórios

{
  "serieId": 1,
  "documentTypeId": 5,
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 2,
      "retailPrice": 50,
      "taxId": 1,
      "secondTaxId": 0
    }
  ],
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 123
    }
  ]
}

Campo	Notas
`payments`	Obrigatório quando o tipo de documento tem fluxo de caixa ou fluxo de conta-corrente activo. Opcional quando nenhum fluxo se aplica — omitir ou fornecer no máximo uma entrada igual ao total do documento. As guias de transporte (GT…GD), encomendas (NE), orçamentos (ORC), proforma (FPF) e documentos internos (DI) são tipicamente configurados sem nenhum dos fluxos.
`payments[].paymentBankDetail`	Obrigatório quando o mecanismo do tipo de pagamento é `TB` ou `CH`. Deve ser omitido para `NU`, `OU`, `CC`, `CD` e `CS`. Ver Detalhes de transferência e cheque.
`discountPercentage`	Desconto de cabeçalho opcional (0–100). Por linha: `documentBodies[].discountPercentage`.
`allowCreditLimitOverride`	Opcional (`false` por defeito). Defina como `true` apenas quando um administrador confirma deliberadamente ultrapassar um limite de crédito de cliente excedido. Ignorado para utilizadores não administradores. Quando `false` e o limite é excedido, a API devolve um erro de validação com `canOverride=true` em `furtherInformations` para que um chamador autorizado possa reenviar. Ver Crédito de cliente.

Moeda

Não envie currencyId. A moeda do documento é resolvida a partir da configuração do terminal e do sistema — não é um campo por pedido.

Armazéns

Campos de armazém por linha em cada entrada de documentBodies[]:

Campo Notas

originWarehouse Opcional. Quando é 0 ou omitido: em linhas referenciadas (NC/ND) usa o armazém da linha de origem, salvo se for indicado um valor específico; nos restantes casos é resolvido a partir do armazém por defeito do documento no terminal (WarehouseId), com fallback para o armazém global do terminal (DefaultWarehouseId). Enviar 0 já não persiste como 0 — é resolvido para o armazém configurado.

destinationWarehouse Aplicável apenas a guias de transporte (GT, GR, GA, GC, GD). Ignorado (forçado a 0) nos restantes tipos de documento e em linhas referenciadas (NC/ND).

Campo	Notas
`originWarehouse`	Opcional. Quando é `0` ou omitido: em linhas referenciadas (NC/ND) usa o armazém da linha de origem, salvo se for indicado um valor específico; nos restantes casos é resolvido a partir do armazém por defeito do documento no terminal (`WarehouseId`), com fallback para o armazém global do terminal (`DefaultWarehouseId`). Enviar `0` já não persiste como `0` — é resolvido para o armazém configurado.
`destinationWarehouse`	Aplicável apenas a guias de transporte (GT, GR, GA, GC, GD). Ignorado (forçado a `0`) nos restantes tipos de documento e em linhas referenciadas (NC/ND).

IDs de armazém desconhecidos são rejeitados com erro de não encontrado antes da construção do documento.

Resolução de entidade (cliente)

entityKeyId é opcional. Ao resolver a entidade, a API segue esta ordem:

entityKeyId fornecido — a entidade é carregada directamente pela chave. Se não for encontrada, o pedido falha imediatamente com Entity.KeyId.NotFound (404). Não é feito qualquer fallback.
entityKeyId omitido, entityVat fornecido — é feita uma pesquisa por NIF. Se for encontrada uma correspondência, essa entidade é utilizada. Se não, é criado um registo temporário com os campos de substituição fornecidos (entityDescription, entityAddress, etc.) e a chave do consumidor final.
Ambos omitidos — o consumidor final por omissão configurado é carregado da base de dados.

cuidado

Fornecer um entityKeyId inexistente é um erro definitivo (404). O campo entityVat é ignorado nesse caso — corrija ou omita o entityKeyId primeiro.

Campos opcionais comuns

{
  "entityDescription": "Cliente Exemplo, Lda",
  "entityVat": "PT123456789",
  "entityAddress": "Rua Exemplo, 123",
  "entityPostalCode": "1000-000",
  "entityCity": "Lisboa",
  "entityCountry": "Portugal",
  "documentDate": "2025-11-28T10:00:00Z",
  "dueDate": "2025-12-31",
  "paymentModeId": 1,
  "obs": "Observações",
  "docReference": "2;1;2026-06-05;FAC;;FAC;",
  "extraDocReference": "REF-EXTRA",
  "emissionReason": "Devolução de mercadoria",
  "loadPlaceDescription": "Armazém Central;Lisboa;1000-100;PT",
  "unloadPlaceDescription": "Loja Cliente;Porto;4000-000;PT",
  "loadPlaceDate": "2025-11-28T10:00:00",
  "unloadPlaceDate": "2025-11-28T15:00:00",
  "carrierDescription": "Transportadora XYZ",
  "taxRegionId": 1,
  "numberPersons": 2
}

Campos de local de carga e descarga

Campo	Descrição
`loadPlaceDescription`	Local de origem / carga (máx. 100 chars)
`unloadPlaceDescription`	Local de destino / descarga (máx. 100 chars)
`loadPlaceDate`	Data e hora de carga (`date-time`)
`unloadPlaceDate`	Data e hora de descarga (`date-time`)
`carrierDescription`	Nome ou descrição do transportador (máx. 100 chars)

Local de carga (`loadPlaceDescription`)

Quando omitido, o motor resolve um valor por omissão nesta ordem:

Valor fornecido pelo caller — utilizado tal como está.
LoadUnloadPlace associado ao armazém por defeito do terminal (formato estruturado).
Morada da licença (formato estruturado).
Nome fiscal / nome comercial da licença como fallback.

Local de descarga (`unloadPlaceDescription`)

Quando omitido, o motor resolve nesta ordem:

Valor fornecido pelo caller — utilizado tal como está.
EntityAddress do cliente marcado com DefaultShipmentAddress = true (formato estruturado).

Formato estruturado de endereço

O formato esperado é "morada;cidade;codigoPostal;pais" — quatro segmentos separados por ponto e vírgula. Quando o campo está presente na requisição, deve seguir este mesmo formato. Quando omitido e resolvido automaticamente pelo motor, os endereços com múltiplas partes são formatados da mesma forma.

Datas

Quando loadPlaceDate ou unloadPlaceDate são omitidos:

Data	Valor por omissão
`loadPlaceDate`	Hora de criação + 15 minutos (ou `LoadDateAdditionMinutes` quando configurado)
`unloadPlaceDate`	Final do dia seguinte às 23:59

LoadDateAdditionMinutes é um valor de configuração do sistema (XConfigMisc). Quando não configurado, são usados 15 minutos.

Ignorado em FS, NC e ND

loadPlaceDescription, unloadPlaceDescription e campos de local de carga e descarga são ignorados em faturas simplificadas (FS), notas de crédito (NC) e notas de débito (ND). Não dependa deles nessas naturezas.

Linhas com referência (NC/ND)

Em cada linha referenciada, apenas originBodyGuid, relationType e quantity são obrigatórios. A API deriva itemKeyId, taxId, retailPrice, netPrice e originWarehouse da linha de origem quando omitidos:

{
  "quantity": 1,
  "originBodyGuid": "660e8400-e29b-41d4-a716-446655440001",
  "relationType": 1
}

Obtenha originBodyGuid via GET /gateway/invoice/invoices/{documentTypeId}/{serieId}/{number}/flat (campo guid em cada linha).
relationType: 1 = ReferenceOrigin (obrigatório para NC/ND).
Quantidades positivas; a natureza do documento define o sentido crédito/débito.
Para substituir preços (ex. correcção de valor), forneça retailPrice / netPrice explicitamente. Em documentos angolanos, os preços devem corresponder a totalAmount / quantity da origem — consulte os guias dedicados para detalhes.

Para a referência completa de campos, regras de campos derivados e restrições específicas de Angola, consulte o Guia de Notas de Crédito e o Guia de Notas de Débito.

Linhas pai-filho (`guid` / `parentGuid`)

Menu e artigo composto são conceitos distintos no catálogo (ver abaixo). Quando envia linhas filho, ambos usam os mesmos campos de ligação no payload:

Campo	Onde	Descrição
`guid`	Apenas na linha pai	UUID gerado pelo cliente que identifica a linha pai no pedido
`parentGuid`	Linhas filho	Deve ser igual ao `guid` da linha pai

Regras comuns:

Um nível apenas — linhas filho não podem ter filhos.
Linhas com parentGuid são tratadas como informativas e excluídas do total fiscal; o valor de venda fica na linha pai.
Gere um UUID novo para cada linha pai em cada pedido.

Um menu é um artigo de tipo Menu no catálogo. O cliente ou operador escolhe opções definidas na composição do menu (ex.: entrada, prato principal, acompanhamento). Cada opção seleccionada vai numa linha filho.

O itemKeyId da linha pai deve ser o artigo menu. Os itemKeyId das linhas filho são as opções escolhidas.

Exemplo: Documento com menu.

Artigo composto

Um artigo composto é um artigo de tipo Composite no catálogo — um kit ou produto acabado com componentes definidos no detalhe de composição.

Ao contrário do menu, não é necessário enviar os artigos componentes em documentBodies. Basta uma linha com o itemKeyId do composto — o mesmo formato de um artigo normal (sem guid / parentGuid).

Opcionalmente, pode incluir linhas filho com parentGuid se quiser os componentes listados explicitamente no documento (quantidades e preços seguem a detalhe de composição do artigo).

Exemplo: Documento com artigo composto.

Exemplos de utilização

Fatura simples com pagamento

POST /gateway/invoice/invoices
Content-Type: application/json
Authorization: Bearer {token}
X-Timezone: Europe/Lisbon

{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "entityDescription": "Cliente Exemplo, Lda",
  "entityVat": "PT123456789",
  "paymentModeId": 1,
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 123
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "itemDescription": "Produto 1",
      "quantity": 2,
      "retailPrice": 50,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

A resposta 201 Created inclui documentNumber, total, totalTaxes, change / netChange (quando aplicável), guid, customerBalance (saldo da conta após a emissão, quando disponível) e warnings (alertas não bloqueantes, como limiar de crédito / override de administrador).

Multi-pagamento

{
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 50
    },
    {
      "paymentTypeId": 3,
      "amount": 73
    }
  ]
}

A soma dos amount deve corresponder ao total entregue. O troco é calculado automaticamente quando o tipo de pagamento o permite.

Utilize ao vender um artigo menu: linha pai com guid (o menu) e linhas filho com parentGuid (opções seleccionadas). Os itemKeyId, preços e total de pagamento são ilustrativos — obtenha valores reais via API.

POST /gateway/invoice/invoices
Content-Type: application/json
Authorization: Bearer {token}
X-Timezone: Europe/Lisbon

{
  "serieId": 1,
  "documentTypeId": 1,
  "entityKeyId": "1",
  "entityVat": "555666777",
  "obs": "Observações do documento.",
  "saleZoneAreaObjectId": 1,
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 1140
    }
  ],
  "documentBodies": [
    {
      "guid": "06a646ac-1101-4252-8fd9-20c7173ded78",
      "itemKeyId": "353",
      "quantity": 1,
      "retailPrice": 10,
      "taxId": 1
    },
    {
      "parentGuid": "06a646ac-1101-4252-8fd9-20c7173ded78",
      "itemKeyId": "366",
      "quantity": 1,
      "retailPrice": 0,
      "taxId": 1
    },
    {
      "parentGuid": "06a646ac-1101-4252-8fd9-20c7173ded78",
      "itemKeyId": "354",
      "quantity": 1,
      "retailPrice": 0,
      "taxId": 1
    }
  ]
}

O artigo 353 é o menu; 366 e 354 são as opções seleccionadas. A soma de payments[].amount deve corresponder ao total calculado pela API.

Documento com artigo composto

Utilize ao vender um artigo composto. Envie apenas a linha do composto — os artigos componentes do detalhe de composição não precisam de ir no pedido.

POST /gateway/invoice/invoices
Content-Type: application/json
Authorization: Bearer {token}
X-Timezone: Europe/Lisbon

{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 49.9
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "KIT001",
      "quantity": 1,
      "retailPrice": 49.9,
      "taxId": 1
    }
  ]
}

O artigo KIT001 deve ser de tipo Composite no catálogo. A API resolve os componentes a partir do detalhe de composição do artigo — não envie COMP-A, COMP-B ou semelhantes, excepto se quiser explicitamente linhas filho informativas no documento impresso.

Listar documentos abertos

GET /gateway/invoice/invoices?status=Open&page=1&pageSize=20
Authorization: Bearer {token}

Tratamento de erros

Código	Quando
`201 Created`	Documento criado
`200 OK`	Actualização ou consulta com sucesso
`400 Bad Request`	Validação falhou
`401 Unauthorized`	Token em falta/inválido
`404 Not Found`	Documento não encontrado
`409 Conflict`	Conflito de concorrência
`500 Internal Server Error`	Erro inesperado

Códigos comuns: DocumentType.NotSupported, Payment.InsufficientValue, SaleDocumentRules.NCND.*, DocumentReferenceBalance.*.

Boas práticas

Enviar sempre X-Timezone para datas locais correctas
Resolver documentTypeId com GET /gateway/document-type — não copiar IDs dos exemplos
Usar payments[] no cabeçalho nos documentos que exigem pagamento
NC/ND: indicar emissionReason; referências por GUID nas linhas para origens no Soba (PT/AO)
Menus: enviar opções seleccionadas como linhas filho com guid / parentGuid — ver exemplo de menu
Artigos compostos: basta uma linha com o itemKeyId do composto — ver exemplo de artigo composto

Guias especializados

Guia	Tópico
Orçamentos	ORC
Encomendas	NE
Faturas	FT, FS
Faturas-Recibo	FR
Notas de Crédito	NC
Notas de Débito	ND
Guias de Transporte	GT, GR, GA, GC, GD
Recibos e Pagamentos a Fornecedores	RE / PF (Core API)

Última actualização: 7 de julho de 2026

Visão geral​

Naturezas de venda suportadas​

Naturezas de compra suportadas​

Mecanismos de pagamento permitidos​

Detalhes de transferência e cheque​

Regras de tipo de pagamento com conta-corrente​

Características principais​

Como funciona a criação de documentos​

Informações técnicas​

URL base​

Headers de pedido​

Health checks​

Autenticação​

Resolução dos IDs de tipo de documento​

Criar tipos de documento (API Base)​

Endpoints disponíveis​

Criar documento​

Atualizar documento​

Obter documento por ID​

Obter por tipo, série e número​

Listar documentos​

Modelo de dados (criar documento)​

Campos obrigatórios​

Armazéns​

Resolução de entidade (cliente)​

Campos opcionais comuns​

Campos de local de carga e descarga​

Local de carga (loadPlaceDescription)​

Local de descarga (unloadPlaceDescription)​

Datas​

Linhas com referência (NC/ND)​

Linhas pai-filho (guid / parentGuid)​

Menu​

Artigo composto​

Exemplos de utilização​

Fatura simples com pagamento​

Multi-pagamento​

Documento com menu​

Documento com artigo composto​

Listar documentos abertos​

Tratamento de erros​

Boas práticas​

Guias especializados​