Devoluciones
Cuando un comprador devuelve productos que compró en tu tienda en línea, registra la devolución en Zenci con POST /orders/{id}/returns. En una sola llamada, Zenci registra la devolución, repone las unidades que corresponden, reembolsa al cliente y emite la nota de crédito.
| Endpoint | Permiso |
|---|---|
GET /return-reasons | returns:write |
POST /orders/{id}/returns | returns:write |
En el panel, el permiso se llama Registrar devoluciones.
Qué ventas se pueden devolver
- Solo las ventas que registró tu misma clave. Una venta del POS o de otra clave responde
404(Order not found). - Solo las ventas entregadas. Un apartado o un pedido por cobrar que todavía no se entregó responde
409(Only delivered orders can be returned). - Dentro del plazo de devolución que configuró el comercio. Fuera de plazo, la respuesta es
409(Return window of … days has expired for this order).
Los motivos de devolución
GET /return-reasonsCada línea de la devolución lleva un motivo de esta lista, que trae los motivos de devolución del comercio.
{
"data": [
{ "value": "change_of_mind", "label": "Cambio de Opinión", "returnsToStock": true },
{ "value": "damaged_or_defective", "label": "Producto Dañado o Defectuoso", "returnsToStock": false },
{ "value": "wrong_size_or_color", "label": "Tamaño o Color Incorrecto", "returnsToStock": true }
]
}| Campo | Descripción |
|---|---|
value | Lo que envías como reason en cada línea |
label | Nombre del motivo, como lo ve el comercio |
returnsToStock | false si lo devuelto con este motivo no vuelve a las existencias |
Registrar una devolución
POST /orders/{id}/returns{id} es el id de la venta que devolvió POST /orders.
Encabezados
| Encabezado | Obligatorio | Descripción |
|---|---|---|
Authorization o X-API-Key | Sí | Tu clave de API |
Content-Type | Recomendado | application/json |
X-Idempotency-Key | Sí | Un identificador único de esta devolución en tu tienda. Consulta |
Cuerpo
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
items | lista | Sí | Al menos una línea |
items[].sku | texto | Sí | SKU de una línea de la venta |
items[].quantity | texto | Sí | Cantidad que se devuelve, mayor que cero. Entera si el producto se vende por unidad |
items[].reason | texto | Sí | El value de un motivo de GET /return-reasons |
items[].damaged | true o false | No | true si las unidades volvieron dañadas: no regresan a las existencias |
refund | objeto | Sí | Cómo se le devuelve el dinero al cliente (ver abajo) |
refund.type | texto | Sí | store_credit o payment |
refund.paymentMethodId | texto | Con payment | Un id de que no sea efectivo |
refund.confirmationNumber | texto | No | Con payment: el número de la transferencia o la operación con que devolviste el dinero |
Envía una línea por SKU con la cantidad total que se devuelve.
Cómo se reembolsa
refund.type | Qué recibe el cliente |
|---|---|
store_credit | Un saldo a favor: la nota de crédito queda canjeable y el cliente la usa en su próxima compra |
payment | El dinero, con la forma de pago que indiques en paymentMethodId |
El efectivo no se puede usar por la API. Una devolución en efectivo sale de una caja del POS, y la API no tiene caja: con un método de efectivo la respuesta es 400 (Cash refunds are done at the POS register…). Para devolver efectivo, registra la devolución en el POS.
Ejemplo
El cliente devuelve una sandalia porque le quedó pequeña y recibe un saldo a favor:
curl -X POST https://api.zenci.app/public/v1/orders/o5h9j3k7l1z4x8c2v6b0n4m8/returns \
-H "Authorization: Bearer $ZENCI_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: devolucion-10482-1" \
-d '{
"items": [
{ "sku": "MB-029-CRU-38", "quantity": "1", "reason": "wrong_size_or_color" }
],
"refund": { "type": "store_credit" }
}'Respuesta 201:
{
"id": "r2t6y0u4i8o1p5a9s3d7f1g5",
"displayId": "000037",
"orderId": "o5h9j3k7l1z4x8c2v6b0n4m8",
"status": "complete",
"refundTotal": "38.52",
"refund": { "type": "store_credit", "paymentMethodId": null },
"items": [
{ "sku": "MB-029-CRU-38", "quantity": "1", "reason": "wrong_size_or_color", "damaged": false }
],
"creditNote": {
"id": "n8m2b6v0c4x7z1l5k9j3h7g1",
"status": "enrolled",
"redeemable": true
},
"createdAt": "2026-11-11T16:02:40.000Z"
}| Campo | Descripción |
|---|---|
id, displayId | La devolución y el número que ve el comercio |
orderId | La venta devuelta |
status | complete cuando la devolución y el reembolso quedaron registrados |
refundTotal | Lo que se le devolvió al cliente |
refund | El tipo de reembolso y, con payment, la forma de pago. Con saldo a favor, paymentMethodId es null |
items | Lo devuelto, con su motivo y si volvió dañado |
creditNote | La nota de crédito electrónica, con id, status (su estado) y redeemable (true si el cliente puede usar el saldo en su próxima compra). null si la venta no tenía factura o si la nota quedó pendiente de emitir |
La nota de crédito
Si la venta tenía factura electrónica, Zenci emite la nota de crédito sola al registrar la devolución: no tienes que pedirla aparte. Con store_credit la nota queda canjeable como saldo a favor del cliente. Si la venta no tenía factura, no se emite nota y creditNote es null.
Qué pasa con las existencias
Las unidades devueltas vuelven a la bodega de la venta, salvo en dos casos:
- La línea va con
damaged: true. - El motivo tiene
returnsToStock: false, como «Producto Dañado o Defectuoso».
La devolución aparece en Zenci como cualquier otra devolución de la venta.
SKU repetidos
- El mismo SKU en dos líneas de tu devolución se rechaza con
400(SKU "…" appears more than once: send one line per SKU with the total quantity). Suma las cantidades en una sola línea. - Un SKU que está en dos líneas de la venta se rechaza con
400(SKU "…" is in more than one line of this order…). Pasa, por ejemplo, cuando una parte se vendió con promoción y otra sin ella: la API no puede saber de cuál línea devolver. Registra esa devolución desde el POS. - Un SKU que no está en la venta responde
400(SKU "…" is not in this order).
Reintentos
X-Idempotency-Key es obligatoria: sin ella, la respuesta es 400. Usa un identificador propio de cada devolución, por ejemplo el número de la devolución en tu tienda.
- Un reintento con la misma clave devuelve la misma devolución. No se repone ni se reembolsa otra vez, aunque la primera respuesta se haya perdido por un corte de red.
- La misma clave con otra devolución responde
409concode: "idempotency_key_reused". - Si la primera petición todavía se está procesando, la respuesta es
409concode: "idempotency_in_progress"y el encabezadoRetry-After: espera y reintenta con la misma clave.
Las reglas generales están en .
Errores frecuentes
| HTTP | Mensaje | Causa |
|---|---|---|
400 | The X-Idempotency-Key header is required | Falta el encabezado |
400 | Unknown reason "…"… | El motivo no está en GET /return-reasons |
400 | SKU "…" is not in this order | El SKU no es de esa venta |
400 | SKU "…" appears more than once… | El mismo SKU en dos líneas de la devolución |
400 | SKU "…" is in more than one line of this order… | El SKU está en dos líneas de la venta: regístrala en el POS |
400 | «…» se vende por unidad: la cantidad debe ser un número entero. | Una cantidad con decimales en un producto que se vende por unidad |
400 | Cash refunds are done at the POS register… | Reembolso con un método de efectivo |
400 | Unknown or disabled payment method "…"… | El paymentMethodId no existe o el comercio lo apagó |
403 | Insufficient permissions | La clave no tiene returns:write |
404 | Order not found | La venta no existe o no la registró tu clave |
409 | Only delivered orders can be returned | La venta todavía no se entregó |
409 | Return window of … days has expired for this order | Pasó el plazo de devolución del comercio |
409 | This X-Idempotency-Key was already used… | Reusaste la clave con otra devolución (code: "idempotency_key_reused") |
Siguientes pasos
- — Cómo usa el cliente su saldo a favor.
- — Las ventas que se pueden devolver.
- — Entérate de las devoluciones registradas en el POS.