Skip to main content
Deja que Sentra escriba tu código de integración por ti.
Usa nuestro asistente de IA en VS Code, Cursor o Windsurf para generar código de SDK/API, controladores de webhooks, asignaciones de créditos y mucho más; solo tienes que describir lo que necesitas.
Prueba Sentra: integración con IA →
En este tutorial crearás NeuralAPI, una plataforma de IA escalonada en la que cada plan de suscripción incluye una asignación mensual de créditos de tokens, los clientes pueden comprar paquetes de recarga cuando se están quedando sin créditos y tu backend descuenta créditos automáticamente a medida que OpenAI procesa las solicitudes.
Este tutorial utiliza Node.js/Express + el SDK de OpenAI. Los conceptos de Dodo Payments (créditos, medidores y webhooks) se aplican a cualquier framework o proveedor de IA; adáptalos libremente.
Al final de este tutorial, sabrás cómo:
  • Crear un entitlement de crédito personalizado (tokens) y un medidor que descuente créditos automáticamente
  • Asociar créditos a planes de suscripción (con y sin exceso de uso) y a un producto de recarga de un solo pago
  • Conectar un endpoint real de completado de OpenAI que facture los tokens mediante Dodo Payments
  • Consultar el saldo de créditos actual de un cliente mediante el SDK
  • Verificar firmas de webhook y enrutar eventos de crédito de Dodo Payments

Lo que vamos a crear

Este es el modelo de precios de NeuralAPI:
Antes de comenzar, asegúrate de tener:
  • Una cuenta de Dodo Payments (el modo de prueba es suficiente)
  • Una clave de API de OpenAI
  • Node.js 18+
  • Conocimientos básicos de TypeScript/Node.js

Paso 1: Crea tu entitlement de crédito de tokens

Primero, crea el entitlement de crédito que compartirán ambos planes de suscripción y el paquete de recarga. Piensa en esto como la definición de la unidad de «token» que utiliza tu plataforma.
Página de listado de créditos que muestra los entitlements de crédito creados

The Credits tab under Products shows all your credit entitlements.

1

Navigate to Credits

  1. Inicia sesión en tu panel de Dodo Payments
  2. Haz clic en Products en la barra lateral izquierda
  3. Selecciona la pestaña Credits
  4. Haz clic en Create Credit
2

Configure the credit unit

Completa los datos básicos de tu crédito de tokens:Nombre del crédito: API TokensTipo de crédito: selecciona Custom UnitNombre de la unidad: tokenPrecisión: 0 (los tokens siempre son números enteros)Caducidad del crédito: 30 days (los créditos se restablecen en cada ciclo de facturación)
La precisión no se puede cambiar después de crear un crédito. Para los recuentos de tokens, 0 (números enteros) casi siempre es la opción correcta.
3

Skip overage at the credit level

Deja el exceso de uso deshabilitado aquí; lo configurarás por plan al asociar el crédito a los productos. Esto permite que el plan Starter bloquee el uso al llegar a cero, mientras que el plan Pro permite el exceso de uso.
La configuración del exceso de uso definida aquí es la predeterminada. Cada asociación de producto puede anularla; eso es exactamente lo que haremos en el paso 3.
4

Save and copy the credit ID

Haz clic en Create Credit. Una vez guardado, abre el crédito y copia su ID; tiene un aspecto similar a cent_xxxxxxxxxxxx.
Tu entitlement de crédito API Tokens está listo. A continuación, crea un medidor para que los eventos de uso activen los descuentos automáticamente.

Paso 2: Crea un medidor para el uso de tokens

Un medidor agrega los eventos de uso entrantes y los convierte en descuentos de créditos. Lo necesitas antes de crear los productos de los planes, ya que lo asociarás durante la creación del producto en el paso 3.
1

Open the Meters section

  1. En la barra lateral del panel, ve a ProductsMeters
  2. Haz clic en Create Meter
2

Configure the meter

