Guia de Recibos e Pagamentos à Fornecedores

Este guia explica como liquidar documentos de clientes e fornecedores através da Core API do XDSoba. O mesmo fluxo suporta recibos de clientes (RE) e pagamentos a fornecedores (PF), incluindo liquidação parcial, vários documentos de origem, múltiplos meios de pagamento, projeção na conta-corrente, movimentos de caixa, consulta, impressão e anulação.

API responsável

Crie recibos de clientes (RE) e pagamentos a fornecedores (PF) através de POST /gateway/receipt-document. A Invoice API cria documentos de venda via POST /gateway/invoice/invoices (incluindo faturas-recibo FR) e documentos de compra via POST /gateway/invoice/purchases. Quando um documento de venda elegível é emitido com pagamento por conta-corrente, a Invoice API regista o respetivo movimento na conta-corrente do cliente. A Invoice API não cria documentos RE nem PF — use este fluxo da Core API para liquidar compras em aberto com PF. Ver o Guia de Compras.

Identificadores específicos de cada ambiente

Os identificadores utilizados neste guia são meramente ilustrativos. Antes de criar um recibo, resolva no tenant os identificadores do tipo documental, série, entidade, colaborador, tipo de pagamento e conta de negócio.

Naturezas suportadas

O tipo documental do recibo determina a entidade, os documentos de origem e a direção do movimento de conta-corrente.

Natureza	Operação	Entidade	Documentos de origem	Efeito do recibo
`RE`	Recibo de cliente	Cliente	Documentos de venda pendentes	Credita a conta-corrente do cliente
`PF`	Pagamento a fornecedor	Fornecedor	Documentos de compra pendentes	Debita a conta-corrente do fornecedor

O endpoint de documentos pendentes normaliza os sinais para a natureza selecionada. Nos dois contextos, as faturas são devolvidas com valor pendente positivo e as notas de crédito com valor negativo. Preserve esse sinal ao enviar paidAmount.

Fluxo de integração recomendado

Comece sempre pela consulta de documentos pendentes. Não construa as linhas do recibo a partir de uma consulta genérica de faturas nem de valores guardados antes do início da operação. O servidor bloqueia e volta a validar os documentos durante a criação, mas a consulta dedicada fornece ao consumidor a elegibilidade, os sinais, a moeda, os valores pendentes e os dados fiscais remanescentes corretos.

1. Consultar documentos pendentes

Ver GET /gateway/receipt-document/pending-documents.

GET /gateway/receipt-document/pending-documents?entityKeyId=CLI001&receiptNature=RE&page=1&pageSize=25
Authorization: Bearer {token}

Para um pagamento a fornecedor, utilize receiptNature=PF e a chave do fornecedor:

GET /gateway/receipt-document/pending-documents?entityKeyId=FOR001&receiptNature=PF&page=1&pageSize=25
Authorization: Bearer {token}

Parâmetros

Parâmetro	Obrigatório	Descrição
`entityKeyId`	Sim	Chave de negócio do cliente ou fornecedor
`receiptNature`	Sim	`RE` para recibo de cliente ou `PF` para pagamento a fornecedor
`search`	Não	Termo de pesquisa documental executado no servidor
`page`	Não	Número da página; quando omitido, aplica-se a regra do servidor
`pageSize`	Não	Número de registos pretendido por página

A resposta utiliza o envelope paginado comum:

{
  "totalCount": 2,
  "pageSize": 25,
  "currentPage": 1,
  "totalPages": 1,
  "data": [
    {
      "idHeader": 1250,
      "documentTypeId": 10,
      "documentTypeKeyId": "FT",
      "documentIdentifier": "FT A/150",
      "invoiceType": "FT",
      "creationDate": "2026-08-01T00:00:00",
      "dueDate": "2026-08-31T00:00:00",
      "daysOverdue": 0,
      "currencyId": 1,
      "currencyKeyId": "EUR",
      "decimalPlaces": 2,
      "currencyRate": 1,
      "total": 100,
      "totalToPay": 80,
      "dueValue": 80,
      "holdingTaxPercentage": 20,
      "remainingHoldingTax": 20,
      "documentGuid": "8d986553-22f4-49f8-ad65-fdf44c0680d1"
    }
  ]
}

