Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/CRISTIANCAMACH34/Zippi/llms.txt

Use this file to discover all available pages before exploring further.

The Business Orders endpoints allow authenticated business roles to view, filter, and act on incoming orders. Every status transition is validated against both the caller’s permissions (e.g. orders.accept, orders.reject) and the order FSM before the change is persisted. Each transition is atomically written to historial_estados_pedido with a correlation_id for full traceability.

​
Order states and business-side FSM transitions

TransitionPermission requiredRoles that hold it
pending → acceptedorders.acceptbusiness_owner, business_admin, business_branch_admin, waiter
pending → rejectedorders.rejectbusiness_owner, business_admin, business_branch_admin, waiter
accepted → preparingorders.preparebusiness_owner, business_admin, business_branch_admin, kitchen_staff
preparing → packedorders.packbusiness_owner, business_admin, business_branch_admin, kitchen_staff
Downstream transitions (courier pickup, in-transit, delivered, closed) are handled by dispatch and courier-side endpoints and are not exposed through the Business Portal.
Every status transition writes an immutable row to historial_estados_pedido. The row stores estado_anterior, estado_nuevo, actor_tipo, actor_id, observacion, correlation_id, and trace_id. This audit trail cannot be modified or deleted via any API endpoint.

​
GET /api/v1/business/orders

Returns a paginated list of orders for the authenticated business scope. Supports filtering by status, branch, and date range. 
curl -X GET "https://api.zippi.app/api/v1/business/orders?status=pending&page=1&page_size=20" \
  -H "Authorization: Bearer <token>"
Query parameters
​
status
string
Filter by order status. Accepted values: pending, accepted, preparing, packed, picked_up, in_transit, delivered, closed, cancelled, failed.
​
page
integer
default:"1"
Page number, 1-indexed.
​
page_size
integer
default:"20"
Records per page. Recommended maximum: 100.
​
branch_id
string
Filter orders for a specific branch. Required when the caller is a business_branch_admin (scope is enforced automatically).
​
from_date
string
ISO 8601 date string (e.g. 2024-06-01). Returns orders created on or after this date.
​
to_date
string
ISO 8601 date string (e.g. 2024-06-30). Returns orders created on or before this date.
Response 200 OK 
{
  "success": true,
  "data": {
    "items": [
      {
        "id_pedido": 1001,
        "codigo_pedido": "ZP-20240601-001",
        "estado_actual": "pending",
        "metodo_pago": "cash",
        "valor_compra_estimado": 2200000,
        "valor_servicio": 350000,
        "fecha_creacion": "2024-06-01T18:45:00Z"
      }
    ],
    "total": 47,
    "page": 1,
    "page_size": 20
  }
}

​
GET /api/v1/business/orders/:id

Returns the full detail of a single order, including line items, status history, courier assignment, and incidents. 
curl -X GET https://api.zippi.app/api/v1/business/orders/1001 \
  -H "Authorization: Bearer <token>"
Response fields
​
id_pedido
integer
Internal primary key of the order.
​
codigo_pedido
string
Human-readable order reference code, unique across the platform.
​
estado_actual
string
Current FSM state of the order.
​
metodo_pago
string
Payment method: cash, nequi, wompi, transfer.
​
valor_servicio
integer
Delivery fee in centavos.
​
valor_compra_estimado
integer | null
Estimated product subtotal in centavos at order creation time.
​
valor_compra_real
integer | null
Confirmed product subtotal in centavos, set when the business confirms the order.
​
valor_total_final
integer | null
Final charged amount in centavos including service fee and adjustments.
​
items
array
​
historial_estados
array
Ordered list of all FSM state transitions for audit purposes.

​
PATCH /api/v1/business/orders/:id/status

Advances the order through the FSM to a new state. The service layer validates the transition against the FSM rules and the caller’s permissions before persisting. 
curl -X PATCH https://api.zippi.app/api/v1/business/orders/1001/status \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"new_status": "accepted"}'

# Rejecting an order with a required reason
curl -X PATCH https://api.zippi.app/api/v1/business/orders/1001/status \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"new_status": "rejected", "reason": "Producto agotado"}'
​
new_status
string
required
Target FSM state. Must be a valid transition from the order’s estado_actual. Accepted business-side values: accepted, rejected, preparing, packed.
​
reason
string
Optional human-readable justification for the transition. Required when new_status is rejected or cancelled. Stored in historial_estados_pedido.observacion.
Response 200 OK 
{
  "success": true,
  "data": {
    "id_pedido": 1001,
    "estado_anterior": "pending",
    "estado_nuevo": "accepted",
    "correlation_id": "corr_a1b2c3d4"
  }
}
The correlation_id returned in the response is the same value written to historial_estados_pedido. Use it to cross-reference log lines, trace distributed events, and correlate audit entries across services.

​
POST /api/v1/business/orders/:id/incident

Reports an operational incident on a specific order (e.g. missing item, wrong product, customer not present). Returns 201 Created. Stored in incidencias_pedido. 
curl -X POST https://api.zippi.app/api/v1/business/orders/1001/incident \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo_incidencia": "producto_faltante",
    "descripcion": "El cliente reportó que faltó una Coca-Cola en el pedido"
  }'
​
tipo_incidencia
string
required
Incident category. Common values: producto_faltante, producto_incorrecto, cliente_ausente, pedido_dañado, otro.
​
descripcion
string
required
Full description of the incident. Stored verbatim for support and dispute resolution.
Response 201 Created 
{
  "success": true,
  "data": {
    "id_incidencia": 55,
    "tipo_incidencia": "producto_faltante",
    "estado_incidencia": "abierta",
    "fecha_creacion": "2024-06-01T19:02:00Z"
  }
}

​
GET /api/v1/business/kitchen/queue

Returns the active kitchen comanda queue for the authenticated branch scope, ordered by creation time. Designed for the kitchen display screen. 
curl -X GET https://api.zippi.app/api/v1/business/kitchen/queue \
  -H "Authorization: Bearer <token>"
Required role: kitchen_staff, business_owner, business_admin, or business_branch_admin (module: orders). The response surfaces orders in accepted or preparing states with their line items expanded, so the kitchen screen can display preparation instructions without additional round-trips.

​
GET /api/v1/business/waiter/floor

Returns the floor map view for the waiter surface: tables with their active orders, seat counts, and pending items that need attention. 
curl -X GET https://api.zippi.app/api/v1/business/waiter/floor \
  -H "Authorization: Bearer <token>"
Required role: waiter, business_owner, business_admin, or business_branch_admin (module: orders). The waiter floor view aggregates orders by table and surfaces pending-acceptance and in-progress items so the front-of-house team can triage service without leaving the floor map.

Build docs developers (and LLMs) love

Get started for freeTalk to us