Quotes Guide

Document type (business): Quote (ORC)

Illustrative IDs

The values in the JSON examples (e.g. "documentTypeId": 1) 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 quote (ORC) in the client's database. See Resolving document type IDs.

If no quotation document type exists, create one in API Base with POST /gateway/document-type (sales family, invoiceType / nature ORC), then use the returned type's id. This requires the appropriate admin permission. Details: Usage Guide – Creating document types.

Quotes use the same POST /gateway/invoice/invoices endpoint as all sales documents. See the Usage Guide for authentication, headers, and the shared payload model.

---

Overview

Quotes are commercial documents that:

• 📝 Present sales proposals to customers
• 💭 Do not affect stock under typical ORC configuration
• 💵 Do not settle payment — header payments[] records planned terms, not collected cash
• 📄 Serve as a base for future invoices or orders
• ⏱️ Generally have limited validity

When to Use

• ✅ Commercial proposal before the sale
• ✅ Price presentation to the customer
• ✅ Terms negotiation
• ✅ Base for order approval

---

Quote Characteristics

Characteristic	Value	Description
Affects Stock	❌ No (typical)	Defined by document type config — not by API line fields
Requires Payment Array	✅ Yes	payments[] required by contract; amounts reflect proposed terms
Can be Closed	✅ Yes	Can be finalized
Fiscal Validation	❌ No	Not a fiscal document
Allows Editing	✅ Yes	While not closed
Conversion	✅ Yes	Can generate invoice or order

Stock movement

Whether stock moves is determined by the document type configuration. ORC types are normally configured with no stock movement. Line quantities are always positive.

---

Create Quote

Basic Example

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

{
  "serieId": 10,
  "documentTypeId": 1,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "entityDescription": "Potential Client, Ltd",
  "entityVat": "PT123456789",
  "obs": "Quote valid until 12/31/2025",
  "dueDate": "2025-12-31",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 6150
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "itemDescription": "Complete Solution",
      "quantity": 1,
      "retailPrice": 5000,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

Set payments[].amount to the expected document total after taxes and discounts. Resolve paymentTypeId with GET /gateway/payment-types.

Quote with Line Discount

Use discountPercentage (0–100):

{
  "serieId": 10,
  "documentTypeId": 1,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "obs": "Special discount for new customer",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 994.5
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 10,
      "retailPrice": 100,
      "discountPercentage": 15,
      "observation": "Volume discount",
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

Quote with Header Discount

{
  "serieId": 10,
  "documentTypeId": 1,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "discountPercentage": 5,
  "dueDate": "2025-12-31",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 5700
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 1,
      "retailPrice": 5000,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

---

Update and Close Quote

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

{
  "id": 123,
  "obs": "Revised pricing — valid 30 days",
  "dueDate": "2026-01-15"
}

Close when accepted, rejected, or converted:

{
  "id": 123,
  "close": true,
  "obs": "Converted to invoice FT A/456"
}

---

Conversion to Invoice

Conversion is a business process: create a new fiscal document with the approved lines — there is no automatic conversion endpoint.

1. Get the approved quote:

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

2. Create an invoice (FT or FR) with the same commercial data:

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

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

Use Invoices Guide for FT/FS or Invoice-Receipt Guide for FR. Stock movement on the invoice follows the invoice document type configuration.

3. Close the original quote (see above).

---

Best Practices

✅ Recommended

• Always send currencyId and header payments[]
• Include validity date in dueDate
• Detail commercial terms in obs
• Use discountPercentage for promotional discounts
• Close rejected or expired quotes
• Resolve document types with GET /gateway/document-type — Usage Guide

❌ Avoid

• Negative quantities
• Leaving quotes open after conversion

---

Common Use Cases

Simple Proposal

Single product with standard terms and validity date.

Volume Discount Proposal

Progressive discountPercentage on lines based on quantity.

Multi-line Proposal

Several products or services in one quote.

Special Terms Proposal

Custom payment mode referenced via paymentModeId and payments[].

---

Differences vs Invoices

Aspect	Quote (ORC)	Invoice (FT/FS)
Stock	Typically none	Outbound (from type config)
Fiscal	No	Yes
Validity	Limited	Definitive
Editing	Yes (open)	Limited
Purpose	Proposal	Sale

---

Next Steps

• Orders Guide — Convert quote to order (NE)
• Invoices Guide — Convert quote to invoice (FT/FS)
• Usage Guide — General API information

---

Last Updated: June 9, 2026