Completa lo siguiente:Nombre del medidor: Token Usage MeterNombre del evento: api.tokens_used (debe coincidir exactamente con lo que envía tu aplicación)Tipo de agregación: Sum; sumamos el recuento de tokens de cada eventoSobre la propiedad: tokens; la clave de metadata de cada evento cuyo valor se sumaráUnidad de medición: tokens
Los nombres de eventos distinguen entre mayúsculas y minúsculas. api.tokens_usedApi.Tokens.Used; elige uno y úsalo siempre.
Guarda el medidor y copia su ID; lo necesitarás al asociarlo a los productos.
El medidor se ha creado. Ahora podemos conectarlo al crédito al configurar los productos.

Paso 3: Crea los productos de los planes

Ambos planes deben ser productos de Usage Based Billing, no simples productos de suscripción: los medidores solo se pueden asociar a productos UBB, y necesitas que el medidor descuente créditos automáticamente a medida que los clientes llaman a tu API. Los productos UBB siguen admitiendo una tarifa base recurrente ($29 / $99); el uso adicional se factura en créditos.
Configuración de precios de Usage Based Billing

Usage Based Billing pricing type with meter configuration.

Plan Starter ($29/mes — 10 M de tokens, sin exceso de uso)

1

Create the Starter UBB product

  1. Ve a Products → Create Product
  2. Selecciona Usage Based Billing como tipo de precios
  3. Completa lo siguiente:
Nombre del producto: NeuralAPI StarterDescripción: 10 million API tokens per month. Perfect for individual developers and small projects.Precio fijo: 29.00 (la tarifa base recurrente, que se factura mensualmente incluso antes de cualquier uso)Ciclo de facturación: MonthlyMoneda: USD
2

Attach the meter

En la sección Select meter, haz clic en + y añade Token Usage Meter. Después, en el medidor:
  1. Activa Bill usage in Credits
  2. Entitlement de crédito: selecciona API Tokens
  3. Unidades del medidor por crédito: 1; cada token del evento equivale a 1 crédito descontado
  4. Umbral gratuito: 0; la asignación de créditos es el «nivel gratuito» del cliente, por lo que no necesitamos una banda gratuita adicional
Medidor con Bill usage in Credits habilitado y API Tokens seleccionados

Toggle 'Bill usage in Credits' on the meter and pick the credit entitlement.

Esta es la conexión que hace que los eventos api.tokens_used entrantes descuenten realmente el saldo del cliente.
3

Configure credit issuance for Starter

En el producto, desplázate hasta la sección de configuración de créditos que aparece una vez asociado un medidor facturado por créditos:Créditos emitidos por ciclo de facturación: 10000000Permitir exceso de uso: Deshabilitado; los clientes de Starter quedan bloqueados cuando se agotan los tokensImportar configuración de crédito predeterminada: Habilitado; utiliza la caducidad de 30 días del entitlement de crédito
Formulario de configuración de crédito con cantidad por ciclo y configuración de exceso de uso

Configure credit issuance per cycle on the UBB product.

Haz clic en Save y copia el ID del producto.
Plan Starter: tarifa base de $29/mes, 10 M de tokens por ciclo, bloqueado al llegar a cero y con descuentos automáticos mediante el medidor.

Plan Pro ($99/mes — 40 M de tokens, exceso de uso habilitado)

1

Create the Pro UBB product

El flujo es el mismo que para Starter, pero con cantidades mayores:Nombre del producto: NeuralAPI ProDescripción: 40 million API tokens per month with overage. Built for production applications.Precio fijo: 99.00Ciclo de facturación: MonthlyMoneda: USD
2

Attach the meter

Igual que en Starter: añade Token Usage Meter, activa Bill usage in Credits, selecciona API Tokens, establece Unidades del medidor por crédito en 1 y Umbral gratuito en 0.
3

Configure credit issuance with overage

