Saltearse al contenido
Nappai Documentation

Stripe Invoice

Este componente te permite gestionar de forma integral las facturas dentro de tu cuenta de Stripe. Funciona como un asistente inteligente que no solo crea facturas, sino que también te permite administrar todo el proceso: desde la generación inicial hasta el envío de correos al cliente, la anulación de documentos erróneos y la gestión de los detalles específicos de los cobros (como los ítems o cargos individuales).

¿Cómo funciona?

El componente actúa como un puente seguro entre tu sistema de automatización (Nappai) y la plataforma de pagos Stripe. Al configurarlo, le indicas a Nappai qué quieres hacer con una factura (por ejemplo, crear una nueva, obtener una específica o enviarla) y le proporcionas los datos necesarios, como el ID de tu cliente o el monto a cobrar.

Internamente, el componente utiliza las credenciales de seguridad que has configurado para hablar directamente con los servidores de Stripe. Dependiendo de tu selección, realizará acciones como:

  • Crear una factura nueva para un cliente específico.
  • Recuperar los detalles de una factura existente para revisarla.
  • Gestionar ítems (los productos o servicios facturados) dentro de una factura.
  • Anular o Eliminar facturas en caso de errores o cancelaciones.

Una vez que la operación se completa, el componente te devuelve un reporte detallado con el estado actual de la factura, asegurando que puedas verificar si el cobro se realizó correctamente o si se requiere alguna acción adicional.

Conexión y Credenciales

Este componente requiere configurar previamente una credencial en el panel de Nappai para poder interactuar con el servicio externo 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 el campo requerido (API Key), que puedes encontrar en tu panel de configuración de Stripe.
  3. En tu flujo de trabajo, selecciona la credencial guardada en el campo de entrada Credential de este nodo.

Entradas

Este componente está diseñado para ser flexible, permitiéndote gestionar tanto la factura completa como los detalles específicos de sus cargos (ítems).

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente. El uso de cada campo dependerá de la acción que elijas realizar:

  • Type: Especifica si vas a gestionar el documento de la factura completo o los ítems (cargos) individuales dentro de ella.
  • Operation: La acción principal que deseas ejecutar con el componente.
  • Mode: Define si quieres trabajar con una factura específica o listar varias.
  • ID: El identificador del registro que deseas modificar o eliminar.
  • Customer ID: El identificador único del cliente en Stripe (por ejemplo, cus_...). Es esencial para crear facturas o listar las existentes.
  • Amount: El monto a cobrar, expresado en la unidad más pequeña de la moneda (ej. centavos). Necesario para crear ítems de factura.
  • Currency: El código de la moneda para la operación (ej. USD, EUR).
  • Description: Un texto explicativo sobre lo que se está facturando.
  • Collection Method: El método de cobro, ya sea “cobrar automáticamente” o “enviar factura para pagar”.
  • Days Until Due: Número de días que el cliente tiene para pagar antes de la fecha de vencimiento. Se usa cuando el método de cobro es “enviar factura”.
  • Footer: Texto adicional que aparecerá al final del documento de la factura.
  • Status Filter: Un filtro para buscar facturas solo en estados específicos (ej. solo las pagadas).
  • Invoice ID: Si estás gestionando ítems, este campo indica a qué factura específica pertenecen esos cargos.
  • Limit: El número máximo de registros que deseas recuperar en una lista.

Salidas

Al finalizar la operación, el componente te proporcioná información detallada que puedes usar para verificar el éxito de la acción o para conectar con otros pasos de tu automatización.

Ejemplo de Respuesta JSON

El siguiente ejemplo muestra el tipo de información que recibirás cuando el componente gestione una factura exitosamente. Puedes usar estos datos en los siguientes nodos de tu flujo: json { “id”: “in_123456789”, “status”: “paid”, “total”: 2500, “hosted_invoice_url”: “https://invoice.stripe.com/i/accounts/…”, “customer”: “cus_abcdefghi”, “lines”: [ { “description”: “Suscripción Mensual Pro”, “amount”: 2500 } ] }

Conectividad

Este componente es un nodo central en los flujos de facturación. Lógicamente, se conecta de la siguiente manera:

  1. Entrada de Datos: Suele recibir información de componentes anteriores que identifican al cliente (como Retrieve Customer) o que procesan pedidos (como E-commerce Cart), para saber a quién facturar.
  2. Salida de Procesos: Sus salidas (como el estado de la factura o la URL de pago) se conectan comúnmente a:
    • Pasarelas de Envío: Para notificar al cliente que su factura está lista.
    • Bases de Datos: Para guardar el registro de la venta y el monto cobrado.
    • Condicionales: Para verificar si el estado es “Pagado” o “Fallido” y decidir el siguiente paso en la automatización.

Ejemplo de Uso

Escenario: Facturación de un servicio premium

Imagina que acabas de vender una suscripción premium a un cliente. Quieres generar la factura automáticamente y asegurarte de que sea válida.

  1. Configuras el Type como Invoice.
  2. Seleccionas la Operation para crear o gestionar la factura.
  3. Ingresas el Customer ID del usuario que compró.
  4. Si necesitas agregar un cargo específico, cambias el contexto para incluir el Amount (monto) y la Description.
  5. Al ejecutar el componente, recibirás la confirmación y los detalles de la factura, permitiéndote saber exactamente cuánto se le cobró al cliente y en qué estado queda la cuenta.

Consejos y Mejores Prácticas

  • Monedas: Recuerda que los montos (Amount) suelen requerirse en la unidad más pequeña (ej. centavos para dólares), no en dólares completos.
  • IDs de Cliente: Para crear facturas, asegúrate siempre de tener el Customer ID correcto de Stripe; no uses solo el nombre o el email.
  • Gestión de Errores: Si una factura no se puede eliminar, verifica su estado; a menudo es necesario “anularla” (void) en lugar de borrarla si ya fue procesada.
  • Validación de Campos: Campos como Days Until Due solo son necesarios si el método de cobro está configurado para enviar facturas para que el cliente las pague manualmente.

Consideraciones de Seguridad

Asegúrate de mantener tu API Key de Stripe segura dentro de la sección de credenciales de Nappai. No compartas esta clave en foros públicos ni la hardcodees en tus scripts. El componente utiliza esta credencial de forma segura para comunicarse con los servidores de Stripe sin exponer tus datos financieros sensibles en el flujo de visualización.