Skip to content

Referencia API ​

Las reglas comunes a todos los endpoints de la API de Zenci: URL base, formato de los datos, paginación, idempotencia, límites y errores.

URL base ​

https://api.zenci.app/public/v1

Todas las rutas de esta documentación son relativas a esa base y todas las peticiones van por HTTPS. Cada petición lleva una clave de API; consulta .

Endpoints ​

MétodoRutaPermiso de la clavePara qué sirve
GET/meNingunoVer qué permisos, sucursal y lista de precios tiene la clave
GET/productscatalog:readListar el catálogo, con sincronización incremental
GET/products/{id}catalog:readLeer un producto
GET/stockstock:readConsultar existencias por variante y bodega
POST/stock/adjustmentsstock:writeSumar o restar unidades con un motivo
GET/stock/adjustments/{id}stock:writeSeguir un ajuste de existencias
PUT/stockstock:writeFijar la cantidad exacta de productos en una bodega
GET/categoriescatalog:readListar las categorías
GET/brandscatalog:readListar las marcas
GET/branchesorders:write, layaways:write, orders:pending o stock:readListar las sucursales y la bodega de cada una
GET/warehousesorders:write, layaways:write, orders:pending o stock:readListar las bodegas
GET/payment-methodsorders:write, layaways:write u orders:pendingListar las formas de pago con las que se puede cobrar
POST/orders/previeworders:write, layaways:write u orders:pendingCalcular los totales de una venta, con promociones y cupón, sin registrarla
POST/ordersorders:write, layaways:write u orders:pending, según el tipoRegistrar una venta, un apartado o un pedido por cobrar
GET/ordersorders:readListar las ventas que registró la clave
GET/orders/{id}orders:readLeer una venta con su factura
POST/orders/{id}/paymentslayaways:writeRegistrar un abono en un apartado
POST/orders/{id}/cancellayaways:writeAnular un apartado
GET/return-reasonsreturns:writeListar los motivos de devolución
POST/orders/{id}/returnsreturns:writeDevolver productos de una venta y reembolsar
POST/quotationsquotations:writeCrear una cotización
GET/quotations/{id}quotations:writeLeer una cotización que creó la clave
GET/gift-cards/{code}gift_cards:redeemConsultar el saldo de una tarjeta de regalo
GET/invoices/{id}/pdfNinguno: enlace firmadoDescargar el PDF de una factura con el pdfUrl de la venta
GET/customerscustomers:readBuscar clientes
GET/customers/{id}customers:readLeer un cliente
POST/customerscustomers:writeCrear un cliente
PATCH/customers/{id}customers:writeCorregir un cliente
POST/customers/{id}/companiescustomers:writeAgregar una compañía a la que se le factura
DELETE/customers/{id}/companies/{companyId}customers:writeQuitar una compañía adicional

No hay más endpoints que estos. Los avisos (webhooks) no se configuran por la API: se crean en el panel. Consulta .

Una ruta que no existe responde 404 con el código not_found.

Especificación OpenAPI ​

La descripción completa de la API, en OpenAPI 3.1, está en:

https://api.zenci.app/public/v1/openapi.json

No pide clave. Trae todos los endpoints, sus parámetros, sus respuestas y los avisos (en la sección webhooks). Puedes importarla en Postman o Insomnia, o generar un cliente para tu lenguaje.

Formato de los datos ​

  • Cuerpo y respuestas en JSON. En los POST, PUT y PATCH, envía el cuerpo en JSON con Content-Type: application/json.
  • Dinero como texto con dos decimales: "36.00", "2.52". No envíes ni esperes números de JSON en los importes.
  • Cantidades como texto, sin ceros de más: "1", "12", "0.5".
  • Tasa de impuesto como texto con dos decimales: "7.00", o null si el producto no lleva impuesto.
  • Fechas en ISO 8601, en UTC: "2026-10-06T15:56:12.000Z".
  • Los precios no incluyen el impuesto. El impuesto se suma al registrar la venta; consulta .