Configura la emisión de créditos, esta vez habilitando el exceso de uso:Créditos emitidos por ciclo de facturación: 40000000Importar configuración de crédito predeterminada: Deshabilitar; necesitamos personalizar la configuración del exceso de uso por productoPermitir exceso de uso: HabilitadoPrecio por unidad: 0.000005 USD por token (es decir, 0.005porcada1.000tokenso0.005 por cada 1.000 tokens o 5 por cada millón de tokens; por encima de la tarifa efectiva por token del plan para desincentivar el consumo excedente)Comportamiento del exceso de uso: Bill overage at billing; el exceso de uso se cobra en la siguiente factura y después el saldo se restableceGuarda el producto y copia su ID.
Plan Pro: tarifa base de 99/mes,40Mdetokensporciclo,excesodeusoa99/mes, 40 M de tokens por ciclo, exceso de uso a 0.005 por cada 1.000 tokens y descuentos automáticos mediante el medidor.

Paso 4: Crea el paquete de recarga de tokens

El paquete de recarga es una compra única que añade 5.000.000 de tokens al saldo de un cliente existente.
Sección de precios del producto con Single Payment seleccionado

Single Payment pricing selected for a one-time credit product.

1

Create a one-time product

  1. Ve a Products → Create Product
  2. Selecciona Single Payment como tipo de precios
  3. Completa lo siguiente:
Nombre del producto: Token Top-Up PackDescripción: Instantly add 5 million tokens to your NeuralAPI balance.Precio: 19.00Moneda: USD
2

Attach the token credit

  1. En la sección Entitlements, haz clic en Attach junto a Credits
  2. Selecciona API Tokens
  3. Establece Créditos emitidos: 5000000
  4. Deshabilita Import Default Credit Settings; queremos anular la caducidad predeterminada de 30 días
  5. Establece Caducidad del crédito: 365 days
  6. Guarda el producto
Copia el ID del producto.
¿Por qué una caducidad más larga para las recargas? Los créditos de suscripción se restablecen cada 30 días porque ese es el ciclo. Las recargas son compras prepagadas: el cliente pagó $19 por adelantado y espera razonablemente que esos tokens duren más de un mes. Los 365 días se ajustan al funcionamiento de los créditos prepagados reales de OpenAI, AWS y Anthropic, a la vez que limitan tu responsabilidad para evitar que los clientes acumulen créditos indefinidamente.
Paquete de recarga configurado: su compra concede 5.000.000 de tokens válidos durante 365 días.

Paso 5: Crea el backend

Ahora crearemos el servidor Express que gestiona el checkout de suscripciones, el checkout de recargas, los completados reales de OpenAI con facturación por tokens, las consultas de saldo y los eventos de webhook de créditos.
1

Set up your project

Crea un tsconfig.json:
tsconfig.json
Actualiza los scripts de package.json:
package.json
2

Set up environment variables

Crea .env con tus credenciales y los ID de los pasos anteriores:
.env
Nunca confirmes .env en el control de versiones. Añádelo inmediatamente a .gitignore.
Completarás DODO_PAYMENTS_WEBHOOK_KEY en el paso 7, después de registrar tu endpoint de webhook.
3

Implement the server

Crea src/server.ts:
Backend terminado: checkout de suscripciones, checkout de recargas, completado de OpenAI con facturación por tokens mediante medidores, consulta de saldo y controlador de webhook verificado.
@dodopayments/ingestion-blueprints proporciona trackers listos para usar que automatizan la llamada usageEvents.ingest por ti, incluidos los usos de LLM Blueprint, API gateway, object storage, streams y time-range.
4

A note on how deductions actually happen

Quizá hayas notado que no existe una llamada explícita para «descontar N créditos». Está diseñado así:
  1. Tu handler llama a OpenAI y obtiene usage.total_tokens (por ejemplo, 1532).
  2. Ingestas un único evento de uso: event_name: api.tokens_used, metadata: { tokens: 1532 }.
  3. Token Usage Meter agrega los eventos por cliente.
  4. Como el medidor está conectado al crédito API Tokens con Bill usage in Credits, Dodo Payments descuenta 1532 créditos de la asignación no caducada más antigua del cliente (FIFO).
  5. Si el exceso de uso está habilitado y el cliente baja de cero, el déficit se registra y se factura en la siguiente factura.
El medidor se encarga de todo eso. Tu código solo ingesta eventos.

