Create Quotation

Endpoint

POST /api/quotations

Creates a new quotation with nested sections and items. This endpoint is implemented in src/controllers/quotationController.js:14.

Request Body

All fields are required. The request must include a complete quotation object with at least one section containing at least one item.

Required Fields

Root Level Fields

Field	Type	Description
`factory`	String	Factory or project identifier
`fix`	String	Fix reference number
`description_quotation`	String	Overall description of the quotation
`subtotal`	Number	Subtotal before additional costs
`unexpected`	Number	Unexpected costs or contingency
`iva`	Number	VAT/IVA tax amount
`administratitive`	Number	Administrative costs
`utility`	Number	Utility or profit margin
`total_price`	Number	Final total price
`sections`	Array	Array of section objects (must have at least one)

Section Object Fields

Each object in the sections array must contain:

Field	Type	Description
`description_sections`	String	Description of the section
`section_price`	Number	Total price for this section
`items`	Array	Array of item objects (must have at least one)

Item Object Fields

Each object in the items array must contain:

Field	Type	Description
`item_name`	String	Name of the item
`item_description`	String	Detailed item description
`item_total`	Number	Total cost for this item (quantity × item_value)
`quantity`	Number	Quantity of items
`unity`	String	Unit of measurement
`item_value`	Number	Unit price per item

Creating a Quotation

Prepare quotation data

Organize your quotation with factory info, fix reference, and description.

Structure sections

Group related items into logical sections (e.g., “Foundation Work”, “Electrical”, “Plumbing”).

Add items to sections

Define individual items with quantities, units, and pricing for each section.

Calculate totals

Compute subtotal, taxes, administrative costs, and final total_price.

Send POST request

Submit the complete JSON payload to the API endpoint.

Request Example

Basic Quotation with Single Section

{
  "factory": "Construction Co. Factory A",
  "fix": "FIX-2026-001",
  "description_quotation": "Residential building foundation work",
  "subtotal": 25000.00,
  "unexpected": 1250.00,
  "iva": 4987.50,
  "administratitive": 1500.00,
  "utility": 2500.00,
  "total_price": 35237.50,
  "sections": [
    {
      "description_sections": "Foundation and Structural Work",
      "section_price": 25000.00,
      "items": [
        {
          "item_name": "Concrete Foundation",
          "item_description": "High-strength concrete mix for foundation base",
          "item_total": 15000.00,
          "quantity": 30,
          "unity": "m3",
          "item_value": 500.00
        },
        {
          "item_name": "Steel Rebar",
          "item_description": "Grade 60 steel reinforcement bars",
          "item_total": 10000.00,
          "quantity": 2000,
          "unity": "kg",
          "item_value": 5.00
        }
      ]
    }
  ]
}

Complete Quotation with Multiple Sections

Show View full example with multiple sections

