La API de devoluciones modela el ciclo completo de RMA: se crea una devolución, se aprueba o rechaza, se envían los ítems de regreso, se reciben y finalmente se reembolsan. Cada paso es un endpoint separado con su propio permiso.
Estados de la devolución
Una devolución avanza: pending → approved → shipped → received → refunded. También puede quedar rejected en cualquier punto antes del envío.
Lista paginada de pedidos que tienen al menos una devolución. Requiere permiso returns:read.
curl "https://api.fenicia.io/orders/returns?status=pending&limit=50" \
-H "Authorization: Bearer fn_live_tu_api_key"Obtiene el número de devoluciones en cada estado. Útil para dashboards. Requiere permiso returns:read.
curl https://api.fenicia.io/orders/returns/counts \
-H "Authorization: Bearer fn_live_tu_api_key"Lista todas las devoluciones asociadas a un pedido. Requiere permiso returns:read.
curl https://api.fenicia.io/orders/ord_01/returns \
-H "Authorization: Bearer fn_live_tu_api_key"Obtiene una sola devolución con detalle completo. Requiere permiso returns:read.
curl https://api.fenicia.io/orders/ord_01/returns/ret_01 \
-H "Authorization: Bearer fn_live_tu_api_key"Crea una nueva devolución para un pedido. Requiere permiso returns:create.
curl -X POST https://api.fenicia.io/orders/ord_01/returns \
-H "Authorization: Bearer fn_live_tu_api_key" \
-H "Content-Type: application/json" \
-d '{"items":[{"sku":"ABC-123","quantity":1}],"reason":"damaged","notes":"Llegó roto"}'Aprueba una devolución pendiente. Requiere permiso returns:approve.
curl -X POST https://api.fenicia.io/orders/ord_01/returns/ret_01/approve \
-H "Authorization: Bearer fn_live_tu_api_key"Rechaza una devolución pendiente. Requiere permiso returns:approve.
curl -X POST https://api.fenicia.io/orders/ord_01/returns/ret_01/reject \
-H "Authorization: Bearer fn_live_tu_api_key" \
-H "Content-Type: application/json" \
-d '{"reason":"outside_return_window","notes":"Comprado hace 120 días"}'Registra que el cliente envió la devolución de regreso. Requiere permiso returns:update.
curl -X POST https://api.fenicia.io/orders/ord_01/returns/ret_01/ship \
-H "Authorization: Bearer fn_live_tu_api_key" \
-H "Content-Type: application/json" \
-d '{"trackingNumber":"1Z999...","carrier":"fedex"}'Registra la recepción e inspección de los ítems devueltos. Requiere permiso returns:process.
curl -X POST https://api.fenicia.io/orders/ord_01/returns/ret_01/receive \
-H "Authorization: Bearer fn_live_tu_api_key" \
-H "Content-Type: application/json" \
-d '{"condition":"new","notes":"Caja sin abrir"}'Emite un reembolso para una devolución recibida. Requiere permiso returns:process.
curl -X POST https://api.fenicia.io/orders/ord_01/returns/ret_01/refund \
-H "Authorization: Bearer fn_live_tu_api_key" \
-H "Content-Type: application/json" \
-d '{"amount":499.00,"method":"original_payment"}'Actualiza campos mutables de una devolución (ítems, razón, notas). Requiere permiso returns:update.
curl -X PUT https://api.fenicia.io/orders/ord_01/returns/ret_01 \
-H "Authorization: Bearer fn_live_tu_api_key" \
-H "Content-Type: application/json" \
-d '{"notes":"Notas actualizadas"}'Tip
Usa GET /orders/returns/counts como fuente de datos para un tile de dashboard de Devoluciones — es económico de consultar y entrega todos los estados en una sola llamada.