İş ortağı yüzeyine başlarken

İki kademeli kimlik

Bu yüzeyin taban yolu /api/partner/v1'dir ve yukarıdaki /api/v1 sözleşmesinin dışındadır. Her istek iki kimliği birlikte taşır; tek istisna, hesap anahtarının henüz var olmadığı üç uçtur: POST /accounts, POST /connections ve GET /connections/{id}. O istisna adıyla kayıtlıdır (DEC-271, DEC-277 ile genişletilmiş hâliyle; aşağıda kendi bölümlerinde). Üçü de yalnız X-App-Key ister, çünkü hesap anahtarı bu akışların çıktısıdır, girdisi olamaz.

Vaat şudur: iki sırdan biri sızdığında sistem açılmaz. Sızan bir hesap anahtarı iş ortağı kimliği olmadan hiçbir şey yapamaz; sızan bir uygulama anahtarı tek başına hiçbir hesaba ulaşamaz.

Hesap anahtarı partner-api yeteneği taşır ve bu bilerek public-apiden ayrıdır: o anahtar tek başına /api/v1e giremez, dolayısıyla iki kademe atlanamaz. Cookie oturumu bu yüzeye giremez: /api/v1deki birinci taraf ayrıcalığı buraya taşınmaz.

Başlangıç sırası

Entegrasyonun ilk adımı hangisidir sorusunun tek cevabı budur. Sıra keyfî değildir: POST /accounts bir onay beyanı ister ve o beyanın çapası olan content_sha256 yalnız GET /legal-documents'ten gelir; o uç ise iki kademelidir, yani henüz sahip olunmayan bir hesap anahtarı ister. Kamuya açık ikiz GET /api/legal-documents bu alanı taşımaz ve bu bilinçlidir (DEC-282): özet, kabul beyanının çapasıdır ve beyanın olmadığı bir yüzeyde hiçbir ihtiyacı karşılamaz. Dolayısıyla ilk hesap anahtarı bağlanma akışından gelir:

2. adımdaki üye iş ortağının kendi Sevkora hesabı olabilir; entegrasyonu kurarken en pratik yol budur.

OLAY ABONELİKLERİ BU SIRANIN HİÇBİR YERİNE BAĞLI DEĞİLDİR (PA-50..PA-54)

POST /event-subscriptions yalnız X-App-Key ister, yani 1. adımdan hemen sonra kurulabilir. Bu bir kolaylık değil, DEC-359'un satın aldığı şeydir: abonelik iki kademeli olsaydı ancak 4. adımdan sonra kurulabilirdi ve 2-4. adımlarda düşen bir akışın account.creation_failed olayı hiçbir zaman duyulmazdı. Entegrasyona başlarken önerilen sıra, topup.succeeded, topup.failed ve account.creation_failed aboneliklerini 1. adımın hemen ardından kurmaktır.

Hesap anahtarı onaya kadar ölüdür

6. adımdan sonra dönen account_key ile, hesap sahibi kendisine giden e-postadaki bağlantıdan parolasını belirleyene kadar yapılan her istek 403 + partner_account_pending_activation döner. Anahtar canlanmıyorsa bakılacak ilk yer postacıdır: açılış e-postası gitmese de POST /accounts yine 201 döner (geçici bir SMTP arızası hesap açılışını kilitlememelidir). Yani 201, e-postanın ulaştığının kanıtı değildir.

Hata sınıfları: ne sızar, ne sızmaz

401 ailesinin dört nedeni de tek bir gövdeye düşer ve ayırt edilemez: aksi hâlde uç bir anahtar keşif aracına dönerdi. 403 ayrışır çünkü operasyonel olarak gereklidir; meşru iş ortağı askıya alındığını bilmelidir, köken uyuşmazlığı ise bir saldırı göstergesidir ve denetim izine yazılır.

İki yüzeyde birden yayımlanan yollar

Aşağıdaki yollar her iki yüzeyde de yayımdadır ve aynı denetleyiciye bağlıdır (DEC-345, DEC-351: kopyalama değil montaj). Gövde alanları, doğrulama kuralları ve durum geçişleri bu yüzden aynıdır; iş ortağı yüzeyi için ikinci bir iş mantığı yazılmadı. Ayrılan şeyler kimliğin kendisinden gelir ve üç başlıkta toplanır:

Hangi kimlik

