Productos (API)

El catálogo de productos se crea y edita solo desde el dashboard (proyecto → Productos). Sobre la API de Integración el catálogo es de solo lectura: consume los productos existentes por su productCode para armar suscripciones y cargos.

Todos los endpoints requieren tu API key de proyecto en el header X-API-Key.

Tipos de producto

Cada producto se define por paymentType (one_time o recurring) y, para los de pago único, requiresSubscription:

paymentType	requiresSubscription	Es un…
recurring	—	Plan — item de suscripción facturado cada ciclo
one_time	false	Producto independiente — compra única (p. ej. créditos)
one_time	true	Addon — cobro único sobre una suscripción activa

Listar productos

GET /v1/products

Parámetros de consulta:

Campo	Tipo	Requerido	Descripción
status	string	No	Filtra por estado del producto (p. ej. activos)
paymentType	string	No	Filtra por one_time o recurring
lim	integer	No	Tamaño de página
off	integer	No	Offset (paginación)

curl "https://api-pay.zelta.dev/v1/products?paymentType=recurring" \
  -H "X-API-Key: tu-api-key-de-proyecto"

Obtener un producto

GET /v1/products/:productCode

curl "https://api-pay.zelta.dev/v1/products/pos-base" \
  -H "X-API-Key: tu-api-key-de-proyecto"

Devuelve el producto identificado por su productCode (el listado devuelve el mismo objeto por cada elemento, bajo data.products junto con total).

{
  "success": true,
  "data": {
    "product": {
      "id": "111",
      "projectId": "prj_1234567890abcdef",
      "productCode": "pos-base",
      "name": "Plan base",
      "description": "Plan mensual del POS",
      "paymentType": "recurring",
      "requiresSubscription": false,
      "price": 3500,
      "currency": "USD",
      "billingPeriod": "month",
      "billingInterval": 1,
      "status": "active",
      "createdAt": "2026-06-04T00:00:00.000Z",
      "updatedAt": "2026-06-04T00:00:00.000Z"
    }
  }
}

Campo	Tipo	Descripción
id	string	Identificador único del producto
projectId	string	Proyecto al que pertenece el producto
productCode	string	Código único con el que lo referencias en cargos y suscripciones
name	string	Nombre del producto
description	string | null	Descripción (null si no se definió)
paymentType	string	one_time o recurring
requiresSubscription	boolean	Si es un addon que exige una suscripción activa (solo aplica a one_time)
price	integer	Precio en centavos
currency	string	Moneda (p. ej. USD)
billingPeriod	string | null	day, week, month o year; null para productos one_time
billingInterval	integer | null	Número de períodos por ciclo (p. ej. 1 = mensual con billingPeriod: month)
status	string	active, inactive o archived
createdAt	string	Fecha de creación (ISO 8601)
updatedAt	string	Fecha de última actualización (ISO 8601)

Para crear o editar productos, usa el dashboard

La API no expone endpoints de escritura sobre el catálogo. Si necesitas un nuevo plan, addon o producto independiente, créalo en el dashboard del proyecto y luego consúmelo por su productCode.

Siguientes pasos

• — usa los productCode recurrentes como items
• — cobra productos one_time a un cliente
• — visión general del modelo de proyectos