Every order in the Ecommerce Delivery API follows a strict, linear lifecycle. From the moment a buyer initiates a purchase to the final delivery confirmation, theDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/fredy-rizo/ecommerce-delivery/llms.txt
Use this file to discover all available pages before exploring further.
status field on the Sale document tracks exactly where the order stands. Understanding this lifecycle is essential for correctly integrating both the buyer-facing application and the admin or delivery dashboards.
The five order statuses
Thestatus field is a single {name, value} object — not an array. Only one status is active at a time.
| Value | Name | Meaning |
|---|---|---|
"2" | Pendiente | Order created; awaiting upload of payment proof |
"4" | Validando | Payment proof uploaded; admin is reviewing |
"1" | Pagado | Payment confirmed; product stock has been decremented |
"3" | Cancelado | Order cancelled |
"5" | Entregado | Order delivered to the buyer |
The codeSale order reference
When a sale is first created, the API generates a unique alphanumeric identifier called codeSale using the generateCodeSale() utility. This code is stored on the Sale document and is used throughout the lifecycle — in push notification messages, admin search queries, and buyer-facing receipts — as the human-readable order reference. All status-change notifications sent via Firebase include this code in their message body.
Full lifecycle walkthrough
The buyer calls
POST /api/sale/pay/:productId with their cart details. The API validates stock, calculates the total price, creates a new Sale document, and sets the initial status to Pendiente.{
"cantBuy": 2,
"colorsSize": [{ "label": "Rojo", "value": "red" }],
"sizes": [{ "label": "M", "value": "M" }],
"typeShirt": "polo",
"client": {
"name_client": "Ana",
"lastName_client": "García",
"typeIdentification": "CC",
"identification": "123456789",
"phone_number": "3001234567",
"address": "Calle 10 #5-20",
"email": "ana@example.com",
"zipCode": "110111",
"city": "Bogotá"
}
}
The response includes the full saved
Sale document with status: { name: "Pendiente", value: "2" } and the generated codeSale.The buyer uploads one or more images of their payment receipt via
POST /api/sale/laod-proof/:saleId. The API updates the status to Validando and sends a push notification to every admin user who has an active FCM token registered.POST /api/sale/laod-proof/:saleId
Authorization: Bearer <buyer_jwt>
Content-Type: multipart/form-data
After this call,
status becomes { name: "Validando", value: "4" } and dateproof is set to today’s date. All admin users receive a push notification with the title “Nuevo comprobante de pago”.An admin calls
POST /api/sale/status-change/:saleId with the new status object. When the status is set to Pagado (value: "1"), the API also decrements the minCant (available stock) field on the corresponding Product document by the quantity purchased.POST /api/sale/status-change/:saleId
Authorization: Bearer <admin_jwt>
Content-Type: application/json
The buyer receives a push notification: “Actualizacion de tu pedido” with their
codeSale and the new status name.As the shipment progresses, a delivery agent adds timestamped checkpoint entries via
POST /api/sale/status-delivery/:saleId. Each call pushes a new entry onto the deliveryStatus array without changing the top-level status field.POST /api/sale/status-delivery/:saleId
Authorization: Bearer <delivery_jwt>
Content-Type: application/json
{
"description": "Paquete en camino",
"detail": "Tu pedido salió del centro de distribución en Bogotá"
}
The server auto-stamps
date (YYYY-M-D) and timeHour (hh:mm AM/PM) on each entry. The buyer receives a push notification with the title “Actualizacion en la entrega”.The admin or delivery agent makes a final
POST /api/sale/status-change/:saleId call setting value: "5" to mark the order as delivered.The deliveryStatus array
Unlike the top-level status object, deliveryStatus is an append-only array that builds a full audit trail of the shipment’s physical journey. Each entry has four fields:
| Field | Type | Description |
|---|---|---|
description | String | Short label for the checkpoint (e.g. “En camino”) |
detail | String | Longer description of the event |
date | String | Server-generated date in YYYY-M-D format |
timeHour | String | Server-generated time in hh:mm AM/PM format |