Recurso único ​

GET /products/{id}, GET /me, GET /orders/{id}, GET /customers/{id}, GET /quotations/{id}, GET /stock/adjustments/{id}, GET /gift-cards/{code} y las altas y cambios (POST, PUT, PATCH) devuelven el objeto tal cual, sin envoltorio. DELETE responde 204 sin cuerpo.

Listas ​

GET /products, GET /stock, GET /orders y GET /customers envuelven los resultados en data y agregan pagination:

json
{
  "data": [ { "id": "k3v9x2m8q1w7e4r6t0y5u2i8" } ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 128,
    "totalPages": 3
  }
}

GET /payment-methods, GET /categories, GET /brands, GET /branches, GET /warehouses y GET /return-reasons devuelven { "data": [ … ] }, sin pagination: las listas son cortas y salen completas.

Paginación ​

ParámetroTipoPor defectoDescripción
pageentero ≥ 11Página que quieres leer
limitentero de 1 a 10050Resultados por página

Un limit mayor que 100 se rechaza con 400; no se recorta en silencio. Para leer todo, avanza page hasta llegar a totalPages. GET /products además devuelve nextCursor, que es la forma segura de recorrerlo para sincronizar; consulta .

Idempotencia ​

Los endpoints que crean o cambian algo aceptan el encabezado X-Idempotency-Key: un identificador que eliges tú para cada operación, por ejemplo el número del pedido o de la devolución en tu tienda. Sirve para reintentar sin miedo después de un corte de red: un reintento con la misma clave no repite la operación.

EndpointX-Idempotency-Key
POST /ordersObligatoria. Tiene reglas propias: consulta
POST /orders/{id}/paymentsObligatoria
POST /orders/{id}/returnsObligatoria
POST /quotationsObligatoria
POST /stock/adjustmentsObligatoria
PUT /stockObligatoria
POST /orders/{id}/cancelOpcional
POST /customersOpcional
POST /customers/{id}/companiesOpcional

Fuera de POST /orders, las reglas son las mismas en todos:

  • Hasta 255 caracteres. Una clave más larga responde 400. Donde es obligatoria, sin ella la respuesta es 400 (The X-Idempotency-Key header is required).
  • Misma clave y mismo cuerpo: recibes la respuesta original, con su mismo estado HTTP. La operación no se repite.
  • Misma clave y otro cuerpo: 409 con code: "idempotency_key_reused". No se hace nada. Una operación nueva lleva una clave nueva.
  • Mientras la primera petición todavía se procesa: 409 con code: "idempotency_in_progress" y el encabezado Retry-After. Espera esos segundos y reintenta con la misma clave.
  • Una petición rechazada no ocupa la clave. Si la respuesta no fue 2xx, corrige y reenvía con la misma clave.
  • Cada clave de API tiene sus propias claves de idempotencia. Dos integraciones del mismo comercio pueden usar el mismo valor sin chocar.

POST /orders compara los datos de la venta en lugar del cuerpo completo, para que un reintento se reconozca aunque cambies, por ejemplo, el cliente. Mientras la venta original se registra responde 409 con code: "conflict" y Retry-After. El detalle está en .

Parámetros desconocidos ​

La API rechaza cualquier parámetro o campo que no conozca, en la URL y en el cuerpo. Un ?limt=20 mal escrito o un campo discount en una línea de venta devuelven 400 validation_error, en vez de ignorarse y hacerte creer que se aplicaron.

json
{
  "code": "validation_error",
  "message": "Unrecognized key: \"limt\""
}

Límites de uso ​

LímiteValorQué pasa al superarlo
Peticiones por clave600 por minuto429 rate_limited
Peticiones sin clave, por IP200 por minuto429 rate_limited
Intentos con una clave inválida, por IP10 por minuto429 rate_limited y la IP queda bloqueada 60 segundos
Intentos con tarjetas de regalo, por clave10 por minuto, entre consultas de saldo y ventas pagadas con tarjeta de regalo429 rate_limited
Tamaño del cuerpo10 MB413 payload_too_large

