Kodsuz partner API portalı kurulumu: anahtarlar, scope'lar, onboarding

Partner API portalı ne çözer (ve neden karmaşıklaşır)

Partner API portalı, dış ekiplerin giriş yapıp kimlik bilgisi alabileceği ve API'nizi nasıl kullanacaklarını anlayabileceği tek bir yerdir — sonsuz e-posta trafiği olmadan. Entegrasyonlar için resepsiyon gibi düşünün: erişim, dokümantasyon ve temel hesap kontrolleri tek noktada.

Bu portal, şirket dışındaki ve sistemlerinize güvenilir erişim ihtiyacı olan herkes içindir: entegrasyon ortakları, bayi satıcılar, müteahhitler, ajanslar veya bir müşterinin bağlayıcı arabirimini yapan BT ekibi. Veri açıyorsanız, sipariş oluşturuyorsanız, hesapları senkronize ediyorsanız veya iş akışlarını tetikliyorsanız, bir portal bu talepleri öngörülebilir bir sürece dönüştürür.

Portal yoksa iş hızla karmaşıklaşır. Yaygın bir örnek “sadece tek bir anahtar paylaş” modelidir; sohbette veya tablonuzda bir anahtar dolaşıma girer. Sonra kim kullanıyor, neye erişebiliyor veya bir sözleşme bittiğinde nasıl iptal edilir kimse hatırlamaz. İzinler sözlü bilgiye döner, kotalar kızgın telefonlarla uygulanır ve her yeni partner özel bir kurulum gerektirir.

Kodsuz partner API portalı, onboarding sürecini hızlandırırken kontrolü gerekli yerde tutmayı amaçlar. Amaç gün birinde kusursuz bir geliştirici platformu inşa etmek değil; manuel işleri azaltmak ve riski düşürmektir.

Çoğu ekip önce dört temel sorunu çözdüğünde en yüksek değeri görür:

• Her partnere kendi API anahtarını verin; böylece erişim izlenebilir ve geri alınabilir.
• Scope'larla izinleri net tutun, partnerler yalnızca ihtiyaç duyduklarına erişsin.
• Basit kotalar ve hız limitleri belirleyin, tek bir entegrasyon sisteminizi aşırı yüklemesin.
• Kısa bir onboarding yolu sağlayın, partnerler ilk başarılı API çağrısını hızlıca yapsın.

Minimal başlayın, sonra zamanla sıkılaştırın. Bir sandbox ortamı ve iki scope (okuma ve yazma) ile başlayabilirsiniz. İlk partner canlıya çıktıktan sonra hangi noktaların daha fazla detaya ihtiyaç duyduğunu çabucak görürsünüz: özellik başına ayrı scope'lar, daha iyi denetim logları veya daha sıkı limitler gibi.

Yapı taşları: anahtarlar, scope'lar, kotalar ve ortamlar

Kodsuz bir partner API portalını çalıştırmak, hareketli parçaları baştan adlandırdığınızda daha kolaydır. Çoğu portal küçük bir nesne seti ve bunların nasıl bağlandığına dair net kurallarla tanımlanır.

Tipik model şu şekildedir:

• Partner: içeri aldığınız şirket (veya ekip).
• Uygulama (veya client): o partner tarafından sahip olunan belirli bir entegrasyon (bir partnerin birden fazla uygulaması olabilir).
• API anahtarı (veya token): uygulamanın API'nizi çağırabildiğini ispatlayan gizli dize. Bir anahtar bir uygulamaya ait olmalı, kişiye değil.
• Scope: anahtarın hangi eylemleri yapmasına izin verildiğini gösteren liste.
• Kota (ve hız limitleri): uygulamanın belli bir zaman aralığında API'yi ne kadar kullanabileceği.

Faydalı bir zihinsel model: Partner -> Uygulama -> API anahtarı, ve scope'lar ile kotalar anahtara (veya uygulamaya) eklenir. Sahiplik net kalır. Bir partner daha sonra ikinci bir entegrasyon oluşturduğunda ikinci bir uygulama ve ayrı anahtarlar alır. Sadece sorunlu olana kısıtlama koyabilir veya devre dışı bırakabilirsiniz.

