PayPal

Kit de herramientas de agente de PayPal

El kit de herramientas de agente de PayPal permite que marcos de agentes populares, incluidos el SDK de agente de OpenAI, LangChain, el SDK de IA de Vercel y el Protocolo de Contexto de Modelo (MCP), se integren con las API de PayPal mediante llamadas a funciones. Incluye soporte para TypeScript y está construido sobre las API de PayPal y los SDK de PayPal.

Herramientas disponibles

El kit de herramientas de agente de PayPal proporciona las siguientes herramientas:

Facturas

• create_invoice: Crear una nueva factura en el sistema de PayPal, incluidos los detalles de facturación del destinatario, los artículos de línea, una nota de factura, un tema de color personalizado, un costo de envío opcional y una opción para habilitar PAY_BY_BANK como método de pago
• create_recurring_series: Crear una serie de facturas recurrentes que genera y envía facturas automáticamente según un cronograma
• list_invoices: Listar facturas con paginación y filtrado opcionales
• get_invoice: Recuperar los detalles de una factura específica
• send_invoice: Enviar una factura a los destinatarios
• send_invoice_reminder: Enviar un recordatorio para una factura existente
• cancel_sent_invoice: Cancelar una factura enviada
• generate_invoice_qr_code: Generar un código QR para una factura

Pagos

• create_order: Crear un pedido en el sistema de PayPal según los detalles proporcionados
• get_order: Recuperar los detalles de un pedido
• pay_order: Procesar el pago de un pedido autorizado
• create_refund: Procesar un reembolso para un pago capturado
• get_refund: Obtener los detalles de un reembolso específico

Gestión de disputas

• list_disputes: Recuperar un resumen de todas las disputas abiertas
• get_dispute: Recuperar información detallada de una disputa específica
• accept_dispute_claim: Aceptar una reclamación de disputa

Seguimiento de envíos

• create_shipment_tracking: Crear un registro de seguimiento de envío
• get_shipment_tracking: Recuperar información de seguimiento de envío
• update_shipment_tracking: Actualizar información de seguimiento de envío

Gestión de catálogo

• create_product: Crear un nuevo producto en el catálogo de PayPal
• list_products: Listar productos con paginación y filtrado opcionales
• show_product_details: Recuperar los detalles de un producto específico

Gestión de suscripciones

• create_subscription_plan: Crear un nuevo plan de suscripción
• list_subscription_plans: Listar planes de suscripción
• show_subscription_plan_details: Recuperar los detalles de un plan de suscripción específico
• create_subscription: Crear una nueva suscripción
• show_subscription_details: Recuperar los detalles de una suscripción específica
• update_subscription: Actualizar una suscripción existente
• cancel_subscription: Cancelar una suscripción activa

Informes y perspectivas

• list_transactions: Listar transacciones con paginación y filtrado opcionales
• get_merchant_insights: Recuperar métricas de inteligencia empresarial y análisis para un comerciante

TypeScript

Instalación

No necesitas este código fuente a menos que quieras modificar el paquete. Si solo quieres usar el paquete, ejecuta:

npm install @paypal/agent-toolkit

Requisitos

• Node 18+

Uso

La biblioteca debe configurarse con el ID de cliente y el secreto de tu cuenta, disponibles en tu Panel de desarrollador de PayPal.

El kit de herramientas funciona con el SDK de IA de Vercel y se puede pasar como una lista de herramientas. Para más detalles, consulta nuestros ejemplos.

import { PayPalAgentToolkit } from '@paypal/agent-toolkit/ai-sdk';
const paypalToolkit = new PayPalAgentToolkit({
  clientId: process.env.PAYPAL_CLIENT_ID,
  clientSecret: process.env.PAYPAL_CLIENT_SECRET,
  configuration: {
    actions: {
      invoices: {
        create: true,
        createRecurringSeries: true,
        list: true,
        send: true,
        sendReminder: true,
        cancel: true,
        generateQRC: true,
      },
      products: { create: true, list: true, update: true },
      subscriptionPlans: { create: true, list: true, show: true },
      shipment: { create: true, show: true, cancel: true },
      orders: { create: true, get: true },
      disputes: { list: true, get: true },
    },
  },
});

Para usar el modo sandbox, agrega contexto dentro de tu configuración.

configuration: {
  context: {
    sandbox: true,
  }
}

Inicialización de los flujos de trabajo

import { PayPalWorkflows, ALL_TOOLS_ENABLED } from '@paypal/agent-toolkit/ai-sdk';
const paypalWorkflows = new PayPalWorkflows({
  clientId: process.env.PAYPAL_CLIENT_ID,
  clientSecret: process.env.PAYPAL_CLIENT_SECRET,
  configuration: {
    actions: ALL_TOOLS_ENABLED,
  },
});