daysOverdue é calculado com base na data civil do tenant. Um valor negativo indica que o documento ainda não venceu; um valor positivo indica que se encontra vencido.

Regras de seleção

Utilize idHeader como chave estável da seleção. O valor selecionado deve manter o sinal devolvido pela API e não pode exceder o valor absoluto de dueValue disponível no momento da criação. Todos os documentos selecionados devem pertencer à mesma entidade e utilizar moeda compatível.

Documento de origem	`dueValue` habitual	Regra de `paidAmount`
Fatura de cliente ou fornecedor	Positivo	Positivo e não superior a `dueValue`
Nota de crédito de cliente ou fornecedor	Negativo	Negativo e não superior a `dueValue` em valor absoluto

Uma nota de crédito pode compensar uma ou várias faturas. Um recibo cujo conjunto de documentos resulte num total líquido igual a zero é válido e não exige um pagamento positivo no caixa.

2. Criar um recibo de cliente (`RE`)

Ver POST /gateway/receipt-document.

O endpoint aceita multipart/form-data, uma vez que os detalhes dos pagamentos bancários podem incluir ficheiros de arquivo digital. Os exemplos seguintes mostram a estrutura equivalente em JSON. O exemplo liquida EUR 80 de uma fatura de cliente pendente.

POST /gateway/receipt-document
Authorization: Bearer {token}
Idempotency-Key: 67d99768-a796-45a1-b336-3a452bbc0692
Content-Type: multipart/form-data

{
  "documentTypeId": 30,
  "serieId": 4,
  "creationDate": "2026-08-31T00:00:00",
  "entityKeyId": "CLI001",
  "receiptBodyDetails": [
    { "idHeader": 1250, "paidAmount": 80 }
  ],
  "businessAccountId": 0,
  "accountCategoryId": 0,
  "accountHeadingId": 0,
  "discountValue": 0,
  "discountOnNetAmount": false,
  "otherValues": 0,
  "observation": "Liquidação parcial da FT A/150",
  "employeeId": 12,
  "payments": [
    { "paymentTypeId": 1, "amount": 80 }
  ]
}

Uma resposta com sucesso identifica o recibo persistido e pode incluir avisos não bloqueantes:

{
  "id": 840,
  "warnings": []
}

Os totais da resposta são derivados pelo servidor. Não envie campos calculados antigos, como total pago, total de incidência, percentagem de desconto ou linhas de troco construídas pelo cliente.

3. Criar um pagamento a fornecedor (`PF`)

Os documentos de compra liquidados aqui são tipicamente emitidos primeiro com POST /gateway/invoice/purchases — ver o Guia de Compras.

Ver POST /gateway/receipt-document.

Resolva um tipo documental com natureza PF e uma série válida para esse tipo. Consulte os documentos pendentes do fornecedor com receiptNature=PF e envie os identificadores dos documentos de compra selecionados.

POST /gateway/receipt-document
Authorization: Bearer {token}
Idempotency-Key: f9a4dedc-1f2e-4e52-8213-409fd1fafcd1
Content-Type: multipart/form-data

{
  "documentTypeId": 31,
  "serieId": 5,
  "creationDate": "2026-08-31T00:00:00",
  "entityKeyId": "FOR001",
  "receiptBodyDetails": [
    { "idHeader": 2300, "paidAmount": 250 }
  ],
  "businessAccountId": 0,
  "accountCategoryId": 0,
  "accountHeadingId": 0,
  "discountValue": 0,
  "discountOnNetAmount": false,
  "otherValues": 0,
  "observation": "Pagamento de fatura do fornecedor",
  "employeeId": 12,
  "payments": [
    { "paymentTypeId": 3, "amount": 250 }
  ]
}

