Catálogos

Los Catálogos son datos de referencia de solo lectura: impuestos, métodos de pago, bodegas y sucursales. Sirven para descubrir los id que necesitas antes de crear facturas, pagos o ajustes de stock.

Todas las rutas son relativas a la URL base de producción:

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

INFO

Todos los endpoints de esta página devuelven { "data": [ ... ] } y no usan paginación. Son listas completas y pequeñas.

TIP

Los métodos de pago y los impuestos no son valores fijos: cada cuenta define los suyos. Por eso se descubren con estos endpoints y se referencian por id en el resto de la API. Por ejemplo, el id de un método de pago se usa en y en .

Impuestos

GET /taxes

Devuelve el catálogo de impuestos ITBMS de Panamá.

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

Ejemplo JS

const res = await fetch('https://api-pos.zelta.dev/public/v1/taxes', {
  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/taxes',
    headers={'Authorization': 'Bearer zpk_live_xxx'}
)
data = res.json()

Respuesta

{
  "data": [
    { "code": "ITBMS_7", "name": "ITBMS 7%", "rate": "0.07" },
    { "code": "ITBMS_0", "name": "Exento", "rate": "0.00" }
  ]
}

Campo	Tipo	Descripción
code	string	Código del impuesto.
name	string	Nombre del impuesto.
rate	string	Tasa aplicada (proporción).

Métodos de pago

GET /payment-methods

Devuelve los métodos de pago configurados. Usa el id de cada método en facturas y pagos.

curl "https://api-pos.zelta.dev/public/v1/payment-methods" \
  -H "Authorization: Bearer zpk_live_xxx"

Ejemplo JS

const res = await fetch('https://api-pos.zelta.dev/public/v1/payment-methods', {
  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/payment-methods',
    headers={'Authorization': 'Bearer zpk_live_xxx'}
)
data = res.json()

Respuesta

{
  "data": [
    { "id": "pm_2x9a8b7c6d5e4f3g", "name": "Efectivo", "dgiCode": "01" },
    { "id": "pm_8h7g6f5d4s3a2x1z", "name": "Tarjeta", "dgiCode": null }
  ]
}

Campo	Tipo	Descripción
id	string	ID del método de pago. Úsalo en facturas y pagos.
name	string	Nombre del método de pago.
dgiCode	string | null	Código DGI del método. Puede ser null.

Bodegas

GET /warehouses

Devuelve las bodegas de la cuenta. Usa el id para consultar o fijar stock.

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

Ejemplo JS

const res = await fetch('https://api-pos.zelta.dev/public/v1/warehouses', {
  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/warehouses',
    headers={'Authorization': 'Bearer zpk_live_xxx'}
)
data = res.json()

Respuesta

{
  "data": [
    { "id": "wh_1a2b3c4d5e6f7g8h", "name": "Bodega principal", "isBranch": true },
    { "id": "wh_9i0j1k2l3m4n5o6p", "name": "Almacén central", "isBranch": false }
  ]
}

Campo	Tipo	Descripción
id	string	ID de la bodega.
name	string	Nombre de la bodega.
isBranch	boolean	Indica si la bodega corresponde a una sucursal.

Sucursales

GET /branches

Devuelve las sucursales de la cuenta. Usa el id como branchId al crear facturas.

curl "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()

Respuesta

{
  "data": [
    {
      "id": "br_0p9o8i7u6y5t4r3e",
      "name": "Sucursal Vía España",
      "warehouseId": "wh_1a2b3c4d5e6f7g8h",
      "solerbaBranchId": null
    }
  ]
}

Campo	Tipo	Descripción
id	string	ID de la sucursal. Úsalo como branchId en facturas.
name	string	Nombre de la sucursal.
warehouseId	string | null	Bodega asociada a la sucursal.
solerbaBranchId	string | null	Identificador de la sucursal en Solerba.

Problemas comunes

Código	HTTP	Causa probable
unauthorized	401	API key ausente o inválida.
forbidden	403	La key no tiene acceso al recurso solicitado.
rate_limited	429	Se superó el límite de peticiones.
internal_error	500	Error interno del servidor.

Siguientes pasos

• — usa los id de métodos de pago y sucursales para registrar ventas.
• — registra pagos con el id de un método de pago.
• — consulta y fija stock por bodega.