Sales Invoices Guide

Document types (business): Sales Invoice (FT) and Simplified Invoice (FS)

Illustrative IDs

The values in the JSON examples (e.g. "documentTypeId": 5) are illustrations; the same number can represent a different document type in another client's database. Resolve the correct id with GET /gateway/document-type and match description / keyId to a sales invoice (FT) or simplified invoice (FS) in the client's database. See Resolving document type IDs.

Both FT and FS use the same endpoint and payload shape. Fiscal behaviour, stock movement, and validations depend on the documentTypeId you choose. See the Usage Guide for the shared data model.

For payment collected on the same document, use invoice-receipt (FR) instead — see the Invoice-Receipt Guide.

---

Overview

Sales invoices are definitive fiscal documents that:

• 🧾 Prove the sale of goods or services
• 📉 Affect stock (outbound) — according to document type configuration
• 💰 Require header-level payments and generate accounts receivable when not fully paid
• 📊 Are registered for tax and accounting purposes
• ✅ Are official fiscal documents

When to Use

Nature	Code	Typical use
Sales invoice	FT	B2B sales, higher amounts, full customer identification
Simplified invoice	FS	Retail / POS, small amounts within legal limits

• ✅ Definitive sale of products or services
• ✅ Issuing a fiscal document
• ✅ Recording company revenue and VAT

---

Invoice Characteristics

Characteristic	Value	Description
Affects Stock	✅ Yes	Outbound — per document type configuration
Requires Payment	✅ Yes	payments[] required at header level
Can be Closed	✅ Yes	Mandatory finalization
Fiscal Validation	✅ Yes	Official fiscal document
Allows Editing	⚠️ Limited	Only before closing
Cancellation	⚠️ Via Credit Note	Cannot be deleted — see Credit Notes Guide

Stock movement

Stock movement follows the document type and item configuration. Line quantities are always positive.

---

Create Invoice

Complete Example (FT)

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

