Geliştirici ve Ajan Dokümantasyonu

eSIM paket kataloğumuz — ülkeler, kapsamlar ve fiyatlar — herkese açıktır. API anahtarı, kayıt ya da token gerekmez. Bu sayfa insanlar için; makineler için hazırlanmış sürüm openapi.json dosyasındadır.

Hızlı başlangıç

Temel adres https://esim.tc. Bütün uçlar GET ve hepsi anonim.

curl https://esim.tc/api/countries

curl "https://esim.tc/api/country/products/yunanistan?page=1&size=5"

İlk çağrı ülkeleri paket sayılarıyla verir, ikincisi Yunanistan'da geçerli paketleri fiyata göre sıralar. Ülkeyi UUID yerine sayfa adresindeki Türkçe slug ile de çağırabilirsiniz — yunanistan, japonya, abd gibi.

Uçlar

Parametrelerin tamamı ve alan açıklamaları için OpenAPI tanımına bakın.

Yanıt zarfı

Her yanıt aynı zarfla gelir; asıl veri data alanındadır.

{ "success": true, "statusCode": 200, "message": "İstek başarıyla gerçekleşti.", "data": ... }

Hata davranışı

Burada dikkatli olun: kayıt bulunamadığında da HTTP 400 döner, 404 değil. Hata türünü ayırt etmek için HTTP durum koduna değil success ve message alanlarına bakın. Mesajlar Türkçedir.

Fiyatlar ve birimler

price alanı Türk Lirası (TRY) cinsinden ve KDV dahildir. quota alanı quotaType ile birlikte okunur, validDays ise paketin ilk aktivasyondan sonraki geçerlilik süresidir. Ülke kodları ISO 3166-1 alpha-2 ve küçük harftir (gr, jp, us).

Bilmeniz gereken üç davranış

Bunlar API'nin gerçek davranışı; sürpriz olmasın diye yazıyoruz.

Paket listeleri tekilleştirilmiştir. Ülke ve bölge listelerinde aynı (kota, gün) kombinasyonundan yalnızca en ucuz paket döner. Yani tek bir ülke için beş sağlayıcının 5 GB / 30 günlük paketini görmezsiniz, en ucuzunu görürsünüz. Gizlenen alternatifler için sameplans ucunu kullanın — ama dikkat, o uç aynı kota/günü değil aynı destinasyonu kapsayan paketleri döndürür, eşleştirmeyi kendiniz yapmanız gerekir.

Liste uçlarında bazı alanlar boş gelir. name, providerName ve isActive yalnızca tekil paket ucunda (/api/product/{uId}) doludur. Listede isActive alanı false görünse de listeler zaten yalnızca aktif paketleri içerir.

productCount alanına dikkat. Tekil ülke ucunda her zaman 0'dır — ülke paket sayıları için /api/countries yanıtını kullanın. Bölge uçlarında ise hem listede hem tekilde her zaman 0'dır; bölgedeki paket sayısı için /api/region/products/{slug} yanıtındaki itemCount alanına bakın.

Hız sınırı

IP başına 60 saniyede 300 istek. Aşarsanız 429 Too Many Requests ve Retry-After başlığı alırsınız.

Bu eşik normal kullanımı kısıtlamak için değil, kaçak döngüleri durdurmak için var. Karşılaştırma olsun diye: sitenin kendi arayüzünde soğuk bir paket sayfası yüklemesi 4 istek, bir filtre değişimi 1 istek. En hırslı insan kullanıcı bile dakikada 30 isteği zor geçiyor.

Yine de birkaç ricamız var:

• Ülke ve bölge listelerini en az bir saat önbelleğe alın. /api/regions yanıtının neredeyse tamamı base64 gömülü bölge ikonlarıdır.
• /api/countries sunucu tarafında 10 dakika önbelleklenir; sık çağırmak size daha taze veri getirmez.

Kimlik doğrulama

Katalog uçlarının hiçbiri kimlik doğrulaması istemez. Sipariş, cüzdan ve profil uçları JWT ister ve bunlar bilerek belgelenmez — kararlı bir sözleşme olarak sunulmuyorlar. Ajanların programatik olarak hesap açabileceği ya da kimlik bilgisi alabileceği bir uç yok.

Gerekçesiyle birlikte tam açıklama: auth.md

Ajanlar için keşif dosyaları

Ayrıca her sayfanın markdown sürümü var: yolun sonuna .md ekleyin ya da Accept: text/markdown başlığı gönderin.

İletişim

Kataloğu ticari bir üründe kullanmak, bir entegrasyon konuşmak ya da bir hata bildirmek isterseniz [email protected] adresine yazın.