Kit de herramientas de agente de PayPal

El kit de herramientas de agente de PayPal permite que los marcos de agentes más conocidos, como 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 compatibilidad con TypeScript y se ha creado sobre las API de PayPal y los SDK de PayPal.

Herramientas disponibles

El kit de herramientas del Agente de PayPal proporciona las herramientas siguientes:

Facturas

• create_invoice: Crear una nueva factura en el sistema PayPal
• list_invoices: Enumerar facturas con paginación y filtrado opcionales
• get_invoice: Recuperar detalles de una factura específica
• send_invoice: Enviar una factura a los destinatarios
• send_invoice_reminder: Enviar un recordatorio para una factura existente
• cancelar_factura_enviada: 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 PayPal basándose en 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
• aceptar_reclamación_de_disputa: Aceptar una reclamación de disputa

Seguimiento de envíos

• create_shipment_tracking: Crear un registro de seguimiento de envíos
• get_shipment_tracking: Recuperar información de seguimiento de envíos

Gestión de catálogos

• create_product: Crear un nuevo producto en el catálogo de PayPal
• list_products: Enumerar productos con paginación y filtrado opcionales
• show_product_details: Recuperar 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
• mostrar_detalles_del_plan_de_suscripción: Recuperar detalles de un plan de suscripción específico
• create_subscription: Crear una nueva suscripción
• mostrar_detalles_de_suscripción: Recuperar detalles de una suscripción específica
• update_subscription: actualizar una suscripción existente
• cancelar_suscripción: Cancelar una suscripción activa

Informes y perspectivas

• list_transactions: Listar transacciones con paginación y filtrado opcionales

TypeScript

Instalación

No necesitas este código fuente a menos que quieras modificar el paquete. Si sólo quieres usar el paquete ejecuta

npm install @paypal/agent-toolkit

Requisitos

• Nodo 18+

Uso

La biblioteca debe configurarse con el Id. de cliente y el secreto de su cuenta, que están disponibles en su 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 obtener más detalles, consulte 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, list: true, send: true, sendReminder: true, cancel: true, generateQRC: true, }, products: { crear: true, lista: true, actualizar: true }, subscriptionPlans: { create: true, list: true, show: true }, shipment: { create: true, show: true, cancel: true }, pedidos: { create: true, get: true }, disputes: { list: true, get: true }, }, }, })

Para utilizar el modo sandbox, añada el contexto dentro de su configuración.