Ortamlar: sandbox vs üretim

Çoğu ekip iki ortama ihtiyaç duyar. Sandbox test içindir; sahte veya sınırlı veri kullanılır. Üretim gerçek müşteri verisi ve gerçek etkidir. Partnerler aynı anahtarı her iki ortamda paylaşmamalıdır.

Neleri denetlemeli (destek mümkün olsun diye)

Basit bir portal bile temel olay izini kaydetmelidir:

• Anahtar oluşturuldu, döndürüldü veya iptal edildi
• Scope eklendi veya kaldırıldı
• Kota değişiklikleri
• Anahtar kullanımı (temel sayımlar ve hatalar)

Bir partner "API'niz çalışmıyor" dediğinde, bu denetim izi genellikle 5 dakikalık bir çözüm ile bir haftalık tahmine dayalı çalışmanın farkını yaratır.

Anlaşılır kalan izin scope'ları tasarlamak

Scope, bir API anahtarına eklenen düz İngilizce (burada korunan terimler kod içinde korunur) bir izin etiketidir. Cevap verir: "Bu partner ne yapmaya izinli?" Örneğin, orders:read olan bir anahtar sipariş detaylarını alabilir; refunds:create olan bir anahtar iade başlatabilir. Bu izinler varsayılan olarak birlikte paketlenmemelidir.

Scope'ları insan tarafından okunabilir ve gerçek iş görevleriyle bağlı tutun. Partnerler ve destek ekipleri bir anahtara bakıp saniyeler içinde anlayabilmeli.

Küçük başlayın. Toplamda 5–10 scope hedefleyin, onlarca değil. Çok fazla scope kafa karışıklığına, yanlış erişim taleplerine ve "bize admin verin" baskısına yol açar. Daha sonra yeni bir scope ekleyebilirsiniz; ancak partnerler ona bağımlı olduktan sonra scope'u geri almak zordur.

Scope tasarlamak için pratik bir yol: endpoint'leri API'nin teknik şekline göre değil, destekledikleri işe göre gruplayın. Yaygın gruplar: siparişler, müşteriler, faturalama (faturalar, ödemeler, iadeler), katalog (ürünler, fiyatlandırma) ve webhook'lar (oluşturma, gizli anahtar döndürme, duraklatma).

Varsayılan olarak en az ayrıcalık prensibini uygulayın. Her partnere şu anda oluşturdukları entegrasyon için sadece gerekeni verin. Anahtar sızarsa hasarı da sınırlar.

Bazı eylemler ekstra sürtünme gerektirir. İade oluşturma, ödeme detaylarını değiştirme, toplu müşteri verisi dışa aktarma veya webhook yönetimi genellikle dahili bir kontrol listesiyle "kilidi açılabilir" izinler olarak daha iyi çalışır.

Sorunsuz anahtar verme ve döndürme

Partnera API erişimi vermek için en sakin an onları tanıdığınız ve ne yapmalarına izin verildiğini bildiğiniz andır. Birçok ekip için bu onay ve imzalı bir sözleşmeden sonradır. Daha küçük programlar için self-serve çalışabilir, eğer scope'ları sıkı tutar ve daha yüksek riskli erişimleri manuel incelemeye ayırırsınız.

Anahtar verme sıkıcı olmalı. Partnerler her zaman net bir anahtar adı, ne yapabildiği ve hangi ortam için olduğu bilgisini görmelidir.

Gizliler parolalar gibi ele alınmalı. Mümkünse gizli değerin yalnızca hash'ini saklayın ve tam gizli değeri oluştururken tam olarak bir kez gösterin. Sonrasında sadece kısa bir anahtar öneki gösterin ki her iki taraf da logları doğru anahtarla eşleştirebilsin.

Döndürme birçok ekip için sorun yaratır; bu yüzden onu standart bir akış haline getirin:

1) Create a new key (same scopes, same partner)
2) Partner switches their integration to the new key
3) Confirm traffic is using the new key
4) Revoke the old key

