Skip to main content

​
POST /api/quote-shipping

Calculates shipping cost estimates based on destination and package details. Uses the LogisticsManager to get the best quote from available carriers.

​
Request Body

​
city_code
string
required
DANE destination city code (e.g., “11001” for Bogotá)
​
subdivision_code
string
required
DANE destination department code (e.g., “11” for Cundinamarca)
​
line_items
array
required
Array of items to ship
​
line_items[].weight
number
Weight in kilograms (default: 0.5)
​
line_items[].weight_unit
string
Weight unit (default: “KG”)
​
line_items[].height
number
Height in centimeters (default: 10)
​
line_items[].width
number
Width in centimeters (default: 10)
​
line_items[].length
number
Length in centimeters (default: 10)
​
line_items[].dimensions_unit
string
Dimensions unit (default: “CM”)
​
line_items[].unit_price
number
required
Item unit price
​
line_items[].quantity
number
required
Item quantity
​
payment_method_code
string
Payment method: “COD” or “EXTERNAL_PAYMENT” (default: “EXTERNAL_PAYMENT”)

​
Response

​
success
boolean
Indicates if quote was successful
​
shipping_cost
number
Shipping cost in Colombian pesos
​
carrier
string
Selected carrier name (e.g., “Coordinadora”, “Servientrega”)
​
days
number
Estimated delivery days
​
details
object
Additional quote details for debugging

​
Example Request

curl -X POST http://localhost:3001/api/quote-shipping \
  -H "Content-Type: application/json" \
  -d '{
    "city_code": "11001",
    "subdivision_code": "11",
    "line_items": [
      {
        "weight": 0.15,
        "weight_unit": "KG",
        "height": 12,
        "width": 4,
        "length": 4,
        "dimensions_unit": "CM",
        "unit_price": 89000,
        "quantity": 1
      },
      {
        "weight": 0.2,
        "weight_unit": "KG",
        "height": 15,
        "width": 5,
        "length": 5,
        "dimensions_unit": "CM",
        "unit_price": 65000,
        "quantity": 2
      }
    ],
    "payment_method_code": "COD"
  }'

​
Example Response

{
  "success": true,
  "shipping_cost": 15500,
  "carrier": "Coordinadora",
  "days": 3,
  "details": {
    "cost": 15500,
    "carrier": "Coordinadora",
    "days": 3,
    "service_type": "STANDARD"
  }
}

​
DANE Codes

DANE codes are Colombian administrative division codes. You can find the complete list at DANE’s official website.

​
Common DANE City Codes

CityCity CodeDepartment Code
Bogotá1100111
Medellín0500105
Cali7600176
Barranquilla0800108
Cartagena1300113

​
Origin Configuration

The origin warehouse is automatically configured from environment variables:
  • VENNDELO_PICKUP_NAME
  • VENNDELO_PICKUP_ADDRESS
  • VENNDELO_PICKUP_CITY_CODE
  • VENNDELO_PICKUP_SUBDIVISION_CODE

​
Carrier Selection

The LogisticsManager automatically selects the best carrier based on:
  • Lowest cost
  • Service availability for destination
  • Payment method compatibility (some carriers don’t support COD)

​
Supported Carriers

Currently integrated with:
  • Venndelo (aggregator for multiple carriers)
  • Coordinadora
  • Servientrega
  • Other carriers via Venndelo API

​
Default Dimensions

If dimensions are not provided for line items, the following defaults are used: 
{
  "weight": 0.5,
  "weight_unit": "KG",
  "height": 10,
  "width": 10,
  "length": 10,
  "dimensions_unit": "CM"
}

​
Volumetric Weight

Carriers may apply volumetric weight calculation: 
Volumetric Weight (kg) = (Height × Width × Length) / 5000
The higher value between actual weight and volumetric weight is used for pricing.

​
Error Responses

​
400 Bad Request - Invalid Data

{
  "error": "Datos de cotización inválidos",
  "details": {
    "city_code": {
      "_errors": ["Required"]
    }
  }
}

​
405 Method Not Allowed

{
  "error": "Método no permitido"
}

​
500 Internal Server Error - Logistics Error

{
  "error": "Error al calcular costos de envío",
  "message": "Venndelo API unavailable"
}

​
Performance

Shipping quotes are calculated in real-time by querying the logistics provider’s API. Response times typically range from 500ms to 2 seconds depending on carrier API availability.

​
Caching Recommendations

For production implementations, consider:
  • Caching quotes by destination + weight combination for 5-10 minutes
  • Implementing client-side debouncing for quote requests
  • Showing loading states during API calls

Build docs developers (and LLMs) love

Get started for freeTalk to us