{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "entityDescription": "Example Client, Ltd",
  "entityVat": "PT123456789",
  "entityAddress": "123 Example Street",
  "entityPostalCode": "1000-000",
  "entityCity": "Lisbon",
  "entityCountry": "Portugal",
  "paymentModeId": 1,
  "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. Resolve paymentTypeId with GET /gateway/payment-types.

Response (201 Created) — relevant fields:

{
  "id": 123,
  "documentNumber": "FT A/1",
  "total": 123,
  "totalTaxes": 23,
  "totalDiscounts": 0,
  "change": 0,
  "netChange": 0,
  "guid": "550e8400-e29b-41d4-a716-446655440000"
}

When the customer pays more than the total with a payment type that allows change (e.g. cash), the response includes change and netChange.

Invoice with Line Discount

Use discountPercentage (0–100) for line and header discounts:

{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 900
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 10,
      "retailPrice": 100,
      "discountPercentage": 10,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

Invoice with Header Discount

{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "discountPercentage": 5,
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 950
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 10,
      "retailPrice": 100,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

Invoice with menu or composite article

Menus require child lines with guid / parentGuid for selected options. Composite articles can be sent as a single line (composite itemKeyId only). See the Usage Guide — menu and composite examples.

VAT Exempt Invoice

{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 100
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 1,
      "retailPrice": 100,
      "taxId": 2,
      "secondTaxId": 0
    }
  ]
}

Simplified Invoice (FS)

Use the documentTypeId whose invoiceType is FS. Payload is the same; legal thresholds come from the FS document type settings:

{
  "serieId": 2,
  "documentTypeId": 6,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 45
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 1,
      "retailPrice": 45,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

---

Multi-Payment

Split payment across mechanisms at header level:

{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 50
    },
    {
      "paymentTypeId": 3,
      "amount": 73
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 2,
      "retailPrice": 50,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

If the customer pays €130 in cash for a €123 total, change is calculated automatically when the payment type supports it:

{
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 130
    }
  ]
}

Example response excerpt:

{
  "total": 123,
  "change": 7,
  "netChange": 7
}

---

FS Legal Limits (FS)

When issuing FS, totals are checked against thresholds configured on the document type (GET /gateway/document-type). Typical fields:

Setting	Purpose
limitValue	Maximum net total allowed for FS. Above this limit, the operation fails or the system may suggest/use a replacement document type (e.g. FT).
fullInfoLimit	When the net total exceeds this value, complete customer fiscal data is required (name, address, VAT, etc.).
nifLimit	When the net total exceeds this value, a valid customer VAT/NIF is required — generic VAT 999999990 is not accepted.

These limits reflect Portuguese fiscal rules (e.g. Article 40 of the VAT Code for FS) . When in doubt, use FT for B2B or higher-value sales with full customer identification.

Common validation codes: SaleDocumentRules.FS.AboveLegal, SaleDocumentRules.Nif.RequiredVat, SaleDocumentRules.FullInfo.RequiredCustomer, SaleDocumentRules.FullInfo.CustomerFiscalData.

---

Update Invoice

Update Observations

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

{
  "id": 123,
  "obs": "Updated observations"
}

Close Invoice

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

{
  "id": 123,
  "close": true
}

Attention

After closing the invoice, it cannot be edited. To correct, use a Credit Note.

---

Get Invoice

By ID

GET /gateway/invoice/invoices/123
Authorization: Bearer {token}

By Number

GET /gateway/invoice/invoices/5/1/1
Authorization: Bearer {token}

Parameters: documentTypeId=5, serieId=1, number=1

List Invoices

GET /gateway/invoice/invoices?documentTypeId=5&status=Open&page=1&pageSize=20
Authorization: Bearer {token}

---

Invoice Lifecycle

1. Create: Invoice created with status Open
2. Edit: Possible to edit while Open
3. Close: Finalize invoice (status Closed)
4. Correction: Only via Credit Note

---

Important Validations

Required Data

• ✅ serieId — Series configured for invoices
• ✅ documentTypeId — FT or FS document type
• ✅ entityKeyId — Valid customer
• ✅ currencyId — Currency identifier (> 0)
• ✅ documentBodies — At least one line with positive quantities
• ✅ payments[] — At least one entry with paymentTypeId and amount

Fiscal Validations

• ✅ Customer VAT/NIF when amount exceeds nifLimit (especially on FS)
• ✅ Complete customer address when amount exceeds fullInfoLimit
• ✅ Exemption code and reason when applicable
• ✅ Correct VAT rate per line

Stock

• ✅ Product exists and stock is available when the document type is configured to move stock
• ✅ Stock movement follows document type configuration

---

Best Practices

✅ Recommended

• Always send currencyId and header payments[]
• Resolve documentTypeId and payment types via the API — see Usage Guide
• Validate stock availability before creating the invoice (when your FT type moves stock)
• Include complete customer address for higher amounts
• Set due date for credit sales
• Close the invoice once confirmed
• Use FT when FS limits would be exceeded

❌ Avoid

• Negative quantities on FT/FS (use Credit Notes for reversals)
• Leaving invoices open indefinitely
• Trying to edit a closed invoice

---

Common Use Cases

Simple Invoice (FT)

Direct sale with full customer data and single payment.

Simplified Invoice (FS)

Retail sale within legal limits; ensure VAT rules are met for the total.

Services Invoice

Service lines with positive quantities; stock movement depends on item and document type configuration.

---

Corrections and Cancellations

❌ WRONG: Edit or delete a closed invoice, or use negative quantities on FT/FS.

✅ CORRECT: Issue a Credit Note (NC) referencing the original invoice, with positive quantities and line references as described in that guide.

---

Integration with Other Documents

From Quote to Invoice

See Quotes Guide

From Order to Invoice

See Orders Guide

Invoice to Receipt / FR

For payment on the same document, see Invoice-Receipt Guide. Standalone receipt nature RE is not available via this API — see Usage Guide.

---

Next Steps

• Usage Guide — Shared API model, headers, and endpoints
• Credit Notes Guide — Corrections and returns
• Invoice-Receipt Guide — FR with payment on the same document
• Quotes Guide — ORC proposals
• Orders Guide — NE customer orders

---

Last Updated: June 9, 2026