İptal etme ve acil kapatma birinci sınıf özellik olmalı. Bir partner sızıntı bildirdiğinde, destek birkaç saniyede bir anahtarı devre dışı bırakabilmeli ve net bir gerekçe loglanmalıdır.

Bir basit önlem destek taleplerini azaltır: partnerlerin birden fazla anahtar oluşturmasına izin verin (staging ve prod için), ancak her biri için açık bir etiket ve sahip gerektirin.

Partnerlerin yaşayabileceği kotalar ve hız limitleri

Kotalar yalnızca sunucularınızı korumakla ilgili değildir. Ayrıca müşterilerinizi yavaşlamadan korur ve partnerleri sürprizlerden (örneğin aniden 100.000 istek gönderen bir döngü) korur.

Bir politika öngörülebilir olduğunda adildir. Partnerler politikayı bir kez okuyunca normal kullanımda, trafik sıçramasında veya bir hatada ne olacağını bilmelidir.

Basit bir başlangıç politikası iki limit içerir: kısa vadeli bir hız limiti ve günlük bir kota. Sayıları ilk etapta muhafazakar tutun, sonra gerçek trafiğe göre artırın.

Örneğin:

• 60 istek/dakika her API anahtarı için
• 10.000 istek/gün her API anahtarı için

Limitleri ortam başına ayrı tutun (sandbox vs üretim) ve dışa aktarma, arama ve dosya yüklemeleri gibi maliyetli endpoint'ler için daha sıkı limitler düşünün.

Bir kota aşıldığında deneyim limit kadar önemlidir. Partnerleri tahmin ettirmeyin. Hangi limitin aşıldığını (dakikalık mı yoksa günlük mü) açıkça söyleyen bir hata dönün, ne zaman tekrar denenebileceğine dair kılavuz verin ve mümkünse Retry-After değeri ekleyin.

Limit artışları bir süreç olmalı; her seferinde pazarlık yapılacak bir şey değil. Beklentileri baştan belirleyin: kim onaylıyor, hangi kullanım kanıtına ihtiyaç var, onaylandığında neler değişecek ve ne zaman tekrar gözden geçirileceksiniz.

Minimal bir onboarding akışı (adım adım)

İyi bir onboarding akışı banka hesabı açmak gibi hissettirmeli: net sorular, net limitler ve net bir sonraki adım. İlk versiyonu küçük ve öngörülebilir tutun; sadece partnerler talep ettikçe ekstralar ekleyin.

Adımlar 1–3: temelleri erken alın

Şirket adı, teknik iletişim, kullanım durumu ve beklenen aylık hacmi (istek ve veri boyutu) toplayın. Bir serbest metin alanı ekleyin: "30 günde başarı nasıl görünür?"

Onaydan sonra partnerin bir uygulama/client oluşturmasını ve önce bir sandbox anahtarı çıkarmasını sağlayın. Anahtara bir amaç adı bağlayın (ör. "Acme - Billing Sync"). Anahtarın yanında iki bilgi net gösterilsin: hangi ortamda çalıştığı ve ne zaman oluşturulduğu.

Adımlar 4–6: scope'lar, ilk çağrı, sonra üretim

Scope seçimini basit tutun: en fazla 3–8 scope, düz dilde tanımlanmış. Sonra onları sandbox'ta bir ilk test çağrısına yönlendirin; basit bir endpoint (ör. "GET /status") ve bir gerçek endpoint içersin.

Başarılı testten sonra partner üretim erişimi talep eder; bir ek soru sorulur: "Ne zaman canlıya geçiyorsunuz?" Onaylandıktan sonra bir üretim anahtarı verin ve destek yolunu net gösterin: ticket'ta neler olmalı (istek ID'si ve zaman damgası) ve kullanım ile hataları nerede görebilecekleri.

Portal ekranları (küçük tutun)

Partner portalı partnerlerin dört soruya çabuk cevap bulabildiği zaman en iyi şekilde çalışır: Anahtarım ne? Neye erişebiliyorum? Ne kadar kullanabilirim? Şu an çalışıyor mu?

