Skip to main content

Sales Invoices Guide

Document Type: Sales Invoice
Document Type ID: 5 (verify with /document-type)

Overview​

Sales Invoices are definitive fiscal documents that:

  • 🧾 Prove the sale of goods or services
  • 📉 AFFECT stock (outbound)
  • 💰 Generate accounts receivable
  • 📊 Registered for tax and accounting purposes
  • ✅ Official fiscal document

When to Use​

  • ✅ Definitive sale of products/services
  • ✅ Issuing fiscal document
  • ✅ Recording company revenue
  • ✅ VAT accounting

Invoice Characteristics​

CharacteristicValueDescription
Affects Stock✅ YesStock outbound
Requires Payment✅ YesGenerates receivable
Can be Closed✅ YesMandatory finalization
Fiscal Validation✅ YesOfficial fiscal document
Allows Editing⚠️ LimitedOnly before closing
Cancellation⚠️ Via Credit NoteCannot be deleted

Create Invoice​

Complete Example​

POST /api/v1/invoices
Content-Type: application/json
Authorization: Bearer {token}
{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "entityDescription": "Example Client, Ltd",
  "entityVat": "PT123456789",
  "entityAddress": "123 Example Street",
  "entityPostalCode": "1000-000",
  "entityCity": "Lisbon",
  "entityCountry": "Portugal",
  "obs": "Invoice for order PO-2025-001",
  "docReference": "PO-2025-001",
  "dueDate": "2025-12-31",
  "paymentModeId": 1,
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "itemDescription": "Product 1",
      "quantity": 2.0,
      "retailPrice": 50.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": 1,              // Stock outbound
      "stockBehavior": 1,          // Normal behavior
      "secondTaxId": 0
    }
  ]
}

Invoice with Discount​

{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 10.0,
      "retailPrice": 100.00,
      "discountValue": 10.00,      // Line discount
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": 1,
      "stockBehavior": 1,
      "secondTaxId": 0
    }
  ]
}

VAT Exempt Invoice​

{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "exemptionCode": "M01",          // Exemption code
  "exemptionReason": "Exempt under article 9 of VAT Code",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 1.0,
      "retailPrice": 100.00,
      "taxId": 2,                  // Exemption tax rate
      "paymentType": 1,
      "stockFlow": 1,
      "stockBehavior": 1,
      "secondTaxId": 0
    }
  ]
}

Update Invoice​

Update Observations​

PUT /api/v1/invoices/123
Content-Type: application/json
Authorization: Bearer {token}
{
  "id": 123,
  "obs": "Updated observations",
  "docReference": "PO-2025-001-REV"
}

Close Invoice​

PUT /api/v1/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 /api/v1/invoices/123
Authorization: Bearer {token}

By Number​

GET /api/v1/invoices/5/1/1
Authorization: Bearer {token}

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

List Invoices​

GET /api/v1/invoices?documentTypeId=5&status=Open&pageNumber=1&pageSize=20
Authorization: Bearer {token}

Invoice Lifecycle​

graph LR
    A[Create Invoice] --> B[Status: Open]
    B --> C[Edit if needed]
    C --> D[Close Invoice]
    D --> E[Status: Closed]
    E --> F{Need correction?}
    F -->|Yes| G[Create Credit Note]
    F -->|No| H[End]
  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 - Document type ID (5)
  • ✅ entityKeyId - Valid customer
  • ✅ documentBodies - At least 1 line
  • ✅ stockFlow = 1 - Stock outbound

Fiscal Validations​

  • ✅ Customer Tax ID/VAT (if PT)
  • ✅ Complete address
  • ✅ Exemption code (if applicable)
  • ✅ Correct VAT rate per line

Stock Validations​

  • ✅ Product exists
  • ✅ Stock available (if stockBehavior = 1)
  • ✅ Valid warehouse

Best Practices​

✅ Recommended​

  • Validate stock before creating invoice
  • Include complete customer address
  • Set due date
  • Reference previous documents (QT, ORD)
  • Close invoice as soon as confirmed
  • Include payment information

❌ Avoid​

  • Creating invoice without validating stock
  • Leaving invoices open indefinitely
  • Trying to edit closed invoice
  • Creating duplicate invoices
  • Forgetting fiscally required fields

Common Use Cases​

Simple Invoice​

Direct sale with cash payment.

Credit Invoice​

Sale with payment terms (30/60/90 days).

Services Invoice​

Service provision (no stock).

Recurring Invoice​

Monthly invoice for contracted services.

Corrections and Cancellations​

Scenario: Invoice Error​

❌ WRONG: Try to edit closed invoice

✅ CORRECT: Create Credit Note

POST /api/v1/invoices
Content-Type: application/json
{
  "serieId": 3,
  "documentTypeId": 7,           // Credit Note
  "entityKeyId": "CLI001",
  "docReference": "INV A/123",   // Reference to original invoice
  "obs": "Cancellation of invoice INV A/123",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": -2.0,            // Negative quantity
      "retailPrice": 50.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": -1,             // Stock inbound
      "stockBehavior": 1,
      "secondTaxId": 0
    }
  ]
}

Integration with Other Documents​

From Quote to Invoice​

See Quotes Guide

From Order to Invoice​

See Orders Guide

Invoice to Receipt​

See Receipts Guide

Next Steps​

Last Updated: December 2, 2025