Geliştiriciler, faturalandırma ve abonelikleri sıfırdan inşa etmeden yönetmek için genellikle güçlü çözümler ararlar. Paddle API, ödeme işleme, müşteri yönetimi ve gelir operasyonlarının yazılımınıza sorunsuz entegrasyonunu sağlayan güçlü bir araç olarak bu alanda öne çıkıyor.
Öncelikle temel bilgileri anlamalısınız. Paddle API, uygulamanızı Paddle'ın faturalandırma sistemine bağlayan bir RESTful arayüz görevi görür. Ürün oluşturma, abonelikleri yönetme ve işlemleri gerçekleştirme gibi işlemleri destekler. Ek olarak, canlıya geçmeden önce güvenli testler için sanal ortamlar sunar. Bu makaleye devam ederken, kurulum, kimlik doğrulama ve gelişmiş kullanım hakkında bilgi edineceksiniz.
Paddle API Nedir ve Neden Kullanmalısınız?
Paddle API, SaaS işletmeleri için küresel ödemeleri, vergileri ve yasal uyumluluğu yöneten bir "merchant-of-record" platformu olan Paddle'ın arka uç arayüzünü temsil eder. Geleneksel ödeme ağ geçitlerinin aksine, Paddle API satıcı olma sorumluluğunu üstlenir, bu da operasyonlarınızı basitleştirir ve yasal yükleri azaltır.
Paddle API'nin Stripe veya Chargebee gibi rakiplerinden farkını merak edebilirsiniz. Paddle, yerleşik abonelik yönetimi, otomatik faturalandırma ve sahtekarlık koruması gibi SaaS'a özel özelliklere odaklanır. Örneğin, 200'den fazla ülkede KDV ve satış vergisi hesaplamalarını otomatik olarak yöneterek geliştiricilerin temel ürün özelliklerine odaklanmasını sağlar.
Ayrıca, Paddle API web uygulamaları, mobil uygulamalar ve arka uç hizmetleriyle kolayca entegre olur. İstekler için standart HTTP yöntemlerini (GET, POST, PATCH ve DELETE) kullanır ve JSON birincil veri formatıdır. Bu uyumluluk, Node.js, Laravel veya Next.js gibi çerçevelere kapsamlı bir yeniden çalışma olmaksızın dahil edebilmenizi sağlar.
Gerçek değer, ölçeklenebilirliğinde yatar. İşletmeniz büyüdükçe, Paddle API artan işlem hacimlerini verimli bir şekilde yönetir. Paddle'ın belgelerindeki istatistikler, binlerce satıcı için yıllık milyarlarca dolar gelir işlediğini göstermektedir. Bu nedenle, Paddle API'yi benimsemek, uygulamanızı para kazanmada uzun vadeli başarı için konumlandırır.
Paddle API Erişimi Nasıl Başlatılır?
Paddle API'ye erişmek için Paddle panosunda bir hesap oluşturarak başlarsınız. Ücretsiz bir hesap için kaydolun. Kaydolduktan sonra, Paddle size kimlik doğrulama için API anahtarları sağlar.
Ardından, sanal ve üretim ortamları arasında ayrım yaparsınız. Sanal mod, gerçek ücretler olmadan API çağrılarını test etmenize olanak tanır. Canlı işlemlere hazır olduğunuzda üretime geçersiniz. Paddle, maliyetli hatalardan kaçınmak için sanal ortamda başlamanızı önerir.
Ek olarak, daha kolay entegrasyon için SDK'lar yüklersiniz. Paddle, PHP, Python, Node.js ve Ruby gibi diller için resmi SDK'lar sunar. Örneğin, Node.js'de, kütüphaneyi eklemek için npm install paddle-sdk komutunu çalıştırırsınız. Bu SDK, karmaşık API çağrılarını soyutlayarak tekrar eden kodu azaltır.
API sürümünü de gözden geçirirsiniz. Paddle, sürümlenmiş uç noktalar kullanır ve en son sürüm faturalandırma için v1'dir. Güncellemeler bozan değişiklikler getirebileceğinden, mevcut sürümü doğrulamak için her zaman developer.paddle.com/api-reference adresindeki API referansını kontrol edin.
Son olarak, yerel geliştirme ortamınızı kurarsınız. PADDLE_VENDOR_ID ve PADDLE_VENDOR_AUTH_CODE gibi API anahtarlarınız için ortam değişkenlerini yapılandırın. Bu uygulama, hassas verileri kod tabanınızın dışında tutarak güvenliği artırır.
Paddle API için Kimlik Doğrulama Nasıl Kurulur?
Kimlik doğrulama, Paddle API ile etkileşimlerinizi güvence altına alır. Paddle, isteklerde satıcı kimliğinizi ve yetkilendirme kodunuzu dahil ettiğiniz API anahtarı tabanlı kimlik doğrulaması kullanır.
Öncelikle, "Geliştirici Araçları" > "Kimlik Doğrulama" altındaki Paddle panosundan anahtarlar oluşturursunuz. Bir satıcı kimliği (sayısal bir değer) ve bir yetkilendirme kodu (bir dize) alırsınız. Bunları, AWS Secrets Manager gibi bir sır yöneticisi kullanarak güvenli bir şekilde saklayın.
Ardından, bunları HTTP isteklerine dahil edersiniz. Temel kimlik doğrulama için Basic <base64-encoded vendor_id:auth_code> formatını kullanırsınız. Ancak Paddle, bunları GET istekleri için sorgu parametreleri olarak veya POST istekleri için gövdede geçirmeyi tercih eder.
Örneğin, ürünleri listelemek için örnek bir curl isteği şöyle görünür:
curl -X GET \
'https://api.paddle.com/products' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json'
Paddle, daha yeni sürümlerde bearer token'lara geçiş yapmıştır, ancak eski sistemler temel kimlik doğrulamayı kullanabilir. Yöntemi her zaman belgelerde doğrulayın.
Ayrıca, token rotasyonunu da yönetirsiniz. Paddle, anahtarların tehlikeye girmesi durumunda yeniden oluşturmanıza olanak tanır. Paddle'ın API limitlerine (genellikle dakikada 100 istek) uymak için kodunuzda hız sınırlaması uygulayın.
401 Yetkisiz gibi kimlik doğrulama hatalarıyla karşılaşırsanız, anahtarlarınızı iki kez kontrol edin ve doğru ortamı (sandbox.paddle.com vs. api.paddle.com) kullandığınızdan emin olun.
Ana Paddle API Uç Noktaları Nelerdir ve Nasıl Çalışırlar?
Paddle API, uç noktaları ürünler, müşteriler, abonelikler ve işlemler gibi kategorilere ayırır. Eksiksiz bir faturalandırma akışı oluşturmak için bunlarla etkileşim kurarsınız.
Ürünlerle başlayarak, kataloğunuzu oluşturur ve yönetirsiniz. /products uç noktası, yeni öğeler eklemek için POST isteklerine izin verir. Örneğin:
{
"name": "Premium Plan",
"description": "Unlimited access",
"tax_category": "standard",
"prices": [
{
"country_codes": ["US"],
"amount": "29.99",
"currency": "USD"
}
]
}
Bu, yerelleştirilmiş fiyatlandırma ile bir ürün oluşturur.
Ardından, müşteri uç noktaları kullanıcı verilerini işler. Profiller oluşturmak ve bunları aboneliklere bağlamak için /customers kullanırsınız. Bir POST isteği e-posta, ad ve özel meta verileri içerebilir.
Abonelikler bunun üzerine inşa edilir. /subscriptions uç noktası yinelenen faturalandırmayı yönetir. Şununla bir abonelik oluşturursunuz:
POST /subscriptions
{
"customer_id": "cus_123",
"plan_id": "plan_456",
"quantity": 1,
"trial_period_days": 14
}
Bu, bir deneme başlatır ve yinelenen ücretleri ayarlar.
İşlemler, tek seferlik ödemeleri kapsar. Bunları /transactions aracılığıyla işleyerek miktar, para birimi ve ödeme yöntemini belirtirsiniz.
Web kancaları gerçek zamanlı bildirimler sağlar. Bunları panoda yapılandırır, sunucunuzun URL'sini işaret edersiniz. Paddle, subscription_created veya payment_succeeded gibi olaylar gönderir. Kurcalamayı önlemek için sağlanan genel anahtarı kullanarak imzaları doğrulayın.
Hata yönetimi tüm uç noktalarda çok önemlidir. Paddle standart HTTP durum kodları döndürür: başarı için 200, hatalı istekler için 400 ve sunucu hataları için 500. Ayrıntılar için her zaman yanıt gövdesini ayrıştırın, örneğin:
{ "error": { "type": "request_error", "detail": "Invalid customer ID" } }
Bu yapı, sorunları hızlı bir şekilde ayıklamanıza yardımcı olur.
Paddle API Uygulamanıza Nasıl Entegre Edilir?
Entegrasyon dikkatli planlama gerektirir. Uygulamanızın iş mantığını Paddle'ın varlıklarına eşleştirerek başlarsınız.
Bir web uygulaması için, ön uç ödemeler için Paddle'ın Checkout.js'ini eklersiniz. Komut dosyasını yükleyin:
<script src="https://cdn.paddle.com/paddle/paddle.js"></script>
<script>
Paddle.Setup({ vendor: YOUR_VENDOR_ID });
</script>
Ardından, Paddle.Checkout.open({ product: PRODUCT_ID }); ile ödeme ekranlarını açarsınız.
Arka uçta, API çağrıları aracılığıyla verileri senkronize edersiniz. Bir Laravel örneğinde, resmi Paddle paketini kullanırsınız: composer require paddlehq/laravel-paddle.
Abonelikler için modeller tanımlar ve denetleyicilerde web kancalarını yönetirsiniz:
public function handleWebhook(Request $request)
{
$payload = $request->all();
// Verify signature
if (!Paddle::verifyWebhookSignature($payload, $request->header('Paddle-Signature'))) {
return response('Invalid signature', 403);
}
// Process event
switch ($payload['alert_name']) {
case 'subscription_created':
// Update user access
break;
}
}
Bu, gerçek zamanlı güncellemeleri sağlar.
Ek olarak, sağlama (provisioning) uygularsınız. Başarılı bir ödemeden sonra, özelliklere erişim izni verin. Paddle'ın karşılama API'sini veya özel mantığı kullanın.
Mobil uygulamalar için, platformlar arası tutarlılık için RevenueCat gibi platformlarla entegre olarak uygulama içi satın almalardan yararlanırsınız.
Sanal ortamda test yapmak gerçek senaryoları taklit eder. Başarılı ücretlendirmeler için 4111 1111 1111 1111 gibi Paddle tarafından sağlanan test kartlarını kullanırsınız.
Paddle API Apidog ile Nasıl Test Edilir?
Test etmek, entegrasyonunuzu doğrular. Apidog, bir API istemci aracı olarak bu konuda mükemmeldir ve Paddle API'ye kod yazmadan istekleri simüle etmenize olanak tanır.
Ayrıca, Apidog'un mock sunucusu, şemalara dayalı sahte yanıtlar üretir, bu da tam arka uç entegrasyonundan önce ön uç geliştirme için faydalıdır.
Paddle API için neden Apidog'u seçmelisiniz? Farklı para birimleri veya miktarlar gibi çeşitli senaryolar için CSV içe aktarımları ile veri odaklı testleri destekleyerek ödeme testini kolaylaştırır.
Paddle API Kullanımı İçin En İyi Uygulamalar Nelerdir?
En iyi uygulamaları benimsemek güvenilirliği sağlar. Hassas verileri korumak için istekler için her zaman HTTPS kullanırsınız.
Ek olarak, yeniden denemeler sırasında yinelenen işlemleri önlemek için POST istekleri için eşsizlik anahtarları uygulayın.
Paddle'ın analitik panosu ile API kullanımını izlersiniz; istek hacmi ve hata oranları gibi metrikleri takip edersiniz.
Ayrıca, başarısız ödemeler gibi uç durumları yönetin. Yeniden denemeleri veya bildirimleri tetiklemek için web kancalarını kullanın.
Uluslararası destek için, Paddle'ın yerelleştirme özelliklerinden yararlanın, fiyatlara ülke kodlarını ayarlayın.
Son olarak, Paddle'ın değişiklik günlüğü ile güncel kalın. API güncellemeleri için geliştirici bültenlerine abone olun.
Yaygın Paddle API Hataları Nasıl Giderilir?
Hatalar akışları bozabilir. Yaygın bir sorun, 429 Çok Fazla İstek'tir; bunu yeniden denemelerde üstel geri çekilme uygulayarak çözersiniz.
Diğeri, JSON'da eksik alanlar gibi geçersiz parametrelerdir. Göndermeden önce yükleri istemci tarafında doğrulayın.
Web kancaları başarısız olursa, imza uyuşmazlıkları için sunucunuzun günlüklerini kontrol edin. Paddle, test için panoda bir simülatör sağlar.
Kimlik doğrulama sorunları için anahtarları yeniden oluşturun ve yapılandırmanızı güncelleyin.
Paddle API Hangi Gelişmiş Özellikleri Sunar?
Temel özelliklerin ötesinde, Paddle API gelir analizleri için raporlama uç noktaları içerir: /reports/revenue.
Markalaşma için geçersiz kılmalarla ödeme ekranlarını özelleştirirsiniz.
Zapier veya Segment gibi üçüncü taraf araçlarla entegrasyon, işlevselliği genişletir.
Kurumsal için Paddle, özel varlıkları ve toplu işlemleri destekler.
Sonuç: En Uygun Sonuçlar İçin Paddle API'ye Hakim Olmak
Artık Paddle API'ye güvenle erişme ve kullanma bilgisine sahipsiniz. Kurulumdan gelişmiş entegrasyonlara kadar bu kılavuz, temel yönleri kapsar. Unutmayın, Apidog gibi araçlar verimliliğinizi artırır.
Uygularken, sanal ortamda deney yapın ve testlere göre yineleyin. Paddle API, SaaS'ınızın minimum ek yük ile küresel olarak ölçeklenmesini sağlar.