Gün 1 için birkaç ekran yeterlidir:

• Genel Bakış: durum (pending, active, suspended, revoked) ve güncel ortam.
• API Anahtarları: anahtar etiketi, oluşturulma tarihi, son döndürme tarihi (oluşturmadan sonra gizli değer gösterilmez).
• Erişim (Scope'lar): anahtarın neler yapabildiğinin düz dilde özeti.
• Kullanım ve Kota: bugünün çağrıları, mevcut limitler ve limite gelince ne olacağı.
• Dokümantasyon ve Örnekler: bir hızlı başlangıç ve birkaç kopyala-yapıştır istek.

Durum modelini sıkı tutun. "Pending" var ama üretimi çağıramaz. "Active" üretimin açık olduğu anlamına gelir. "Suspended" geçici durdurma (fatura veya kötüye kullanım). "Revoked" kalıcıdır ve tüm anahtarları geçersiz kılar.

Self-serve işlemler destek yükünü azaltabilir ama kontrolü elden bırakmaz. Partnerlerin bir anahtarı döndürmesine, ekstra scope talep etmesine ve daha yüksek kota istemesine izin verin; ancak bu talepleri onay kuyruğuna yönlendirin ki hiçbir şey sessizce değişmesin.

Güvenlik ve destek sorunlarına yol açan yaygın hatalar

Çoğu partner API portalı basit nedenlerle başarısız olur: erken kısa yollar hızlı hissettirir, sonra sonsuz destek taleplerine dönüşür.

Birden fazla partner arasında paylaşılan tek bir API anahtarı (veya çoklu uygulamalar için aynı anahtar) klasik hatadır. Birisi onu kötüye kullandığında, kimin ne yaptığını söyleyemezsiniz ve bir partnerin erişimini iptal etmek herkesin erişimini bozabilir. Partner başına ayrı anahtar, tercihen uygulama başına anahtar kullanın.

Scope'lar da hızla yanlış gidebilir. Tek bir "full_access" scope'u kolay görünür ama her entegrasyona eşit şekilde güvenmenizi zorunlu kılar ve partnerleri tedirgin eder. Scope'ları eylemlere (read, write, admin) ve belirli kaynaklara göre bağlayın.

Yanlışlıkla üretimde test etmek

Sandbox ortamı atlamak iki tür acıya neden olur: güvenlik riski ve karmaşık veri. Partnerler uç vaka testleri yapacaktır. Sadece üretime erişim sağlarsanız sahte müşteriler, bozuk iş akışları ve temizlik istekleri ile karşılaşırsınız.

Basit bir kural yardımcı olur: sandbox anahtarları asla üretim verilerine erişemez ve üretim anahtarları sandbox'a erişemez.

Rastgele başarısızlık gibi görünen kotalar

Hız limitleri sorun değil, ama belirsiz hatalar tekrarlı yeniden denemelere ve daha fazla yüke yol açar. Her limit hatasının aynı soruları yanıtladığından emin olun: ne oldu, ne zaman tekrar denenebilir, mevcut kullanım nereden görülebilir, nasıl yüksek limit istenir ve yanlış görünüyorsa kimle iletişime geçilir.

Anahtar döndürmeyi baştan planlayın. Uzun ömürlü anahtarlar ekran görüntüleri, loglar veya eski dizüstü bilgisayarlarda sızar. Döndürme rutin olsun, kriz değil.

İlk partner davet etmeden önce hızlı kontrol listesi

İlk daveti göndermeden önce partner bakış açısından son bir kontrol yapın. Küçük kontroller iki yaygın sonucu önler: aşırı izin verme ve kafa karıştıran erişim sorunları.

• Partnerin kim olduğunu kaydedin (tüzel kişilik, teknik kontakt ve kimliğin nasıl doğrulandığı).
• UI ve dokümanda sandbox'ı belirgin yapın ve güvenli test etmeyi kolaylaştırın.
• Üretim erişimini ayrı bir karar ve açık bir onay adımı olarak bırakın.
• Scope'ları yüksek sesle tekrar kontrol edin. Bir scope geniş ("full access") veya belirsiz ("general") görünüyorsa bölün veya yeniden adlandırın.
• Kotaları belirleyin ve hata yolunu prova edin (hata yanıtı, yeniden deneme zamanlaması, destek görünürlüğü).

Pratik bir test yapın: sahte bir partner hesabı oluşturun ve uçtan uca akışı baştan sona deneyin. Ardından "break glass" eylemlerini en az bir kez test edin: bir anahtarı döndürün, eskiyi iptal edin ve partnerin hemen engellendiğini doğrulayın.

Örnek: gerçek bir partneri bir saatten kısa sürede onboard etmek

Orta ölçekli bir lojistik partneri, NorthShip, iki şeye ihtiyaç duyar: dispatch paneli için salt-okunur sevkiyat durumu ve sevkiyat değiştiğinde bildirim almak için bir webhook.

Scope setini küçük ve okunabilir tutun. Örnek:

• shipments:read (sevkiyat detaylarını ve durumunu al)
• shipments:events:read (en son takip olaylarını al)
• webhooks:manage (webhook uç noktasını oluştur, güncelle ve devre dışı bırak)
• partner:profile:read (hata ayıklama için partner hesap bilgisini görüntüle)

Kotalar için normal kullanımı cezalandırmadan koruyan makul tahminlerle başlayın. İlk hafta için 60 istek/dakika ve 50.000 istek/gün, ayrıca yanlışlıkla döngüleri önlemek için webhook kayıtları için ayrı bir üst sınır belirleyebilirsiniz.

Bir hafta sonra gerçek verilere göre ayarlayın. Eğer ortalama 8 istek/dakika ve vardiya değişiminde kısa sıçramalar görüyorsanız dakikalık limiti yükseltin ama günlük sınırı koruyun. Sürekli polling görürseniz cache ve webhook kullanımını teşvik edin.

Gerçekçi bir sorun: gösterge paneli her dispatch için 2 saniyede bir poll yaptığı için 2. gün hız limitine takılmak. Loglarınız çok sayıda 429 gösteriyor. Çözüm: onlardan sonuçları 15–30 saniye cache'lemelerini ve değişiklikler için webhooks'a güvenmelerini isteyin. Trafik stabilize olduğunda dakikalık limiti hafifçe artırın ve izlemeye devam edin.

Sonraki adımlar: inşa et, bir partner ile test et, sonra genişlet

İlk versiyonu bir pilot gibi ele alın. Basit bir portal, temel işleri temizce yapan aşırı özellikli ama kafa karıştıran bir portaldan daha iyidir.

Bir partnerin uçtan uca başarılı olmasını sağlayan en küçük ekran ve kurallar setiyle başlayın: erişim talebi, onay, anahtar alma ve ilk başarılı API çağrısını yapma. Diğer her şey, gerçekten destek taleplerinde gördüğünüz bir problemi çözdüğünde yerini kazansın.

Yönetilebilir bir inşa sırası genellikle şöyledir:

• Partnerleri, uygulamaları, API anahtarlarını, scope'ları ve statüleri (requested, approved, suspended) modele dökün.
• Net sahibi ve kriterleri olan bir onay adımı ekleyin.
• Anahtar verme ve döndürmeyi otomatikleştirin, her değişikliği (kim, ne zaman, neden) loglayın.
• "Daha fazla erişim gerek" anları için bir scope talep akışı ekleyin.
• Gerçek kullanım verilerini gördükten sonra kotaları ekleyin.

Eğer kodsuz inşa ediyorsanız, AppMaster veriyi modellemenize, hem dahili hem partner tarafı UI'lerini oluşturmanıza ve görsel araçlarla anahtar ve scope kurallarını uygulamanıza yardımcı olabilir. İleride self-host seçeneğini korumak isterseniz, AppMaster (appmaster.io) ayrıca ihtiyaç duyduğunuzda üretilmiş kaynak kodu dışa aktarabilir.