{
  "factory": "MegaBuild Factory",
  "fix": "FIX-2026-042",
  "description_quotation": "Complete office building renovation - 3 floors",
  "subtotal": 120000.00,
  "unexpected": 6000.00,
  "iva": 23940.00,
  "administratitive": 7200.00,
  "utility": 12000.00,
  "total_price": 169140.00,
  "sections": [
    {
      "description_sections": "Structural Repairs",
      "section_price": 45000.00,
      "items": [
        {
          "item_name": "Column Reinforcement",
          "item_description": "Carbon fiber wrapping for column strengthening",
          "item_total": 18000.00,
          "quantity": 12,
          "unity": "units",
          "item_value": 1500.00
        },
        {
          "item_name": "Beam Repair",
          "item_description": "Concrete beam crack repair and reinforcement",
          "item_total": 15000.00,
          "quantity": 25,
          "unity": "meters",
          "item_value": 600.00
        },
        {
          "item_name": "Foundation Underpinning",
          "item_description": "Foundation stabilization work",
          "item_total": 12000.00,
          "quantity": 15,
          "unity": "m3",
          "item_value": 800.00
        }
      ]
    },
    {
      "description_sections": "Electrical Systems",
      "section_price": 35000.00,
      "items": [
        {
          "item_name": "Main Electrical Panel",
          "item_description": "400A main distribution panel with breakers",
          "item_total": 8000.00,
          "quantity": 1,
          "unity": "unit",
          "item_value": 8000.00
        },
        {
          "item_name": "Commercial Wiring",
          "item_description": "12 AWG copper wiring for outlets and lighting",
          "item_total": 15000.00,
          "quantity": 1500,
          "unity": "meters",
          "item_value": 10.00
        },
        {
          "item_name": "LED Light Fixtures",
          "item_description": "Energy-efficient LED panel lights",
          "item_total": 12000.00,
          "quantity": 80,
          "unity": "units",
          "item_value": 150.00
        }
      ]
    },
    {
      "description_sections": "HVAC Installation",
      "section_price": 40000.00,
      "items": [
        {
          "item_name": "Central AC Units",
          "item_description": "Commercial-grade air conditioning units",
          "item_total": 25000.00,
          "quantity": 5,
          "unity": "units",
          "item_value": 5000.00
        },
        {
          "item_name": "Ductwork",
          "item_description": "Galvanized steel ductwork and fittings",
          "item_total": 10000.00,
          "quantity": 200,
          "unity": "meters",
          "item_value": 50.00
        },
        {
          "item_name": "Ventilation Grilles",
          "item_description": "Adjustable air supply and return grilles",
          "item_total": 5000.00,
          "quantity": 100,
          "unity": "units",
          "item_value": 50.00
        }
      ]
    }
  ]
}

Response

Success Response (201 Created)

{
  "message": "Cotización almacenada correctamente",
  "quotation": {
    "_id": "65abc123def456789",
    "factory": "Construction Co. Factory A",
    "fix": "FIX-2026-001",
    "description_quotation": "Residential building foundation work",
    "subtotal": 25000.00,
    "unexpected": 1250.00,
    "iva": 4987.50,
    "administratitive": 1500.00,
    "utility": 2500.00,
    "total_price": 35237.50,
    "sections": [
      {
        "description_sections": "Foundation and Structural Work",
        "section_price": 25000.00,
        "items": [
          {
            "item_name": "Concrete Foundation",
            "item_description": "High-strength concrete mix for foundation base",
            "item_total": 15000.00,
            "quantity": 30,
            "unity": "m3",
            "item_value": 500.00,
            "_id": "65abc123def456790"
          },
          {
            "item_name": "Steel Rebar",
            "item_description": "Grade 60 steel reinforcement bars",
            "item_total": 10000.00,
            "quantity": 2000,
            "unity": "kg",
            "item_value": 5.00,
            "_id": "65abc123def456791"
          }
        ],
        "_id": "65abc123def456792"
      }
    ],
    "__v": 0
  }
}

Error Responses

400 Bad Request - Invalid Format

{
  "error": "Formato de JSON inválido"
}

This error occurs when:

Any required root-level field is missing
sections is not an array
Any numeric field is undefined (note: 0 is valid)
Required nested fields in sections or items are missing

500 Internal Server Error

{
  "message": "Error al almacenar la cotización",
  "error": "[Error details]"
}

This error occurs when there’s a database or server-side issue.

Validation Logic

The controller implements validation at src/controllers/quotationController.js:18-24:

if (!data || !data.factory || !data.fix || !data.description_quotation || 
    data.subtotal === undefined || data.unexpected === undefined || 
    data.iva === undefined || data.administratitive === undefined || 
    data.utility === undefined || data.total_price === undefined || 
    !Array.isArray(data.sections)) {
  return res.status(400).json({ error: "Formato de JSON inválido" });
}

Notice that numeric fields check for undefined rather than falsy values. This means you can send 0 as a valid value for any numeric field.

Best Practices

