Quotes Guide

Document Type: Quote
Document Type ID: 1 (verify with /document-type)

---

Overview

Quotes are commercial documents that:

• 📝 Present sales proposals to customers
• 💭 DO NOT affect stock
• 💵 DO NOT require immediate payment
• 📄 Serve as a base for future invoices
• ⏱️ Generally have limited validity

When to Use

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

---

Quote Characteristics

Characteristic	Value	Description
Affects Stock	❌ No	Stock is not affected
Requires Payment	❌ No	Proposal only
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/Order

---

Create Quote

Basic Example

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

{
  "serieId": 10,
  "documentTypeId": 1,
  "entityKeyId": "CLI001",
  "entityDescription": "Potential Client, Ltd",
  "entityVat": "PT123456789",
  "obs": "Quote valid until 12/31/2025",
  "dueDate": "2025-12-31",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "itemDescription": "Complete Solution",
      "quantity": 1.0,
      "retailPrice": 5000.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": 0,          // Does NOT affect stock
      "stockBehavior": 0,
      "secondTaxId": 0
    }
  ]
}

Quote with Discount

{
  "serieId": 10,
  "documentTypeId": 1,
  "entityKeyId": "CLI001",
  "obs": "Special discount for new customer",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 10.0,
      "retailPrice": 100.00,
      "discountValue": 15.00,  // 15% discount
      "observation": "Volume discount",
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": 0,
      "stockBehavior": 0,
      "secondTaxId": 0
    }
  ]
}

---

Conversion to Invoice

Step by Step

1. Get approved quote:

GET /api/v1/invoices/123
Authorization: Bearer {token}

2. Create invoice with the same data:

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

{
  "serieId": 1,                // Invoice series
  "documentTypeId": 5,         // Invoice
  "entityKeyId": "CLI001",     // Same customer
  "docReference": "QT A/123",  // Reference to quote
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 1.0,
      "retailPrice": 5000.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": 1,          // NOW affects stock
      "stockBehavior": 1,
      "secondTaxId": 0
    }
  ]
}

3. Close original quote:

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

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

---

Best Practices

✅ Recommended

• Include validity date in dueDate field
• Detail commercial terms in obs field
• Reference customer's RFQ in docReference
• Include promotional discounts in discountValue
• Close rejected or expired quotes

❌ Avoid

• Creating quotes without validity date
• Leaving quotes open indefinitely
• Forgetting to reference quote in invoice
• Setting stockFlow != 0 (quotes don't affect stock)

---

Common Use Cases

Simple Proposal

Quote for single product with standard terms.

Volume Discount Proposal

Quote with progressive discount based on quantity.

Multi-line Proposal

Quote with multiple products/services.

Special Terms Proposal

Quote with customized payment or delivery terms.

---

Differences vs Invoices

Aspect	Quote	Invoice
Stock	Does not affect	Affects (outbound)
Fiscal	No	Yes
Validity	Limited	Definitive
Editing	Yes (open)	Limited
Purpose	Proposal	Sale

---

Next Steps

• Orders Guide - Convert quote to order
• Invoices Guide - Convert quote to invoice
• Usage Guide - General API information

---

Last Updated: December 2, 2025