Guia de Recibos (Receipts)

Tipo de Documento: Recibo
Document Type ID: 6 (verificar com /document-type)

---

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 /api/v1/invoices
Content-Type: application/json
Authorization: Bearer {token}

{
  "serieId": 4,
  "documentTypeId": 6,
  "entityKeyId": "CLI001",
  "entityDescription": "Cliente Exemplo, Lda",
  "obs": "Pagamento referente à fatura FT A/123",
  "docReference": "FT A/123",
  "paymentModeId": 1,              // Dinheiro
  "documentBodies": [
    {
      "itemKeyId": "PGTO001",      // Item de pagamento
      "itemDescription": "Pagamento",
      "quantity": 1.0,
      "retailPrice": 1000.00,      // Valor pago
      "taxId": 2,                  // Taxa isenta
      "paymentType": 1,            // Dinheiro
      "stockFlow": 0,              // Não afeta stock
      "stockBehavior": 0,
      "secondTaxId": 0
    }
  ]
}

Recibo com Múltiplas Formas de Pagamento

{
  "serieId": 4,
  "documentTypeId": 6,
  "entityKeyId": "CLI001",
  "obs": "Pagamento misto - dinheiro e transferência",
  "docReference": "FT A/123",
  "documentBodies": [
    {
      "itemKeyId": "PGTO001",
      "itemDescription": "Pagamento - Dinheiro",
      "quantity": 1.0,
      "retailPrice": 500.00,       // Parte em dinheiro
      "taxId": 2,
      "paymentType": 1,            // Dinheiro
      "stockFlow": 0,
      "stockBehavior": 0,
      "secondTaxId": 0
    },
    {
      "itemKeyId": "PGTO001",
      "itemDescription": "Pagamento - Transferência",
      "quantity": 1.0,
      "retailPrice": 500.00,       // Parte em transferência
      "taxId": 2,
      "paymentType": 3,            // Transferência
      "stockFlow": 0,
      "stockBehavior": 0,
      "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 /payment-types para lista completa.

---

Vinculação com Faturas

Recibo para Fatura Específica

{
  "serieId": 4,
  "documentTypeId": 6,
  "entityKeyId": "CLI001",
  "obs": "Liquidação total da fatura FT A/123",
  "docReference": "FT A/123",      // Referência à fatura
  "paymentModeId": 1,
  "documentBodies": [
    {
      "itemKeyId": "PGTO001",
      "itemDescription": "Liquidação FT A/123",
      "quantity": 1.0,
      "retailPrice": 1230.00,      // Valor total da fatura
      "taxId": 2,
      "paymentType": 1,
      "stockFlow": 0,
      "stockBehavior": 0,
      "secondTaxId": 0
    }
  ]
}

Recibo para Múltiplas Faturas

{
  "serieId": 4,
  "documentTypeId": 6,
  "entityKeyId": "CLI001",
  "obs": "Pagamento de múltiplas faturas",
  "docReference": "FT A/123, FT A/124, FT A/125",
  "documentBodies": [
    {
      "itemKeyId": "PGTO001",
      "itemDescription": "Liquidação múltiplas faturas",
      "quantity": 1.0,
      "retailPrice": 5000.00,      // Total das 3 faturas
      "taxId": 2,
      "paymentType": 3,            // Transferência
      "stockFlow": 0,
      "stockBehavior": 0,
      "secondTaxId": 0
    }
  ]
}

---

Integração com Tesouraria

Fluxo Completo

graph LR
    A[Fatura Criada] --> B[Cliente Paga]
    B --> C[Criar Recibo]
    C --> D[Registar em Tesouraria]
    D --> E[Fatura Liquidada]

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

• Sempre referenciar fatura em docReference
• 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 sem docReference).

---

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 - Criar faturas para receber
• Guia de Notas de Crédito - Devoluções
• Guia de Utilização - Informações gerais da API

---

Última Atualização: 28 de Novembro de 2025