Uso

Uso del kit de herramientas

const llm: LanguageModelV1 = getModel(); // The model to be used with ai-sdk
const { text: response } = await generateText({
  model: llm,
  tools: paypalToolkit.getTools(),
  maxSteps: 10,
  prompt: `Create an order for $50 for custom handcrafted item and get the payment link.`,
});

Variables de entorno

Se pueden usar las siguientes variables de entorno:

• PAYPAL_ACCESS_TOKEN: Tu token de acceso de PayPal
• PAYPAL_ENVIRONMENT: Establézcalo en SANDBOX para el modo sandbox, PRODUCTION para producción (por defecto, modo SANDBOX)

Esta guía explica cómo generar un token de acceso para la integración con la API de PayPal, incluido cómo encontrar tu ID de cliente y secreto de cliente.

Requisitos previos

• Cuenta de desarrollador de PayPal (para Sandbox)
• Cuenta de negocio de PayPal (para producción)

Cómo encontrar tu ID de cliente y secreto de cliente

1. Crea una cuenta de desarrollador de PayPal:

   • Ve al Panel de desarrollador de PayPal
   • Regístrate o inicia sesión con tus credenciales de PayPal

2. Accede a tus credenciales:

   • En el Panel de desarrollador, haz clic en Aplicaciones y credenciales en el menú
   • Cambia entre los modos Sandbox y Live según tus necesidades

3. Crea o ve una aplicación:

   • Para crear una nueva aplicación, haz clic en Crear aplicación
   • Dale un nombre a tu aplicación y selecciona una cuenta de negocio para asociarla
   • Para aplicaciones existentes, haz clic en el nombre de la aplicación para ver los detalles

4. Recupera las credenciales:

   • Una vez que tu aplicación esté creada o seleccionada, verás una pantalla con tu:
     • ID de cliente: Un identificador público para tu aplicación
     • Secreto de cliente: Una clave privada (se muestra después de hacer clic en "Mostrar")
   • Guarda estas credenciales de forma segura, ya que son necesarias para generar tokens de acceso

Generación de un token de acceso

Uso de cURL

curl -v https://api-m.sandbox.paypal.com/v1/oauth2/token \\
  -H \"Accept: application/json\" \\
  -H \"Accept-Language: en_US\" \\
  -u \"CLIENT_ID:CLIENT_SECRET\" \\
  -d \"grant_type=client_credentials\"

Reemplaza CLIENT_ID y CLIENT_SECRET con tus credenciales reales. Para producción, usa https://api-m.paypal.com en lugar de la URL de sandbox.

Uso de Postman

1. Crea una nueva solicitud a https://api-m.sandbox.paypal.com/v1/oauth2/token
2. Establece el método en POST
3. En Autorización, selecciona Autenticación básica e ingresa tu ID de cliente y secreto de cliente
4. En Cuerpo, selecciona x-www-form-urlencoded y agrega una clave grant_type con el valor client_credentials
5. Envía la solicitud

Respuesta

Una respuesta exitosa se verá así:

{
  "scope": "...",
  "access_token": "Your Access Token",
  "token_type": "Bearer",
  "app_id": "APP-80W284485P519543T",
  "expires_in": 32400,
  "nonce": "..."
}

Copia el valor de access_token para usarlo en tu integración con Claude Desktop.

Detalles del token

• Tokens de Sandbox: Válidos por 3-8 horas
• Tokens de producción: Válidos por 8 horas
• Se recomienda implementar lógica de renovación de tokens antes de la expiración

Uso del token con Claude Desktop

Una vez que tengas tu token de acceso, actualiza el valor de PAYPAL_ACCESS_TOKEN en la configuración de tu conector de Claude Desktop:

{
  "env": {
    "PAYPAL_ACCESS_TOKEN": "YOUR_NEW_ACCESS_TOKEN",
    "PAYPAL_ENVIRONMENT": "SANDBOX"
  }
}

Mejores prácticas

1. Almacena el ID de cliente y el secreto de cliente de forma segura
2. Implementa lógica de renovación de tokens para manejar la expiración de tokens
3. Usa tokens específicos del entorno (sandbox para pruebas, producción para transacciones reales)
4. Evita codificar tokens en el código de la aplicación

Aviso legal

El contenido generado por IA puede ser inexacto o incompleto. Los usuarios son responsables de verificar de forma independiente cualquier información antes de confiar en ella. PayPal no ofrece garantías sobre la precisión de los resultados y no se hace responsable de ninguna decisión, acción o consecuencia derivada de su uso.