Fenicia modela el ciclo de vida del pedido como una máquina de estados finita. Este artículo agrupa todos los endpoints que cambian el estado de un pedido, desde acciones simples como accept hasta transiciones masivas con metadatos de auditoría.
¿Qué endpoint debo usar?
Usa accept, reject y cancel para las acciones comunes del comerciante. Usa el endpoint genérico transition cuando necesites registrar una razón personalizada, adjuntar metadatos o mover a un estado no trivial.
Acepta un pedido pendiente. Requiere permiso orders:update.
curl -X POST https://api.fenicia.io/orders/ord_01HXYZ/accept \
-H "Authorization: Bearer fn_live_tu_api_key" \
-H "Content-Type: application/json"Rechaza un pedido pendiente. Requiere permiso orders:cancel.
curl -X POST https://api.fenicia.io/orders/ord_01HXYZ/reject \
-H "Authorization: Bearer fn_live_tu_api_key" \
-H "Content-Type: application/json" \
-d '{"reason":"out_of_stock","description":"SKU ABC-123 no disponible"}'Cancela un pedido aceptado o en preparación. Requiere permiso orders:cancel.
curl -X POST https://api.fenicia.io/orders/ord_01HXYZ/cancel \
-H "Authorization: Bearer fn_live_tu_api_key" \
-H "Content-Type: application/json" \
-d '{"reason":"customer_request","description":"El cliente cambió de opinión"}'Establece directamente el estado de un pedido. Requiere permiso orders:update.
curl -X POST https://api.fenicia.io/orders/ord_01HXYZ/status \
-H "Authorization: Bearer fn_live_tu_api_key" \
-H "Content-Type: application/json" \
-d '{"status":"preparing"}'Transiciona un pedido con razón obligatoria y metadatos opcionales. Almacenado en el log de auditoría. Requiere permiso orders:update.
curl -X POST https://api.fenicia.io/orders/ord_01HXYZ/transition \
-H "Authorization: Bearer fn_live_tu_api_key" \
-H "Content-Type: application/json" \
-d '{"toStatus":"on_hold","reason":"awaiting_payment","metadata":{"provider":"stripe"}}'Transiciona muchos pedidos a la vez. Se reporta éxito parcial por pedido. Requiere permiso orders:update.
curl -X POST https://api.fenicia.io/orders/bulk/transition \
-H "Authorization: Bearer fn_live_tu_api_key" \
-H "Content-Type: application/json" \
-d '{"orderIds":["ord_01","ord_02"],"toStatus":"accepted","reason":"bulk_accept"}'Devuelve el conjunto de estados a los que un pedido puede transicionar desde su estado actual. Requiere permiso orders:read.
curl https://api.fenicia.io/orders/ord_01HXYZ/valid-transitions \
-H "Authorization: Bearer fn_live_tu_api_key"Tip
Maneja tu UI con GET /orders/{id}/valid-transitions. El mapa actions indica qué endpoints están disponibles y los permisos requeridos, para que puedas ocultar los botones no permitidos.