PayPal

PayPal Agent Toolkit

PayPal Agent Toolkit; OpenAI Agent SDK, LangChain, Vercel AI SDK ve Model Context Protocol (MCP) dahil olmak üzere popüler ajan çerçevelerinin, fonksiyon çağırma yoluyla PayPal API'leriyle entegre olmasını sağlar. TypeScript desteği içerir ve PayPal API'leri ile PayPal SDK'ları üzerine inşa edilmiştir.

Kullanılabilir araçlar

PayPal Agent toolkit aşağıdaki araçları sağlar:

Faturalar

• create_invoice: PayPal sisteminde, alıcı fatura bilgileri, satır kalemleri, fatura notu, özel renk teması, isteğe bağlı kargo ücreti ve PAY_BY_BANK ödeme yöntemini etkinleştirme seçeneği dahil olmak üzere yeni bir fatura oluşturur
• create_recurring_series: Bir programa göre otomatik olarak fatura oluşturan ve gönderen yinelenen bir fatura serisi oluşturur
• list_invoices: İsteğe bağlı sayfalama ve filtreleme ile faturaları listeler
• get_invoice: Belirli bir faturanın ayrıntılarını alır
• send_invoice: Bir faturayı alıcılara gönderir
• send_invoice_reminder: Mevcut bir fatura için hatırlatma gönderir
• cancel_sent_invoice: Gönderilmiş bir faturayı iptal eder
• generate_invoice_qr_code: Bir fatura için QR kodu oluşturur

Ödemeler

• create_order: Sağlanan ayrıntılara göre PayPal sisteminde bir sipariş oluşturur
• get_order: Bir siparişin ayrıntılarını alır
• pay_order: Yetkilendirilmiş bir sipariş için ödeme işlemini gerçekleştirir
• create_refund: Yakalanan bir ödeme için iade işlemini gerçekleştirir
• get_refund: Belirli bir iadenin ayrıntılarını alır

Anlaşmazlık Yönetimi

• list_disputes: Tüm açık anlaşmazlıkların özetini alır
• get_dispute: Belirli bir anlaşmazlığın ayrıntılı bilgilerini alır
• accept_dispute_claim: Bir anlaşmazlık talebini kabul eder

Gönderi Takibi

• create_shipment_tracking: Bir gönderi takip kaydı oluşturur
• get_shipment_tracking: Gönderi takip bilgilerini alır
• update_shipment_tracking: Gönderi takip bilgilerini günceller

Katalog Yönetimi

• create_product: PayPal kataloğunda yeni bir ürün oluşturur
• list_products: İsteğe bağlı sayfalama ve filtreleme ile ürünleri listeler
• show_product_details: Belirli bir ürünün ayrıntılarını alır

Abonelik Yönetimi

• create_subscription_plan: Yeni bir abonelik planı oluşturur
• list_subscription_plans: Abonelik planlarını listeler
• show_subscription_plan_details: Belirli bir abonelik planının ayrıntılarını alır
• create_subscription: Yeni bir abonelik oluşturur
• show_subscription_details: Belirli bir aboneliğin ayrıntılarını alır
• update_subscription: Mevcut bir aboneliği günceller
• cancel_subscription: Aktif bir aboneliği iptal eder

Raporlama ve İçgörüler

• list_transactions: İsteğe bağlı sayfalama ve filtreleme ile işlemleri listeler
• get_merchant_insights: Bir satıcı için iş zekası metriklerini ve analizlerini alır

TypeScript

Kurulum

Paketi değiştirmek istemiyorsanız bu kaynak koda ihtiyacınız yoktur. Yalnızca paketi kullanmak istiyorsanız şunu çalıştırın:

npm install @paypal/agent-toolkit

Gereksinimler

• Node 18+

Kullanım

Kütüphanenin, PayPal Developer Dashboard adresinde bulunan hesabınızın client id ve secret bilgileriyle yapılandırılması gerekir.

Toolkit, Vercel'in AI SDK'sı ile çalışır ve bir araç listesi olarak aktarılabilir. Daha fazla ayrıntı için örneklerimize bakın.

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

Sandbox modunu kullanmak için yapılandırmanıza bağlam ekleyin.

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

