Referencia API

Documentación general del API público de Zelta POS: URL base, formato de respuestas, códigos de error, paginación y convenciones comunes a todos los endpoints.

URL Base

https://api-pos.zelta.dev/public/v1

Todas las solicitudes deben usar HTTPS y todas las rutas de esta documentación son relativas a esa base. La autenticación se realiza con una API key — ver .

Referencia interactiva (OpenAPI)

El API publica su especificación OpenAPI 3.1 y una referencia interactiva donde puedes explorar y probar los endpoints:

Recurso	URL
Referencia interactiva	https://api-pos.zelta.dev/public/v1/docs
Especificación OpenAPI	https://api-pos.zelta.dev/public/v1/openapi.json

Formato de respuesta

El API usa dos formas según el tipo de respuesta:

Recurso único

Los endpoints que devuelven un solo recurso retornan el objeto directamente, sin envoltorio:

{
  "id": "abc123",
  "name": "Cliente de ejemplo",
  "createdAt": "2026-06-30T15:30:00.000Z"
}

Listas

Los endpoints de lista envuelven los resultados en data:

{
  "data": [
    { "id": "abc123" },
    { "id": "def456" }
  ]
}

Si agregas el parámetro metadata=true, la respuesta incluye además el total de registros:

{
  "data": [ ... ],
  "metadata": { "total": 142 }
}

Códigos de estado y errores

Las respuestas de error tienen un formato plano con code y message:

{
  "code": "validation_error",
  "message": "Validation failed - items must contain at least 1 element"
}

code	HTTP	Descripción
validation_error	400	Datos inválidos o faltantes en la solicitud
unauthorized	401	API key ausente, inválida o revocada
forbidden	403	Sin acceso o suscripción del negocio restringida
not_found	404	El recurso solicitado no existe
conflict	409	Conflicto con el estado actual del recurso
insufficient_stock	409	No hay stock suficiente para completar la operación
rate_limited	429	Se superó el límite de solicitudes
internal_error	500	Error interno — contacta a soporte

Errores de negocio

Algunas operaciones pueden devolver códigos específicos de dominio como branch_required, warehouse_not_found, invalid_sku, customer_not_found, payment_method_invalid o fiscal_config_missing, con un message que describe la causa y cómo resolverla.

Paginación y sincronización

Todos los endpoints de lista (excepto y la lista de ) aceptan los mismos parámetros de query para paginar y sincronizar de forma incremental:

Parámetro	Tipo	Default	Descripción
start	integer	0	Desplazamiento (offset) desde el inicio, base cero
limit	integer	30	Cantidad de registros a devolver (máx. 100)
updatedSince	string	—	Fecha-hora ISO 8601. Devuelve solo registros actualizados a partir de ese momento
from	string	—	Fecha inicial YYYY-MM-DD (inclusiva, zona horaria del negocio)
to	string	—	Fecha final YYYY-MM-DD (inclusiva)
metadata	boolean	false	Si es true, incluye metadata.total en la respuesta

Sincronización incremental

Para mantener un sistema externo sincronizado, guarda el momento de tu última consulta y úsalo en updatedSince en la siguiente llamada. Así solo recibes lo que cambió desde entonces.

Ejemplo:

curl -X GET "https://api-pos.zelta.dev/public/v1/invoices?updatedSince=2026-06-30T00:00:00Z&limit=50&metadata=true" \
  -H "Authorization: Bearer zpk_live_xxx"

Ejemplo JS

const params = new URLSearchParams({
  updatedSince: '2026-06-30T00:00:00Z',
  limit: '50',
  metadata: 'true'
});
const res = await fetch(`https://api-pos.zelta.dev/public/v1/invoices?${params}`, {
  headers: { 'Authorization': `Bearer ${process.env.ZELTA_POS_API_KEY}` }
});
const { data, metadata } = await res.json();

Ejemplo Py

import requests

res = requests.get(
    'https://api-pos.zelta.dev/public/v1/invoices',
    params={'updatedSince': '2026-06-30T00:00:00Z', 'limit': 50, 'metadata': 'true'},
    headers={'Authorization': 'Bearer zpk_live_xxx'}
)
body = res.json()

Direccionamiento de productos

Los productos (variantes) se referencian de dos maneras:

• id — el identificador interno de la variante en Zelta POS (lo obtienes de ). Tiene precedencia si envías ambos.
• referenceId — una referencia externa propia de tu sistema (hasta 120 caracteres), única por negocio.

SKU y código de barras no se aceptan

Las llamadas al API direccionan productos por id o referenceId, nunca por SKU ni código de barras. En compras, transferencias y ajustes de inventario solo se admite referenceId.

Impuestos (ITBMS)

El ITBMS de cada producto se toma de su configuración en el catálogo y no se puede sobrescribir por línea en facturas ni compras. Las son la excepción: aceptan una tasa de impuesto por línea. Consulta el catálogo de impuestos con .

Siguientes pasos

• — Cómo obtener y usar tu API key
• — Descubre id de impuestos, métodos de pago, bodegas y sucursales
• — Crea ventas y facturas electrónicas
• — Recibe eventos en tiempo real