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

Fluxo	Documentos	Disponibilidade na API
FR — fatura-recibo	Um documento (venda + pagamento)	✅ Disponível
FT + RE — fatura e depois recibo	Dois documentos	❌ RE não disponível na API

Recibos (RE) não disponíveis na API

A natureza RE não pode ser criada através desta API. Para vendas pagas no acto, use FR com payments[] no mesmo payload. O Guia de Recibos mantém-se apenas como referência.

---

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",
  "currencyId": 1,
  "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",
  "currencyId": 1,
  "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",
  "currencyId": 1,
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 108
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 1,
      "retailPrice": 120,
      "discountPercentage": 10,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

---

Características

Característica	Valor
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

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

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

---

FR vs FT vs RE

Aspecto	FT (fatura)	FR (fatura-recibo)	RE (recibo)
Linhas de venda	✅	✅	❌ Só pagamento
payments[]	✅ (ou crédito)	✅ Obrigatório	N/A
Disponibilidade na API	✅	✅	❌ Não disponível
Caso de uso	Crédito / pagamento diferido	Pagamento no acto	Fluxo 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 currencyId e X-Timezone em cada pedido.
• Resolver paymentTypeId com GET /gateway/payment-types.

❌ Evitar

• Tentar criar documentos RE (naturezas não suportadas).
• Omitir payments na FR.

---

Resposta

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

---

Próximos passos

• Guia de Faturas — FT e FS (vendas a crédito)
• Guia de Recibos — referência RE (não disponível na API)
• Guia de Utilização — modelo de pagamentos e fluxo de criação

---

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