Autenticación
La API de Zenci se usa con una clave de API que emites desde el panel. La clave identifica al comercio y define qué puede hacer: leer el catálogo, ver y ajustar existencias, registrar y consultar ventas, apartados y pedidos por cobrar, crear cotizaciones, registrar devoluciones, cobrar con tarjetas de regalo y administrar clientes. No necesitas enviar ningún otro dato para decir de qué comercio se trata.
Antes de empezar
Para emitir claves necesitas un usuario con permiso sobre Integraciones.
Emitir una clave
Las claves se administran en Administración → Integraciones, en la sección Claves de API.


- Haz clic en Emitir clave.
- Escribe un Nombre para reconocerla después, por ejemplo «Tienda en línea».
- Marca en Qué puede hacer esta clave solo los permisos que tu integración necesita (ver la tabla de abajo).
- Elige la Sucursal de las ventas: la sucursal donde se registran las ventas de esta clave y de cuya bodega salen las existencias. Si eliges La que indique cada pedido, cada venta tiene que enviar su
branchId. - En Precios, deja Los del catálogo o elige una lista de precios. Con una lista, la tienda ve y vende con esos precios.
- En Dónde puede consultar y vender, deja Todo el comercio o elige Solo las sucursales que elijas y marca las sucursales. Consulta .
- En Qué productos vende, deja Todo el catálogo o elige Solo algunas categorías o marcas y márcalas.
- Si quieres, pon una fecha en Vence el (opcional). La clave deja de funcionar al terminar ese día. Sin fecha, sirve hasta que la revoques.
- Haz clic en Crear clave.


Al crearla, Zenci muestra la clave completa una sola vez. Cópiala y guárdala en un lugar seguro antes de cerrar la ventana: después no se puede volver a consultar. Si la pierdes, revócala y emite una nueva.


Las claves empiezan con zpk_ seguido de 40 letras y números. En la lista ves su nombre, el inicio de la clave, sus permisos, su Alcance (por ejemplo, «Todo el comercio» o «Solo Sucursal Centro»), su estado (Activa, Vencida o Revocada), el último uso y la fecha de creación.


