Solicitar demo Demo

Orders API

Listar pedidos

Consulta pedidos con filtros, paginación y ordenación desde el perfil autenticado.

Ver referencia Todos los endpoints
Volver a todos los endpoints

Orders API

Listar pedidos

Usa este endpoint para sincronizar pedidos o construir listados operativos. restaurantToken y dispatcherToken son los filtros canónicos para acotar el restaurante o dispatcher solicitado. Por compatibilidad, restaurantId y dispatcherId aceptan el token correspondiente como alias legacy; sus valores se resuelven siempre como credenciales y no como UUIDs de recursos. La respuesta queda acotada al perfil autenticado: un dispatcher ve sus pedidos, un restaurante ve los suyos y un rider ve los pedidos asignados a su cuenta.

GET /api/orders 200 OK
Auth requerida Perfil: dispatcher, restaurant o rider

Campos principales

Resumen de los campos relevantes para este endpoint.

Campo Tipo Uso Descripción
orderId uuid Opcional Filtra por el identificador del pedido devuelto por OperioHub.
dispatchOrderId string Opcional Filtra por la referencia del pedido en tu sistema.
currentStatus string Opcional Filtra por un único estado: pending_approval, dispatcher_accepted, going_to_pickup, arrived_at_pickup, in_route, arrived_at_dropoff, delivered, failed o cancelled.
statuses string Opcional Lista de estados separados por coma para filtrar varios estados en una misma consulta.
pickupAddress string Opcional Filtra por texto contenido en la dirección de recogida.
deliveryAddress string Opcional Filtra por texto contenido en la dirección de entrega.
restaurantToken string Opcional Filtro canónico por token del restaurante. En cuentas dispatcher limita los resultados a un restaurante vinculado; en cuentas restaurante normalmente coincide con el restaurante autenticado. No es la cabecera Authorization.
dispatcherToken string Opcional Filtro canónico por token del dispatcher. En cuentas dispatcher debe corresponder al dispatcher autenticado; en cuentas restaurante limita los resultados a un dispatcher vinculado.
dispatcherId string Opcional Alias legacy de dispatcherToken. Su valor se interpreta siempre como token, nunca como UUID del dispatcher. Si el dispatcher autenticado ya queda determinado por el token, omítelo en consultas normales.
restaurantId string Opcional Alias legacy de restaurantToken. Su valor se interpreta siempre como token, nunca como UUID del restaurante. En cuentas restaurante el token ya determina el restaurante y normalmente puede omitirse.
riderId uuid Opcional Filtra por rider asignado. En cuentas rider, si se envía, debe coincidir con el rider autenticado.
createdFrom ISO date Opcional Fecha mínima de creación, inclusive.
createdTo ISO date Opcional Fecha máxima de creación, inclusive.
updatedFrom ISO date Opcional Fecha mínima de actualización, inclusive.
updatedTo ISO date Opcional Fecha máxima de actualización, inclusive.
limit number Opcional Número máximo de pedidos a devolver. Rango permitido: 1 a 200. Por defecto: 50.
offset number Opcional Desplazamiento para paginación. Por defecto: 0.
sortBy updatedAt | createdAt Opcional Campo usado para ordenar resultados. Por defecto: updatedAt.
sortOrder asc | desc Opcional Dirección de ordenación. Por defecto: desc.

Código de verificación de entrega

Las respuestas pueden incluir el código que el rider utilizará al contactar con el cliente.

  • El campo aparece como deliveryInfo.deliveryPhoneCode.
  • Es opcional y puede ser null en pedidos antiguos o sin código.
  • Cuando existe, contiene entre 1 y 100 caracteres y está separado de deliveryInfo.deliveryNotes.

Request cURL

curl -X GET 'https://api.operiohub.com/api/orders?restaurantToken=rest_tok_demo_123&dispatcherToken=disp_tok_demo_456&statuses=going_to_pickup,in_route&deliveryAddress=C.%20Cisne&createdFrom=2026-02-01T00:00:00.000Z&createdTo=2026-02-26T23:59:59.999Z&limit=25&offset=0&sortBy=updatedAt&sortOrder=desc' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Respuesta 200

