API de Órdenes

La API de Órdenes cubre el ciclo de vida completo de un pedido: listarlo y buscarlo, crearlo, consultarlo, actualizarlo, transicionarlo entre estados, prepararlo y enviarlo, gestionar devoluciones y adjuntos, recuperar carritos abandonados, y auditar/exportar su historial.

Este artículo es la puerta de entrada al dominio. Léelo antes de cualquier otro artículo de la sección: define el envelope de respuesta, que gobierna la forma de absolutamente todas las respuestas de esta API.

URL base y autenticación

https://api.fenicia.io

No hay prefijo de versión (/v1) en la URL. Todos los endpoints de este dominio cuelgan del path base /orders.

Cada petición requiere un API key enviado como Bearer token:

Authorization: Bearer fkapi_tu_api_key

El envelope de respuesta (léelo con atención)

Toda respuesta de la API de Órdenes sigue una de estas tres formas. No hay excepciones dentro de este dominio salvo la documentada explícitamente en Excepción: carritos abandonados más abajo.

Éxito — recurso único

{
  "data": {
    "_id": "65f3a1b2c4d5e6f7a8b9c0d1",
    "externalId": "FEN-10042",
    "orderStatus": "accepted",
    "total": 1986.26,
    "_links": {
      "prepare": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/prepare",
      "cancel": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/cancel"
    }
  }
}

El campo meta es opcional en respuestas de recurso único (puede llevar links adicionales fuera del recurso, aunque lo habitual es que _links viva dentro de data, como en el ejemplo).

Éxito — lista paginada

{
  "data": [
    { "_id": "65f3a1b2c4d5e6f7a8b9c0d1", "externalId": "FEN-10042", "orderStatus": "accepted" },
    { "_id": "65f3a1b2c4d5e6f7a8b9c0d2", "externalId": "FEN-10043", "orderStatus": "pending" }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 143,
      "totalPages": 8,
      "hasMore": true
    }
  }
}

meta.pagination es obligatorio en toda respuesta de lista. meta.links es opcional y, cuando aparece, trae enlaces de navegación de la propia colección — no lo confundas con el _links de cada recurso individual.

Error

{
  "error": {
    "code": "orders:not_found",
    "message": "Order not found",
    "details": {
      "field": "orderId",
      "value": "65f3a1b2c4d5e6f7a8b9c0d1"
    }
  }
}

El error siempre va envuelto en un objeto error — nunca aparecen code/message como propiedades de nivel superior. code sigue siempre el formato namespace:snake_case (ej. orders:not_found, returns:already_approved). El catálogo completo de códigos, agrupado por namespace, está en Catálogo de errores.

Enlaces HATEOAS (_links)

Los recursos de pedido y devolución incluyen un objeto _links dentro de data con las acciones válidas para el estado actual del recurso. Las acciones posibles son: accept, reject, cancel, prepare, fulfill, returns. Un cliente bien construido no necesita hardcodear qué transición es válida en qué estado — simplemente revisa si el link está presente en la respuesta.

Paginación

Los endpoints de listado aceptan page y limit como query params y devuelven meta.pagination con page, limit, total, totalPages y hasMore. Los valores por defecto y límites exactos de cada endpoint se documentan en su propio artículo (ver Listar pedidos).

Filtros comunes de listado

La mayoría de los endpoints de listado (GET /orders, /orders/search, los de conteo, /orders/export) comparten el mismo normalizador de filtros. Los más usados:

La lista exhaustiva, con tipos y ejemplos, vive en Listar pedidos.

Máquina de estados (resumen)

Un pedido transita por un grafo de estados dirigido — no un flujo lineal simple. Los estados terminales (sin transiciones de salida) son cancelled, rejected y returned; el resto tiene una o más transiciones válidas dependiendo del canal, la modalidad de cumplimiento y si el pedido se envía en una o varias partes.

Para agrupar visualmente los pedidos (por ejemplo en un tablero), la API expone un conjunto reducido de grupos de estado, distinto de los estados individuales de la máquina de transición:

No hardcodees el grafo de transiciones en tu aplicación: usa _links en cada respuesta para saber qué acción es válida en cada momento, y consulta Transiciones de estado para el detalle completo de la máquina de estados, incluyendo la taxonomía de motivos de cancelación.

Excepción: carritos abandonados

{
  "data": {
    "data": [
      { "id": "cart_8f2a1", "status": "abandoned", "totalValue": 1245.00 }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 34,
      "totalPages": 2,
      "hasMore": true
    }
  }
}

Además, el path legacy /abandoned-carts/* (sin el prefijo /orders) sigue funcionando pero está deprecado desde el 2026-06-01. La ruta canónica y recomendada es /orders/abandoned-carts/*. Detalle completo en Carritos abandonados.

Ejemplo rápido

curl https://api.fenicia.io/orders?limit=5 \
  -H "Authorization: Bearer $FENICIA_API_KEY"

Mapa de la sección

Siguientes pasos

• Listar pedidos
• Crear un pedido
• Catálogo de errores