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 existencias, registrar y consultar ventas, 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.

Administración → Integraciones, antes de emitir la primera clave.

1. Haz clic en Emitir clave.
2. Escribe un Nombre para reconocerla después, por ejemplo «Tienda en línea».
3. Marca en Qué puede hacer esta clave solo los permisos que tu integración necesita (ver la tabla de abajo).
4. 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.
5. En Precios, deja Los del catálogo o elige una lista de precios. Con una lista, la tienda ve y vende con esos precios.
6. 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.
7. Haz clic en Crear clave.

Nueva clave de API: permisos, sucursal de las ventas, precios y vencimiento.

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.

La clave se muestra una sola vez. Cópiala antes de cerrar.

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 estado (Activa, Vencida o Revocada), el último uso y la fecha de creación.

Claves de API: permisos, estado y último uso de cada una.

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
orders:write	Crear pedidos	POST /orders, 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
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.

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 vencimiento se fijan al emitir la clave y no se editan después. Para cambiarlos, emite una clave nueva y revoca la anterior.

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" }
}

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

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.

Revocar una clave

En la lista de claves, haz clic en Revocar. La clave deja de funcionar de inmediato y no se puede reactivar. 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.