Pular para o conteúdo principal

Guia de Faturas-Recibo

Natureza de documento (negócio): Fatura-Recibo (FR)

IDs ilustrativos

Os valores nos exemplos JSON são ilustrativos. Obtenha o id correto com GET /gateway/document-type e faça corresponder description / keyId à fatura-recibo (FR) na base de dados do cliente. Veja Resolução dos IDs de tipo de documento.

Visão geral​

Uma fatura-recibo (FR) combina venda + pagamento num único documento fiscal. Use FR quando o cliente paga na totalidade no acto da venda — cenário típico de retalho / POS.

POST /gateway/invoice/invoices

FR vs fatura + recibo separados​

FluxoDocumentosDisponibilidade na API
FR — fatura-reciboUm documento (venda + pagamento)Invoice API
FT + RE — fatura e depois reciboDois documentosInvoice API para a fatura; Core API para o recibo

Quando usar FR​

  • ✅ Venda a retalho paga de imediato (dinheiro, cartão, MB Way)
  • ✅ Substituição de FS quando o valor excede o limite legal (definições do tipo de documento)
  • ✅ Qualquer venda com cobrança na emissão
  • ❌ Vendas a crédito com pagamento posterior → use FT (conta corrente)

Criar fatura-recibo​

Uma forma de pagamento​

POST /gateway/invoice/invoices
Content-Type: application/json
Authorization: Bearer {token}
X-Timezone: Europe/Lisbon
{
  "serieId": 1,
  "documentTypeId": 9,
  "entityKeyId": "CLI001",
  "entityDescription": "Cliente Exemplo, Lda",
  "entityVat": "PT123456789",
  "obs": "Venda balcão — pago em numerário",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 123
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "itemDescription": "Produto 1",
      "quantity": 2,
      "retailPrice": 50,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

A soma de payments[].amount deve coincidir com o total do documento. O troco é calculado automaticamente quando o tipo de pagamento o permite.

Pagamento misto​

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

Com desconto na linha​

{
  "serieId": 1,
  "documentTypeId": 9,
  "entityKeyId": "CLI001",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 108
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 1,
      "retailPrice": 120,
      "discountPercentage": 10,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

Características​

CaracterísticaValor
Pagamentos✅ Obrigatório — payments[] no cabeçalho
Stock✅ Conforme tipo de documento (saída para mercadorias)
Documento fiscal✅ Sim
Conta a receber❌ Liquidada no mesmo documento
Recibo separado❌ Desnecessário (e RE não suportado)

Tipos de pagamento​

paymentTypeIdMétodo típico
1Numerário
2Cheque
3Transferência bancária
4Multibanco / referência
5Cartão
6MB Way

Use GET /gateway/payment-types para a lista completa de tipos de pagamento.

FR vs FT vs RE​

AspectoFT (fatura)FR (fatura-recibo)RE (recibo)
Linhas de venda✅✅❌ Só pagamento
payments[]✅ (ou crédito)✅ ObrigatórioPayload da Core API
APIInvoice APIInvoice APICore API
Caso de usoCrédito / pagamento diferidoPagamento no actoFluxo em dois passos (FT + RE)

Boas práticas​

✅ Recomendado​

  • Usar FR em vez de FT + RE para pagamento imediato.
  • Garantir que a soma de payments[].amount corresponde ao total.
  • Enviar X-Timezone em cada pedido.
  • Resolver paymentTypeId com GET /gateway/payment-types.

❌ Evitar​

  • Criar RE com POST /gateway/invoice/invoices. Use a Core API POST /gateway/receipt-document.
  • Omitir payments na FR.

Resposta​

201 Created inclui documentNumber, total, totalTaxes, change (quando aplicável) e guid.

Próximos passos​

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