El cupo de 600 es de cada clave, no de tu servidor: dos tiendas que comparten un mismo hosting no se gastan el cupo entre sí.

Cada respuesta autenticada trae el límite en estos encabezados:

EncabezadoValor
RateLimit-Policy600;w=60: 600 peticiones por ventana de 60 segundos
X-RateLimit-Limit600
Retry-AfterSolo en el 429: los segundos que conviene esperar antes de reintentar

La API no informa cuántas peticiones te quedan en la ventana: el límite lo aplica la red de Cloudflare y no lo expone. Regula tu ritmo con la política y, si recibes un 429, espera lo que dice Retry-After.

Errores ​

Todo error responde con un estado HTTP y un cuerpo plano con dos campos:

json
{
  "code": "not_found",
  "message": "Product not found"
}
HTTPcodeCuándo ocurre
400validation_errorParámetro o campo inválido, campo desconocido, cuerpo que no es JSON, falta X-Idempotency-Key, SKU que no existe, pago por encima del saldo con una forma de pago sin vuelto, ajuste de existencias que no se puede aplicar
401unauthorizedFalta la clave, o es desconocida, está revocada o venció
403forbiddenLa clave no tiene el permiso que pide la ruta, o la suscripción del comercio está restringida
403out_of_scopePediste una sucursal o una bodega fuera del
404not_foundEl recurso no existe, la ruta no existe, o el comercio no tiene activa la API
409conflictLos pagos no cubren el total de la venta, el reenvío de una venta que todavía se registra (con Retry-After) o que no terminó bien, un cliente que cambió desde que lo leíste (expectedUpdatedAt), una tarjeta de regalo sin saldo o que no se puede usar, un apartado con abonos que se anula sin decir qué pasa con ellos, o una devolución fuera de plazo
409stock_set_needs_approvalPUT /stock en un comercio que revisa los ajustes antes de aplicarlos: envía la diferencia con POST /stock/adjustments
409stock_changed_while_settingLas existencias siguieron cambiando mientras PUT /stock las fijaba. No cambió nada; reintenta
409idempotency_key_reusedReusaste una X-Idempotency-Key con otro cuerpo, o con un pedido distinto en POST /orders; consulta
409idempotency_in_progressLa primera petición con esa X-Idempotency-Key todavía se procesa. Reintenta después de Retry-After
404coupon_not_foundNo hay un cupón con el couponCode de la venta
409coupon_not_activeEl cupón todavía no empieza, ya venció o está desactivado
409coupon_exhaustedEl cupón ya se usó todas las veces permitidas
409coupon_customer_limitEl cliente ya usó el cupón todas las veces que permite
400coupon_needs_customerEl cupón tiene límite por cliente y la venta no lleva customerId
400coupon_not_applicableEl cupón no cubre ningún producto de la venta, o no mejora el precio porque las promociones dan más
400coupon_below_min_purchaseLos productos que cubre el cupón no llegan a su compra mínima
413payload_too_largeEl cuerpo pasa de 10 MB
429rate_limitedSuperaste un límite de uso, incluido el de intentos con tarjetas de regalo
500internal_errorFalla inesperada del servidor

Decide qué hacer con el estado HTTP y el code. El message explica el motivo en inglés y sirve para tus registros, pero su texto puede cambiar: no lo compares en tu código.

Un 500 nunca trae detalle ("An unexpected error occurred"). Si te ocurre en POST /orders, reintenta con la misma X-Idempotency-Key; consulta .

Siguientes pasos ​

  • — Emite tu clave y envíala en cada petición.
  • — Lee el catálogo y sincronízalo.
  • — Registra una venta paso a paso.
  • — Devuelve productos de una venta.

Documentación oficial de Zelta