Always ensure that:

item_total equals quantity × item_value for each item
section_price represents the sum of all item_total values in that section
Financial calculations are accurate before submission

Consider these tips:

Use descriptive section names that group related work
Include detailed item descriptions for clarity
Use standard units of measurement (m2, m3, kg, units, meters)
Double-check all calculations before submitting

Code Example

Using JavaScript Fetch API

const createQuotation = async () => {
  const quotationData = {
    factory: "Construction Co. Factory A",
    fix: "FIX-2026-001",
    description_quotation: "Residential building foundation work",
    subtotal: 25000.00,
    unexpected: 1250.00,
    iva: 4987.50,
    administratitive: 1500.00,
    utility: 2500.00,
    total_price: 35237.50,
    sections: [
      {
        description_sections: "Foundation and Structural Work",
        section_price: 25000.00,
        items: [
          {
            item_name: "Concrete Foundation",
            item_description: "High-strength concrete mix for foundation base",
            item_total: 15000.00,
            quantity: 30,
            unity: "m3",
            item_value: 500.00
          },
          {
            item_name: "Steel Rebar",
            item_description: "Grade 60 steel reinforcement bars",
            item_total: 10000.00,
            quantity: 2000,
            unity: "kg",
            item_value: 5.00
          }
        ]
      }
    ]
  };

  try {
    const response = await fetch('http://localhost:3000/api/quotations', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(quotationData)
    });

    const result = await response.json();
    
    if (response.ok) {
      console.log('Quotation created:', result.quotation._id);
      return result.quotation;
    } else {
      console.error('Error:', result.error || result.message);
      throw new Error(result.error || result.message);
    }
  } catch (error) {
    console.error('Request failed:', error);
    throw error;
  }
};

Using cURL

curl -X POST http://localhost:3000/api/quotations \
  -H "Content-Type: application/json" \
  -d '{
    "factory": "Construction Co. Factory A",
    "fix": "FIX-2026-001",
    "description_quotation": "Residential building foundation work",
    "subtotal": 25000.00,
    "unexpected": 1250.00,
    "iva": 4987.50,
    "administratitive": 1500.00,
    "utility": 2500.00,
    "total_price": 35237.50,
    "sections": [
      {
        "description_sections": "Foundation and Structural Work",
        "section_price": 25000.00,
        "items": [
          {
            "item_name": "Concrete Foundation",
            "item_description": "High-strength concrete mix for foundation base",
            "item_total": 15000.00,
            "quantity": 30,
            "unity": "m3",
            "item_value": 500.00
          },
          {
            "item_name": "Steel Rebar",
            "item_description": "Grade 60 steel reinforcement bars",
            "item_total": 10000.00,
            "quantity": 2000,
            "unity": "kg",
            "item_value": 5.00
          }
        ]
      }
    ]
  }'

Get Started

Authentication

Quotations

Guides

Endpoint

Request Body

Required Fields

Creating a Quotation

Request Example

Basic Quotation with Single Section

Complete Quotation with Multiple Sections

Response

Success Response (201 Created)

Error Responses

Validation Logic

Best Practices

Code Example

Using JavaScript Fetch API

Using cURL

Build docs developers (and LLMs) love

Get Started

Authentication

Quotations

Guides

​Endpoint

​Request Body

​Required Fields

​Creating a Quotation

​Request Example

​Basic Quotation with Single Section

​Complete Quotation with Multiple Sections

​Response

​Success Response (201 Created)

​Error Responses

​Validation Logic

​Best Practices

​Code Example

​Using JavaScript Fetch API

​Using cURL

Build docs developers (and LLMs) love

Endpoint

Request Body

Required Fields

Creating a Quotation

Request Example

Basic Quotation with Single Section

Complete Quotation with Multiple Sections

Response

Success Response (201 Created)

Error Responses

Validation Logic

Best Practices

Code Example

Using JavaScript Fetch API

Using cURL