Skip to content

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 .

EndpointPermiso
POST /ordersSegún el tipo: orders:write, layaways:write u orders:pending
POST /orders/previeworders:write, layaways:write u orders:pending
GET /ordersorders:read
GET /orders/{id}orders:read
POST /orders/{id}/paymentslayaways:write
POST /orders/{id}/cancellayaways:write

Antes de vender ​

  1. Revisa la clave con . Si defaultBranchId es null, cada venta tiene que enviar branchId: búscalo en .
  2. Lee las formas de pago con y guarda sus id.
  3. Ten a mano los SKU de tus productos, que salen de .
  4. 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.).

typeQué esPermisoPagos
sale (por defecto)Venta cobrada y entregadaorders:writeAl menos uno, que cubra el total
layaway: las unidades quedan reservadas para un cliente mientras pagalayaways:writeEl 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ísicaorders:pendingNinguno

La petición ​

Encabezados ​

EncabezadoObligatorioDescripción
Authorization o X-API-KeySíTu clave de API
Content-TypeRecomendadoapplication/json
X-Idempotency-KeySíUn identificador único de esta venta en tu tienda, por ejemplo el número de tu pedido. Consulta

Cuerpo ​

CampoTipoObligatorioDescripción
itemslistaSíAl menos una línea
items[].skutextoSíSKU de la variante. Debe coincidir exactamente, con mayúsculas y minúsculas; no se busca por código de barras
items[].quantitytextoSíCantidad mayor que cero, hasta 6 decimales: "1", "2", "0.5"
items[].pricetextoNoPrecio por unidad sin impuesto, hasta 2 decimales. Solo con el permiso orders:set-price; consulta
typetextoNosale (por defecto), layaway o pending. Consulta
paymentslistaSegún el tipoEn una venta, al menos un pago. En un apartado, el abono inicial. En un pedido por cobrar, ninguno
payments[].paymentMethodIdtextoSíUn id de GET /payment-methods
payments[].amounttextoSíMonto, hasta 2 decimales
payments[].confirmationNumbertextoNoEl número de la transferencia o del comprobante. Conviene enviarlo con las formas de pago que tienen requiresConfirmationNumber: true; consulta
payments[].giftCardCodetextoCon tarjeta de regaloEl código de 16 caracteres de la tarjeta. Consulta
branchIdtextoNoSucursal de la venta. Si no lo envías, se usa la de la clave. Si la clave está , tiene que ser una de ellas
customerIdtexto o nullEn un apartadoCliente 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
companyIdtexto o nullNoUna de las compañías del cliente, para facturarle a ella y no a la principal. Necesita customerId
couponCodetexto o nullNoCódigo de un cupón del comercio. Consulta
expiresAtfecha ISO 8601NoSolo 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:

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

json
{
  "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"
}
CampoDescripción
idIdentificador de la venta en Zenci. Guárdalo junto a tu pedido
displayIdNúmero de orden que ve el comercio en Órdenes
typesale, layaway o pending
statusEstado del cobro: paid (pagada), partial (con abonos), pending (sin pagos), expired (vencida) o cancelled (anulada). Una venta completa sale en paid
trackingStatusEl 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, companyIdEl cliente y la compañía a la que se factura, o null
invoiceLa factura electrónica (ver ). Al registrar la venta todavía es null: se emite unos segundos después
subtotalSuma de price × quantity de las líneas, sin impuesto y antes de descuentos
taxesImpuesto total
totalLo que se cobró: subtotal + taxes − los descuentos de las líneas (items[].discount)
items[].skuEl SKU que enviaste
items[].nameNombre del producto
items[].pricePrecio por unidad sin impuesto con el que se vendió
items[].discountDescuento total de la línea, sin impuesto. "0.00" si no tuvo
items[].promotionLa promoción que se aplicó a la línea, con id, name, percent y discount (lo que descontó), o null
items[].couponDiscountLa parte de discount que puso el cupón de la venta, o null si la línea no tuvo cupón
items[].totalprice × quantity − discount, sin impuesto
payments[].amountLo que se aplicó a la venta
payments[].tenderedAmountLo que entregó el comprador. Igual a amount si pagó exacto
payments[].changeEl vuelto de ese pago; "0.00" si no hubo
amountPaidLo pagado hasta ahora
balanceLo que falta por pagar: "0.00" en una venta cobrada
expiresAtHasta cuándo se guarda un apartado o un pedido por cobrar; null en una venta
changeLa 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:

  1. Base de la línea = price × quantity, redondeada a centavos.
  2. Impuesto de la línea = base × taxRate ÷ 100, redondeado a centavos. Si taxRate es null, el impuesto es 0.00.
  3. 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íneaBaseImpuesto
1 × MB-029-CRU-38 a 36.0036.002.52
1 × MB-087-PAN-M a 12.5012.500.88 (de 0.875)
1 × MB-087-PAN-L a 12.5012.500.88 (de 0.875)
Sumasubtotal 61.00impuesto 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 conflict con el mensaje Payments 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 misma X-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 giftCardCode y la clave necesita gift_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: verano10 y VERANO10 son 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[].couponDiscount la parte del descuento que puso el cupón. Ese monto también está incluido en items[].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:

