Saltearse al contenido
Nappai Documentation

StripeSubscription

El componente StripeSubscription en Nappai es tu herramienta clave para automatizar la gestión de clientes recurrentes y pagos. Funciona como un puente seguro entre tu sistema de automatización y la pasarela de pagos Stripe.

Su propósito principal es permitirte crear, buscar, modificar y cancelar suscripciones de manera fácil y segura. Ya sea que necesites activar una nueva suscripción para un cliente nuevo, verificar el estado de una suscripción existente o cancelar un servicio al final del ciclo de facturación, este componente se encarga de toda la comunicación técnica con Stripe, dejándote a ti concentrarte en la experiencia del usuario final.

¿Cómo funciona?

Internamente, este componente se conecta a la API de Stripe utilizando credenciales seguras que tú configuras previamente. Cuando ejecutas el componente, este realiza las siguientes acciones:

  1. Valida la información: Verifica que tengas los identificadores correctos (como el ID del cliente o del plan) y que la cuenta de Stripe esté activa.
  2. Comunica con Stripe: Envía instrucciones a los servidores de Stripe para realizar la acción deseada (crear, actualizar, listar o cancelar).
  3. Procesa la respuesta: Recibe la confirmación de Stripe y te devuelve los detalles actualizados en formato de datos (JSON) para que puedas usarlos en el siguiente paso de tu automatización.

Este proceso ocurre en segundos y está diseñado para ser confiable, manejando errores comunes y proporcionando mensajes claros si algo sale mal.

Conexión y Credenciales

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

  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 (claves de API, tokens, etc.).
  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: Permite seleccionar la acción que deseas realizar con la suscripción. Las opciones disponibles son ‘By ID’ para recuperar un registro específico o ‘All’ para listar múltiples registros.
  • Mode: Determina si el componente debe buscar un único registro específico (‘By ID’) o una lista completa de registros (‘All’).
  • Subscription ID: Es el identificador único de la suscripción (ej. sub_…) que deseas gestionar. Es necesario para operaciones de Cancelación, Actualización y Recuperación (‘By ID’).
  • Customer ID: Es el identificador del cliente de Stripe (ej. cus_…). Es necesario para crear nuevas suscripciones o obtener todas las suscripciones de un cliente específico.
  • Price ID: Es el identificador del precio o plan (ej. price_…) al que deseas suscribir al cliente. Es obligatorio al crear una nueva suscripción.
  • Payment Method ID: Es el identificador del método de pago (ej. pm_…) que se asociará al cliente para este pago. Incluye métodos de prueba como Visa, Mastercard o tarjetas de débito.
  • Trial Period Days: Define el número de días de prueba gratuita que tendrá el cliente antes de que se le comience a facturar.
  • Cancel at Period End: Una opción que indica si la suscripción debe cancelarse automáticamente al final del periodo de facturación actual en lugar de de inmediato.
  • Status Filter: Permite filtrar la lista de suscripciones por su estado actual (ej. activas, vencidas, canceladas).
  • Limit: Establece el número máximo de suscripciones que quieres recuperar en una sola lista, útil para gestionar grandes volúmenes de datos.

Salidas

El componente devuelve información detallada sobre el resultado de la operación. Principalmente, recibirás:

  • result: Un objeto JSON que contiene los detalles de la suscripción (si fue creada o recuperada) o una lista paginada (si usaste la operación de listado).
  • success: Un indicador booleano que confirma si la operación fue exitosa (True) o si falló (False).
  • error_message: Si la operación falla, este campo contendrá un mensaje explicando el motivo del error.

Ejemplo de Respuesta JSON

Este es un ejemplo de cómo se ve la salida cuando se crea exitosamente una suscripción o se recupera una existente: json { “id”: “sub_123456789”, “customer_id”: “cus_987654321”, “price_id”: “price_monthly_premium”, “status”: “active”, “current_period_start”: 1698765432, “current_period_end”: 1701443832, “cancel_at_period_end”: false, “metadata”: { “internal_ref”: “CLIENT_001” } }

Conectividad

Este componente se conecta lógicamente en flujos de automatización de ventas y soporte al cliente.

  • Entradas: Suele recibir el Customer ID y Price ID de componentes previos que registran nuevos clientes o procesan órdenes de compra.
  • Salidas: El campo result se conecta frecuentemente a componentes de notificación (para enviar confirmaciones por email) o a bases de datos (para guardar el historial de facturación). Si la salida success es falsa, la conexión puede derivar hacia un componente de registro de errores o de manejo de excepciones.

Ejemplo de Uso

Escenario: Dar de alta una suscripción premium a un nuevo cliente

  1. Crear Cliente: Primero, usas otro componente para crear el cliente en Stripe y obtener su Customer ID.
  2. Gestionar Suscripción: Conectas ese Customer ID al campo Customer ID de este componente.
  3. Configurar Plan: Seleccionas el plan deseado en el campo Price ID.
  4. Ejecutar: Configuras el Mode para crear la suscripción.
  5. Resultado: El componente devuelve el Subscription ID, el cual puedes usar para confirmar el pago o enviar un correo de bienvenida al cliente.

Consejos y Mejores Prácticas

  • Usa Metadatos: Aprovecha los campos de metadatos para añadir referencias internas de tu empresa, facilitando la búsqueda posterior de la suscripción.
  • Maneja Errores: Siempre verifica la salida success. Si es falsa, usa el error_message para entender qué falló (ej. tarjeta rechazada) y notificar al usuario.
  • Prueba con IDs de Prueba: Utiliza los métodos de pago de prueba (como pm_card_visa) para asegurar que tus flujos funcionan antes de activarlos con pagos reales.

Consideraciones de Seguridad

Asegúrate de nunca compartir tus claves de API privadas (API Keys) en el código de tu automatización o en canales públicos. Utiliza siempre la sección de Credenciales de Nappai para almacenar y gestionar estas claves de forma segura.