O backend confirma que a entidade selecionada é um fornecedor, que o tipo de recibo possui natureza PF e que todos os documentos de origem são documentos de compra elegíveis. Não utilize um tipo de recibo de cliente (RE) para pagar documentos de fornecedor.

Vários documentos e notas de crédito

Adicione uma entrada indexada em receiptBodyDetails por cada documento de origem. O total dos pagamentos deve reconciliar com a liquidação líquida depois de créditos, descontos, outros valores e troco derivado pelo servidor.

{
  "receiptBodyDetails": [
    { "idHeader": 1250, "paidAmount": 100 },
    { "idHeader": 1260, "paidAmount": -20 }
  ],
  "payments": [
    { "paymentTypeId": 1, "amount": 80 }
  ]
}

A mesma regra aplica-se aos pagamentos a fornecedores: as faturas de fornecedor são positivas e as notas de crédito de fornecedor são negativas na resposta de documentos pendentes.

Meios de pagamento e contas de negócio

Cada pagamento contém paymentTypeId e um amount entregue positivo. Os tipos de pagamento configurados para enviar novamente valores para conta-corrente são rejeitados, porque o recibo liquida uma posição já existente na conta-corrente.

businessAccountId representa a conta principal opcional do caixa. Enviar 0 corresponde a Caixa = Nenhum, mas não desativa os movimentos de caixa. O backend pode continuar a resolver uma conta através da configuração do tipo de pagamento ou dos detalhes bancários. Quando é indicada uma conta principal, esta funciona como alternativa para os pagamentos que não resolvam uma conta mais específica.

Cheque ou transferência bancária

Envie paymentBankDetail apenas nos mecanismos que exigem informação bancária.

{
  "payments": [
    {
      "paymentTypeId": 4,
      "amount": 250,
      "paymentBankDetail": {
        "checkSequenceNumber": "000123",
        "accountNumber": "PT50000000000000000000000",
        "bankKeyId": "BANK01",
        "bankDescription": "Banco Exemplo",
        "deferredDate": "2026-09-05T00:00:00",
        "businessAccountId": 8,
        "observation": "Referência da transferência 2026-150"
      }
    }
  ]
}

Os recursos de arquivo digital podem ser enviados em payments[n].paymentBankDetail.files[n]. O arquivo é processado depois da confirmação financeira. Se esta operação falhar, o recibo permanece criado e a resposta inclui um aviso.

Descontos, troco, excedentes e retenção

Descontos

Envie discountValue e configure discountOnNetAmount de acordo com a base pretendida. O backend recalcula a percentagem e valida que o desconto não excede a base permitida da liquidação.

Troco

Envie apenas os montantes entregues pelo pagador. Não envie isChange nem uma linha de pagamento negativa. Quando o mecanismo permite troco, o backend calcula e persiste a respetiva linha.

Outros valores e excedentes

otherValues representa um valor acima dos documentos pendentes selecionados quando as regras de negócio o permitem. O excedente é registado como uma posição rastreável em conta-corrente. Não utilize este campo como ajuste genérico de arredondamento.

Retenção na fonte

A retenção registada num recibo é informação fiscal associada aos documentos de origem; não representa um valor recebido do cliente nem pago ao fornecedor no caixa. Quando paidAmount é diferente de zero, o recibo associa integralmente a retenção remanescente desse documento de origem. Se paidAmount for zero, não é associada retenção. Um recibo posterior para o mesmo documento regista apenas o valor que ainda não tenha sido associado.

Idempotência e repetição de pedidos

POST /gateway/receipt-document exige o cabeçalho Idempotency-Key.

