Saltearse al contenido
Nappai Documentation

Stripe Plan

Esta sección es fundamental para cualquier sistema de facturación automatizado. Te permite crear, visualizar y gestionar los planes de precios que tus clientes verán y pagarán. Piensa en el componente Stripe Plan como un “almacén” o “base de datos” de tus ofertas: aquí es donde guardas la información de qué paquete estás vendiendo, cuánto cuesta y con qué frecuencia se cobra.

El componente se conecta directamente con Stripe, el sistema de pagos externo, para asegurar que cada plan esté sincronizado y listo para ser utilizado en suscripciones reales.

¿Cómo funciona?

Internamente, este componente actúa como un mensajero entre Nappai y Stripe. Cuando le das instrucciones (por ejemplo, “crear un plan mensual”), el componente envía esa petición a Stripe de forma segura. Stripe procesa la solicitud, verifica que los datos sean correctos y devuelve una confirmación o los detalles del plan creado.

Al estar integrado en Nappai, no tienes que preocuparte por configurar claves de seguridad manualmente en cada paso; simplemente conectas tu cuenta de Stripe y el componente se encarga de hablar con ellos de forma automática y segura.

Conexión y Credenciales

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

  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 los campos requeridos (como tu clave secreta de API).
  3. En tu flujo de trabajo, selecciona la credencial guardada en el campo de entrada Credential de este nodo.

Entradas

Modo de Mapeo (Mapping Mode)

Este componente cuenta con un modo especial llamado “Mapping Mode” (Modo de Mapeo). Cuando activas este modo mediante el interruptor, se habilita una entrada adicional llamada “Mapping Data” y cada campo de entrada te ofrece tres formas diferentes de proporcionar datos:

  • Fixed (Fijo): Escribes el valor directamente en el campo.
  • Mapped (Mapeado): Conectas la salida de otro componente para usar su resultado como valor.
  • Javascript: Escribes código Javascript para calcular el valor dinámicamente.

Esta flexibilidad te permite crear flujos de trabajo más dinámicos y conectados.

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente. Cada campo puede estar visible en diferentes operaciones:

  • Operation: [REQUERIDO] Selecciona la acción principal que deseas realizar (Ver más abajo en la sección de Operaciones).
  • Mode: Indica si deseas recuperar un único plan específico usando su ID o si prefieres listar todos los planes disponibles. Opciones disponibles: ‘By ID’ o ‘All’.
  • Plan ID: El identificador único del plan en Stripe (ej. plan_abc123). Es necesario si seleccionas la operación de borrar o recuperar un plan específico.
  • Amount: El precio del plan. Debe escribirse en la unidad de moneda más pequeña (por ejemplo, para $10 USD, debes poner 1000 centavos).
  • Currency: El código de la moneda en el que se cobrará (ej. ‘usd’, ‘eur’, ‘mxn’).
  • Billing Interval: La frecuencia con la que se cobra al cliente. Opciones típicas: ‘day’, ‘week’, ‘month’, ‘year’.
  • Interval Count: Un número entero que indica cuántas veces se repite el intervalo. Por ejemplo, si pones 3 meses y el intervalo es ‘month’, se cobrará cada trimestre.
  • Product ID: El ID de un producto existente en Stripe (ej. prod_abc123). Sirve para vincular este plan de facturación con la descripción del producto.
  • Trial Period Days: (Opcional) Número de días de prueba gratuitos antes de comenzar el cobro.
  • Limit: (Para modo de listado) Número máximo de registros a devolver (1-100).

Salidas

Después de ejecutar este componente, recibirás información que puedes usar en el siguiente paso de tu automatización:

  • plan: Un objeto JSON completo con todos los detalles del plan (si la operación fue exitosa). Puedes usar los datos de este objeto para pasar información a otros componentes.
  • success: Un valor verdadero (true) o falso (false) que indica si la acción se realizó correctamente.
  • error_message: Si la acción falló, aquí aparecerá un texto explicando el motivo del error.

Ejemplo de Respuesta JSON

Si creas o recuperas un plan exitosamente, la salida plan se verá similar a esto: json { “id”: “plan_Gb392d7fS1Zqb9”, “object”: “plan”, “active”: true, “aggregate_usage”: null, “amount”: 5000, “currency”: “usd”, “interval”: “month”, “interval_count”: 1, “livemode”: false, “metadata”: {}, “nickname”: “Plan Mensual Premium”, “product”: “prod_Gb392d7fS1Zqb9” }

Conectividad

Este componente es la base de cualquier flujo de facturación. Generalmente, su salida plan se conecta a nodos de suscripción (para que un cliente empiece a pagar este plan) o a nodos de facturación (para generar un recibo basado en el plan). A su vez, se conecta siempre a una credencial de Stripe API para tener permiso de acceso.

Ejemplo de Uso

Escenario: Quieres crear un nuevo plan de suscripción llamado “Plan Premium” que cueste $20 USD mensuales.

  1. En el campo Operation, selecciona la acción para crear el plan (o asegúrate de estar en el modo adecuado para su gestión).
  2. En Amount, escribe 2000 (porque son 20 dólares en centavos).
  3. En Currency, selecciona usd.
  4. En Billing Interval, selecciona month.
  5. En Product ID, ingresa el ID del producto creado previamente para este servicio.
  6. Al ejecutar, si el resultado en success es true, sabrás que el plan existe en Stripe y puedes usarlo para cobrar a tus clientes.

Consejos y Mejores Prácticas

  • Entiende los centavos: Stripe no trabaja con decimales directos (como 10.50). Siempre convierte los precios a la moneda más pequeña (centavos). $10 USD se convierte en 1000.
  • IDs son clave: Si necesitas borrar o buscar un plan específico, asegúrate de tener el Plan ID correcto. Este ID empieza usualmente por plan_.
  • Validación de Producto: Si estás creando un plan nuevo, verifica primero que el Product ID exista en tu cuenta de Stripe para evitar errores de conexión.

Consideraciones de Seguridad

  • Asegúrate de nunca compartir tu Stripe API Key (credencial) públicamente. Nappai gestiona estas credenciales de forma segura, pero es vital proteger tu acceso a la cuenta de Stripe.
  • Revisa los permisos de tu API Key; algunas claves solo permiten lectura (solo ver planes) y otras permiten escritura (crear y borrar planes).