Optifora API nasıl çalışır
Bu sayfa API'nin kalıbını anlatır: kimliğin nasıl doğrulandığını, sürümlerin nasıl ilerlediğini, isteğin hangi sınırlar içinde kaldığını, hatanın hangi biçimde döndüğünü ve verinin dışarıyla nasıl alışverişe girdiğini.
Ürün geliştirme aşamasındadır ve API yüzeyi tamamlanıyor. Uçların referans belgesi ayrı yayımlanacaktır; bu sayfada adres ve örnek çağrı yer almaz, yalnız işleyiş anlatılır.
Kimlik doğrulama
Her istek ya bir kişiye ya da kayıtlı bir uygulamaya aittir. Kimliksiz bir istek korumalı bir uca ulaştığında yetkisiz yanıtıyla döner.
- Taşıyıcı jetonErişim jetonu isteğin yetkilendirme başlığında taşınır. Jeton imzalıdır ve yalnız isteğin kime ait olduğunu söyler.
- Kısa ömürErişim jetonu dakikalarla ölçülen bir sürenin sonunda geçersizleşir; süre dağıtım ayarıdır ve varsayılanı otuz dakikadır.
- Yenileme ve döndürmeOturum yenileme jetonuyla uzatılır ve her uzatmada yeni bir jeton çifti verilir. Kullanılmış bir yenileme jetonu ikinci kez gelirse o kişinin bütün oturumları iptal edilir.
- Yetki jetonda taşınmazJeton yalnız kimliği taşır; kişinin neyi görebileceği her istekte veri tabanına sorulur. Böylece geri alınan bir yetki, elindeki jetonun süresi dolmadan da geçerliliğini yitirir.
- Entegratör anahtarıKayıtlı bir uygulama kendi anahtarıyla bağlanır. Anahtarın açık değeri yalnız üretildiği anda gösterilir; saklanan şey özeti ve anahtarı tanımaya yarayan gizli olmayan ön ekidir.
- İzni işletme verirBir uygulama ne kadar yaygın olursa olsun, işletmenin verdiği izin kaydı yoksa tek satır veri görmez. İzin tarihlidir, kapsamlıdır ve geri alınabilir.
Sürümleme
- Sürüm yolda dururUçlar sürüm ön ekiyle yayımlanır; bugünkü yüzey birinci sürümdür.
- Kırıcı değişiklik yeni yol açarVar olan bir ucun sözleşmesi yerinde bozulmaz. Uyumsuz bir değişiklik yeni sürüm yolunda yayımlanır, eskisi çalışmaya devam eder.
- Belge kendi sürümünü bildirirReferans belge üretildiği sürüm numarasını içinde taşır; hangi sürüme baktığınız belgenin kendisinden okunur.
Ortamlar ve sınırlar
Referans belgede iki ortam ilan edilir: üretim ve yerel geliştirme. Kök adres, anahtarla birlikte entegratöre verilir; bu sayfada yayımlanmaz.
- Canlılık ve hazır olma ayrı ölçülürBir uç sürecin ayakta olduğunu söyler; ikincisi veri tabanına gerçek bir sorgu gönderip erişilebildiğini doğrular. Trafiğin yönlendirilip yönlendirilmeyeceğine ikincisi karar verir.
- Tarayıcı kaynağı listeyle sınırlıdırÇapraz kaynaklı istekler yalnız önceden ilan edilmiş kaynaklardan kabul edilir; liste boşken tarayıcıdan gelen çapraz istek reddedilir.
- Gövde sınırıBir isteğin gövdesi beş megabaytı aşamaz. Büyük kümeler tek istekle değil, kendi durum kaydı olan toplu aktarım işiyle taşınır.
- Sır günlüğe yazılmazSunucu günlüğünde yetkilendirme başlığı, çerez, parola ve kimlik numarası tutulmaz.
Hız sınırı
Sınır adres başına ve dakikalıktır. Varsayılan dakikada 120 istektir ve dağıtım ayarıyla değiştirilir. Kalan hak her yanıtta başlıklarla bildirilir.
| Yanıt başlığı | Ne söyler |
|---|---|
| x-ratelimit-limit | Pencere içinde tanınan toplam istek hakkı. |
| x-ratelimit-remaining | Bu pencerede kalan hak. |
| x-ratelimit-reset | Hakkın yenilenmesine kalan saniye. |
| retry-after | Kaç saniye sonra yeniden denenebileceği. Yalnız sınır aşıldığında dönen yanıtta bulunur. |
Sınır aşılınca istek reddedilir ve yanıt, ne kadar beklenmesi gerektiğini saniye olarak söyler. Yeniden deneme, beklemeden değil süre dolduktan sonra yapılır.
Hata biçimi
Her hata aynı zarfla döner: makinenin dallanacağı kısa bir kod alanı ve insanın okuyacağı bir açıklama alanı.
- errorİstemcinin karar vereceği kısa kod.
- messageNe olduğunu anlatan açıklama.
| Durum | Kod alanı | Ne demek |
|---|---|---|
| 400 | Bad Request | İstek şemaya uymuyor. Açıklama hangi alanın eksik ya da geçersiz olduğunu söyler. |
| 401 | unauthenticated | Geçerli bir kimlik yok: jeton hiç gönderilmedi, süresi doldu ya da doğrulanmadı. |
| 404 | Not Found | Böyle bir uç ya da böyle bir kayıt yok. |
| 429 | Too Many Requests | Hız sınırı aşıldı; yanıt ne kadar beklenmesi gerektiğini bildirir. |
| 5xx | internal_error | Beklenmeyen hata. Ayrıntı istemciye verilmez, sunucu günlüğüne yazılır. |
Sayfalama
Liste dönen uçlar aynı iki parametreyi alır ve aynı sayaçları döndürür. Böylece sayfalayan istemci her uçta yeniden yazılmaz.
- limitBir sayfada kaç kayıt isteniyor. En az bir, en çok iki yüz; belirtilmezse elli.
- offsetKaç kaydın atlanacağı. Sıfırdan başlar.
- totalSüzgeçlere uyan toplam kayıt sayısı.
- countBu yanıtta gerçekten dönen kayıt sayısı.
Yanıt, kullanılan limit ve offset değerlerini de geri verir; istemci kendi konumunu tahmin etmez, yanıttan okur.
Veri alışverişi ve webhook
Alışveriş kipi bir ayardır, ayrı bir ürün değil: kayıtlı her uygulama hangi kiple çalıştığını kendi kaydında taşır.
| Kip | Ne demek |
|---|---|
| Tek yönlü — dışarı | Optifora veri yayımlar; karşı taraf okur ya da olaya abone olur. |
| Tek yönlü — içeri | Karşı taraf veri basar; Optifora doğrular ve yazar. |
| Çift yönlü | İki taraf da yazar; çakışma kuralı önceden tanımlıdır. |
| El sıkışmalı | Her aktarım bir oturum açar: teklif, doğrulama, onay, transfer ve makbuz. Makbuz iki tarafta da kalır. |
- Olay dışarı itilirWebhook, kayıtlı uygulamanın bildirdiği geri çağırma adresine olayı gönderir. Teslim edilemeyen olay kuyrukta kalır ve yeniden denenir; sessizce düşmez.
- Aynı istek iki kez yazmazYazma isteği bir tekillik anahtarı taşır. Aynı anahtarla gelen ikinci istek yeni kayıt oluşturmaz.
- Her çağrı ölçülürKim, ne zaman, hangi kapsamla ve hangi sonuçla çağırdı — hepsi kaydedilir. Aynı kayıt hem hata ayıklamanın hem de bu veriyi kimin çektiği sorusunun tek kaynağıdır.
- Kendi uygulamalarımız da aynı kapıdan geçerAyrıcalıklı ikinci bir yol açılmaz. Kendi entegrasyonumuz, dışarıdan bağlanan bir geliştiricinin karşılaştığı yüzeyin kanıtıdır.
Alışveriş katmanının veri modeli kuruldu; uçları henüz yayımlanmadı. Yayımlandığında bu bölüm, referans belgedeki karşılıklarına bağlanacaktır.
Referans dokümanlar
Referans elle yazılmaz; uçların şemasından üretilir. Bir uç şemasını devrettikçe belgedeki karşılığı kendiliğinden dolar, böylece belge ile davranış birbirinden ayrışmaz.
- Bugünkü durum: hazırlanıyorŞemalar modül modül taşınıyor. Belge yayıma alınmadan önce her ucun isteği ve yanıtı belgede görünür olacaktır.
- İki biçim yayımlanacakMakine okunur bir OpenAPI belgesi ve aynı belgeden çizilen, tarayıcıda gezilebilen bir referans sayfası.
- Erişim kademelidirGenel bakış herkese açıktır. Tam referans, kayıtlı entegratöre verilen bir belge anahtarının arkasında durabilir; üretim anahtarları ve geri çağırma adresleri ise doküman konusu değil, uygulama kaydının konusudur.
- Adres standardıİki referans yayımlanır ve adresleri sabittir: client-api.optifora.com/docs dışa açıktır, admin-api.optifora.com/docs yetki ister ve dışa kapalıdır. Bugün ikisi de yayında değildir; yayına alındığında bağlantıları bu bölüme eklenir.
Entegrasyon planınız bugünden belliyse iletişim sayfasından yazın: yüzey yayına açıldığında ilk haber verilenler arasında olursunuz.
Somut bir talebiniz mi var?
Bu sayfalar destek sürecinin nasıl işlediğini anlatır. Bir talebiniz ya da sorunuz varsa iletişim sayfasından bize yazın.
İletişim sayfasına gidin