http
POST /orders/preview

Recibe items, branchId, customerId y couponCode, igual que POST /orders, y devuelve los totales sin registrar nada: no reserva unidades ni gasta el cupón.

bash
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" }
    ]
  }'
json
{
  "subtotal": "36.00",
  "discountTotal": "3.60",
  "taxTotal": "2.27",
  "total": "34.67"
}
CampoDescripción
subtotalSuma de las líneas antes de descuentos, sin impuesto
discountTotalDescuentos de promociones y del cupón
taxTotalImpuesto
totalLo 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é:

HTTPcodeCausa
404coupon_not_foundNo hay un cupón con ese código
409coupon_not_activeTodavía no empieza, ya venció o el comercio lo desactivó
409coupon_exhaustedYa se usó todas las veces permitidas
409coupon_customer_limitEse cliente ya lo usó todas las veces que permite
400coupon_needs_customerTiene límite por cliente y no enviaste customerId
400coupon_not_applicableNo cubre ningún producto de la venta, o no mejora el precio porque las promociones ya dan un descuento mayor
400coupon_below_min_purchaseLos 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 es 400 (A layaway needs customerId).
  • payments es 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 ​

http
POST /orders/{id}/payments
CampoTipoObligatorioDescripción
paymentMethodIdtextoSíUn id de GET /payment-methods
amounttextoSíMonto mayor que cero, hasta 2 decimales
confirmationNumbertextoNoEl 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.

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

http
POST /orders/{id}/cancel

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

paymentsCuándo usarlo
refundLe devolviste el dinero al cliente
keepEl 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 ({}).

bash
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_recorded y order.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 responde 400 (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.
  • expiresAt solo va en un pedido por cobrar. En una venta o un apartado responde 400 (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.
bash
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 201 con la venta original. No se cobra ni se descuenta otra vez.
  • La misma clave con otro pedido: recibes 409 con code: "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 ​

RespuestaQué 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
500Reintenta con la misma clave en unos segundos
409 Payments do not cover the order totalCorrige 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_reusedEsa 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, 404Corrige la petición y reenvíala. Una venta rechazada no ocupa la clave, así que puedes usar la misma
429Espera 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.
Lista de Órdenes con la orden 004518 marcada con la etiqueta Tienda en línea, pagada y entregadaLista de Órdenes con la orden 004518 marcada con la etiqueta Tienda en línea, pagada y entregada
Una venta registrada por la API, en Órdenes, con la etiqueta Tienda en línea.

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 ​

HTTPMensajeCausa
400The X-Idempotency-Key header is requiredFalta el encabezado
400A JSON body is requiredEl cuerpo no es JSON
400Unknown SKU "…"El SKU no existe, está eliminado, tiene otra escritura o está fuera del alcance de la clave
400No branch was provided and this API key has no default branch…La clave no tiene sucursal y no enviaste branchId
400This API key cannot set prices…Enviaste price sin el permiso orders:set-price
400Invalid "items.0.quantity": …Un campo con formato inválido; el mensaje dice cuál
400Payment amount exceeds remaining balance of …Pago de más con una forma de pago que no da vuelto
400Unknown 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
400A sale needs at least one paymentUna venta sin pagos
400A layaway needs customerIdUn apartado sin cliente
400A pending order is paid at the POS: send it without paymentsUn pedido por cobrar con pagos
400expiresAt only applies to pending ordersexpiresAt en una venta o un apartado
400expiresAt must be in the future and at most 30 days aheadFecha de vencimiento pasada o a más de 30 días
400, 404, 409coupon_* (en code)El cupón no aplica; consulta
400"companyId" requires "customerId"Enviaste una compañía sin cliente
400The billing company does not belong to this customerLa compañía no es de ese cliente
400Not enough stock for "…"El comercio no permite vender sin existencias
403Insufficient permissionsLa clave no tiene ninguno de los permisos para crear ventas
403This API key cannot create this kind of order…Falta el permiso del tipo de venta: orders:write, layaways:write u orders:pending
403This API key cannot charge gift cards…Un pago con giftCardCode sin el permiso gift_cards:redeem
403Branch "…" is outside this API key's scopeLa sucursal no es una de las de la clave (code: "out_of_scope"). No se cobra nada
404Customer not foundEl customerId no es un cliente del comercio
404Warehouse not found for branch …El branchId no es una sucursal del comercio
409Payments do not cover the order totalLos pagos no llegan al total
409This 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:

http
GET /orders/{id}
json
{
  "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.statusQué significa
pendingSe envió a la DGI y todavía no hay respuesta
enrolledLa DGI la aceptó. Trae number, cufe, issuedAt (en UTC) y pdfUrl
failedLa DGI la rechazó. El comercio la corrige y reintenta desde Zenci
review_requiredLa respuesta fue ambigua y el comercio la revisa en Zenci
cancelledSe 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 ​

http
GET /orders
ParámetroTipoDescripción
pageenteroPágina, desde 1. Por defecto 1
limitenteroDe 1 a 100. Por defecto 50
createdSincefecha ISO 8601Solo las ventas registradas en ese momento o después
createdUntilfecha ISO 8601Solo 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.

Documentación oficial de Zelta