Saltearse al contenido
Nappai Documentation

Stripe Meter Event

Este componente actúa como un puente entre tu aplicación de automatización (Nappai) y la plataforma de pagos Stripe. Su propósito principal es informar a Stripe sobre el uso de recursos, como la cantidad de “tokens” de IA utilizados o las llamadas a una API hechas. Al hacer esto, Stripe puede calcular automáticamente la factura correspondiente basada en el consumo real, en lugar de una tarifa fija.

¿Cómo funciona?

Básicamente, este componente envía una “notificación” a Stripe cada vez que se consume un recurso facturable. Piensa en ello como un contador de electricidad: cada vez que enciendes un dispositivo (por ejemplo, generas una respuesta de IA), este componente registra cuánta energía (recursos) se ha consumido y envía ese dato a Stripe.

El proceso interno sigue estos pasos:

  1. Validación: Verifica que tienes los permisos correctos y que los datos del cliente son válidos.
  2. Envío: Transmite el nombre del servicio usado y la cantidad exacta de recursos consumidos al sistema de Stripe.
  3. Confirmación: Recibe una respuesta de Stripe para confirmar que el registro se ha guardado correctamente.

Si todo sale bien, tu cliente quedará registrado con su consumo para ser facturado al final del ciclo de facturación.

Conexión y Credenciales

Este componente requiere configurar previamente una credencial en el panel de Nappai para poder interactuar con Stripe de forma segura:

  1. Dirígete a la sección de Credenciales en tu panel de Nappai.
  2. Crea una nueva credencial del tipo Stripe API y guarda la API Key (clave de acceso) proporcionada por tu cuenta de Stripe.
  3. En tu flujo de trabajo, selecciona la credencial que acabas de crear en el campo de entrada Credential de este nodo.

Nota: No necesitas ingresar la clave de API manualmente dentro del componente. Al seleccionar la credencial guardada, el sistema conecta automáticamente las claves necesarias de forma segura.

Entradas

Los siguientes campos están disponibles para configurar este componente. Estos son los datos que debes proporcionar para que el registro de uso sea correcto:

  • Event Name: Es el nombre único del evento de facturación tal como está configurado en tu cuenta de Stripe (por ejemplo, “ai_tokens_used” o “api_calls_made”). Debe coincidir exactamente con lo que configuraste en Stripe para que el consumo se registre en la métrica correcta.

    • Visible en: N/A (Campo obligatorio del componente)

  • Customer ID: El identificador único del cliente de Stripe (generalmente empieza con “cus_”). Esto asegura que el consumo se asigne al cliente correcto y aparezca en su factura.

    • Visible en: N/A (Campo obligatorio del componente)

  • Value: El valor numérico del consumo actual (por ejemplo, el número de tokens consumidos o 1 llamada de API). Este número es el que Stripe usará para calcular el costo.

    • Visible en: N/A (Campo obligatorio del componente)

  • Identifier: Un ID único opcional para este evento específico. Se usa para evitar duplicados (por si por alguna razón el sistema intenta registrar el mismo evento dos veces). Si lo dejas vacío, Stripe generará uno automáticamente.

    • Visible en: N/A (Campo opcional del componente)

  • Timestamp: La fecha y hora en que ocurrió el consumo (en formato Unix). Por defecto, usa la hora actual. Debe estar dentro de los últimos 35 días.

    • Visible en: N/A (Campo opcional del componente)

Salidas

Al finalizar la ejecución, este componente devuelve información sobre el éxito de la operación, lo cual es útil para crear flujos que reaccionen a errores o confirmaciones.

  • Success Status: Un indicador (Verdadero/Falso) que te dice si el evento fue enviado y registrado correctamente en Stripe. Si es falso, deberás revisar los detalles de error.
  • Stripe Response Data: Detalles completos de la respuesta de Stripe. En caso de éxito, contiene la confirmación del evento; en caso de error, contiene el mensaje de error específico para que puedas solucionar el problema.

Ejemplo de Respuesta JSON

Cuando el componente se ejecuta con éxito, el nodo Stripe Response Data podría contener algo similar a esto: json { “id”: “me_1234567890abcdef”, “object”: “meter_event”, “created”: 1678886400, “currency”: null, “event_name”: “ai_tokens_used”, “livemode”: false, “payload”: { “amount”: “50”, “metadata”: {} }, “status”: “processed” }

Conectividad

Este componente suele conectarse después de las acciones que generan consumo de recursos. Por ejemplo, en un flujo de automatización de IA:

  1. Entrada Lógica: Se conecta típicamente a la salida de un nodo que ejecuta un modelo de IA o realiza una llamada API.
  2. Flujo de Trabajo: Una vez registrado el uso (Stripe Meter Event), el flujo puede continuar hacia una lógica de notificación al cliente o simplemente finalizar la tarea de automatización.

La conexión lógica es: Acción (IA/API) -> Registro de Consumo (Stripe Meter Event) -> Fin/Notificación.

Ejemplo de Uso

Escenario: Automatización de Respuestas de IA y Facturación

Imagina que tienes un asistente de IA que responde preguntas a tus clientes. Quieres que cada vez que el asistente responda, el consumo de tokens se cuente para la factura mensual del cliente.

  1. Paso 1: Un nodo de “Generación de Texto” responde a la pregunta del usuario.
  2. Paso 2: Conectas la salida de ese nodo al componente Stripe Meter Event.
  3. Configuración:
    • En Event Name, escribes ai_tokens_used.
    • En Customer ID, seleccionas el ID del cliente actual del flujo.
    • En Value, mapeas la salida que indica cuántos tokens se usaron para generar la respuesta.
  4. Resultado: Stripe registra ese consumo. Al final del mes, Stripe generará una factura basada en la suma de todos estos “Values” registrados.

Consejos y Mejores Prácticas

  • Verifica los Nombres: Asegúrate de que el nombre en Event Name sea idéntico al que creaste en el panel de Stripe. Si hay un error de ortografía, el evento será rechazado.
  • Manejo de Errores: Configura tu flujo para verificar la salida Success Status. Si es falso, puedes enviar una alerta al equipo de administración para que revise si hubo problemas con la API de Stripe.
  • Datos de Prueba: Usa un Identifier único si estás probando el flujo muchas veces rápidamente, para evitar que Stripe elimine eventos duplicados inadvertidamente.

Consideraciones de Seguridad

  • Protección de Claves: Nunca compartas tu API Key directamente. Siempre usa la sección de Credenciales de Nappai para almacenarla de forma segura.
  • Validación de Clientes: Asegúrate de que el Customer ID que pasas al componente pertenezca realmente al cliente actual para evitar facturar a la persona incorrecta.