Situação	Comportamento necessário
Nova operação de negócio	Gerar uma nova chave opaca, preferencialmente um UUID
Timeout ou perda de ligação	Repetir o mesmo corpo com a mesma chave
HTTP `409` enquanto o pedido ainda está em processamento	Aguardar e repetir o mesmo corpo com a mesma chave
Mesma chave com corpo diferente	Não repetir; gerar uma chave apenas para uma operação realmente nova
Resposta com `id` e warnings	Considerar o recibo criado; não voltar a emiti-lo

O bloqueio pessimista dos documentos de origem evita a sobreliquidação concorrente. A idempotência resolve um problema diferente: a repetição do mesmo comando lógico de criação.

Consultar recibos emitidos

Listar e pesquisar

Ver GET /gateway/receipt-document.

GET /gateway/receipt-document?documentTypeId=30&seriesId=4&search=CLI001&page=1&pageSize=20&deleted=false
Authorization: Bearer {token}

Parâmetro	Descrição
`documentTypeId`	Tipo documental do recibo ou pagamento a fornecedor
`seriesId`	Série a consultar
`search`	Pesquisa por número, entidade ou ATCUD
`page` / `pageSize`	Paginação no servidor
`deleted`	`false` para ativos, `true` para anulados, omitido para ambos

Consultar por chave documental

Ver GET /gateway/receipt-document/{documentTypeId}/{serieId}/{number}.

GET /gateway/receipt-document/{documentTypeId}/{serieId}/{number}
Authorization: Bearer {token}

O snapshot inclui entidade e morada, colaborador, totais, documentos de origem, pagamentos, ATCUD, estado de anulação e motivo.

Próximo número previsto

Ver GET /gateway/receipt-document/next-number/{documentTypeId}/{serieId}.

GET /gateway/receipt-document/next-number/{documentTypeId}/{serieId}
Authorization: Bearer {token}

O número devolvido é informativo. O número definitivo é reservado dentro da transação de criação e pode mudar se outro recibo for confirmado em simultâneo.

Impressão e arquivo digital

Ver GET /gateway/receipt-document/{id}/printing-data.

GET /gateway/receipt-document/{id}/printing-data
Authorization: Bearer {token}

A informação fiscal apresentada na impressão é determinada pelo país da licença do tenant. Portugal utiliza a certificação da série seguida de /AT, enquanto Angola utiliza o texto de validação da AGT.

Endpoints de arquivo relacionados: GET .../digital-archives-directories/root e GET .../{keyId}/digital-archives-directories:

GET /gateway/receipt-document/digital-archives-directories/root
Authorization: Bearer {token}

GET /gateway/receipt-document/{keyId}/digital-archives-directories
Authorization: Bearer {token}

Anular um recibo

Ver DELETE /gateway/receipt-document/{id}.

DELETE /gateway/receipt-document/840
Authorization: Bearer {token}
Content-Type: application/json

{
  "reason": "Recibo emitido com o meio de pagamento incorreto"
}

Uma anulação concluída devolve 204 No Content. A operação repõe os valores pendentes reversíveis e remove, na mesma transação, os respetivos efeitos na conta-corrente e no caixa. A anulação pode ser rejeitada quando um excedente criado pelo recibo já tiver sido utilizado numa operação posterior.

Garantias do processamento

A API recalcula os totais e valida os dados associados ao recibo, incluindo a entidade, os documentos de origem, a moeda e os meios de pagamento. Antes de confirmar a operação, volta a verificar a elegibilidade e o valor pendente atual de cada documento, rejeitando o pedido caso o respetivo estado tenha sido alterado entretanto.

A confirmação financeira é atómica: uma resposta de sucesso indica que o recibo e os respetivos efeitos financeiros foram persistidos de forma consistente. O arquivo digital é processado posteriormente; uma falha nessa etapa não anula o recibo já criado e é comunicada através de warnings.

Cenários avançados

