Saltar al contenido principal
La CLI de Onflay es la forma más rápida de arrancar un proyecto de integración sin tocar el dashboard. Define tu catálogo en un archivo TypeScript, aplícalo al entorno y genera tipos listos para usar en tu backend — todo desde la terminal.

​
Instalación y autenticación

No necesitas instalar nada de forma global. Usa npx directamente o agrégala como devDependency: 
# Sin instalación
npx onflay --help

# Como devDependency (recomendado para proyectos)
pnpm add -D onflay
Autentica exportando tu API key de sandbox: 
export ONFLAY_API_KEY=sk_test_...
Agrega ONFLAY_API_KEY a tu archivo .env y cárgalo con dotenv-cli o el mecanismo de tu framework. La CLI lo detecta automáticamente.

​
Flujo CLI-first para un proyecto nuevo

Puedes configurar toda tu integración sin abrir el dashboard:
1

Crea el archivo de catálogo

Define tus productos, precios o listings en pricing.onflay.ts.
2

Revisa el plan

Ejecuta catalog plan para ver qué se creará o modificará sin aplicar nada.
3

Aplica el catálogo

Ejecuta catalog apply para sincronizar el archivo con tu entorno sandbox.
4

Genera los tipos

Ejecuta catalog codegen para obtener un archivo TypeScript con IDs y helpers listos para importar.
5

Levanta el túnel de webhooks

Ejecuta onflay listen para recibir eventos en tu servidor local.
6

Dispara un evento de prueba

Ejecuta onflay trigger para simular un pago completado y probar tu handler.

​
Catálogo declarativo

El catálogo es un archivo .ts que exporta la definición de lo que vendes. La CLI lo lee, calcula la diferencia con el entorno y aplica solo los cambios necesarios — similar a Terraform para tu catálogo de Onflay.

​
Estructura del archivo

// pricing.onflay.ts
import { defineCatalog } from 'onflay/catalog';

export default defineCatalog({
  products: [
    {
      key: 'pro-plan',
      name: 'Plan Pro',
      description: 'Acceso completo a todas las funciones.',
      prices: [
        {
          key: 'pro-monthly',
          nickname: 'Pro mensual',
          unitAmountInCents: 2900,
          currency: 'usd',
          interval: 'month',
        },
        {
          key: 'pro-annual',
          nickname: 'Pro anual',
          unitAmountInCents: 29000,
          currency: 'usd',
          interval: 'year',
        },
      ],
    },
    {
      key: 'starter-plan',
      name: 'Plan Starter',
      description: 'Para proyectos personales y pruebas.',
      prices: [
        {
          key: 'starter-monthly',
          nickname: 'Starter mensual',
          unitAmountInCents: 900,
          currency: 'usd',
          interval: 'month',
        },
      ],
    },
  ],
});
El campo key es tu identificador local — estable y único dentro del archivo. La CLI lo usa para rastrear qué objeto de Onflay corresponde a cada entrada. No lo cambies una vez aplicado, o la CLI lo tratará como un objeto nuevo.

​
Pagos únicos

Para productos sin recurrencia, omite interval: 
prices: [
  {
    key: 'ebook-usd',
    nickname: 'Ebook — pago único',
    unitAmountInCents: 1500,
    currency: 'usd',
  },
],

​
Listings y Variants

Si vendes servicios o experiencias con variantes (duración, paquete, nivel de acceso), usa listings en lugar de products: 
import { defineCatalog } from 'onflay/catalog';

export default defineCatalog({
  listings: [
    {
      key: 'consultoria-ux',
      name: 'Consultoría UX',
      description: 'Sesión de consultoría de diseño de producto.',
      variants: [
        {
          key: 'consultoria-30min',
          name: '30 minutos',
          unitAmountInCents: 4900,
          currency: 'usd',
        },
        {
          key: 'consultoria-60min',
          name: '60 minutos',
          unitAmountInCents: 8900,
          currency: 'usd',
        },
      ],
    },
  ],
});

​
Catálogo mixto

Puedes combinar products y listings en el mismo archivo: 
export default defineCatalog({
  products: [ /* ... */ ],
  listings: [ /* ... */ ],
});

