Skip to content

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.

Página Integraciones sin claves de API ni avisos configuradosPágina Integraciones sin claves de API ni avisos configurados
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. En Dónde puede consultar y vender, deja Todo el comercio o elige Solo las sucursales que elijas y marca las sucursales. Consulta .
  7. En Qué productos vende, deja Todo el catálogo o elige Solo algunas categorías o marcas y márcalas.
  8. 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.
  9. Haz clic en Crear clave.
Formulario Nueva clave de API con nombre, permisos, Dónde puede consultar y vender limitado a Marea Obarrio, Qué productos vende limitado a las categorías Damas y Accesorios, sucursal de las ventas, precios y vencimientoFormulario Nueva clave de API con nombre, permisos, Dónde puede consultar y vender limitado a Marea Obarrio, Qué productos vende limitado a las categorías Damas y Accesorios, sucursal de las ventas, precios y vencimiento
Nueva clave de API: permisos, dónde puede consultar y vender, qué productos vende, 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.

Ventana Tu clave de API con la clave zpk_ y el botón CopiarVentana Tu clave de API con la clave zpk_ y el botón Copiar
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 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.

Lista de claves de API con su nombre, permisos, estado, último uso y el botón RevocarLista de claves de API con su nombre, permisos, estado, último uso y el botón Revocar
Claves de API: permisos, estado y último uso de cada una.

Permisos ​

PermisoEn el panelQué permite
catalog:readVer el catálogoGET /products, GET /products/{id}, GET /categories y GET /brands
stock:readVer existenciasGET /stock, GET /branches y GET /warehouses
stock:writeAjustar existenciasPOST /stock/adjustments, GET /stock/adjustments/{id} y PUT /stock. Respeta la aprobación de ajustes del comercio; consulta
orders:writeCrear pedidosPOST /orders con type: "sale", POST /orders/preview, GET /payment-methods, GET /branches y GET /warehouses
orders:set-priceFijar el precio de ventaEnviar price en cada línea de POST /orders en lugar de usar el precio del POS
layaways:writeCrear apartados y registrar abonosPOST /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:pendingCrear pedidos por cobrarPOST /orders con type: "pending". También POST /orders/preview, GET /payment-methods, GET /branches y GET /warehouses
quotations:writeCrear cotizacionesPOST /quotations y GET /quotations/{id} en las cotizaciones de la clave
returns:writeRegistrar devolucionesGET /return-reasons y POST /orders/{id}/returns en las ventas de la clave
gift_cards:redeemCobrar con tarjeta de regaloGET /gift-cards/{code} y los pagos con giftCardCode. Con él, GET /payment-methods incluye la forma de pago de tarjeta de regalo
orders:readVer pedidosGET /orders y GET /orders/{id}, con la factura y su PDF
customers:readVer clientesGET /customers y GET /customers/{id}
customers:writeCrear y modificar clientesPOST /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 /branches y GET /warehouses solo traen las sucursales y bodegas de la clave.
  • Pedir una sucursal o una bodega fuera del alcance responde 403 con code: "out_of_scope", en GET /products, GET /stock, POST /orders, POST /quotations y 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:

http
Authorization: Bearer zpk_…
http
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.

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

bash
curl https://api.zenci.app/public/v1/me \
  -H "Authorization: Bearer $ZENCI_API_KEY"
json
{
  "scopes": ["catalog:read", "stock:read", "orders:write"],
  "defaultBranchId": "b7n2q8w4e1r9t3y6u0i5o2p7",
  "priceListId": "l4k8j2h6g0f3d7s1a5p9o3i7",
  "priceList": { "id": "l4k8j2h6g0f3d7s1a5p9o3i7", "name": "Mayoreo" },
  "locationScope": {
    "branchIds": ["b7n2q8w4e1r9t3y6u0i5o2p7"],
    "warehouseIds": ["w2e6r0t4y8u1i5o9p3a7s1d5"]
  },
  "catalogScope": null
}
CampoDescripción
scopesPermisos de la clave
defaultBranchIdSucursal de las ventas, o null si cada venta debe enviar branchId
priceListId, priceListLa 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
locationScopeLas 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
catalogScopeLas 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 ​

HTTPcodeCausa
401unauthorizedFalta la clave (An API key is required), o es desconocida, está revocada o venció (Invalid or revoked API key)
403forbiddenLa suscripción del comercio está restringida. El acceso vuelve cuando se regulariza el pago
404not_foundEl comercio no tiene activa la API para integraciones
429rate_limitedMá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.

Documentación oficial de Zelta