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

El código de producto

Zelta Pay genera el productCode al crear el producto en el dashboard, con el formato prod_ seguido de 10 letras mayúsculas o dígitos (por ejemplo, prod_PLANBASE01). No se puede elegir ni cambiar. Cópialo del dashboard o de GET /v1/products para usarlo en cargos y suscripciones.

Listar productos

GET /v1/products

Parámetros de consulta:

Campo	Tipo	Requerido	Descripción
status	string	No	Filtra por estado: active, inactive o archived. Sin este filtro se devuelven productos de todos los estados
paymentType	string	No	Filtra por one_time o recurring
lim	integer	No	Tamaño de página, de 1 a 100 (default 10)
off	integer	No	Offset (paginación)

Los resultados se ordenan del más reciente al más antiguo. La respuesta trae los productos en data.products junto con total.

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

Filtra por productos activos

Solo los productos active se pueden usar en nuevos cargos, suscripciones o links de pago de cliente; con uno inactive o archived la solicitud falla con ERR_PRODUCT_NOT_ACTIVE. Usa status=active para listar solo los que puedes usar.

Obtener un producto

GET /v1/products/:productCode

curl "https://api-pay.zelta.dev/v1/products/prod_PLANBASE01" \
  -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). Si no existe en el proyecto, responde 404 con ERR_PRODUCT_NOT_FOUND.

{
  "success": true,
  "data": {
    "product": {
      "id": "7314444555566667777",
      "projectId": "7301234567890123456",
      "productCode": "prod_PLANBASE01",
      "name": "Plan base",
      "description": "Plan mensual del POS",
      "paymentType": "recurring",
      "requiresSubscription": false,
      "price": 3500,
      "currency": "USD",
      "billingPeriod": "month",
      "billingInterval": 1,
      "status": "active",
      "metadata": null,
      "createdAt": "2026-06-04T00:00:00.000Z",
      "updatedAt": "2026-06-04T00:00:00.000Z",
      "deletedAt": null
    }
  },
  "message": "Operation completed successfully",
  "timestamp": "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 (mínimo 100)
currency	string	Moneda (p. ej. USD)
billingPeriod	string | null	day, week, month o year; null para productos one_time
billingInterval	integer	Número de períodos por ciclo (p. ej. 1 = mensual con billingPeriod: month). Por defecto 1, también en productos one_time, donde no se usa
status	string	active, inactive o archived
createdAt	string	Fecha de creación (ISO 8601)
updatedAt	string	Fecha de última actualización (ISO 8601)

El objeto también incluye metadata y deletedAt, que puedes ignorar.

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.

Errores

Código	HTTP	Cuándo
ERR_PRODUCT_NOT_FOUND	404	No existe un producto con ese productCode en el proyecto
ERR_API_KEY_NOT_PROJECT_SCOPED	403	Usaste una API key de la cuenta en lugar de la del proyecto

Los parámetros de consulta inválidos devuelven 400 con el formato de .

Siguientes pasos

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