​
catalog plan — previsualizar cambios

Muestra qué se creará, actualizará o archivará sin modificar nada en el entorno. 
npx onflay catalog plan pricing.onflay.ts
Salida de ejemplo: 
~ Plan Pro               (actualizar descripción)
+ Plan Starter           (crear)
+ Starter mensual        (crear price)
  Pro mensual            (sin cambios)
  Pro anual              (sin cambios)
Úsalo en CI para detectar drift entre el archivo y el entorno.

​
catalog apply — aplicar cambios

Sincroniza el archivo con el entorno activo según la API key configurada. 
npx onflay catalog apply pricing.onflay.ts
apply modifica objetos en el entorno apuntado por ONFLAY_API_KEY. Con sk_test_ toca sandbox; con sk_live_ toca producción. Revisa siempre el plan antes.

​
catalog codegen — generar tipos TypeScript

Genera un archivo con los IDs reales de Onflay mapeados a tus keys, listo para importar en tu backend: 
npx onflay catalog codegen pricing.onflay.ts --out src/onflay-catalog.ts
Archivo generado (src/onflay-catalog.ts): 
// Archivo generado automáticamente — no editar manualmente
export const catalog = {
  products: {
    'pro-plan': { id: 'prod_abc123', name: 'Plan Pro' },
    'starter-plan': { id: 'prod_def456', name: 'Plan Starter' },
  },
  prices: {
    'pro-monthly': { id: 'price_ghi789', unitAmountInCents: 2900 },
    'pro-annual': { id: 'price_jkl012', unitAmountInCents: 29000 },
    'starter-monthly': { id: 'price_mno345', unitAmountInCents: 900 },
  },
} as const;
Úsalo directamente al crear sesiones de checkout: 
import { catalog } from '@/onflay-catalog';
import { Onflay } from '@onflay/node';

const onflay = new Onflay(process.env.ONFLAY_API_KEY!);

const session = await onflay.checkoutSessions.create({
  lineItems: [{ priceId: catalog.prices['pro-monthly'].id, quantity: 1 }],
  successUrl: 'https://tu-app.com/gracias',
  cancelUrl: 'https://tu-app.com/precios',
});

​
Webhooks locales

Levanta un túnel para recibir eventos de Onflay en tu servidor local durante el desarrollo: 
npx onflay listen --forward-to http://localhost:3000/api/webhooks/onflay
La CLI imprime un secret temporal que expira al cerrar el proceso: 
  Webhook secret: whsec_dev_...
  Esperando eventos → http://localhost:3000/api/webhooks/onflay
Expórtalo para que tu handler lo use: 
export ONFLAY_WEBHOOK_SECRET=whsec_dev_...
O agrégalo a tu .env.local si tu framework lo carga automáticamente.
En producción usa el secret permanente del dashboard, no el whsec_dev_... que genera listen.

​
Disparar eventos de prueba

Simula un evento sin necesitar un pago real: 
npx onflay trigger payment.completed
Eventos disponibles para trigger:
EventoDescripción
payment.completedPago exitoso procesado
payment.refundedReembolso emitido
checkout.abandonedSesión expiró sin pago
payout.sentPayout enviado al creador
trigger solo funciona en sandbox. No lo uses con sk_live_.

​
Gestión de eventos

Consulta y reenvía eventos pasados del entorno: 
# Listar eventos recientes
npx onflay events list

# Ver detalle de un evento
npx onflay events show evt_...

# Reenviar un evento al webhook configurado
npx onflay events resend evt_...
events resend es útil para reprobar un handler sin crear una transacción nueva.

​
Scripts recomendados en package.json

{
  "scripts": {
    "catalog:plan": "onflay catalog plan pricing.onflay.ts",
    "catalog:apply": "onflay catalog apply pricing.onflay.ts",
    "catalog:codegen": "onflay catalog codegen pricing.onflay.ts --out src/onflay-catalog.ts",
    "webhooks:dev": "onflay listen --forward-to http://localhost:3000/api/webhooks/onflay"
  }
}
Con esto puedes correr pnpm catalog:plan antes de cada deploy para verificar que el catálogo esté sincronizado.