Skip to main content

​
GET /api/track-order

Tracks an order by its ID, returning current status and shipment details. Supports multiple ID formats for flexible lookups.

​
Query Parameters

​
id
string
required
Order identifier. Accepts multiple formats:
  • Readable order ID (e.g., “1050”)
  • Database UUID
  • Venndelo external ID
  • Tracking number/guide

​
Response

​
id
string
Venndelo order ID
​
readable_id
number
Human-readable KAIU order number (e.g., 1050)
​
pin
string
Venndelo PIN number
​
status
string
Order status: PENDING, APPROVED, SENT, DELIVERED, CANCELLED
​
fulfillment_status
string
Fulfillment status from logistics provider
​
tracking_url
string
URL for tracking shipment on carrier website
​
carrier
string
Carrier name (e.g., “Coordinadora”, “Servientrega”)
​
tracking_number
string
Carrier tracking/guide number
​
created_at
string
Order creation timestamp (ISO 8601)
​
total
number
Total order amount

​
Example Request by Readable ID

curl http://localhost:3001/api/track-order?id=1050

​
Example Request by Tracking Number

curl http://localhost:3001/api/track-order?id=70012345678901

​
Example Response

{
  "id": "VND-2026-001234",
  "readable_id": 1050,
  "pin": "567890",
  "status": "SENT",
  "fulfillment_status": "IN_TRANSIT",
  "tracking_url": "https://www.coordinadora.com/portafolio-de-servicios/servicios-online/rastreo/",
  "carrier": "Coordinadora",
  "tracking_number": "70012345678901",
  "created_at": "2026-03-04T10:30:00.000Z",
  "total": 104500
}

​
Order Status Values

StatusDescription
PENDINGOrder created, awaiting payment/confirmation
APPROVEDPayment confirmed, ready for fulfillment
SENTShipment created and picked up by carrier
DELIVEREDPackage delivered to customer
CANCELLEDOrder cancelled

​
Fulfillment Status Values

Fulfillment status provides more granular tracking:
StatusDescription
PENDINGAwaiting pickup
PICKED_UPPicked up by carrier
IN_TRANSITIn transit to destination
OUT_FOR_DELIVERYOut for delivery
DELIVEREDSuccessfully delivered
FAILEDDelivery failed
RETURNEDReturned to sender

​
ID Resolution Strategy

The endpoint uses intelligent ID resolution:
  1. Numeric check: If the ID is a number ≤ 2,147,483,647, it’s treated as a readable ID
  2. Database lookup: Searches by readableId, UUID id, externalId, and trackingNumber
  3. Venndelo query: Fetches the last 100 orders from Venndelo API
  4. Match: Finds matching order by ID, PIN, or tracking number
  5. Fallback: Returns local database data if not found in Venndelo
The endpoint searches the last 100 orders from Venndelo. For older orders not in this range, it returns data from the local database.

​
Data Privacy

The response includes only safe, customer-facing fields. Sensitive information like payment details, customer PII, and internal notes are filtered out.

​
Example: Local Database Fallback

If an order exists in the database but not in Venndelo’s last 100 orders: 
{
  "id": "VND-2025-000123",
  "readable_id": 123,
  "status": "DELIVERED",
  "created_at": "2025-11-15T14:20:00.000Z",
  "total": 95000,
  "carrier": "Coordinadora",
  "tracking_number": "70098765432109",
  "tracking_url": "https://www.coordinadora.com/portafolio-de-servicios/servicios-online/rastreo/"
}

​
Error Responses

​
400 Bad Request - Missing ID

{
  "error": "Falta parametro ID"
}

​
404 Not Found

{
  "error": "Orden no encontrada en sistema logístico."
}

​
405 Method Not Allowed

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

​
500 Internal Server Error

{
  "error": "Error Interno"
}

​
502 Bad Gateway - Venndelo API Error

If the Venndelo API returns an error, the endpoint returns: 
{
  "error": "Error consultando Venndelo"
}

​
Integration with Venndelo

The endpoint integrates with Venndelo’s API: 
GET https://api.venndelo.com/v1/admin/orders?page_size=100&status=ANY
Headers: 
X-Venndelo-Api-Key: YOUR_API_KEY

​
CORS Headers

The endpoint includes full CORS support:
  • Access-Control-Allow-Origin: *
  • Access-Control-Allow-Methods: GET, OPTIONS
  • Access-Control-Allow-Credentials: true

​
Performance Considerations

  • Database Query: ~10-50ms
  • Venndelo API Call: ~500-2000ms
  • Total Response Time: ~600-2500ms
For better performance, consider implementing a caching layer for frequently tracked orders (5-minute cache TTL).

​
Using Readable IDs

Readable IDs are customer-friendly order numbers: 
# Customer sees: "Your order #1050"
curl http://localhost:3001/api/track-order?id=1050
These are auto-incrementing integers stored in the database, making them easier for customers to remember and communicate than UUIDs.

​
Tracking URL Format

The tracking_url field provides a direct link to the carrier’s tracking page. Customers can click this link to see real-time updates on the carrier’s website.

Build docs developers (and LLMs) love

Get started for freeTalk to us