Consultar un pedido

Este endpoint devuelve toda la información de un pedido: sus items, el cliente, el canal de origen y los enlaces HATEOAS con las acciones disponibles según su estado actual. Esta página también cubre dos endpoints relacionados sobre un pedido puntual: sus transiciones de estado válidas y su desglose financiero de utilidad.

Úsalo cuando necesites:

  • Mostrar el detalle de un pedido en tu aplicación.
  • Sincronizar información hacia sistemas externos.
  • Verificar qué acciones están disponibles antes de ejecutar una transición (aceptar, preparar, cancelar).
  • Calcular la utilidad real de un pedido después de envío, comisión, costo de mercancía y empaque.

Endpoint

Obtiene un pedido por su ID

orderIdstringrequired

ID del pedido (MongoDB ObjectId de 24 caracteres).

200
{
  "data": {
    "_id": "65f3a1b2c4d5e6f7a8b9c0d1",
    "externalId": "FEN-10042",
    "handle": "fen-10042",
    "locationId": "65f2a0b1c4d5e6f7a8b9c0aa",
    "origin": "manual",
    "channelId": "manual",
    "orderStatus": "accepted",
    "paymentStatus": "paid",
    "currency": "MXN",
    "totalAmount": 1986.26,
    "subtotal": 1798.50,
    "tax": 287.76,
    "orderCreated": "2026-04-11T14:23:11.000Z",
    "items": [
      {
        "sku": "CAM-ROJO-M",
        "title": "Camisa Roja Talla M",
        "quantity": 2,
        "totalAmount": 998.00
      },
      {
        "sku": "PAN-AZUL-32",
        "title": "Pantalón Azul 32",
        "quantity": 1,
        "totalAmount": 799.50
      }
    ],
    "customerInfo": { "name": "María González" },
    "customerId": "65f3a1b2c4d5e6f7a8b9c0d2",
    "_links": {
      "prepare": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/prepare",
      "cancel": "/orders/65f3a1b2c4d5e6f7a8b9c0d1/cancel"
    }
  }
}
404
{
  "error": {
    "code": "orders:not_found",
    "message": "Order not found"
  }
}

Permiso requerido: orders:read

Parámetros de ruta

ParámetroTipoDescripción
orderIdstringObjectId del pedido (24 caracteres hex). Se obtiene al crear un pedido o desde el listado.

Enlaces HATEOAS

El objeto _links (dentro de data, no como hermano del pedido) indica qué acciones están disponibles según el estado actual. Las acciones posibles son accept, reject, cancel, prepare, fulfill y returns — el motor de enlaces solo expone las que son válidas para el estado actual del pedido según la máquina de estados. No tienes que hardcodear esa lógica en tu cliente.

Si una acción no aparece en _links, no es válida en el estado actual; consulta Transiciones de estado para la máquina de estados completa.

Ejemplos

curl https://api.fenicia.io/orders/65f3a1b2c4d5e6f7a8b9c0d1 \
  -H "Authorization: Bearer fkapi_tu_api_key"

Errores

CódigoStatusDescripción
orders:not_found404No existe un pedido con ese ID en tu tenant.
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.

Aislamiento por tenant

Solo puedes consultar pedidos de tu propio tenant. Intentar acceder a un pedido de otro tenant devuelve 404, nunca información cruzada.

Transiciones válidas de un pedido

Devuelve los estados a los que el pedido puede transicionar desde su estado actual

orderIdstringrequired

ID del pedido.

200
{
  "data": {
    "currentStatus": "accepted",
    "validTransitions": ["processing", "preparing", "cancelled"]
  }
}

Permiso requerido: orders:read

Shape de respuesta no verificado campo a campo

Los valores de estado del ejemplo (accepted → processing, preparing, cancelled) son reales y provienen directamente de la máquina de estados (ORDER_STATE_MACHINE, ver Transiciones de estado). Los nombres exactos de las claves del objeto de respuesta (currentStatus, validTransitions) no fueron verificados línea por línea contra el código fuente — confírmalos contra la respuesta real antes de depender de su forma exacta.

Ningún estado devuelto por este endpoint puede ser distinto de los 23 estados reales de la máquina de estados; estados como on_hold no existen y nunca aparecerán en la respuesta.

Desglose financiero de un pedido

Calcula la utilidad neta del pedido: ingreso menos envío real, comisión, costo de mercancía (COGS) y empaque

orderIdstringrequired

ID del pedido.

200
{
  "data": {
    "orderId": "65f3a1b2c4d5e6f7a8b9c0d1",
    "currency": "MXN",
    "revenue": 1986.26,
    "subtotal": 1798.50,
    "shippingCharged": 150.00,
    "costs": {
      "shipping": 187.40,
      "commission": 99.31,
      "cogs": 850.00,
      "packaging": 25.00,
      "otherFees": 0
    },
    "taxWithheld": 0,
    "netProfit": 824.55,
    "marginPercent": 41.51,
    "flags": {
      "cogsComplete": true,
      "currencyMixed": false,
      "packagingPending": false
    }
  }
}

Permiso requerido: orders:read

Este endpoint responde la pregunta "¿cuánto ganó realmente este pedido?" restando del ingreso (revenue) el costo real de envío, la comisión del canal, el costo de mercancía vendida (COGS) y el empaque — a diferencia de shippingCharged, que es lo cobrado al cliente por envío, costs.shipping es lo que realmente costó el envío.

CampoDescripción
revenueIngreso total del pedido.
subtotalSubtotal antes de impuestos.
shippingChargedMonto de envío cobrado al cliente.
costs.shippingCosto real del envío (tarifa pagada a la paquetería).
costs.commissionComisión del canal de venta.
costs.cogsCosto de la mercancía vendida.
costs.packagingCosto de empaque.
costs.otherFeesOtras comisiones o cargos.
taxWithheldImpuestos retenidos.
netProfitUtilidad neta (revenue menos todos los costos).
marginPercentMargen de utilidad como porcentaje.
flags.cogsCompletefalse si alguna línea del pedido no tiene snapshot de costo — en ese caso el desglose no inventa un costo, lo marca incompleto.
flags.currencyMixedtrue si el pedido mezcla monedas distintas en sus componentes.
flags.packagingPendingtrue si el costo de empaque aún no se ha registrado.

Sin costos inventados

Cuando falta el snapshot de costo de una línea, el desglose marca flags.cogsComplete: false en lugar de estimar o inventar un costo. Un netProfit calculado con cogsComplete: false es parcial: trátalo como un mínimo, no como la utilidad final.

Errores

CódigoStatusDescripción
orders:not_found404No existe un pedido con ese ID en tu tenant.
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