Receipts Guide

Document Type: Receipt
Document Type ID: 6 (verify with /document-type)

---

Overview

Receipts are documents that:

• 💰 Prove payment received
• ❌ DO NOT affect stock
• 💳 Register payment method
• 🧾 Linked to invoices (optional)
• 📊 Integrate with treasury

When to Use

• ✅ Customer makes payment
• ✅ Prove receipt of funds
• ✅ Register in treasury
• ✅ Settle invoices

---

Receipt Characteristics

Characteristic	Value	Description
Affects Stock	❌ No	Payment only
Requires Payment	✅ Yes	Registers payment
Can be Closed	✅ Yes	Mandatory finalization
Fiscal Validation	✅ Yes	Fiscal document
Allows Editing	⚠️ Limited	Only before closing
Cancellation	⚠️ Complex	Requires reversal

---

Create Receipt

Simple Receipt

POST /api/v1/invoices
Content-Type: application/json
Authorization: Bearer {token}

{
  "serieId": 4,
  "documentTypeId": 6,
  "entityKeyId": "CLI001",
  "entityDescription": "Example Client, Ltd",
  "obs": "Payment for invoice INV A/123",
  "docReference": "INV A/123",
  "paymentModeId": 1,              // Cash
  "documentBodies": [
    {
      "itemKeyId": "PYMT001",      // Payment item
      "itemDescription": "Payment",
      "quantity": 1.0,
      "retailPrice": 1000.00,      // Amount paid
      "taxId": 2,                  // Exempt rate
      "paymentType": 1,            // Cash
      "stockFlow": 0,              // Does not affect stock
      "stockBehavior": 0,
      "secondTaxId": 0
    }
  ]
}

Receipt with Multiple Payment Methods

{
  "serieId": 4,
  "documentTypeId": 6,
  "entityKeyId": "CLI001",
  "obs": "Mixed payment - cash and bank transfer",
  "docReference": "INV A/123",
  "documentBodies": [
    {
      "itemKeyId": "PYMT001",
      "itemDescription": "Payment - Cash",
      "quantity": 1.0,
      "retailPrice": 500.00,       // Cash portion
      "taxId": 2,
      "paymentType": 1,            // Cash
      "stockFlow": 0,
      "stockBehavior": 0,
      "secondTaxId": 0
    },
    {
      "itemKeyId": "PYMT001",
      "itemDescription": "Payment - Bank Transfer",
      "quantity": 1.0,
      "retailPrice": 500.00,       // Transfer portion
      "taxId": 2,
      "paymentType": 3,            // Bank Transfer
      "stockFlow": 0,
      "stockBehavior": 0,
      "secondTaxId": 0
    }
  ]
}

---

Payment Types

Code	Type	Description
1	Cash	Currency
2	Check	Bank check
3	Bank Transfer	Wire transfer
4	ATM	ATM reference
5	Card	Debit/Credit
6	MB Way	MB Way

Check API

Use endpoint /payment-types for complete list.

---

Invoice Linking

Receipt for Specific Invoice

{
  "serieId": 4,
  "documentTypeId": 6,
  "entityKeyId": "CLI001",
  "obs": "Full settlement of invoice INV A/123",
  "docReference": "INV A/123",      // Reference to invoice
  "paymentModeId": 1,
  "documentBodies": [
    {
      "itemKeyId": "PYMT001",
      "itemDescription": "Settlement INV A/123",
      "quantity": 1.0,
      "retailPrice": 1230.00,      // Total invoice value
      "taxId": 2,
      "paymentType": 1,
      "stockFlow": 0,
      "stockBehavior": 0,
      "secondTaxId": 0
    }
  ]
}

Receipt for Multiple Invoices

{
  "serieId": 4,
  "documentTypeId": 6,
  "entityKeyId": "CLI001",
  "obs": "Payment for multiple invoices",
  "docReference": "INV A/123, INV A/124, INV A/125",
  "documentBodies": [
    {
      "itemKeyId": "PYMT001",
      "itemDescription": "Settlement multiple invoices",
      "quantity": 1.0,
      "retailPrice": 5000.00,      // Total of 3 invoices
      "taxId": 2,
      "paymentType": 3,            // Bank Transfer
      "stockFlow": 0,
      "stockBehavior": 0,
      "secondTaxId": 0
    }
  ]
}

---

Treasury Integration

Complete Flow

graph LR
    A[Invoice Created] --> B[Customer Pays]
    B --> C[Create Receipt]
    C --> D[Register in Treasury]
    D --> E[Invoice Settled]

1. Invoice issued - Receivable created
2. Customer makes payment
3. Create receipt - Prove receipt
4. Register in treasury - Update cash/bank
5. Mark invoice as paid - (accounting system)

---

Best Practices

✅ Recommended

• Always reference invoice in docReference
• Validate receipt amount vs invoice amount
• Record correct payment method
• Close receipt immediately after creation
• Include bank details (if transfer)
• Issue receipt on the same day as payment

❌ Avoid

• Creating receipt without linked invoice
• Receipt amount different from actual payment
• Leaving receipts open
• Issuing receipt before confirming payment
• Forgetting to report payment method

---

Common Use Cases

Cash Payment

Customer pays invoice at time of purchase.

Credit Invoice Payment

Customer pays invoice 30/60 days after issuance.

Partial Payment

Customer pays part of invoice (create multiple receipts).

Advance Payment

Customer pays before invoice (receipt without docReference).

---

Differences vs Invoices

Aspect	Invoice	Receipt
Purpose	Sale	Payment
Stock	Affects	Does not affect
Value	Sale	Payment
Timing	At sale	At payment
VAT	Includes	Exempt

---

Receipt Cancellation

Attention

Canceling a receipt is complex and may require accounting reversal.

Scenario: Receipt Issued by Mistake

1. Create Credit Note (if invoice adjustment needed)
2. Record reversal in treasury
3. Create new correct receipt

---

Next Steps

• Invoices Guide - Create invoices to receive
• Credit Notes Guide - Returns
• Usage Guide - General API information

---

Last Updated: December 2, 2025