PayPal

PayPal Agent Toolkit

O PayPal Agent Toolkit permite que frameworks de agentes populares, incluindo o Agent SDK da OpenAI, LangChain, o AI SDK da Vercel e o Model Context Protocol (MCP), integrem-se às APIs do PayPal por meio de chamadas de função. Ele inclui suporte para TypeScript e é construído sobre as APIs do PayPal e os SDKs do PayPal.

Ferramentas disponíveis

O PayPal Agent Toolkit fornece as seguintes ferramentas:

Faturas

• create_invoice: Crie uma nova fatura no sistema do PayPal, incluindo detalhes de cobrança do destinatário, itens de linha, uma nota na fatura, um tema de cor personalizado, um custo de envio opcional e uma opção para habilitar PAY_BY_BANK como método de pagamento
• create_recurring_series: Crie uma série de faturas recorrentes que gera e envia faturas automaticamente em um cronograma
• list_invoices: Liste faturas com paginação e filtros opcionais
• get_invoice: Recupere detalhes de uma fatura específica
• send_invoice: Envie uma fatura para os destinatários
• send_invoice_reminder: Envie um lembrete para uma fatura existente
• cancel_sent_invoice: Cancele uma fatura enviada
• generate_invoice_qr_code: Gere um código QR para uma fatura

Pagamentos

• create_order: Crie um pedido no sistema do PayPal com base nos detalhes fornecidos
• get_order: Recupere os detalhes de um pedido
• pay_order: Processe o pagamento de um pedido autorizado
• create_refund: Processe um reembolso para um pagamento capturado
• get_refund: Obtenha os detalhes de um reembolso específico

Gerenciamento de Disputas

• list_disputes: Recupere um resumo de todas as disputas abertas
• get_dispute: Recupere informações detalhadas de uma disputa específica
• accept_dispute_claim: Aceite uma reivindicação de disputa

Rastreamento de Envios

• create_shipment_tracking: Crie um registro de rastreamento de envio
• get_shipment_tracking: Recupere informações de rastreamento de envio
• update_shipment_tracking: Atualize informações de rastreamento de envio

Gerenciamento de Catálogo

• create_product: Crie um novo produto no catálogo do PayPal
• list_products: Liste produtos com paginação e filtros opcionais
• show_product_details: Recupere detalhes de um produto específico

Gerenciamento de Assinaturas

• create_subscription_plan: Crie um novo plano de assinatura
• list_subscription_plans: Liste planos de assinatura
• show_subscription_plan_details: Recupere detalhes de um plano de assinatura específico
• create_subscription: Crie uma nova assinatura
• show_subscription_details: Recupere detalhes de uma assinatura específica
• update_subscription: Atualize uma assinatura existente
• cancel_subscription: Cancele uma assinatura ativa

Relatórios e Insights

• list_transactions: Liste transações com paginação e filtros opcionais
• get_merchant_insights: Recupere métricas de inteligência de negócios e análises para um comerciante

TypeScript

Instalação

Você não precisa deste código-fonte, a menos que queira modificar o pacote. Se você apenas quiser usar o pacote, execute:

npm install @paypal/agent-toolkit

Requisitos

• Node 18+

Uso

A biblioteca precisa ser configurada com o client id e o secret da sua conta, que estão disponíveis no seu PayPal Developer Dashboard.

O toolkit funciona com o AI SDK da Vercel e pode ser passado como uma lista de ferramentas. Para mais detalhes, consulte nossos exemplos

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 o modo sandbox, adicione o contexto dentro da sua configuração.

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

Inicializando os Workflows

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

Usando o toolkit

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.`,
});

Variáveis de Ambiente

As seguintes variáveis de ambiente podem ser usadas:

• PAYPAL_ACCESS_TOKEN: Seu token de acesso do PayPal
• PAYPAL_ENVIRONMENT: Defina como SANDBOX para o modo sandbox, PRODUCTION para produção (o padrão é o modo SANDBOX)

Este guia explica como gerar um token de acesso para a integração com a API do PayPal, incluindo como encontrar seu client ID e client secret.

Pré-requisitos

• Conta de desenvolvedor do PayPal (para Sandbox)
• Conta comercial do PayPal (para produção)

Encontrando seu Client ID e Client Secret

1. Crie uma conta de desenvolvedor do PayPal:

   • Acesse o PayPal Developer Dashboard
   • Cadastre-se ou faça login com suas credenciais do PayPal

2. Acesse suas credenciais:

   • No Developer Dashboard, clique em Apps & Credentials no menu
   • Alterne entre os modos Sandbox e Live conforme suas necessidades

3. Crie ou visualize um aplicativo:

   • Para criar um novo aplicativo, clique em Create App
   • Dê um nome ao seu aplicativo e selecione uma conta comercial para associar a ele
   • Para aplicativos existentes, clique no nome do aplicativo para ver os detalhes

4. Recupere as credenciais:

   • Depois que seu aplicativo for criado ou selecionado, você verá uma tela com:
     • Client ID: Um identificador público para seu aplicativo
     • Client Secret: Uma chave privada (exibida após clicar em "Show")
   • Salve essas credenciais com segurança, pois elas são necessárias para gerar tokens de acesso

Gerando um Token de Acesso

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\" \\
  -d \"grant_type=client_credentials\"

Substitua CLIENT_ID e CLIENT_SECRET pelas suas credenciais reais. Para produção, use https://api-m.paypal.com em vez da URL do sandbox.

Usando Postman

1. Crie uma nova solicitação para https://api-m.sandbox.paypal.com/v1/oauth2/token
2. Defina o método como POST
3. Em Authorization, selecione Basic Auth e insira seu Client ID e Client Secret
4. Em Body, selecione x-www-form-urlencoded e adicione uma chave grant_type com o valor client_credentials
5. Envie a solicitação

Resposta

Uma resposta bem-sucedida terá a seguinte aparência:

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

Copie o valor de access_token para uso na sua integração com o Claude Desktop.

Detalhes do Token

• Tokens de Sandbox: Válidos por 3-8 horas
• Tokens de Produção: Válidos por 8 horas
• Recomenda-se implementar a lógica de renovação do token antes da expiração

Usando o Token com o Claude Desktop

Depois de obter seu token de acesso, atualize o valor de PAYPAL_ACCESS_TOKEN na configuração do seu conector do Claude Desktop:

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

Melhores Práticas

1. Armazene o client ID e o client secret com segurança
2. Implemente a lógica de renovação do token para lidar com a expiração
3. Use tokens específicos do ambiente (sandbox para testes, produção para transações reais)
4. Evite codificar tokens diretamente no código do aplicativo

Aviso Legal

O conteúdo gerado por IA pode ser impreciso ou incompleto. Os usuários são responsáveis por verificar independentemente qualquer informação antes de confiar nela. O PayPal não oferece garantias quanto à precisão da saída e não se responsabiliza por decisões, ações ou consequências resultantes do seu uso.