/api/v1 tek kademelidir: istek yalnız Authorization: Bearer <anahtar> taşır ve o anahtar bir kullanıcıya, kullanıcı bir tenant'a bağlıdır. /api/partner/v1 iki kademelidir: X-App-Key (hangi iş ortağı) ile Authorization: Bearer (hangi hesap adına) birlikte sunulur. Hesap anahtarı partner-api yeteneği taşır ve tek başına /api/v1e giremez; public-api yetenekli bir v1 anahtarı da iş ortağı yüzeyine giremez. Kapı iki yönde de kapalıdır.

Hangi kapsam

İki yüzeyde de kayıtlar tek bir tenant'a kapatılır, ama tenant'ı seçen şey farklıdır: /api/v1de anahtarın sahibi olan kullanıcının tenant'ı, iş ortağı yüzeyinde hesap anahtarının bağlı olduğu hesabın tenant'ı. İş ortağı kendi verisini değil, adına çalıştığı hesabın verisini okur ve yazar. Kapsam iş ortağı başına değil hesap başına çizilir: aynı iş ortağının iki hesabı birbirinin kaydına ulaşamaz. Taşıyıcı hesabı yazma uçlarında (PA-61..PA-64) bu kapsam bir de yön taşır: iş ortağı hesabın taşıyıcı kimliğini adına yazar, ama hiçbir yüzey o kimliği geri okutmaz; denetim satırı hesap sahibinin üyesine yazılır ve bildirim hesabın tüm üyelerine gider.

Hangi hata dalları

İş ortağı yüzeyinde v1'de karşılığı olmayan ret dalları vardır: uygulama anahtarı yok, tanınmıyor, iptal edilmiş ya da süresi dolmuş (401; bu nedenler tek gövdeye düşer ve ayırt edilemez), iş ortağı askıda (403), hesap anahtarının kökeni sunulan uygulama anahtarıyla eşleşmiyor (403), hesap sahibi parolasını henüz belirlemedi (403). Oran limitinin sayacı da başkadır: /api/v1de anahtar başına, iş ortağı yüzeyinde hesap anahtarı başına. Tek istisna kendi-hesap doğrulama ucudur (PA-59 ve PA-63): onun sayacı iki yüzeyde de hesap sahibi üye ve taşıyıcı hesabı başınadır, çünkü koruduğu şey taşıyıcıya karşı yapılan kimlik denemesidir. Bir yolun v1 tarafındaki doğrulama ve iş kuralı hataları (422 ve ailesi) ise aynen geçerlidir, çünkü onları üreten denetleyici aynıdır.

Çift yayımlanan yolların tamamı aşağıdadır. Tablo mekanik olarak bağlıdır: bir yol bu kılavuzda iki yüzeyde birden yayımlandığı hâlde buraya yazılmazsa, ya da burada yazılıp bir yüzeyden kalkarsa, iki yüzeyin uç kümesini tabloyla karşılaştıran sözleşme testi kırmızıya döner.

Kapsamı adıyla yazılıdır: o karşılaştırma bu kılavuzun kendi uç sayfalarından türetilir, canlı rota tablosundan değil. Bir yol iki yüzeyde de çalıştığı hâlde v1 uç sayfası bu kılavuzda yazılmamışsa çift hiç oluşmaz, tablo onu istemez ve sözleşme testi boş küme üzerinde yeşil döner. Bu yüzden tablonun tamlığı ikinci bir ölçüyle, karşılaştırmanın bir ucunu CANLI rota tablosundan okuyan .specforge/evidence/TASK-481/yuzey.py ile bağlanır; bugün iki ölçü de sapmasızdır. Bilinen tek örnek GET /user/credit'ti: uç iki yüzeyde de yayımdaydı, iş ortağı ikizi PA-28 yazılıydı, v1 sayfası yoktu ve kapı bunu göremiyordu. Sayfa TASK-482'de yazıldı (PA-65) ve satır aşağıdadır.

Tabloda olmayan bir iş ortağı ucu, kural olarak v1'de karşılığı bulunmayan ve yalnız bu yüzeyde yaşayan bir uçtur: kimlik kurulumu, hukuki metin sürümleri, hesap açma, bağlanma akışı, hesap profili ve bakiye yükleme. Onlar bu bölümün kendi sözleşmesidir ve v1'de aranmamalıdır.