Os exemplos seguintes ilustram combinações que frequentemente originam integrações incorretas. Utilizam a mesma estrutura JSON dos exemplos de criação anteriores e pressupõem que o consumidor já consultou pending-documents e utiliza o idHeader, o sinal, a moeda e o dueValue atuais devolvidos pela API.

Fatura e nota de crédito no mesmo recibo

A nota de crédito deve manter o sinal negativo devolvido pelo endpoint de documentos pendentes. Neste exemplo, o cliente tem uma fatura com dueValue = 100 e uma nota de crédito com dueValue = -20; o recibo liquida os dois documentos e recebe apenas o valor líquido de 80.

POST /gateway/receipt-document
Authorization: Bearer {token}
Idempotency-Key: 8f80f984-5fbf-4d9a-93dc-0d8c7d93f701
Content-Type: multipart/form-data

{
  "documentTypeId": 30,
  "serieId": 4,
  "creationDate": "2026-08-31T00:00:00",
  "entityKeyId": "CLI001",
  "receiptBodyDetails": [
    { "idHeader": 1250, "paidAmount": 100 },
    { "idHeader": 1260, "paidAmount": -20 }
  ],
  "businessAccountId": 0,
  "accountCategoryId": 0,
  "accountHeadingId": 0,
  "discountValue": 0,
  "discountOnNetAmount": false,
  "otherValues": 0,
  "employeeId": 12,
  "payments": [
    { "paymentTypeId": 1, "amount": 80 }
  ]
}

A mesma regra aplica-se aos pagamentos a fornecedores: as faturas de fornecedor são enviadas com paidAmount positivo e as notas de crédito de fornecedor com paidAmount negativo. As linhas de pagamento devem reconciliar com o valor líquido depois de créditos, descontos, excedentes e troco derivado pelo servidor.

Encontro de contas com total líquido zero

Quando a fatura e a nota de crédito selecionadas se compensam integralmente, o recibo pode ser criado sem pagamento positivo no caixa. As linhas selecionadas continuam a documentar a liquidação, mas o valor líquido exigido nos meios de pagamento é zero.

POST /gateway/receipt-document
Authorization: Bearer {token}
Idempotency-Key: 7f8efc6e-2bdf-419e-a6f3-08a0d1e3c0f6
Content-Type: multipart/form-data

{
  "documentTypeId": 30,
  "serieId": 4,
  "creationDate": "2026-08-31T00:00:00",
  "entityKeyId": "CLI001",
  "receiptBodyDetails": [
    { "idHeader": 1250, "paidAmount": 100 },
    { "idHeader": 1261, "paidAmount": -100 }
  ],
  "businessAccountId": 0,
  "accountCategoryId": 0,
  "accountHeadingId": 0,
  "discountValue": 0,
  "discountOnNetAmount": false,
  "otherValues": 0,
  "employeeId": 12
}

Não envie uma linha de pagamento artificial com amount = 0. Quando o valor líquido da liquidação é zero, os dados relevantes são as linhas dos documentos de origem com os respetivos sinais.

Liquidação parcial com retenção na fonte

A retenção continua a ser informação fiscal associada ao documento de origem. Se uma fatura tiver dueValue = 80 e remainingHoldingTax = 20, um pagamento parcial de 40 associa a retenção remanescente a este recibo; o pagador continua a entregar apenas o valor financeiro representado nas linhas de pagamento.

POST /gateway/receipt-document
Authorization: Bearer {token}
Idempotency-Key: 6d717c9e-7d12-48c4-9127-d174d027886a
Content-Type: multipart/form-data

{
  "documentTypeId": 30,
  "serieId": 4,
  "creationDate": "2026-08-31T00:00:00",
  "entityKeyId": "CLI001",
  "receiptBodyDetails": [
    { "idHeader": 1270, "paidAmount": 40 }
  ],
  "businessAccountId": 0,
  "accountCategoryId": 0,
  "accountHeadingId": 0,
  "discountValue": 0,
  "discountOnNetAmount": false,
  "otherValues": 0,
  "employeeId": 12,
  "payments": [
    { "paymentTypeId": 1, "amount": 40 }
  ]
}