Permisos
| Permiso | En el panel | Qué permite |
|---|---|---|
catalog:read | Ver el catálogo | GET /products, GET /products/{id}, GET /categories y GET /brands |
stock:read | Ver existencias | GET /stock, GET /branches y GET /warehouses |
stock:write | Ajustar existencias | POST /stock/adjustments, GET /stock/adjustments/{id} y PUT /stock. Respeta la aprobación de ajustes del comercio; consulta |
orders:write | Crear pedidos | POST /orders con type: "sale", POST /orders/preview, GET /payment-methods, GET /branches y GET /warehouses |
orders:set-price | Fijar el precio de venta | Enviar price en cada línea de POST /orders en lugar de usar el precio del POS |
layaways:write | Crear apartados y registrar abonos | POST /orders con type: "layaway", POST /orders/{id}/payments y POST /orders/{id}/cancel en los apartados de la clave. También POST /orders/preview, GET /payment-methods, GET /branches y GET /warehouses |
orders:pending | Crear pedidos por cobrar | POST /orders con type: "pending". También POST /orders/preview, GET /payment-methods, GET /branches y GET /warehouses |
quotations:write | Crear cotizaciones | POST /quotations y GET /quotations/{id} en las cotizaciones de la clave |
returns:write | Registrar devoluciones | GET /return-reasons y POST /orders/{id}/returns en las ventas de la clave |
gift_cards:redeem | Cobrar con tarjeta de regalo | GET /gift-cards/{code} y los pagos con giftCardCode. Con él, GET /payment-methods incluye la forma de pago de tarjeta de regalo |
orders:read | Ver pedidos | GET /orders y GET /orders/{id}, con la factura y su PDF |
customers:read | Ver clientes | GET /customers y GET /customers/{id} |
customers:write | Crear y modificar clientes | POST /customers, PATCH /customers/{id} y las compañías adicionales. No permite eliminar clientes |
orders:set-price no abre ninguna ruta por sí solo y necesita orders:write: el panel no deja marcarlo sin Crear pedidos. Sin él, el precio de cada venta siempre lo decide Zenci. GET /me no pide ningún permiso.
gift_cards:redeem tampoco registra ventas por sí solo: para cobrar con tarjeta de regalo, la clave necesita además el permiso del tipo de venta.
Si llamas a una ruta sin el permiso que pide, la respuesta es 403 forbidden con el mensaje Insufficient permissions.
Los permisos, la sucursal, la lista de precios y el alcance se pueden cambiar después sin cambiar la clave; consulta .
Limitar una clave
Una clave puede ver todo el comercio o solo una parte. Sirve, por ejemplo, para que cada empresa de una misma cuenta tenga su propia tienda en línea, o para una tienda que vende una sola línea de productos.
Por sucursal. Con Solo las sucursales que elijas, la clave solo ve los productos, las existencias, las sucursales y las bodegas de esas sucursales, y solo puede vender en ellas. En Bodegas sin sucursal (opcional) puedes sumar bodegas que no pertenecen a ninguna sucursal. Puedes elegir hasta 50 de cada una.
- Un producto entra si tiene existencias registradas en alguna bodega del alcance. Los servicios entran siempre.
GET /branchesyGET /warehousessolo traen las sucursales y bodegas de la clave.- Pedir una sucursal o una bodega fuera del alcance responde
403concode: "out_of_scope", enGET /products,GET /stock,POST /orders,POST /quotationsy los ajustes de existencias. En la venta no se cobra nada. - Cuando el comercio factura por sucursal, la venta sale con los datos fiscales de la sucursal donde se registra.
Por catálogo. Con Solo algunas categorías o marcas, la clave solo ve los productos que estén en alguna de las categorías (con sus subcategorías) o de las marcas que marques. GET /categories y GET /brands solo traen las elegidas, y las existencias y las ventas se limitan a esos productos.
Si limitas por sucursal y por catálogo a la vez, un producto tiene que cumplir las dos cosas.
Un producto fuera del alcance responde 404 en GET /products/{id}, igual que uno que no existe, y venderlo responde Unknown SKU. Los clientes y las formas de pago son de todo el comercio: una clave limitada los ve todos.
Una clave sin límites ve todo el comercio, como las que ya existían antes de esta opción. Para saber el alcance de tu clave, consulta .
Enviar la clave
Envía la clave en uno de estos dos encabezados:
Authorization: Bearer zpk_…X-API-Key: zpk_…Guárdala en una variable de entorno de tu servidor, nunca en el código del navegador ni en la app: quien la tenga puede actuar en nombre del comercio.
export ZENCI_API_KEY="zpk_…"Comprobar la clave: GET /me
Devuelve la configuración de la clave con la que llamas. Es una buena primera llamada para confirmar que todo está bien.
curl https://api.zenci.app/public/v1/me \
-H "Authorization: Bearer $ZENCI_API_KEY"{
"scopes": ["catalog:read", "stock:read", "orders:write"],
"defaultBranchId": "b7n2q8w4e1r9t3y6u0i5o2p7",
"priceListId": "l4k8j2h6g0f3d7s1a5p9o3i7",
"priceList": { "id": "l4k8j2h6g0f3d7s1a5p9o3i7", "name": "Mayoreo" },
"locationScope": {
"branchIds": ["b7n2q8w4e1r9t3y6u0i5o2p7"],
"warehouseIds": ["w2e6r0t4y8u1i5o9p3a7s1d5"]
},
"catalogScope": null
}| Campo | Descripción |
|---|---|
scopes | Permisos de la clave |
defaultBranchId | Sucursal de las ventas, o null si cada venta debe enviar branchId |
priceListId, priceList | La lista de precios que de verdad se aplica, o null si la clave usa los precios del catálogo. También es null si la lista de la clave se eliminó o se desactivó: en ese caso se vende a precio de catálogo |
locationScope | Las sucursales (branchIds) y bodegas (warehouseIds) que ve la clave. warehouseIds trae las bodegas de esas sucursales más las bodegas sin sucursal que se sumaron. null si la clave ve todo el comercio |
catalogScope | Las categorías (categoryIds) y marcas (brandIds) que vende la clave. null si vende todo el catálogo |
Hasta el 6 de octubre de 2026, GET /me traía además affectsInventory, que siempre valía false y no hacía nada. Ya no aparece: si tu integración lo leía, quítalo.
Errores de autenticación
| HTTP | code | Causa |
|---|---|---|
401 | unauthorized | Falta la clave (An API key is required), o es desconocida, está revocada o venció (Invalid or revoked API key) |
403 | forbidden | La suscripción del comercio está restringida. El acceso vuelve cuando se regulariza el pago |
404 | not_found | El comercio no tiene activa la API para integraciones |
429 | rate_limited | Más de 10 intentos con una clave inválida en un minuto desde la misma IP. Espera 60 segundos |
Una clave desconocida, una revocada y una vencida responden igual a propósito: así nadie puede averiguar cuáles existen.
Editar una clave
En la lista de claves, haz clic en Editar. En Editar clave de API puedes cambiar el nombre, los permisos, la sucursal de las ventas, los precios y el alcance; pulsa Guardar cambios. Los cambios aplican de inmediato y la integración sigue usando la misma clave. El vencimiento no se puede cambiar: para eso, emite una clave nueva y revoca la anterior.
Si cambias las sucursales, bodegas, categorías o marcas de una clave, los avisos atados a ella reciben catalog.resync_required para que la tienda vuelva a leer su catálogo; consulta .
Si otra persona guardó cambios en la misma clave mientras la editabas, Zenci no guarda los tuyos y te pide cerrarla, volver a abrirla y repetir el cambio.
Usuarios con sucursales asignadas
Un usuario con acceso a todas las sucursales puede emitir y editar cualquier clave. Un usuario con también puede, siempre que la clave quede dentro de sus sucursales:
- En Dónde puede consultar y vender, la clave tiene que estar limitada a Solo las sucursales que elijas, y todas tienen que ser suyas. No puede dejarla en Todo el comercio.
- La Sucursal de las ventas tiene que ser una de las suyas.
- No puede sumar Bodegas sin sucursal: solo las bodegas de sus sucursales.
Si la clave se sale de sus sucursales, Zenci no la guarda y muestra «Solo puedes dar a la clave tus propias sucursales y sus bodegas.».
Revocar una clave
En la lista de claves, haz clic en Revocar. La clave deja de funcionar de inmediato y no se puede reactivar. Los avisos atados a esa clave se apagan. Revoca cualquier clave que haya quedado expuesta y emite una por integración, para poder cortar una sin afectar a las demás.
Siguientes pasos
- — Formato de los datos, paginación, límites y errores.
- — Lee el catálogo.
- — Registra tu primera venta.