Routes API
Asignar pedidos a riders en bulk
Cada item crea una route para un rider y puede incluir pedidos de varios restaurantes, incluidos restaurantes externos sin usuario, siempre que esos pedidos ya pertenezcan al dispatcher autenticado mediante order_budgets. El dispatcher se resuelve desde el token, no desde el body. Si una asignacion falla, el resto puede completarse y el error queda codificado en results[].error.
Campos principales
Resumen de los campos relevantes para este endpoint.
| Campo | Tipo | Uso | Descripción |
|---|---|---|---|
assignments | array | Obligatorio | Lista de grupos de asignacion. Maximo 100 grupos por peticion. |
assignments[].riderId | uuid | Obligatorio | Rider que recibira la route. Debe pertenecer al dispatcher autenticado y estar online. |
assignments[].orderIds | uuid[] | Obligatorio | Pedidos que se asignan al rider. Maximo 50 por grupo y 500 en total. Pueden pertenecer a restaurantes distintos. |
Request JSON
{
"assignments": [
{
"riderId": "8c385706-6a67-4fba-84ea-0d653f5d3928",
"orderIds": [
"aaaaaaaa-1111-4111-8111-111111111111",
"bbbbbbbb-2222-4222-8222-222222222222"
]
},
{
"riderId": "9f496817-7b78-4acb-9d33-1e764f6e4a10",
"orderIds": [
"cccccccc-3333-4333-8333-333333333333"
]
}
]
}Respuesta con exito parcial
{
"data": {
"results": [
{
"assignmentIndex": 0,
"status": "created",
"routeId": "44444444-4444-4444-8444-444444444444",
"riderId": "8c385706-6a67-4fba-84ea-0d653f5d3928",
"orderIds": [
"aaaaaaaa-1111-4111-8111-111111111111",
"bbbbbbbb-2222-4222-8222-222222222222"
],
"route": {
"routeId": "44444444-4444-4444-8444-444444444444",
"riderId": "8c385706-6a67-4fba-84ea-0d653f5d3928",
"orderIds": [
"aaaaaaaa-1111-4111-8111-111111111111",
"bbbbbbbb-2222-4222-8222-222222222222"
],
"riderBudgetTotalAmount": "7.80",
"riderBudgetCurrency": "EUR",
"createdAt": "2026-06-17T10:00:00.000Z",
"updatedAt": "2026-06-17T10:00:00.000Z"
}
},
{
"assignmentIndex": 1,
"status": "failed",
"riderId": "9f496817-7b78-4acb-9d33-1e764f6e4a10",
"orderIds": [
"cccccccc-3333-4333-8333-333333333333"
],
"error": {
"code": "ROUTE_BULK_RIDER_OFFLINE",
"message": "Rider must be online before assigning a route"
}
}
],
"summary": {
"requested": 2,
"created": 1,
"alreadyExisting": 0,
"failed": 1
}
}
}Consola de prueba
Prueba una asignacion bulk
Pega un token dispatcher, ajusta el payload y envía una asignacion bulk desde esta página. El dispatcher se toma del token autenticado y la petición impacta rutas reales asociadas a ese token.
Errores esperados
Respuestas habituales que debe contemplar la integración.
ROUTE_BULK_INVALID_PAYLOAD Payload invalido
El body no cumple el esquema esperado o supera los limites: 100 asignaciones, 50 pedidos por asignacion o 500 pedidos totales.
AUTH_MISSING_TOKEN Token requerido
No se ha enviado token en Authorization ni x-api-token.
AUTH_INVALID_AUTHORIZATION_HEADER Cabecera Authorization invalida
La cabecera Authorization no tiene un formato valido.
AUTH_INVALID_TOKEN Token invalido
Token inexistente, expirado o no resoluble.
AUTH_DISPATCHER_ROLE_REQUIRED Rol dispatcher requerido
La cuenta autenticada no tiene rol dispatcher.
ROUTE_BULK_DUPLICATE_RIDER_IN_REQUEST Rider duplicado en el lote
Un mismo riderId aparece en mas de un item. Agrupa todos sus pedidos en una unica asignacion.
ROUTE_BULK_DUPLICATE_ORDER_IN_REQUEST Pedido duplicado en el lote
Un mismo orderId aparece en mas de una asignacion del mismo lote.
ROUTE_BULK_RIDER_OFFLINE Rider offline
El rider no esta online segun la presencia vigente y no puede recibir una route.
ROUTE_BULK_RIDER_NOT_FOUND Rider no encontrado
El rider no existe o no pertenece al dispatcher autenticado.
ROUTE_BULK_RIDER_ACTIVE_ROUTE Rider ocupado
El rider ya tiene una route activa con pedidos no cerrados.
ROUTE_BULK_ORDER_NOT_FOUND Pedido no encontrado
El pedido no existe o no pertenece al dispatcher autenticado mediante order_budgets.
ROUTE_BULK_ORDER_NOT_ASSIGNABLE_STATUS Estado no asignable
El pedido no esta en dispatcher_accepted. Solo pedidos aceptados por el dispatcher pueden entrar en una route nueva.
ROUTE_BULK_ORDER_ACTIVE_ROUTE Pedido ya asignado
El pedido ya esta en una route activa y no puede asignarse de nuevo.
ROUTE_BULK_ASSIGNMENT_FAILED Asignacion fallida
Error no clasificado durante una asignacion concreta. El resto del lote puede continuar.
RATE_LIMIT_EXCEEDED Too Many Requests
Se ha superado el limite de peticiones para esta ruta.
ROUTE_BULK_ASSIGNMENT_FAILED Error interno
La operacion bulk no pudo ejecutarse por un error interno antes de devolver resultados por item.
Ejemplo de error por item
{
"data": {
"results": [
{
"assignmentIndex": 0,
"status": "failed",
"riderId": "8c385706-6a67-4fba-84ea-0d653f5d3928",
"orderIds": [
"aaaaaaaa-1111-4111-8111-111111111111"
],
"error": {
"code": "ROUTE_BULK_ORDER_ACTIVE_ROUTE",
"message": "One or more orders are already assigned to an active route"
}
}
],
"summary": {
"requested": 1,
"created": 0,
"alreadyExisting": 0,
"failed": 1
}
}
}