Marketplace externo
Actualizar el estado del pedido externo
Usa operations.status.url y operations.status.bearerToken del evento marketplace_order.awarded. Esta capacidad solo sirve para la adjudicación y el pedido indicados; no uses el Primary Token del dispatcher, el token de tracking ni el token de chat.
Requisitos para solicitud y respuesta
- Enviar Authorization: Bearer STATUS_TOKEN.
- El STATUS_TOKEN vence y se revoca al cancelar el pedido o fallar la adjudicación.
- La misma petición de un estado ya cerrado es idempotente; no se puede reabrir un pedido.
- Una posición de tracking no cambia estados: el estado y la ubicación deben enviarse por este endpoint cuando la transición lo requiera.
Campos principales
Resumen de los campos relevantes para este endpoint.
| Campo | Tipo | Uso | Descripción |
|---|---|---|---|
orderId | uuid | Path param | Debe coincidir con el pedido vinculado al STATUS_TOKEN. |
currentStatus | string | Obligatorio | going_to_pickup, arrived_at_pickup, in_route, arrived_at_dropoff, delivered, failed o cancelled. No se acepta pending_approval ni dispatcher_accepted. |
location | object | Según transición | Evidencia efímera para validar una llegada. Incluir lat y lng juntos cuando sea obligatoria. |
location.lat / location.lng | number | Obligatorio con location | Coordenadas WGS84 del rider en el momento del cambio. |
location.accuracy | number | Opcional | Precisión horizontal en metros. Si se envía, debe ser menor o igual que 100 m. |
Límites de ubicación
La ubicación aportada es evidencia de la transición, no una actualización de tracking ni una posición persistida.
- arrived_at_pickup: location obligatoria, a ≤100 m de recogida.
- in_route desde dispatcher_accepted o going_to_pickup: location obligatoria, a ≤100 m de recogida.
- arrived_at_dropoff: location obligatoria, a ≤100 m de destino.
- delivered desde in_route: location obligatoria, a ≤100 m de destino.
- Si se facilita location.accuracy, debe ser ≤100 m; una precisión superior se rechaza con 400.
- failed y cancelled no requieren ubicación. delivered desde arrived_at_dropoff tampoco requiere una nueva ubicación.
Transiciones permitidas
La adjudicación deja el pedido en dispatcher_accepted; ese estado inicial no se solicita a través de esta API.
- 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.
- Los atajos a in_route y delivered insertan la llegada intermedia solo cuando la ubicación acredita el radio exigido.
Alcance de la credencial
La adjudicación entrega tres capacidades independientes.
- STATUS_TOKEN autoriza exclusivamente este endpoint para el pedido y la propuesta adjudicada.
- TRACKING_TOKEN solo autoriza POST /api/marketplace/orders/:orderId/external-rider-location.
- CHAT_TOKEN solo autoriza los mensajes de incidencias. Ninguno de estos tokens es intercambiable.
Request JSON
{
"currentStatus": "arrived_at_pickup",
"location": {
"lat": 38.344498,
"lng": -0.509259,
"accuracy": 8
}
}Request cURL
curl -X POST 'https://api.operiohub.com/api/marketplace/orders/11111111-1111-4111-8111-111111111111/external-status' \
+ -H 'Authorization: Bearer STATUS_TOKEN' \
+ -H 'Content-Type: application/json' \
+ -d '{"currentStatus":"arrived_at_pickup","location":{"lat":38.344498,"lng":-0.509259,"accuracy":8}}'Respuesta 200
{
"data": {
"orderId": "11111111-1111-4111-8111-111111111111",
"currentStatus": "arrived_at_pickup",
"updatedAt": "2026-07-16T10:25:00.000Z"
}
}Errores esperados
Respuestas habituales que debe contemplar la integración.
Solicitud inválida
El estado no está permitido, faltan coordenadas necesarias o accuracy es superior a 100 m.
Token de estado inválido
Falta el Bearer, no existe, ha caducado o fue revocado.
Pedido no coincide
El STATUS_TOKEN pertenece a otra adjudicación o a otro pedido.
Transición o llegada no válida
El salto no está permitido o la ubicación queda fuera del radio de 100 m de recogida o destino.