Guia de Recibos (Receipts)

Tipo de documento (negócio): Recibo

RE não disponível na API de Facturação

A natureza RE não pode ser criada através desta API. Para vendas pagas no acto, use Fatura-Recibo (FR) com payments[] no mesmo documento. Este guia mantém-se apenas como referência.

IDs ilustrativos

Os números nos exemplos JSON (ex.: "documentTypeId": 6) são ilustrativos; o mesmo valor pode representar outro tipo de documento noutra base de dados do cliente. Obtenha o id correto com GET /gateway/document-type e faça corresponder description / keyId ao recibo na base de dados do cliente. Veja Resolução dos IDs de tipo de documento.

---

Visão Geral

Os Recibos (Receipts) são documentos que:

• 💰 Comprovam recebimento de pagamento
• ❌ NÃO afetam stock
• 💳 Registam método de pagamento
• 🧾 Vinculados a faturas (opcional)
• 📊 Integram com tesouraria

Quando Usar

• ✅ Cliente efetua pagamento
• ✅ Comprovar recebimento de valores
• ✅ Registar em tesouraria
• ✅ Liquidar faturas

---

Características dos Recibos

Característica	Valor	Descrição
Afeta Stock	❌ Não	Apenas pagamento
Requer Pagamento	✅ Sim	Regista pagamento
Pode ser Fechado	✅ Sim	Finalização obrigatória
Validação Fiscal	✅ Sim	Documento fiscal
Permite Edição	⚠️ Limitada	Só antes de fechar
Cancelamento	⚠️ Complicado	Requer estorno

---

Criar Recibo

Recibo Simples

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

{
  "serieId": 4,
  "documentTypeId": 6,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "entityDescription": "Cliente Exemplo, Lda",
  "obs": "Pagamento referente à fatura FT A/123",
  "paymentModeId": 1,
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 1000
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PGTO001",
      "itemDescription": "Pagamento",
      "quantity": 1,
      "retailPrice": 1000,
      "taxId": 2,
      "secondTaxId": 0
    }
  ]
}

Recibo com Múltiplas Formas de Pagamento

{
  "serieId": 4,
  "documentTypeId": 6,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "obs": "Pagamento misto - dinheiro e transferência",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 500
    },
    {
      "paymentTypeId": 3,
      "amount": 500
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PGTO001",
      "itemDescription": "Pagamento - Dinheiro",
      "quantity": 1,
      "retailPrice": 500,
      "taxId": 2,
      "secondTaxId": 0
    },
    {
      "itemKeyId": "PGTO001",
      "itemDescription": "Pagamento - Transferência",
      "quantity": 1,
      "retailPrice": 500,
      "taxId": 2,
      "secondTaxId": 0
    }
  ]
}

---

Tipos de Pagamento

Código	Tipo	Descrição
1	Dinheiro	Numerário
2	Cheque	Cheque bancário
3	Transferência	Transferência bancária
4	Multibanco	Referência MB
5	Cartão	Débito/Crédito
6	MB Way	MB Way

Consultar API

Use endpoint /gateway/payment-types para lista completa.

---

Vinculação com Faturas

Recibo para Fatura Específica

{
  "serieId": 4,
  "documentTypeId": 6,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "obs": "Liquidação total da fatura FT A/123",
  "paymentModeId": 1,
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 1230
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PGTO001",
      "itemDescription": "Liquidação FT A/123",
      "quantity": 1,
      "retailPrice": 1230,
      "taxId": 2,
      "secondTaxId": 0
    }
  ]
}

Recibo para Múltiplas Faturas

{
  "serieId": 4,
  "documentTypeId": 6,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "obs": "Pagamento de múltiplas faturas",
  "payments": [
    {
      "paymentTypeId": 3,
      "amount": 5000
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PGTO001",
      "itemDescription": "Liquidação múltiplas faturas",
      "quantity": 1,
      "retailPrice": 5000,
      "taxId": 2,
      "secondTaxId": 0
    }
  ]
}

---

Integração com Tesouraria

Fluxo Completo

1. Fatura emitida - Conta a receber criada
2. Cliente efetua pagamento
3. Criar recibo - Comprovar recebimento
4. Registar em tesouraria - Atualizar caixa/banco
5. Marcar fatura como paga - (sistema contabilístico)

---

Boas Práticas

✅ Recomendado

• Validar valor do recibo vs valor da fatura
• Registar método de pagamento correto
• Fechar recibo imediatamente após criação
• Incluir informações bancárias (se transferência)
• Emitir recibo no mesmo dia do pagamento

❌ Evitar

• Criar recibo sem fatura vinculada
• Valor de recibo diferente do pagamento real
• Deixar recibos abertos
• Emitir recibo antes de confirmar pagamento
• Esquecer de informar método de pagamento

---

Casos de Uso Comuns

Pagamento à Vista

Cliente paga fatura no ato da compra.

Pagamento de Fatura a Prazo

Cliente paga fatura 30/60 dias após emissão.

Pagamento Parcial

Cliente paga parte da fatura (criar múltiplos recibos).

Adiantamento

Cliente paga antes da fatura (recibo avulso).

---

Diferenças vs Faturas

Aspecto	Fatura	Recibo
Objetivo	Venda	Pagamento
Stock	Afeta	Não afeta
Valor	Venda	Pagamento
Timing	Na venda	No pagamento
IVA	Inclui	Isento

---

Cancelamento de Recibo

Atenção

Cancelar recibo é complexo e pode requerer estorno contabilístico.

Cenário: Recibo Emitido por Erro

1. Criar Nota de Crédito (se necessário ajustar fatura)
2. Registar estorno em tesouraria
3. Criar novo recibo correto

---

Próximos Passos

• Guia de Faturas-Recibo — fluxo suportado de pagamento no acto (FR)
• Guia de Faturas - Criar faturas para receber
• Guia de Notas de Crédito - Devoluções
• Guia de Utilização - Informações gerais da API

---

Última Actualização: 5 de junho de 2026