Invoice-Receipt Guide

Document nature (business): Invoice-Receipt (FR)

Illustrative IDs

The values in the JSON examples are illustrations. Resolve the correct id with GET /gateway/document-type and match description / keyId to invoice-receipt (FR) in the client's database. See Resolving document type IDs.

---

Overview

An invoice-receipt (FR) combines sale + payment on a single fiscal document. Use FR when the customer pays in full at the time of sale — the common retail / point-of-sale scenario.

POST /gateway/invoice/invoices

FR vs separate invoice + receipt

Flow	Documents	API availability
FR — invoice-receipt	One document (sale + payment)	✅ Available
FT + RE — invoice then receipt	Two documents	❌ RE not available via API

Receipts (RE) not available

Receipt nature RE cannot be created through this API. For payment-at-sale flows, use FR with payments[] on the same payload. The Receipts Guide is kept for reference only.

---

When to use FR

• ✅ Retail sale paid immediately (cash, card, MB Way)
• ✅ Simplified invoice replacement when amount exceeds FS limit (document type settings)
• ✅ Any sale where payment is collected at issuance
• ❌ Credit sales with later payment → use FT without immediate settlement (checking-account flows)

---

Create invoice-receipt

Single payment method

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

{
  "serieId": 1,
  "documentTypeId": 9,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "entityDescription": "Example Client, Ltd",
  "entityVat": "PT123456789",
  "obs": "Counter sale — paid in cash",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 123
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "itemDescription": "Product 1",
      "quantity": 2,
      "retailPrice": 50,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

The sum of payments[].amount must match the document total. Change is calculated automatically when the payment type allows it.

Split payment

{
  "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
    }
  ]
}

With line discount

{
  "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
    }
  ]
}

---

Characteristics

Characteristic	Value
Payments	✅ Required — header payments[]
Stock	✅ Per document type (outbound for goods)
Fiscal document	✅ Yes
Receivable	❌ Settled on same document
Separate receipt	❌ Not needed (and RE unsupported)

---

Payment types

paymentTypeId	Typical method
1	Cash
2	Check
3	Bank transfer
4	ATM / reference
5	Card
6	MB Way

Use GET /gateway/payment-types for the full list in the client's database.

---

FR vs FT vs RE

Aspect	FT (invoice)	FR (invoice-receipt)	RE (receipt)
Sale lines	✅	✅	❌ Payment only
payments[]	✅ (or credit)	✅ Required	N/A
API availability	✅	✅	❌ Not available
Use case	Credit / deferred payment	Pay at sale	Two-step flow (FT + RE)

---

Best practices

✅ Recommended

• Use FR instead of FT + RE for immediate payment.
• Ensure payments[].amount totals match the document total.
• Send currencyId and X-Timezone on every request.
• Resolve paymentTypeId values with GET /gateway/payment-types.

❌ Avoid

• Attempting to create RE documents (API returns DocumentType.NotSupported).
• Omitting payments on FR.

---

Response

201 Created includes documentNumber, total, totalTaxes, change (when applicable), and guid.

---

Next steps

• Invoices Guide — FT and FS (credit sales)
• Receipts Guide — RE reference (not available via API)
• Usage Guide — payments model and document creation flow

---

Last Updated: June 9, 2026