configuración: { contexto: { 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 conjunto de herramientas

const llm: LanguageModelV1 = getModel(); // El modelo a utilizar con ai-sdk const { text: response } = await generateText({ model: llm, tools: paypalToolkit.getTools(), maxSteps: 10, prompt: `Crear un pedido de $50 para un artículo artesanal personalizado y obtener el enlace de pago.`, })

Protocolo de contexto de modelo de PayPal

El servidor de protocolo de contexto de modelo de PayPal le permite integrarse con las API de PayPal mediante llamadas a funciones. Este protocolo admite varias herramientas para interactuar con distintos servicios de PayPal.

Ejecución del inspector MCP

Para ejecutar el servidor MCP de PayPal mediante npx, utilice el siguiente comando:

npx -y @paypal/mcp --tools=all PAYPAL_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PAYPAL_ENVIRONMENT="SANDBOX"

Sustituya YOUR_ACCESS_TOKEN por el código de acceso activo generado siguiendo estos pasos: Código de acceso de PayPal. Como alternativa, puede establecer PAYPAL_ACCESS_TOKEN en sus variables de entorno.

Servidor MCP personalizado

Puede configurar su propio servidor MCP. Por ejemplo

import { PayPalAgentToolkit } from "@paypal/agent-toolkit/modelcontextprotocol"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; const orderSummary = await paypalWorkflows.generateOrder( llm, transactionInfo, merchantInfo, ); const server = new PayPalAgentToolkit({ accessToken: process.env.PAYPAL_ACCESS_TOKEN }); async function main() { const transport = new StdioServerTransport(); await server.connect(transport); console.error("Servidor MCP de PayPal ejecutándose en stdio"); } main().catch((error) => { console.error("Error fatal en main():", error); process.exit(1); })

Uso con host MCP (Claude Desktop/Cline/Cursor/Github Co-Pilot)

Esta guía explica cómo integrar el conector de PayPal con Claude Desktop.

Requisitos previos

• Aplicación Claude Desktop instalada
• instalar Node.js localmente

Pasos de la instalación

1. Instalar Node.js

Node.js es necesario para que el conector de PayPal funcione:

1. Visite el sitio web oficial de Node.js, descárguelo e instálelo.
2. Requisitos: Node 18+

2. Configurar el conector de PayPal con el host MCP (Claude desktop / Cursor / Cline)

Mostraremos la integración con Claude desktop. Puede utilizar su host MCP favorito.

1. Abra Claude Desktop
2. Vaya a Configuración
3. Busque la sección Desarrollador o Configuración avanzada
4. Localice el área de configuración de herramientas externas o conectores
5. Añada la siguiente configuración de conectores PayPal a este ~/Claude/claude_desktop_config.json:

{ "mcpServers": { "paypal": { "command": "npx", "args": [ "-y", "@paypal/mcp", "--tools=all" ], "env": { "PAYPAL_ACCESS_TOKEN": "YOUR_PAYPAL_ACCESS_TOKEN", "PAYPAL_ENVIRONMENT": "SANDBOX" } } }

Asegúrese de sustituir YOUR_PAYPAL_ACCESS_TOKEN por su código de acceso de PayPal real. También puede establecer PAYPAL_ACCESS_TOKEN como variable de entorno. También puede pasarlo como argumento utilizando --access-token en "args" Establezca el valor de PAYPAL_ENVIRONMENT como SANDBOX para la fase de pruebas y PRODUCTION para el entorno de producción.

6. Guarde los cambios de configuración

3. Pruebe la integración

1. Salga y reinicie Claude Desktop para aplicar los cambios
2. Pruebe la conexión pidiendo a Claude que realice una tarea relacionada con PayPal
   • Ejemplo "Listar mis facturas de PayPal"

Variables de entorno

Se pueden utilizar las siguientes variables de entorno:

• PAYPAL_ACCESS_TOKEN: Su código de acceso a PayPal
• PAYPAL_ENVIRONMENT: Establecer en SANDBOX para el modo sandbox, PRODUCTION para producción (predeterminado en modo SANDBOX )

Esta guía explica cómo generar un código de acceso para la integración de la API de PayPal, incluido cómo encontrar el Id. de cliente y el secreto de cliente.

Requisitos previos

• Cuenta de integrador de PayPal (para Sandbox)
• Cuenta PayPal Business (para producción)

Encontrar el Id. de cliente y el secreto de cliente

1. Cree una cuenta de programador de PayPal:

   • Vaya a Panel de integrador de PayPal
   • Regístrese o inicie sesión con sus credenciales de PayPal

2. Acceder a sus credenciales:

   • En el panel de integrador, haga clic en Aplicaciones y credenciales en el menú
   • Cambie entre los modos Sandbox y Activo en función de sus necesidades

3. Crear o ver una aplicación:

   • Para crear una nueva aplicación, haga clic en Crear aplicación
   • Asigne un nombre a su aplicación y seleccione una cuenta de empresa para asociarla a ella
   • Para las aplicaciones existentes, haga clic en el nombre de la aplicación para ver los detalles

4. Recuperar credenciales:

   • Una vez creada o seleccionada la aplicación, aparecerá una pantalla con
     • ID de cliente: Un identificador público para tu aplicación
     • Secreto del 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 los tokens de acceso

Generación de un token de acceso

Usando 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" (CLIENTE_ID:CLIENTE_SECRET) -d "grant_type=client_credentials"

Sustituya CLIENT_ID y CLIENT_SECRET por sus credenciales reales. Para producción, utilice https://api-m.paypal.com en lugar de la URL del sandbox.

Uso de Postman

1. Cree una nueva petición a https://api-m.sandbox.paypal.com/v1/oauth2/token
2. Establezca el método POST
3. En Authorization, seleccione Basic Auth e introduzca su Client ID y Client Secret
4. En Cuerpo, seleccione x-www-form-urlencoded y añada una clave grant_type con valor client_credentials
5. Envíe la solicitud

Respuesta

Una respuesta correcta tendrá el aspecto siguiente

{ "scope": "...", "access_token": "Tu token de acceso", "token_type": "Bearer", "app_id": "APP-80W284485P519543T", "expires_in": 32400, "nonce": "..." }

Copie el valor de access_token para utilizarlo en su integración con Claude Desktop.

Detalles del token

• Fichas Sandbox: Válidos durante 3-8 horas
• Tokens de producción: Válido durante 8 horas
• Se recomienda implementar una lógica de actualización del token antes de su caducidad

Uso del token con Claude Desktop

Una vez que tenga su token de acceso, actualice el valor PAYPAL_ACCESS_TOKEN en la configuración de su conector Claude Desktop:

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

Buenas prácticas

1. Almacene el ID y el secreto del cliente de forma segura
2. Implementar una lógica de actualización de tokens para gestionar su caducidad
3. Utilice tokens específicos para cada entorno (sandbox para pruebas, producción para transacciones reales)
4. Evite codificar los tokens en el código de la aplicación

Descargo de responsabilidad

El contenido generado por la 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 garantiza la precisión de los resultados y no se hace responsable de ninguna decisión, acción o consecuencia derivada de su uso.