Workflow'ları Başlatma

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

Kullanım

Toolkit'i kullanma

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

Ortam Değişkenleri

Aşağıdaki ortam değişkenleri kullanılabilir:

• PAYPAL_ACCESS_TOKEN: PayPal Erişim Token'ınız
• PAYPAL_ENVIRONMENT: Sandbox modu için SANDBOX olarak ayarlayın, üretim için PRODUCTION (varsayılan SANDBOX modudur)

Bu kılavuz, PayPal API entegrasyonu için erişim token'ı oluşturmayı ve client ID ile client secret bilgilerinizi nasıl bulacağınızı açıklar.

Ön Koşullar

• PayPal Developer hesabı (Sandbox için)
• PayPal Business hesabı (üretim için)

Client ID ve Client Secret Bulma

1. PayPal Developer Hesabı Oluşturun:

   • PayPal Developer Dashboard adresine gidin
   • PayPal kimlik bilgilerinizle kaydolun veya oturum açın

2. Kimlik Bilgilerinize Erişin:

   • Developer Dashboard'da menüden Apps & Credentials seçeneğine tıklayın
   • İhtiyacınıza göre Sandbox ve Live modları arasında geçiş yapın

3. Uygulama Oluşturun veya Görüntüleyin:

   • Yeni bir uygulama oluşturmak için Create App seçeneğine tıklayın
   • Uygulamanıza bir ad verin ve ilişkilendirmek için bir Business hesabı seçin
   • Mevcut uygulamalar için ayrıntıları görüntülemek üzere uygulama adına tıklayın

4. Kimlik Bilgilerini Alın:

   • Uygulamanız oluşturulduğunda veya seçildiğinde, şu bilgilerinizi içeren bir ekran görürsünüz:
     • Client ID: Uygulamanız için genel bir tanımlayıcı
     • Client Secret: Özel bir anahtar ("Show" seçeneğine tıklandıktan sonra gösterilir)
   • Bu kimlik bilgilerini güvenli bir şekilde saklayın; erişim token'ı oluşturmak için gereklidirler

Erişim Token'ı Oluşturma

cURL Kullanarak

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\"

CLIENT_ID ve CLIENT_SECRET değerlerini gerçek kimlik bilgilerinizle değiştirin. Üretim için sandbox URL'si yerine https://api-m.paypal.com kullanın.

Postman Kullanarak

1. https://api-m.sandbox.paypal.com/v1/oauth2/token adresine yeni bir istek oluşturun
2. Yöntemi POST olarak ayarlayın
3. Authorization altında Basic Auth seçin ve Client ID ile Client Secret bilgilerinizi girin
4. Body altında x-www-form-urlencoded seçin ve grant_type anahtarını client_credentials değeriyle ekleyin
5. İsteği gönderin

Yanıt

Başarılı bir yanıt şuna benzer:

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

Claude Desktop entegrasyonunuzda kullanmak için access_token değerini kopyalayın.

Token Ayrıntıları

• Sandbox Token'ları: 3-8 saat geçerlidir
• Üretim Token'ları: 8 saat geçerlidir
• Süresi dolmadan önce token yenileme mantığı uygulanması önerilir

Token'ı Claude Desktop ile Kullanma

Erişim token'ınızı aldıktan sonra, Claude Desktop bağlayıcı yapılandırmanızdaki PAYPAL_ACCESS_TOKEN değerini güncelleyin:

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

En İyi Uygulamalar

1. Client ID ve client secret bilgilerini güvenli bir şekilde saklayın
2. Token süresinin dolmasını yönetmek için token yenileme mantığı uygulayın
3. Ortama özel token'lar kullanın (test için sandbox, gerçek işlemler için üretim)
4. Uygulama kodunda token'ları sabit kodlamaktan kaçının

Sorumluluk Reddi

Yapay zeka tarafından üretilen içerik hatalı veya eksik olabilir. Kullanıcılar, herhangi bir bilgiye güvenmeden önce bunu bağımsız olarak doğrulamakla yükümlüdür. PayPal, çıktı doğruluğu konusunda hiçbir garanti vermez ve kullanımından kaynaklanan kararlar, eylemler veya sonuçlardan sorumlu değildir.