Ventas
Cuando un comprador paga en tu tienda en línea, registra la venta en Zenci con POST /orders. La venta queda cobrada y entregada en una sola llamada: descuenta las existencias, aparece en Ventas → Órdenes con la etiqueta Tienda en línea y, si el comercio tiene la facturación electrónica configurada, se factura sola unos segundos después.
Con el mismo endpoint también puedes registrar un apartado o un pedido por cobrar en el POS; consulta .
| Endpoint | Permiso |
|---|---|
POST /orders | Según el tipo: orders:write, layaways:write u orders:pending |
POST /orders/preview | orders:write, layaways:write u orders:pending |
GET /orders | orders:read |
GET /orders/{id} | orders:read |
POST /orders/{id}/payments | layaways:write |
POST /orders/{id}/cancel | layaways:write |
Antes de vender
- Revisa la clave con . Si
defaultBranchIdesnull, cada venta tiene que enviarbranchId: búscalo en . - Lee las formas de pago con y guarda sus
id. - Ten a mano los SKU de tus productos, que salen de .
- Si la venta lleva factura a nombre del comprador, búscalo o créalo con y envía su
customerId.
Tipos de venta
type dice qué se registra. Cada tipo pide su propio permiso: con una clave que no lo tiene, la respuesta es 403 (This API key cannot create this kind of order. Grant the … scope.).
type | Qué es | Permiso | Pagos |
|---|---|---|---|
sale (por defecto) | Venta cobrada y entregada | orders:write | Al menos uno, que cubra el total |
layaway | : las unidades quedan reservadas para un cliente mientras paga | layaways:write | El abono inicial. Puede ir vacío si el comercio permite apartados sin abono |
pending | : el cliente lo paga y lo retira en la tienda física | orders:pending | Ninguno |
La petición
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 venta en tu tienda, por ejemplo el número de tu pedido. Consulta |
Cuerpo
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
items | lista | Sí | Al menos una línea |
items[].sku | texto | Sí | SKU de la variante. Debe coincidir exactamente, con mayúsculas y minúsculas; no se busca por código de barras |
items[].quantity | texto | Sí | Cantidad mayor que cero, hasta 6 decimales: "1", "2", "0.5" |
items[].price | texto | No | Precio por unidad sin impuesto, hasta 2 decimales. Solo con el permiso orders:set-price; consulta |
type | texto | No | sale (por defecto), layaway o pending. Consulta |
payments | lista | Según el tipo | En una venta, al menos un pago. En un apartado, el abono inicial. En un pedido por cobrar, ninguno |
payments[].paymentMethodId | texto | Sí | Un id de GET /payment-methods |
payments[].amount | texto | Sí | Monto, hasta 2 decimales |
payments[].confirmationNumber | texto | No | El número de la transferencia o del comprobante. Conviene enviarlo con las formas de pago que tienen requiresConfirmationNumber: true; consulta |
payments[].giftCardCode | texto | Con tarjeta de regalo | El código de 16 caracteres de la tarjeta. Consulta |
branchId | texto | No | Sucursal de la venta. Si no lo envías, se usa la de la clave. Si la clave está , tiene que ser una de ellas |
customerId | texto o null | En un apartado | Cliente al que se le vende y se le factura. Búscalo o créalo con . Sin cliente, la factura sale a consumidor final. Un apartado siempre lo necesita |
companyId | texto o null | No | Una de las compañías del cliente, para facturarle a ella y no a la principal. Necesita customerId |
couponCode | texto o null | No | Código de un cupón del comercio. Consulta |
expiresAt | fecha ISO 8601 | No | Solo en un pedido por cobrar: hasta cuándo se guarda. Consulta |
No hay campos para descuentos manuales, notas ni envío. Cualquier campo que no esté en esta tabla se rechaza con 400.
Ejemplo
Un par de sandalias talla 38, pagado en efectivo con 40.00:
curl -X POST https://api.zenci.app/public/v1/orders \
-H "Authorization: Bearer $ZENCI_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: pedido-10482" \
-d '{
"items": [
{ "sku": "MB-029-CRU-38", "quantity": "1" }
],
"payments": [
{ "paymentMethodId": "m1a5s9d3f7g2h6j0k4l8z2x6", "amount": "40.00" }
]
}'Respuesta 201:
{
"id": "o5h9j3k7l1z4x8c2v6b0n4m8",
"displayId": "004518",
"type": "sale",
"status": "paid",
"trackingStatus": {
"id": "t4y8u2i6o0p3a7s1d5f9g3h7",
"label": "Entregada",
"category": "completed"
},
"customerId": null,
"companyId": null,
"invoice": null,
"subtotal": "36.00",
"taxes": "2.52",
"total": "38.52",
"items": [
{
"sku": "MB-029-CRU-38",
"name": "Sandalia Crucero",
"quantity": "1",
"price": "36.00",
"discount": "0.00",
"promotion": null,
"couponDiscount": null,
"total": "36.00"
}
],
"payments": [
{
"paymentMethodId": "m1a5s9d3f7g2h6j0k4l8z2x6",
"paymentMethodName": "Efectivo",
"amount": "38.52",
"tenderedAmount": "40.00",
"change": "1.48"
}
],
"amountPaid": "38.52",
"balance": "0.00",
"expiresAt": null,
"change": "1.48",
"createdAt": "2026-10-06T15:56:12.000Z"
}| Campo | Descripción |
|---|---|
id | Identificador de la venta en Zenci. Guárdalo junto a tu pedido |
displayId | Número de orden que ve el comercio en Órdenes |
type | sale, layaway o pending |
status | Estado del cobro: paid (pagada), partial (con abonos), pending (sin pagos), expired (vencida) o cancelled (anulada). Una venta completa sale en paid |
trackingStatus | El de la venta, con id, label (el nombre que le puso el comercio) y category: pending, in_progress, completed o cancelled. Puede ser null |
customerId, companyId | El cliente y la compañía a la que se factura, o null |
invoice | La factura electrónica (ver ). Al registrar la venta todavía es null: se emite unos segundos después |
subtotal | Suma de price × quantity de las líneas, sin impuesto y antes de descuentos |
taxes | Impuesto total |
total | Lo que se cobró: subtotal + taxes − los descuentos de las líneas (items[].discount) |
items[].sku | El SKU que enviaste |
items[].name | Nombre del producto |
items[].price | Precio por unidad sin impuesto con el que se vendió |
items[].discount | Descuento total de la línea, sin impuesto. "0.00" si no tuvo |
items[].promotion | La promoción que se aplicó a la línea, con id, name, percent y discount (lo que descontó), o null |
items[].couponDiscount | La parte de discount que puso el cupón de la venta, o null si la línea no tuvo cupón |
items[].total | price × quantity − discount, sin impuesto |
payments[].amount | Lo que se aplicó a la venta |
payments[].tenderedAmount | Lo que entregó el comprador. Igual a amount si pagó exacto |
payments[].change | El vuelto de ese pago; "0.00" si no hubo |
amountPaid | Lo pagado hasta ahora |
balance | Lo que falta por pagar: "0.00" en una venta cobrada |
expiresAt | Hasta cuándo se guarda un apartado o un pedido por cobrar; null en una venta |
change | La suma de los vueltos |
Cómo se calcula el total
Los precios de Zenci no incluyen el impuesto. Para cobrarle al comprador lo mismo que registrará Zenci, calcula así, línea por línea:
- Base de la línea =
price×quantity, redondeada a centavos. - Impuesto de la línea = base ×
taxRate÷ 100, redondeado a centavos. SitaxRateesnull, el impuesto es0.00. - Subtotal = suma de las bases. Impuesto = suma de los impuestos de cada línea. Total = subtotal + impuesto.
El redondeo es al centavo más cercano y, en el medio exacto, hacia arriba (0.125 → 0.13).
Ejemplo con tres líneas al 7 %:
| Línea | Base | Impuesto |
|---|---|---|
1 × MB-029-CRU-38 a 36.00 | 36.00 | 2.52 |
1 × MB-087-PAN-M a 12.50 | 12.50 | 0.88 (de 0.875) |
1 × MB-087-PAN-L a 12.50 | 12.50 | 0.88 (de 0.875) |
| Suma | subtotal 61.00 | impuesto 4.28 |
Total: 61.00 + 4.28 = 65.28.
Redondea el impuesto por línea, no sobre el subtotal. Sobre el subtotal saldría 61.00 × 7 % = 4.27, un centavo menos: tu tienda cobraría 65.27 y la venta se rechazaría porque el pago no cubre el total.
El taxRate y el price que debes usar son los de GET /products con la misma clave. Si la variante trae promotionPrice, usa ese precio en lugar de price para calcular la base de la línea.
Si la venta lleva un , no lo calcules por tu cuenta: pide el total a .
Los pagos
- En una venta, la suma de los pagos tiene que cubrir el total. Si queda corta, la respuesta es
409 conflictcon el mensajePayments do not cover the order total. La venta se anula en el acto: no queda cobrada ni descuenta existencias, aunque el comercio puede verla como anulada en Órdenes. Corrige los montos y reenvía con la mismaX-Idempotency-Key. - Pagar de más solo se puede con una forma de pago que da vuelto, como el efectivo. El pago se aplica hasta el total y el resto se devuelve en
change. - Con las demás formas de pago, el monto debe ser exacto. Un monto de más con tarjeta responde
400(Payment amount exceeds remaining balance of …) y la venta se anula, igual que en el caso anterior. - Puedes combinar pagos, por ejemplo una parte con tarjeta y otra en efectivo. Lo más simple para una tienda en línea es un solo pago por el total exacto.
- Con tarjeta de regalo, el pago lleva además
giftCardCodey la clave necesitagift_cards:redeem. El detalle está en .
El precio de venta
Por defecto, el precio lo pone Zenci: cada línea se vende al precio de la variante en el catálogo o, si la clave tiene una lista de precios, en esa lista. Es el mismo price que ves en GET /products.
Si el producto tiene una vigente, Zenci la aplica sola: la línea se registra con su price normal y el descuento de la promoción en discount y promotion. Lo que cobra por unidad es el promotionPrice de GET /products.
Si tu tienda necesita vender a otro precio (una oferta propia, por ejemplo), la clave necesita el permiso orders:set-price. Con él, puedes enviar price en cada línea: es el precio por unidad sin impuesto, y el impuesto se suma igual que siempre. Las líneas sin price siguen usando el precio de Zenci.
Si envías price con una clave que no tiene ese permiso, la venta se rechaza con 400 (This API key cannot set prices…). No se ignora en silencio: así nunca cobras un precio y registras otro.
Cupones
Si el comercio creó , tu tienda puede aplicarlos: envía el código que escribió el comprador en couponCode. No necesita un permiso aparte.
- El código se compara sin importar mayúsculas ni espacios:
verano10yVERANO10son el mismo cupón. - El cupón se aplica además de las promociones vigentes, según cómo lo configuró el comercio. Si no se suma a las promociones, en cada producto queda el descuento mayor: el de la promoción o el del cupón.
- Cada línea muestra en
items[].couponDiscountla parte del descuento que puso el cupón. Ese monto también está incluido enitems[].discount. - Un cupón con límite de usos por cliente necesita
customerId. - El uso del cupón cuenta al registrar la venta. Si después la venta se anula, ese uso se devuelve.
Calcular el total antes de cobrar
Con un cupón, el total depende de las reglas del cupón y de las promociones, así que pídeselo a Zenci antes de cobrar:
POST /orders/previewRecibe items, branchId, customerId y couponCode, igual que POST /orders, y devuelve los totales sin registrar nada: no reserva unidades ni gasta el cupón.
curl -X POST https://api.zenci.app/public/v1/orders/preview \
-H "Authorization: Bearer $ZENCI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"couponCode": "VERANO10",
"items": [
{ "sku": "MB-029-CRU-38", "quantity": "1" }
]
}'{
"subtotal": "36.00",
"discountTotal": "3.60",
"taxTotal": "2.27",
"total": "34.67"
}| Campo | Descripción |
|---|---|
subtotal | Suma de las líneas antes de descuentos, sin impuesto |
discountTotal | Descuentos de promociones y del cupón |
taxTotal | Impuesto |
total | Lo que tienes que cobrar |
Cobra ese total en POST /orders. El cupón se revisa otra vez al registrar la venta: si entretanto venció o se agotó, la venta se rechaza.
Cuando el cupón no aplica
Un cupón que no se puede usar rechaza la venta completa y no se cobra nada. El code del error dice por qué:
| HTTP | code | Causa |
|---|---|---|
404 | coupon_not_found | No hay un cupón con ese código |
409 | coupon_not_active | Todavía no empieza, ya venció o el comercio lo desactivó |
409 | coupon_exhausted | Ya se usó todas las veces permitidas |
409 | coupon_customer_limit | Ese cliente ya lo usó todas las veces que permite |
400 | coupon_needs_customer | Tiene límite por cliente y no enviaste customerId |
400 | coupon_not_applicable | No cubre ningún producto de la venta, o no mejora el precio porque las promociones ya dan un descuento mayor |
400 | coupon_below_min_purchase | Los productos que cubre no llegan a su compra mínima. El mensaje dice el mínimo |
Muéstrale al comprador el motivo y deja que pague sin el cupón o con otro.
Apartados
Un apartado reserva productos para un cliente mientras los paga en abonos. Se registra con type: "layaway" y el permiso layaways:write.
- Lleva
customerId. Sin él, la respuesta es400(A layaway needs customerId). paymentses el abono inicial. Aplica el abono mínimo que configuró el comercio. Si el comercio permite apartados sin abono, puede ir vacío.- Las unidades quedan reservadas hasta que el apartado se entrega o vence. El vencimiento lo fija la política de apartados del comercio y llega en
expiresAt. - Se factura cuando se termina de pagar, no al crearlo.
- El comercio lo ve y lo administra en el POS como cualquier otro .
Abonar a un apartado
POST /orders/{id}/payments| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
paymentMethodId | texto | Sí | Un id de GET /payment-methods |
amount | texto | Sí | Monto mayor que cero, hasta 2 decimales |
confirmationNumber | texto | No | El número de la transferencia o del comprobante |
Lleva X-Idempotency-Key obligatoria. Responde 201 con la venta actualizada: amountPaid sube y balance baja. Cuando balance llega a "0.00", la factura se emite sola.
curl -X POST https://api.zenci.app/public/v1/orders/o8k2j6h0g4f7d1s5a9p3o7i1/payments \
-H "Authorization: Bearer $ZENCI_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: abono-10490-2" \
-d '{ "paymentMethodId": "m7q1w5e9r3t6y0u4i8o2p6a0", "amount": "20.00" }'- Solo para apartados que creó tu misma clave. Otra venta responde
404(Order not found). - Una venta que no es apartado responde
409(Only layaways take payments or can be cancelled through the API). - Un apartado vencido no recibe abonos hasta que el comercio lo prorrogue.
- Los abonos no aceptan tarjeta de regalo.
Anular un apartado
POST /orders/{id}/cancelAnula un apartado que creó tu clave y que todavía no se entregó. Las unidades reservadas vuelven a estar disponibles. X-Idempotency-Key es opcional.
Si el apartado ya tiene abonos, indica qué pasó con ese dinero en payments:
payments | Cuándo usarlo |
|---|---|
refund | Le devolviste el dinero al cliente |
keep | El comercio se queda con el anticipo |
Sin payments, un apartado con abonos no se anula: la respuesta es 409 y el mensaje dice cuánto se cobró. Un apartado sin abonos se anula con el cuerpo vacío ({}).
curl -X POST https://api.zenci.app/public/v1/orders/o8k2j6h0g4f7d1s5a9p3o7i1/cancel \
-H "Authorization: Bearer $ZENCI_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "payments": "refund" }'Responde con la venta actualizada. Por la API solo se anulan apartados: una venta o un pedido por cobrar responde 409 (Only layaways take payments or can be cancelled through the API).
Pedidos por cobrar
Un pedido por cobrar es una compra hecha en tu tienda que el cliente paga y retira en la tienda física. Se registra con type: "pending" y el permiso orders:pending, sin pagos: si envías alguno, la respuesta es 400 (A pending order is paid at the POS: send it without payments).
- Las unidades quedan reservadas hasta que se cobre o venza.
- El comercio lo cobra en el POS desde Por cobrar, con sus formas de pago. Al cobrarlo queda pagado y entregado, y se factura como cualquier venta. Te enteras con los avisos
order.payment_recordedyorder.delivered. - Vence en
expiresAt. Puedes enviar la fecha, hasta 30 días después; si no la envías, se usan los días que configuró el comercio (3 por defecto). Una fecha pasada o a más de 30 días responde400(expiresAt must be in the future and at most 30 days ahead). - Al vencer sin cobrarse, se anula solo y las unidades vuelven a estar disponibles, a más tardar unas horas después de esa fecha. Te enteras con el aviso
order.expired. expiresAtsolo va en un pedido por cobrar. En una venta o un apartado responde400(expiresAt only applies to pending orders).- No se anula por la API. Si el comprador se arrepiente, pídele al comercio que lo anule en el POS; recibirás
order.cancelled.
curl -X POST https://api.zenci.app/public/v1/orders \
-H "Authorization: Bearer $ZENCI_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: pedido-10495" \
-d '{
"type": "pending",
"customerId": "u3i7o1p5a9s2d6f0g4h8j2k6",
"expiresAt": "2026-11-14T22:00:00-05:00",
"items": [
{ "sku": "MB-029-CRU-38", "quantity": "1" }
]
}'La respuesta trae type: "pending", status: "pending", amountPaid: "0.00", el balance por cobrar y la fecha en expiresAt.
Reintentos e idempotencia
Todo POST /orders lleva X-Idempotency-Key. Sin ella, la respuesta es 400 (The X-Idempotency-Key header is required).
Zenci registra una sola venta por cada X-Idempotency-Key de tu clave de API.
- Reintento con la misma clave y el mismo pedido: recibes
201con la venta original. No se cobra ni se descuenta otra vez. - La misma clave con otro pedido: recibes
409concode: "idempotency_key_reused"y no se registra nada. Zenci compara lo que la venta ya no puede cambiar: el tipo, la sucursal (si la envías), el cupón, y en cada línea el SKU, la cantidad y si fijaste el precio y a cuánto. El cliente, la compañía y los pagos no se comparan, porque el comercio puede cambiar el cliente desde el POS. - Un reenvío con otro cupón, o con cupón cuando el original no lo tenía, también responde
idempotency_key_reused: para la tienda es otro pedido, con otro total. - Una venta nueva lleva una clave nueva. Usa el identificador de tu pedido, no uno al azar en cada intento: así un reintento siempre reconoce su venta.
El reintento de una venta ya cobrada se reconoce antes de revisar la sucursal, así que devuelve la venta original aunque después hayan limitado tu clave a otras sucursales.
La clave es propia de cada clave de API. Dos tiendas del mismo comercio que usan claves de API distintas pueden mandar la misma X-Idempotency-Key sin chocar.
Cuándo reintentar
| Respuesta | Qué hacer |
|---|---|
| Sin respuesta (corte de red, tiempo agotado) | Reintenta con la misma clave. Si la venta ya entró, recibes la original |
409 The original sale is still being registered. Retry in a few seconds. | La venta original todavía se está registrando. Espera lo que dice el encabezado Retry-After y reintenta con la misma clave |
500 | Reintenta con la misma clave en unos segundos |
409 Payments do not cover the order total | Corrige los pagos y reenvía con la misma clave: la venta fallida no la ocupa |
409 We could not confirm whether the original sale completed. Review it before charging again. | No reintentes. La venta con esa clave quedó a medias hace más de cinco minutos: pídele al comercio que la revise en Órdenes |
409 The original sale was cancelled while completing. Register it manually. | No reintentes. La venta se anuló mientras se registraba: el comercio debe registrarla a mano |
409 idempotency_key_reused | Esa clave ya se usó para otro pedido. Si es una venta nueva, envíala con una clave nueva; si es un reintento, reenvía el pedido original para recibir la venta original |
400, 403, 404 | Corrige la petición y reenvíala. Una venta rechazada no ocupa la clave, así que puedes usar la misma |
429 | Espera unos segundos y reintenta con la misma clave |
Qué pasa con la venta en Zenci
Con type: "sale":
- Se registra en la sucursal de la clave, o en la de
branchId, y descuenta las existencias de la bodega de esa sucursal en el momento. - Queda pagada y entregada. No pasa por ninguna caja, así que no aparece en el cierre de una caja.
- Se factura sola si el comercio tiene configurada la facturación electrónica, a nombre del cliente y la compañía de la venta. Si el comercio tiene una configuración fiscal por sucursal, sale con la de la sucursal de la venta. Si el cliente tiene correo, la DGI se la envía como cualquier otra factura. Si el comercio no factura electrónicamente, la venta queda sin factura y no da error.
- Aparece en Ventas → Órdenes con la etiqueta Tienda en línea.
- Una presentación enlazada (por ejemplo, una caja de 12) descuenta sus unidades de la variante base.
- Los servicios no mueven existencias.