Se paidAmount for zero, não é associada retenção nessa linha. Nos recibos posteriores para o mesmo documento de origem, a API considera apenas a retenção que ainda não tenha sido associada.

Timeout e repetição idempotente

Se a ligação falhar depois do envio do pedido, repita o mesmo comando lógico com a mesma Idempotency-Key e o mesmo corpo. Não crie uma segunda chave apenas porque o consumidor não recebeu a primeira resposta.

POST /gateway/receipt-document
Authorization: Bearer {token}
Idempotency-Key: 5bf8ed52-cf95-4a8d-8095-5bc6bbd99106
Content-Type: multipart/form-data

{
  "documentTypeId": 30,
  "serieId": 4,
  "creationDate": "2026-08-31T00:00:00",
  "entityKeyId": "CLI001",
  "receiptBodyDetails": [
    { "idHeader": 1250, "paidAmount": 80 }
  ],
  "businessAccountId": 0,
  "accountCategoryId": 0,
  "accountHeadingId": 0,
  "discountValue": 0,
  "discountOnNetAmount": false,
  "otherValues": 0,
  "employeeId": 12,
  "payments": [
    { "paymentTypeId": 1, "amount": 80 }
  ]
}

Se a repetição devolver a resposta de sucesso { id, warnings }, considere o recibo criado. Se devolver um conflito por o pedido continuar em processamento, aguarde e repita novamente o mesmo corpo. Se for necessário alterar o corpo, gere uma nova chave e trate-o como uma nova operação de negócio.

Erros frequentes

Estado HTTP	Causa habitual	Ação recomendada
`400`	Natureza, entidade, série, sinal, valor, desconto, detalhe bancário ou reconciliação de pagamentos inválidos	Atualizar os pendentes e corrigir o pedido
`401`	Autenticação ausente ou inválida	Obter um token de acesso válido
`403`	Utilizador sem autorização para uma conta de negócio resolvida	Selecionar ou autorizar a conta correta
`404`	Entidade, colaborador, documento, tipo, série, tipo de pagamento ou conta inexistente	Resolver novamente os identificadores no tenant
`409`	Conflito de idempotência, pedido ainda em processamento, alteração concorrente ou anulação não reversível	Reutilizar a mesma chave apenas na repetição do mesmo pedido; nos restantes casos, atualizar o estado antes de criar uma nova operação
`500`	Falha inesperada do servidor	Não assumir que um timeout significa falha; repetir de forma segura com a mesma chave de idempotência

Os erros seguem o contrato Problem Details da API. O consumidor deve tratar o código devolvido, em vez de interpretar a descrição localizada.

Referência relacionada da API

Última atualização: 1 de setembro de 2026

Naturezas suportadas​

Fluxo de integração recomendado​

1. Consultar documentos pendentes​

Parâmetros​

Regras de seleção​

2. Criar um recibo de cliente (RE)​

3. Criar um pagamento a fornecedor (PF)​

Vários documentos e notas de crédito​

Meios de pagamento e contas de negócio​

Cheque ou transferência bancária​

Descontos, troco, excedentes e retenção​

Descontos​

Troco​

Outros valores e excedentes​

Retenção na fonte​

Idempotência e repetição de pedidos​

Consultar recibos emitidos​

Listar e pesquisar​

Consultar por chave documental​

Próximo número previsto​

Impressão e arquivo digital​

Anular um recibo​

Garantias do processamento​

Cenários avançados​

Fatura e nota de crédito no mesmo recibo​

Encontro de contas com total líquido zero​

Liquidação parcial com retenção na fonte​

Timeout e repetição idempotente​

Erros frequentes​

Referência relacionada da API​