Skip to content

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.

EndpointPermiso
GET /return-reasonsreturns:write
POST /orders/{id}/returnsreturns: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 ​

http
GET /return-reasons

Cada línea de la devolución lleva un motivo de esta lista, que trae los motivos de devolución del comercio.

json
{
  "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 }
  ]
}
CampoDescripción
valueLo que envías como reason en cada línea
labelNombre del motivo, como lo ve el comercio
returnsToStockfalse si lo devuelto con este motivo no vuelve a las existencias

Registrar una devolución ​

http
POST /orders/{id}/returns

{id} es el id de la venta que devolvió POST /orders.

Encabezados ​

EncabezadoObligatorioDescripción
Authorization o X-API-KeySíTu clave de API
Content-TypeRecomendadoapplication/json
X-Idempotency-KeySíUn identificador único de esta devolución en tu tienda. Consulta

Cuerpo ​

CampoTipoObligatorioDescripción
itemslistaSíAl menos una línea
items[].skutextoSíSKU de una línea de la venta
items[].quantitytextoSíCantidad que se devuelve, mayor que cero. Entera si el producto se vende por unidad
items[].reasontextoSíEl value de un motivo de GET /return-reasons
items[].damagedtrue o falseNotrue si las unidades volvieron dañadas: no regresan a las existencias
refundobjetoSíCómo se le devuelve el dinero al cliente (ver abajo)
refund.typetextoSístore_credit o payment
refund.paymentMethodIdtextoCon paymentUn id de que no sea efectivo
refund.confirmationNumbertextoNoCon 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.typeQué recibe el cliente
store_creditUn saldo a favor: la nota de crédito queda canjeable y el cliente la usa en su próxima compra
paymentEl 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:

bash
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:

json
{
  "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"
}
CampoDescripción
id, displayIdLa devolución y el número que ve el comercio
orderIdLa venta devuelta
statuscomplete cuando la devolución y el reembolso quedaron registrados
refundTotalLo que se le devolvió al cliente
refundEl tipo de reembolso y, con payment, la forma de pago. Con saldo a favor, paymentMethodId es null
itemsLo devuelto, con su motivo y si volvió dañado
creditNoteLa 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 409 con code: "idempotency_key_reused".
  • Si la primera petición todavía se está procesando, la respuesta es 409 con code: "idempotency_in_progress" y el encabezado Retry-After: espera y reintenta con la misma clave.

Las reglas generales están en .

Errores frecuentes ​

HTTPMensajeCausa
400The X-Idempotency-Key header is requiredFalta el encabezado
400Unknown reason "…"…El motivo no está en GET /return-reasons
400SKU "…" is not in this orderEl SKU no es de esa venta
400SKU "…" appears more than once…El mismo SKU en dos líneas de la devolución
400SKU "…" 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
400Cash refunds are done at the POS register…Reembolso con un método de efectivo
400Unknown or disabled payment method "…"…El paymentMethodId no existe o el comercio lo apagó
403Insufficient permissionsLa clave no tiene returns:write
404Order not foundLa venta no existe o no la registró tu clave
409Only delivered orders can be returnedLa venta todavía no se entregó
409Return window of … days has expired for this orderPasó el plazo de devolución del comercio
409This 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.

Documentación oficial de Zelta