Sin existencias suficientes
Depende de cómo tenga configurado el comercio la venta sin existencias. Si la permite, la venta se registra y las existencias quedan en negativo. Si la bloquea, la venta se rechaza con 400 y no se cobra nada; el mensaje dice qué producto no alcanzó: Not enough stock for "Sandalia Crucero". Consulta GET /stock antes de cobrar para evitarlo.
Errores frecuentes
| HTTP | Mensaje | Causa |
|---|---|---|
400 | The X-Idempotency-Key header is required | Falta el encabezado |
400 | A JSON body is required | El cuerpo no es JSON |
400 | Unknown SKU "…" | El SKU no existe, está eliminado, tiene otra escritura o está fuera del alcance de la clave |
400 | No branch was provided and this API key has no default branch… | La clave no tiene sucursal y no enviaste branchId |
400 | This API key cannot set prices… | Enviaste price sin el permiso orders:set-price |
400 | Invalid "items.0.quantity": … | Un campo con formato inválido; el mensaje dice cuál |
400 | Payment amount exceeds remaining balance of … | Pago de más con una forma de pago que no da vuelto |
400 | Unknown or disabled payment method "…" | El paymentMethodId no existe o el comercio lo apagó |
400 | "…" cannot be used to charge through the API… | Una forma de pago que la API no acepta: crédito, nota de crédito o retención |
400 | A sale needs at least one payment | Una venta sin pagos |
400 | A layaway needs customerId | Un apartado sin cliente |
400 | A pending order is paid at the POS: send it without payments | Un pedido por cobrar con pagos |
400 | expiresAt only applies to pending orders | expiresAt en una venta o un apartado |
400 | expiresAt must be in the future and at most 30 days ahead | Fecha de vencimiento pasada o a más de 30 días |
400, 404, 409 | coupon_* (en code) | El cupón no aplica; consulta |
400 | "companyId" requires "customerId" | Enviaste una compañía sin cliente |
400 | The billing company does not belong to this customer | La compañía no es de ese cliente |
400 | Not enough stock for "…" | El comercio no permite vender sin existencias |
403 | Insufficient permissions | La clave no tiene ninguno de los permisos para crear ventas |
403 | This API key cannot create this kind of order… | Falta el permiso del tipo de venta: orders:write, layaways:write u orders:pending |
403 | This API key cannot charge gift cards… | Un pago con giftCardCode sin el permiso gift_cards:redeem |
403 | Branch "…" is outside this API key's scope | La sucursal no es una de las de la clave (code: "out_of_scope"). No se cobra nada |
404 | Customer not found | El customerId no es un cliente del comercio |
404 | Warehouse not found for branch … | El branchId no es una sucursal del comercio |
409 | Payments do not cover the order total | Los pagos no llegan al total |
409 | This X-Idempotency-Key was already used for a different order… | Reusaste la clave de idempotencia con otro pedido (code: "idempotency_key_reused") |
El formato de todos los errores está en la .
La factura
Después de registrar la venta, Zenci emite la factura electrónica por detrás. Mientras la DGI responde, la venta trae la factura en pending; cuando la acepta, en enrolled, con su número, su CUFE y un enlace al PDF. Normalmente tarda unos segundos.
Para enterarte sin consultar a cada rato, suscríbete al order.invoiced. También puedes consultar la venta:
GET /orders/{id}{
"id": "o5h9j3k7l1z4x8c2v6b0n4m8",
"displayId": "004518",
"type": "sale",
"status": "paid",
"trackingStatus": {
"id": "t4y8u2i6o0p3a7s1d5f9g3h7",
"label": "Entregada",
"category": "completed"
},
"customerId": "u3i7o1p5a9s2d6f0g4h8j2k6",
"companyId": null,
"invoice": {
"id": "f7g1h5j9k3l6z0x4c8v2b6n0",
"status": "enrolled",
"number": "004518",
"cufe": "FE01200000155612345-2-2015-001000000000451820261006…",
"issuedAt": "2026-10-06T15:56:19.000Z",
"pdfUrl": "https://api.zenci.app/public/v1/invoices/f7g1h5j9k3l6z0x4c8v2b6n0/pdf?tenant=…&expires=…&signature=…",
"pdfUrlExpiresAt": "2026-10-06T16:11:24.000Z"
},
"subtotal": "36.00",
"taxes": "2.52",
"total": "38.52",
"items": [ … ],
"payments": [ … ],
"amountPaid": "38.52",
"balance": "0.00",
"expiresAt": null,
"change": "1.48",
"createdAt": "2026-10-06T15:56:12.000Z"
}invoice.status | Qué significa |
|---|---|
pending | Se envió a la DGI y todavía no hay respuesta |
enrolled | La DGI la aceptó. Trae number, cufe, issuedAt (en UTC) y pdfUrl |
failed | La DGI la rechazó. El comercio la corrige y reintenta desde Zenci |
review_required | La respuesta fue ambigua y el comercio la revisa en Zenci |
cancelled | Se anuló |
number es el número de la factura en Zenci, el mismo que ve el comercio en Órdenes. El comprobante de la DGI muestra además el número de documento del proveedor; lo que identifica la factura ante la DGI es el cufe.
invoice es null mientras la factura se crea, y también si el comercio no tiene la facturación electrónica configurada o si la factura no se pudo crear. En ese último caso llega el aviso order.invoice_failed con el motivo, por ejemplo que el cliente no tiene DV: corrige el cliente y Zenci la vuelve a intentar sola en las horas siguientes.
El PDF
pdfUrl es un enlace temporal: vence a los 15 minutos (pdfUrlExpiresAt) y no necesita la clave de API, así que puedes mostrárselo al comprador o descargar el PDF desde tu servidor. Si venció, vuelve a consultar la venta y recibirás uno nuevo. Úsalo tal cual: cualquier cambio en el enlace lo invalida.
Consultar tus ventas
GET /orders| Parámetro | Tipo | Descripción |
|---|---|---|
page | entero | Página, desde 1. Por defecto 1 |
limit | entero | De 1 a 100. Por defecto 50 |
createdSince | fecha ISO 8601 | Solo las ventas registradas en ese momento o después |
createdUntil | fecha ISO 8601 | Solo las registradas antes de ese momento |
Cada clave ve solo las ventas que registró ella, de la más reciente a la más antigua, incluidos sus apartados y pedidos por cobrar. Cada elemento trae id, displayId, type, status, total, customerId, companyId, invoice, expiresAt y createdAt; para las líneas y los pagos, consulta GET /orders/{id}. Una venta de otra clave responde 404.
Siguientes pasos
- — A quién le vendes y a qué compañía se factura.
- — Con qué puedes cobrar.
- — Consulta el saldo y cobra con una tarjeta.
- — Devuelve productos de una venta y reembolsa al cliente.
- — Entérate cuando la venta se factura, se cobra o se anula en el POS, se devuelve o vence.