Autenticación

El API público de Zelta POS se autentica con una API key que identifica a tu negocio. Cada solicitud debe incluir la key en uno de dos headers: Authorization: Bearer o X-API-Key.

¿Cómo funciona?

Incluye tu API key en uno de estos headers (cualquiera de los dos es válido):

Authorization: Bearer zpk_live_xxx

X-API-Key: zpk_live_xxx

Las API keys de Zelta POS empiezan con el prefijo zpk_. La key identifica al negocio (tenant) — no necesitas enviar ningún header de empresa o sucursal adicional: el negocio se resuelve automáticamente a partir de la key.

Sin scopes por key

Una API key válida tiene acceso a todo el API público. No existen permisos granulares por endpoint. Controla el acceso generando y revocando keys desde el dashboard.

Obtener una API key

Configuración → API y Webhooks → pestaña Claves API.

1. Inicia sesión en el .
2. Ve a Configuración → API y Webhooks → pestaña Claves API.
3. Haz clic en Nueva API key.
4. Asígnale un nombre descriptivo y, si quieres, una sucursal por defecto (se usará cuando una solicitud no especifique branchId). Activa Afecta inventario si sus operaciones deben mover stock real.
5. Copia la key generada y guárdala de forma segura: solo se muestra una vez.

Nombre, sucursal por defecto y el interruptor «Afecta inventario».

El secreto zpk_… se muestra una sola vez: cópialo y guárdalo.

Sucursal por defecto y efecto en inventario

Cada API key puede tener una sucursal por defecto y un indicador de si sus operaciones afectan el inventario. Esto te permite, por ejemplo, dedicar una key a tu e-commerce con su propia bodega.

Uso de la key

curl -X GET "https://api-pos.zelta.dev/public/v1/branches" \
  -H "Authorization: Bearer zpk_live_xxx"

Ejemplo JS

const res = await fetch('https://api-pos.zelta.dev/public/v1/branches', {
  headers: { 'Authorization': `Bearer ${process.env.ZELTA_POS_API_KEY}` }
});
const data = await res.json();

Ejemplo Py

import requests

res = requests.get(
    'https://api-pos.zelta.dev/public/v1/branches',
    headers={'Authorization': 'Bearer zpk_live_xxx'}
)
data = res.json()

Errores de autenticación

HTTP	code	Causa
401	unauthorized	API key ausente, inválida o revocada
403	forbidden	La suscripción del negocio está restringida — regulariza el pago para restaurar el acceso al API

Ejemplo de respuesta de error:

{
  "code": "unauthorized",
  "message": "Missing or invalid API key"
}

Buenas prácticas de seguridad

• Nunca expongas la key en código fuente público, repositorios ni URLs.
• Usa variables de entorno para almacenarla en tu aplicación.
• Genera una key por integración para poder revocarla de forma aislada.
• Revoca de inmediato cualquier key comprometida desde el dashboard.

# Ejemplo con variable de entorno
export ZELTA_POS_API_KEY="zpk_live_xxx"

curl -X GET "https://api-pos.zelta.dev/public/v1/branches" \
  -H "Authorization: Bearer $ZELTA_POS_API_KEY"

Siguientes pasos

• — URL base, formato de respuestas, errores y paginación
• — Descubre los id de sucursales, bodegas y métodos de pago
• — Crea tu primera venta por API
• — Recibe eventos en tiempo real