Orders API
Cancelar pedido
Usa este endpoint para cancelaciones manuales de operación. No es un cambio genérico de estado con PUT: el backend valida permisos, marca el pedido como cancelled, libera la ruta activa cuando corresponde y publica los eventos operativos asociados.
Campos principales
Resumen de los campos relevantes para este endpoint.
| Campo | Tipo | Uso | Descripción |
|---|---|---|---|
orderId | uuid | Path param | Identificador del pedido activo que se quiere cancelar. |
Authorization | Bearer token | Header obligatorio | Token de una cuenta dispatcher vinculada al pedido o de una cuenta restaurante vinculada al restaurante del pedido. |
body | none | No requerido | No hace falta enviar payload. El actor que cancela se resuelve desde el token autenticado. |
Roles permitidos
El endpoint cubre el mismo flujo de cancelación manual usado por el frontend de dispatcher y restaurante.
- Un dispatcher puede cancelar pedidos activos asignados a su dispatcher.
- Un restaurante puede cancelar pedidos activos de su restaurante antes de una asignación activa a route o rider.
- Un restaurante solo puede cancelar pedidos ya asignados a route o rider si la relación con el dispatcher tiene allowRestaurantOrderCancellationOverride activado.
- Los riders no pueden cancelar pedidos con este endpoint.
Efectos de la cancelación
La cancelación manual conserva trazabilidad y no se mezcla con incidencias operativas reportadas por riders.
- El pedido pasa a currentStatus = cancelled.
- El historial de estado guarda metadata de cancelación manual, estado anterior, si había route activa y si se permitió por override.
- Si el pedido estaba en una route activa, OperioHub libera el pedido de esa route y emite eventos de actualización.
- Los pedidos cerrados delivered, failed o cancelled no pueden cancelarse otra vez.
Diferencia con actualizar estado
Hay dos formas válidas de llegar a cancelled según el caso de uso.
- Para cancelación manual desde dispatcher o restaurante, usa POST /api/orders/:orderId/cancel.
- Para una integración dispatcher que sincroniza estados externos, POST /api/orders/:orderId/status puede recibir currentStatus = cancelled y aplicará la misma lógica interna.
- No uses PUT /api/orders/:orderId como contrato público para cancelar pedidos manualmente.
Request cURL como dispatcher
curl -X POST 'https://api.operiohub.com/api/orders/11111111-1111-4111-8111-111111111111/cancel' \
-H 'Authorization: Bearer YOUR_DISPATCHER_TOKEN'Request cURL como restaurante
curl -X POST 'https://api.operiohub.com/api/orders/11111111-1111-4111-8111-111111111111/cancel' \
-H 'Authorization: Bearer YOUR_RESTAURANT_TOKEN'Respuesta 200
{
"data": {
"orderId": "11111111-1111-4111-8111-111111111111",
"dispatchOrderId": "POS-93442",
"currentStatus": "cancelled",
"createdAt": "2026-06-20T10:00:00.000Z",
"updatedAt": "2026-06-20T10:15:00.000Z"
}
}Consola de prueba
Cancelar pedido
Pega un token dispatcher o restaurante, indica el orderId y ejecuta la cancelación manual. La petición impacta el pedido real asociado al token.
Errores esperados
Respuestas habituales que debe contemplar la integración.
Parámetros inválidos
El orderId del path no tiene formato uuid válido.
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.
Actor no autorizado
El actor es rider, el dispatcher no está vinculado al pedido, el restaurante no está vinculado al pedido o falta el override para cancelar un pedido con route activa.
Pedido ya cerrado
El pedido ya está delivered, failed o cancelled.
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": "restaurant_cancellation_override_required"
}