Paso 6: Añade un frontend de demostración

Crea public/index.html para probar todos los flujos en el navegador. Guardamos el ID del cliente en localStorage para que suscribirse → generar → recargar compartan la misma identidad, imitando una aplicación con sesión iniciada:

Paso 7: Conecta el webhook

Los webhooks permiten que tu servidor reaccione a los cambios de saldo; los usarás para enviar correos de «saldo bajo» antes de que los clientes lleguen a cero.
1

Expose your local server

Los webhooks necesitan una URL pública. Para el desarrollo local, utiliza ngrok o cualquier túnel:
Copia la URL de https://...ngrok-free.app.
2

Register the webhook in Dodo Payments

  1. En el panel, ve a Developers → Webhooks → Add Endpoint
  2. URL: https://your-tunnel.ngrok-free.app/webhooks/dodo
  3. Suscríbete como mínimo a:
    • credit.added
    • credit.deducted
    • credit.overage_charged
  4. Guarda y copia el Signing Secret
  5. Pégalo en .env como DODO_PAYMENTS_WEBHOOK_KEY y reinicia npm run dev
El dodo.webhooks.unwrap() del SDK valida los encabezados webhook-id, webhook-timestamp y webhook-signature mediante tu secreto de firma. No necesitas implementar manualmente la verificación HMAC; de hecho, no deberías hacerlo, porque Dodo Payments utiliza Standard Webhooks, que firma id.timestamp.body en lugar de firmar únicamente el cuerpo.

Paso 8: Prueba el flujo completo

1

Subscribe a test customer

  1. Ejecuta npm run dev
  2. Abre http://localhost:3000
  3. Elige Plan Pro, introduce un correo y un nombre de prueba, haz clic en Get Checkout Link y completa el checkout con datos de tarjeta de prueba
  4. En el panel, ve a Customers → most recent y copia el ID de cus_...
  5. Pégalo en el campo «Logged-in customer ID» de la demostración y haz clic en Save
El cliente debería tener 40.000.000 de tokens. Haz clic en Refresh Balance para confirmarlo.
2

Generate a real AI response

Escribe un prompt y haz clic en Generate. El servidor llama a OpenAI, obtiene el total_tokens real, ingesta un evento de uso y devuelve la respuesta.
Los eventos de uso se procesan mediante un worker en segundo plano aproximadamente cada minuto. El saldo no disminuirá al instante: espera entre 30 y 90 segundos y vuelve a hacer clic en Refresh Balance. No concluyas que algo está roto si la primera actualización no muestra cambios.
3

Test the top-up flow

Haz clic en Buy 5M Tokens — $19 y completa el checkout. Cuando el pago se haya realizado correctamente, actualiza el saldo; debería aumentar en 5.000.000 de tokens. El registro del servidor debería mostrar un evento credit.added.

Solución de problemas

Posibles causas:
  • El nombre del evento del medidor no coincide con el event_name que estás enviando (api.tokens_used distingue entre mayúsculas y minúsculas)
  • El medidor no está vinculado al crédito API Tokens del producto; ve a la configuración del medidor del producto y confirma que Bill usage in Credits esté habilitado
  • La clave metadata.tokens no coincide con el campo «Over Property» del medidor
  • La asignación del cliente ha caducado (consulta el historial de créditos del cliente)
Qué comprobar:
  1. Products → Meters: abre el medidor y confirma que muestre el nombre del crédito vinculado en la asociación del producto
  2. La pestaña Events del medidor; los eventos ingeridos deberían aparecer allí incluso antes del descuento
  3. Customers → [Customer] → Credits: las entradas del ledger deberían aparecer en uno o dos minutos
Posibles causas:
  • El cliente aún no ha completado el checkout; los créditos solo se emiten después de un pago correcto
  • Estás consultando con el customer_id incorrecto (utiliza el ID cus_... del panel, no el ID de tu propia base de datos)
  • El CREDIT_ENTITLEMENT_ID en .env no coincide con el crédito asociado al producto
