Orders API
Actualizar estado de pedido
Este endpoint está pensado para integraciones del dispatcher y paneles externos que necesitan reflejar estados como recogido, en ruta o entregado. Solo permite cambiar el estado de pedidos vinculados al dispatcher autenticado. La ubicación se usa únicamente como evidencia efímera de llegada, no se almacena y no actualiza el tracking live del rider. Para una flota adjudicada en Marketplace externo, usa su contrato y credencial temporal específicos. Para cancelaciones manuales desde dispatcher o restaurante, usa POST /api/orders/:orderId/cancel.
Requisitos para estados sin validación física
- El pedido debe pertenecer al dispatcher autenticado.
- No se puede solicitar pending_approval.
- dispatcher_accepted, going_to_pickup, failed y cancelled no requieren location.
- cancelled reutiliza la lógica de cancelación y libera la ruta activa cuando corresponde.
- Si la cancelación no viene de una integración dispatcher sino de operación manual, usa POST /api/orders/:orderId/cancel.
Requisitos para estados con validación de llegada
- arrived_at_pickup valida location contra el punto de recogida.
- in_route valida location contra recogida si el pedido aún no acreditó recogida.
- arrived_at_dropoff valida location contra el punto de entrega.
- delivered valida location contra entrega si el pedido aún no acreditó llegada a entrega.
Campos principales
Resumen de los campos relevantes para este endpoint.
| Campo | Tipo | Uso | Descripción |
|---|---|---|---|
orderId | uuid | Path param | Identificador del pedido devuelto por OperioHub al crearlo. |
currentStatus | string | Obligatorio | Estado solicitado: dispatcher_accepted, going_to_pickup, arrived_at_pickup, in_route, arrived_at_dropoff, delivered, failed o cancelled. pending_approval no está permitido. |
location | object | Según transición | Evidencia efímera de ubicación para validar recogida o entrega cuando el cambio de estado implica una llegada. Acepta lat, lng y accuracy opcional. |
location.lat | number | Obligatorio si se envia location | Latitud del rider en el momento de la transición. No se almacena. |
location.lng | number | Obligatorio si se envia location | Longitud del rider en el momento de la transición. No se almacena. |
location.accuracy | number | Opcional | Precisión horizontal en metros. Si se envía, debe ser menor o igual que 100 m. |
Reglas de estados
El endpoint separa el contrato público de integraciones del PUT interno de pedidos.
- pending_approval está bloqueado para evitar reasignaciones o reaperturas antes de aceptación.
- Los pedidos cerrados no se reabren: delivered, failed y cancelled solo admiten repetir el mismo estado de forma idempotente.
- La integracion no puede cambiar el dispatcher del pedido.
- Los saltos que no se puedan validar con una sola ubicación se rechazan.
- location acepta { lat, lng, accuracy? }; no se almacenan esos valores y no actualizan el tracking live del rider.
- cancelled no requiere location.
- Para cancelación manual desde una cuenta dispatcher o restaurante, usa POST /api/orders/:orderId/cancel; este endpoint de status queda reservado para integraciones dispatcher.
- Si el pedido tiene onOrderStatusWebhook configurado, OperioHub enviará order.status_changed tras persistir el cambio.
Transiciones soportadas
Los saltos directos soportados pueden crear eventos intermedios automáticos cuando la ubicación permite acreditar una llegada.
- pending_approval -> dispatcher_accepted.
- dispatcher_accepted -> going_to_pickup, in_route, failed o cancelled.
- going_to_pickup -> arrived_at_pickup, in_route, failed o cancelled.
- arrived_at_pickup -> in_route, failed o cancelled.
- in_route -> arrived_at_dropoff, delivered, failed o cancelled.
- arrived_at_dropoff -> delivered, failed o cancelled.
- delivered, failed y cancelled son estados cerrados.
Marketplace externo
Una flota externa adjudicada usa un contrato Marketplace separado de esta API de Dispatcher.
- El token de tracking externo no autoriza cambios de estado; solo permite publicar ubicación en POST /api/marketplace/orders/:orderId/external-rider-location.
- Para cambiar estados, la flota debe usar operations.status.url y el STATUS_TOKEN temporal recibidos en la adjudicación, no el Primary Token de Dispatcher.
- Consulta la ficha Marketplace externo: Actualizar el estado del pedido externo.
- No documentes ni implementes una transición de estado basada únicamente en la llegada de una posición de tracking.
Request JSON
{
"currentStatus": "going_to_pickup"
}Request cURL
curl -X POST 'https://api.operiohub.com/api/orders/11111111-1111-4111-8111-111111111111/status' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"currentStatus": "in_route",
"location": {
"lat": 38.344498,
"lng": -0.509259
}
}'Cancelar sin ubicación
curl -X POST 'https://api.operiohub.com/api/orders/11111111-1111-4111-8111-111111111111/status' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"currentStatus": "cancelled"
}'Respuesta 200
{
"data": {
"orderId": "11111111-1111-4111-8111-111111111111",
"dispatchOrderId": "EXT-1001",
"currentStatus": "in_route",
"createdAt": "2026-06-20T10:00:00.000Z",
"updatedAt": "2026-06-20T10:05:00.000Z"
}
}Consola de prueba
Actualizar estado
Pega un token dispatcher, indica el orderId y prueba el cambio de estado con un payload editable. La petición impacta el pedido real asociado al token.
Errores esperados
Respuestas habituales que debe contemplar la integración.
Payload inválido
El body no cumple el esquema esperado, incluye campos no permitidos, usa un orderId no uuid o solicita pending_approval.
Ubicación requerida
La transición necesita validar recogida o entrega y no se ha enviado location.lat/lng.
Coordenadas objetivo requeridas
El pedido no tiene coordenadas de recogida o entrega necesarias para validar la llegada.
AUTH_MISSING_TOKEN Token requerido
No se ha enviado token en Authorization ni x-api-token.
AUTH_INVALID_TOKEN Token inválido
Token inexistente, expirado o no resoluble.
Dispatcher requerido
El token autenticado no pertenece a una cuenta dispatcher.
Pedido no vinculado
El pedido no pertenece al dispatcher autenticado.
Fuera de radio
La ubicación enviada no está dentro del radio aceptado para la recogida o entrega.
Transición no soportada
El salto solicitado no está permitido o intenta reabrir un pedido cerrado.
RATE_LIMIT_EXCEEDED Too Many Requests
Más de 100 peticiones de mutación por minuto para la misma IP o identidad.
Ejemplo de error
{
"error": "location is required for this order status transition"
}