Saltearse al contenido
Nappai Documentation

PayPalPayoutItem

Este componente, llamado PayPalPayoutItem, es una herramienta especializada dentro del sistema Nappai diseñada para interactuar con los pagos masivos (payouts) de PayPal.

Su propósito principal es darte control sobre los elementos individuales dentro de un lote de pagos. Imagina que has enviado un pago a 50 personas en un solo lote; este componente te permite actuar sobre una sola de esas personas (por ejemplo, cancelarle el pago si cometiste un error en los datos, o verificar si ya le llegó el dinero).

Funciona como un puente seguro entre tu automatización y la cuenta de PayPal, asegurando que las acciones se realicen con la seguridad necesaria.

¿Cómo funciona?

El componente funciona como un “gestor de detalle”. No crea pagos nuevos por sí solo, sino que trabaja sobre pagos que ya han sido creados en lotes.

  1. Conexión Segura: Primero, el componente se conecta a tu cuenta de PayPal utilizando credenciales seguras que has configurado previamente.
  2. Identificación: Te pide identificar el “Item ID” (el identificador único) de la transacción específica que quieres manejar dentro del lote.
  3. Acción: Dependiendo de lo que elijas, el componente hace una de dos cosas:
    • Cancelar: Intenta detener el pago para ese ítem específico antes de que se procese.
    • Consultar (Get): Revisa el estado actual del ítem para saber si está pendiente, pagado, fallido, etc.

Al finalizar, te devuelve información detallada (como el estado del pago y posibles errores) para que puedas tomar decisiones o seguir el flujo de tu automatización.

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 PayPal API y guarda los campos requeridos (Client ID, Client Secret y Environment).
  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:

  • Credential: Selecciona aquí la credencial de PayPal API que configuraste previamente en Nappai para autenticar la conexión.
  • Operation: Permite elegir qué acción deseas realizar con el ítem seleccionado. Solo puedes elegir una acción a la vez. Las opciones son:
    • cancel: Cancela el procesamiento de un ítem específico dentro de un lote de pagos. Útil si necesitas detener un pago que se envió por error.
    • get: Recupera los detalles y el estado actual de un ítem específico (por ejemplo, para saber si un pago fue entregado exitosamente).
  • Payout Item ID: Es el identificador único (UUID) del ítem dentro del lote de pago que deseas gestionar. Este dato es obligatorio para realizar cualquier acción, ya que sin este ID el sistema no sabrá a qué pago específico te refieres.

Salidas

Al ejecutar este componente, recibirás información estructurada que puedes usar en pasos siguientes de tu automatización.

  • response: Contiene la respuesta completa del servidor de PayPal en formato JSON. Aquí encontrarás detalles sobre el éxito de la operación o el estado actual del ítem.
  • status_code: Un número que indica el resultado de la conexión (ej. 200 significa éxito, 400 significa error en la solicitud).
  • error_message: Si algo salió mal (por ejemplo, un ID incorrecto o credenciales expiradas), aquí encontrarás el mensaje de error explicando qué falló.
  • headers: Información técnica adicional de la red, útil para desarrolladores avanzados que necesitan depurar problemas de conexión o límites de velocidad.

Ejemplo de Respuesta JSON

Cuando utilizas la operación get con éxito, la salida podría verse similar a este ejemplo: json { “batch_header”: { “batch_id”: “5OT2018052212345” }, “items”: [ { “sender_batch_item_id”: “1”, “links”: [ { “href”: “https://api-m.sandbox.paypal.com/v1/payments/payouts-item/5OT2018052212345/1”, “rel”: “self”, “method”: “GET” } ], “errors”: { “message”: “Item not found” }, “sender_batch_item”: { “recipient_type”: “EMAIL”, “amount”: { “value”: “9.87”, “currency”: “USD” }, “note”: “Thanks for your purchase”, “sender_item_id”: “2015_Q2_2014_100000003” }, “transaction_id”: null, “transaction_status”: “UNCLAIMED”, “transaction_date”: “2018-05-22 12:34:56 PDT”, “activity_info”: null } ], “batch_status”: “PENDING”, “links”: [ { “href”: “https://api-m.sandbox.paypal.com/v1/payments/payouts/5OT2018052212345”, “rel”: “self”, “method”: “GET” } ] }

Conectividad

Este componente suele conectarse como un paso de “verificación” o “corrección” en medio de un flujo de pagos.

  • Conexión Lógica Común: Generalmente recibe datos de un componente anterior que genera los IDs de los payouts (como PayPalPayoutBatch).
  • Flujo de Trabajo Típico:
    1. Un componente crea un lote de pagos.
    2. El componente PayPalPayoutItem (con operación get) se usa para verificar el estado de un pago específico.
    3. Dependiendo de la respuesta (status_code o error_message), el flujo puede decidir si notifica al usuario sobre un pago fallido o si procede a cancelar un pago (operation: cancel) si se detecta un error en los datos de destino.

Ejemplo de Uso

Imagina que estás automatizando el pago de nóminas o reembolsos a una lista de empleados.

  1. Escenario: Has enviado un lote de pagos a 10 empleados, pero el sistema te avisa que uno de los correos electrónicos estaba mal escrito.
  2. Acción:
    • Usas este componente seleccionando la operación cancel.
    • En el campo Payout Item ID, ingresas el ID único del pago que debe ser detenido.
    • En el campo Credential, seleccionas tu cuenta de PayPal.
  3. Resultado: El componente envía la orden a PayPal para detener ese pago específico. Si tienes éxito, el flujo puede proceder a corregir los datos del empleado y volver a enviar el pago manualmente o mediante otro paso.

Consejos y Mejores Prácticas

  • Verifica antes de Cancelar: Antes de usar la operación cancel, es recomendable usar la operación get primero para confirmar el estado actual del ítem y asegurar que aún es posible cancelarlo (si ya fue pagado, no se podrá cancelar).
  • Manejo de Errores: Usa la salida error_message en tus siguientes pasos para crear una lógica de “si falla, entonces avisa al administrador”. Esto evita que tu automatización se quede “trabada” en pagos fallidos sin intervención humana.
  • IDs Únicos: Asegúrate de copiar el Item ID exacto. Un solo carácter incorrecto hará que la operación falle.

Consideraciones de Seguridad

  • Seguridad de Credenciales: Las credenciales de PayPal (Client ID y Secret) son sensibles. Nappai las maneja de forma segura, pero asegúrate de no compartir tus credenciales ni tus IDs de ítems públicamente.
  • Entorno Sandbox: Cuando estés probando tu automatización, asegúrate de que tu credencial de PayPal esté configurada en modo sandbox. Esto evitará que muevas dinero real mientras pruebas tus flujos.