Qué comprobar: Abre Customers → [Customer] → Credits. Si no aparecen créditos, el entitlement del producto no se asoció o el pago no se completó.
Posibles causas:
  • El exceso de uso no se habilitó en la asociación de crédito del producto Pro (la configuración del nivel de crédito solo es un valor predeterminado)
  • El cliente está realmente en Starter, no en Pro
  • El límite de exceso de uso se estableció en 0
Qué comprobar: Edita Pro → Entitlements → Credits → confirma que Allow Overage esté habilitado y que Price Per Unit sea 0.000005 (= $5 por cada millón de tokens; comprueba los ceros iniciales: el campo acepta el precio por token, no por cada 1.000 tokens).
Posibles causas:
  • Orden del análisis del cuerpo: express.json() se aplicó a /webhooks/dodo antes que express.raw(); el SDK necesita los bytes sin procesar de la solicitud, no JSON analizado
  • Secreto de firma incorrecto en DODO_PAYMENTS_WEBHOOK_KEY
  • El proxy inverso está reescribiendo los encabezados
Qué comprobar: Confirma que la línea app.use('/webhooks/dodo', express.raw(...)) aparezca antes que app.use(express.json()) en server.ts.

¿Necesitas ayuda?

¡Enhorabuena! Has creado la facturación basada en créditos para NeuralAPI

Tu plataforma ahora cuenta con un sistema completo de facturación de créditos listo para producción:

Token Credit Entitlement

Un crédito API Tokens reutilizable con una caducidad de 30 días, compartido entre todos los planes y el paquete de recarga

Tiered Plans, One Credit

Starter (10 M, límite estricto) y Pro (40 M + exceso de uso), configurados por producto sin duplicar el crédito

One-Time Top-Up Pack

Los clientes añaden 5 M de tokens por $19 sin cambiar su suscripción

Auto-Deduction via Meter

Los recuentos reales de tokens de OpenAI se ingieren como eventos; el medidor descuenta créditos mediante FIFO sin seguimiento manual

Live Balance API

Saldo en tiempo real mediante el SDK para controlar el acceso, mostrar el uso o advertir a los clientes dentro de la aplicación

Verified Webhook Pipeline

Eventos del ledger de créditos (credit.added, credit.deducted, credit.overage_charged) enrutados mediante un handler cuya firma se verifica utilizando el helper Standard Webhooks del SDK
¿Vas a pasar a producción? Refuerza estos aspectos:
  • Autenticación en /credits/:customerId y /api/generate; actualmente cualquiera puede acceder a ellos con cualquier ID de cliente. Autentica a los usuarios y busca su ID de cliente en el servidor.
  • event_ids estables; el ejemplo utiliza Date.now() + random. En producción, usa el ID de tu solicitud para que los reintentos sean idempotentes (Dodo Payments deduplica por event_id).
  • Persistencia de la relación cliente↔usuario; guarda customer_id en tu base de datos después del primer checkout para no tener que pegarlo manualmente.
  • Decide qué ocurre cuando termina una suscripción. Los créditos del plan permanecen en el ledger del cliente hasta su caducidad natural (30 días desde su emisión) y los créditos de recarga son válidos durante 365 días; sin embargo, /api/generate del cookbook solo comprueba el saldo, no el estado de la suscripción. Por tanto, un cliente cancelado aún puede consumir los tokens restantes. Ese es el comportamiento predeterminado más favorable para el consumidor. Si quieres un control de acceso más estricto, (a) escucha el webhook subscription.cancelled y controla /api/generate según el estado de la suscripción, o (b) llama a la API de ledger de Dodo para debitar los créditos no utilizados del plan al cancelar, dejando intactos los créditos de recarga.
  • Supervisa el panel de Usage Billing para detectar pronto anomalías en la medición.

Credit-Based Billing Reference

Documentación completa de CBB: rollover, modos de exceso de uso, gestión del ledger y todos los endpoints de API.

Credit Webhook Events

Esquemas de payload para cada evento de crédito que pueda recibir tu servidor.
Última modificación el 31 de julio de 2026