Saltearse al contenido
Nappai Documentation

PayPalInvoice

Bienvenido a la guía de uso del componente PayPalInvoice dentro del sistema de automatización Nappai. Este componente actúa como un puente inteligente entre tu sistema y PayPal, permitiéndote crear, enviar y gestionar facturas de forma automática sin necesidad de tocar manualmente cada paso del proceso.

¿Necesitas cobrar a un cliente, verificar el estado de una factura o simplemente listar tus transacciones recientes? Este componente se encarga de toda la comunicación técnica con los servidores de PayPal para que tú puedas enfocarte en tu negocio.

¿Cómo funciona?

Internamente, este componente se conecta a la API oficial de facturas de PayPal (PayPal Invoicing API). Al ejecutarlo, realiza las siguientes acciones de manera invisible para ti:

  1. Autenticación Segura: Utiliza las credenciales que configures para verificar que eres tú quien está realizando las operaciones.
  2. Ejecución de Tareas: Dependiendo de lo que elijas hacer (crear una factura, enviarla, etc.), el componente redacta la petición y la envía a los servidores seguros de PayPal.
  3. Procesamiento de Datos: Recibe la respuesta de PayPal (confirmación de pago, ID de factura, detalles, etc.) y la estructura para que puedas usarla en los siguientes pasos de tu automatización.

Piensa en este componente como un asistente administrativo que tiene la llave de tu cuenta de PayPal: tú le dices qué hacer, y él se encarga de hablar con el banco y los registros de facturación por ti.

Conexión y Credenciales

Para que este componente funcione, es fundamental que primero configures una conexión segura con tu cuenta de PayPal. No podrás crear ni enviar facturas sin esta configuración previa.

Sigue estos pasos sencillos para configurar tu credencial en Nappai:

  1. Dirígete a la sección de Credenciales en tu panel de control de Nappai.
  2. Crea una nueva credencial seleccionando el tipo PayPal API.
  3. Rellena los campos requeridos (generalmente el Client ID y Client Secret que obtienes desde el panel de desarrolladores de PayPal) y guarda la credencial.
  4. Vuelve al componente PayPalInvoice en tu flujo de trabajo.
  5. En el campo de entrada Credential, selecciona la credencial que acabas de crear.

Una vez que hayas vinculado la credencial, el componente ya está listo para operar.

Entradas

Para interactuar con este componente, deberás rellenar ciertos campos. Ten en cuenta que algunos campos solo serán visibles o necesarios dependiendo de la acción que elijas realizar.

Campos de Entrada

  • Operation: La acción principal que deseas que el componente realice. Las opciones comunes son “Create” (Crear), “Send” (Enviar), “Retrieve” (Obtener detalles), “Mark As Paid” (Marcar como pagada), entre otras.
  • Get Mode: Define qué tipo de información específica buscas recuperar, útil al listar facturas o buscar por ID.
  • Invoice ID: El identificador único de una factura en PayPal. Es obligatorio para operaciones como cancelar, enviar o marcar como pagada una factura existente.
  • Recipient Email: La dirección de correo electrónico del cliente al que se enviará la factura.
  • Currency: El código de la moneda en la que se emitirá la factura (ej. USD, EUR, MXN).
  • Item Name: El nombre del producto o servicio que estás facturando.
  • Quantity: La cantidad de unidades del ítem (por defecto es 1).
  • Unit Amount: El precio por unidad del ítem (debe ser un valor numérico).
  • Due Date: La fecha límite de vencimiento de la factura (formato AAAA-MM-DD).
  • Note: Mensajes adicionales o instrucciones para el cliente (ej. “Por favor incluir referencia de pedido”).
  • Terms and Conditions: Los términos legales o de servicio aplicables a esta factura.
  • Payment Method: El método de pago utilizado (ej. Check, Wire Transfer, PayPal), necesario al marcar una factura como pagada.
  • Payment Date: La fecha en la que se recibió el pago (formato AAAA-MM-DD), requerida solo al marcar como pagada.
  • Limit: Número máximo de facturas a devolver al realizar una búsqueda o listado.

Salidas

Una vez que el componente ha ejecutado la operación, te devolverá información estructurada que puedes usar en el siguiente paso de tu automatización.

Ejemplo de Respuesta JSON

Al operar con éxito (por ejemplo, al crear o recuperar una factura), recibirás una estructura de datos similar a la siguiente. Esto te permitirá acceder a datos como el estado de la factura o su enlace de visualización. json { “invoice_id”: “INV2-4XJ89012AB3456789”, “status”: “SENT”, “link”: “https://www.paypal.com/invoice/p/ABC123XYZ”, “details”: { “number”: “INV-2023-001”, “total_amount”: { “currency”: “USD”, “value”: “150.00” }, “items”: [ { “name”: “Servicio de Consultoría”, “quantity”: 1, “unit_amount”: { “currency”: “USD”, “value”: “150.00” } } ] } }

Nota: Las salidas pueden variar ligeramente dependiendo de la operación seleccionada (por ejemplo, una lista de facturas tendrá una estructura diferente a una sola factura).

Conectividad

Este componente es diseñado para integrarse secuencialmente en flujos de trabajo de gestión de pagos:

  • Entradas: Suele recibir datos de otros componentes que generan la información del cliente (como una base de datos de CRM o un formulario de entrada de datos) para rellenar el correo del destinatario y los detalles del ítem.
  • Salidas: Sus salidas (como invoice_id o status) se conectan típicamente a componentes de seguimiento (para notificar al cliente) o a hojas de cálculo/bases de datos para archivar el registro de la venta.

Ejemplo de Uso

Escenario: Crear y Enviar Factura Automática

  1. Configuración: Eliges la operación create para generar una nueva factura.
  2. Datos: Introduces el Item Name (“Mensualidad Premium”), Unit Amount (“50.00”), Currency (“USD”) y el Recipient Email del cliente.
  3. Acción: El componente genera la factura en PayPal y te devuelve un Invoice ID.
  4. Seguimiento: En el siguiente paso de tu flujo, usas ese Invoice ID para enviar una notificación por correo electrónico al cliente con el enlace de pago.

Consejos y Mejores Prácticas

  • Validación de Datos: Asegúrate de que los correos electrónicos y las fechas estén en el formato correcto para evitar errores de validación en PayPal.
  • Entorno de Prueba: Utiliza la opción sandbox durante el desarrollo de tus flujos para probar sin mover dinero real.
  • Manejo de Errores: Siempre configura un paso alternativo en tu flujo para capturar posibles errores (como credenciales inválidas o montos incorrectos) y notificar al equipo técnico.

Consideraciones de Seguridad

Asegúrate de nunca compartir tus credenciales de PayPal (Client ID y Client Secret) en texto plano. Utiliza siempre la sección de Credenciales seguras de Nappai y nunca hardcodees estos valores en el código de las entradas. Mantén tu entorno de producción (live) separado de tu entorno de pruebas (sandbox) para evitar facturaciones accidentales.