Buscar pedidos

Este endpoint combina búsqueda de texto libre (q) con el mismo conjunto de filtros estructurados que expone el listado de pedidos. En la práctica, GET /orders también admite q, por lo que ambos endpoints ofrecen una funcionalidad de búsqueda equivalente; usa /orders/search cuando el propósito principal de la consulta sea buscar por texto.

Úsalo cuando necesites:

  • Encontrar un pedido a partir de un dato parcial (ID externo, nombre de cliente, SKU) sin construir filtros exactos.
  • Dar soporte al cliente con una barra de búsqueda única.
  • Combinar texto libre con filtros de fecha, canal o estado.

Endpoint

Busca pedidos combinando texto libre con filtros estructurados

qstring

Término de búsqueda de texto libre. Es, en la práctica, el propósito de este endpoint.

pagenumber

Número de página.

limitnumber

Cantidad de resultados por página.

orderStatusstring

Filtra por estado exacto de pedido. Alias: status.

statusGroupstring

Filtra por grupo visual de estado: pending, preparing, completed, cancelled, problematic, all.

channelIdsstring

Uno o más IDs de canal de venta. Alias: channelId.

salesChannelstring

Filtra por tipo de canal (ej. shopify, amazon, manual). Alias: origin.

salesChannelsstring

Variante que acepta múltiples tipos de canal. Alias: origins.

locationstring

Filtra por ubicación/sucursal del pedido.

startDatestring

Fecha mínima del rango (ISO 8601).

endDatestring

Fecha máxima del rango (ISO 8601).

paymentStatusstring

Filtra por estado de pago.

tagsstring

Filtra por etiqueta(s) asignada(s) al pedido.

deliveryStatusstring

Filtra por estado de entrega.

hasShipmentboolean

Filtra pedidos que tienen (o no) un envío asociado.

fulfillmentModestring

Filtra por modalidad de cumplimiento.

deliveryCarrierstring

Filtra por paquetería/carrier de entrega.

customerIdstring

Filtra los pedidos de un cliente específico.

extendstring

Controla la inclusión de datos relacionados adicionales en la respuesta.

metafieldsstring

Filtra por metafields personalizados. Recibe un objeto JSON serializado.

200
{
  "data": [
    {
      "_id": "65f3a1b2c4d5e6f7a8b9c0d1",
      "externalId": "FEN-10042",
      "origin": "manual",
      "channelId": "manual",
      "orderStatus": "accepted",
      "paymentStatus": "paid",
      "currency": "MXN",
      "totalAmount": 1986.26,
      "orderCreated": "2026-04-11T14:23:11.000Z",
      "items": [
        {
          "sku": "CAM-ROJO-M",
          "title": "Camisa Roja Talla M",
          "quantity": 2,
          "totalAmount": 998.00
        }
      ],
      "customerInfo": { "name": "María González" },
      "_links": {
        "prepare": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/prepare",
        "cancel": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/cancel"
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 3,
      "totalPages": 1,
      "hasMore": false
    }
  }
}

Permiso requerido: orders:read

Tip

/orders/search y GET /orders con q resuelven la misma búsqueda. Si tu integración ya lista pedidos con filtros, es más simple agregar q a esa misma llamada que mantener dos rutas de código distintas.

Ejemplos

curl "https://api.fenicia.io/orders/search?q=maria%40example.com&orderStatus=accepted" \
  -H "Authorization: Bearer fkapi_tu_api_key"

Errores

CódigoStatusDescripción
validation:invalid_pagination400page o limit tienen un valor inválido.
validation:invalid_date_range400startDate/endDate forman un rango inválido.
validation:invalid_value400Algún filtro recibió un valor con formato incorrecto.
auth:invalid_token401La API key es inválida o fue revocada.
auth:permission_denied403La API key no tiene el permiso orders:read.

Consulta el catálogo completo de errores para el resto de los códigos posibles.

Siguientes pasos