{
  "data": [
    {
      "orderId": "11111111-1111-4111-8111-111111111111",
      "dispatchOrderId": "POS-93442",
      "currentStatus": "in_route",
      "createdAt": "2026-02-25T17:00:00.000Z",
      "updatedAt": "2026-02-26T09:59:00.000Z",
      "customerInfo": {
        "customerName": "Ana Perez",
        "customerPhone": "+34 600 000 000",
        "customerEmail": "ana\u0040example.com",
        "customerNotes": "Llamar si no responde"
      },
      "deliveryInfo": {
        "pickupAddress": "Av. de Orihuela, 27, 03007 Alicante",
        "pickupLat": 38.344498,
        "pickupLng": -0.509259,
        "deliveryAddress": "C. Cisne, 21-17, 03006 Alicante",
        "deliveryLat": 38.346158,
        "deliveryLng": -0.510089,
        "deliveryNotes": "Piso 2, puerta B"
      },
      "paymentInfo": {
        "method": "cash",
        "status": "pending",
        "totalAmount": "18.50",
        "currency": "EUR",
        "cashExpectedAmount": "20.00"
      },
      "assignment": {
        "orderBudgetId": "22222222-2222-4222-8222-222222222222",
        "dispatcherId": "33333333-3333-4333-8333-333333333333",
        "restaurantId": "44444444-4444-4444-8444-444444444444",
        "amount": "9.50",
        "currency": "EUR"
      }
    }
  ],
  "total": 1,
  "limit": 25,
  "offset": 0
}

Campo en la respuesta

{
  "deliveryInfo": {
    "deliveryPhoneCode": "A7-42"
  }
}

Consola de prueba

Consulta pedidos desde la página

Ajusta la URL base, pega tu token y prueba los filtros de listado. También puedes copiar el ejemplo como cURL o JavaScript.

La respuesta aparecerá aquí.

Errores esperados

Respuestas habituales que debe contemplar la integración.

400
GET_ORDERS_INVALID_QUERY

Query inválida

Algún filtro no cumple el formato esperado, el rango de fechas es incoherente o los valores de paginación quedan fuera de rango.

401
AUTH_MISSING_TOKEN

Token requerido

No se ha enviado token en Authorization ni x-api-token.

401
AUTH_INVALID_AUTHORIZATION_HEADER

Cabecera Authorization inválida

La cabecera Authorization no tiene un formato válido.

401
AUTH_INVALID_TOKEN

Token inválido

Token inexistente, expirado o no resoluble.

401
GET_ORDERS_UNAUTHORIZED

Usuario no autenticado

La ruta llega sin usuario autenticado tras el middleware. Es un caso defensivo.

403
DISPATCHER_GET_ORDERS_DISPATCHER_ID_MISMATCH

Dispatcher no coincide

Una cuenta dispatcher intenta filtrar por un dispatcherToken distinto al suyo. dispatcherId solo se acepta como alias legacy de dispatcherToken.

403
DISPATCHER_GET_ORDERS_RESTAURANT_RELATION_REQUIRED

Relación con restaurante requerida

Una cuenta dispatcher intenta filtrar por un restaurantToken que no está vinculado a su integración. restaurantId solo se acepta como alias legacy de restaurantToken.

403
AUTH_UNAUTHORIZED

Acceso no autorizado

La cuenta autenticada no tiene permisos para consultar el alcance solicitado por restaurantToken o dispatcherToken.

429
RATE_LIMIT_EXCEEDED

Too Many Requests

Más de 3 peticiones por minuto a esta ruta para la misma IP o identidad.

500
AUTH_TOKEN_VALIDATION_FAILED

Fallo validando token

Fallo consultando el token del usuario durante autenticación.

500
AUTH_RESTAURANT_MEMBERSHIPS_READ_FAILED

Fallo leyendo membresías

Fallo leyendo membresías de restaurante durante autenticación.

500
GET_ORDERS_REPOSITORY_READ_FAILED

Fallo leyendo pedidos

Fallo leyendo pedidos desde el repositorio.

500
GET_ORDERS_FAILED

Fallo no clasificado

Fallo no clasificado al listar pedidos.

Ejemplo de error

{
  "error": {
    "code": "GET_ORDERS_INVALID_QUERY",
    "message": "Invalid query parameters"
  }
}