eSIM API Kontrol Listesi (2026): Bir Seyahat eSIM API'sinde Olması Gereken 12 Özellik — ve Her Biri Nasıl Test Edilir

Bir eSIM API'sini uygulamanıza, seyahat platformunuza veya rezervasyon motorunuza bağlamak zor değildir. Zor olan, lansmandan sonra API'nin zaman aşımı durumunda mükerrer ücret aldığını, bir müşterinin verisinin ne zaman bittiğini size söyleyemediğini veya hataları test etmeniz için size hiçbir yol sunmadığını fark etmektir.

Bu kontrol listesi, üretime dahil olan 12 önemli özelliği ve her biri için kayıt olmadan önce nasıl test edileceğini kapsamaktadır. Örnek olarak TripoSIM Partner API'sini kullanıyoruz, ancak herhangi bir sağlayıcıyı karşılaştırmak için aynı kontrol listesini kullanabilirsiniz.

1. Güvenli token kimlik doğrulaması

Neye bakmalı: OAuth 2.0 client credentials: bir client ID ve secret'ı kısa süreli bir access token ile değiştirirsiniz. Secret bilgiler asla her istekte taşınmaz.

Nasıl test edilir: bir token talep edin, ardından süresinin dolup dolmadığını kontrol edin. TripoSIM API'sinde, POST /auth/token 15 dakika boyunca geçerli olan bir access token döndürür. Kodunuzun, süresi dolmadan önce bunu otomatik olarak yenilediğinden emin olun.

2. Idempotency anahtarları (mükerrer ödemelere hayır)

Neye bakmalı: her sipariş ve yükleme (top-up) üzerinde bir Idempotency-Key başlığı. Eğer isteğiniz zaman aşımına uğrarsa ve aynı anahtarla tekrar denerseniz, API ikinci bir ücretli eSIM oluşturmak yerine orijinal sonucu döndürmelidir.

Nasıl test edilir: aynı anahtarla aynı siparişi iki kez gönderin ve tek bir sipariş aldığınızı onaylayın. Ardından aynı anahtarı farklı bir gövde (body) ile gönderin — iyi bir API bunu reddeder. TripoSIM, üretim siparişlerinde ve yüklemelerinde anahtar gerektirir ve bir anahtar farklı bir istekle yeniden kullanılırsa 409 IDEMPOTENCY_KEY_REUSED döndürür.

3. Fiyatı sabitleyen fiyat teklifleri

Neye bakmalı: bir fiyatı çekme ve onu kısa bir süre tutma yolu; böylece müşteriniz tam olarak gösterdiğiniz tutarı öder.

Nasıl test edilir: bir teklif oluşturun, bekleyin, ardından bu teklifle sipariş verin. TripoSIM teklifleri 10 dakika boyunca geçerlidir; süresi dolan bir teklif 409 QUOTE_EXPIRED döndürür, böylece sürpriz bir fiyat tahsil etmek yerine yeniden teklif verebilirsiniz.

4. Temiz bir katalog akışı

Neye bakmalı: fiyat, veri, geçerlilik süresi, kapsama ülkeleri, 5G, yükleme desteği — ve sınırsız planlar için günlük tam hız sınırını listeleyen tek bir uç nokta (endpoint).

Nasıl test edilir: bir ülke için kataloğu çekin ve sağlayıcının kendi web sitesiyle karşılaştırın. TripoSIM /catalog uç noktası JSON veya CSV döndürür, ülkeyi kapsayan bölgesel planları içerir ve sınırsız planlar için adil kullanım alanlarını (fup_daily_mb, fup_throttle_kbps) ekler. [Sınırsız günlük limitlerin nasıl çalıştığını](/blog/unlimited-esim-daily-limit-by-country-2026) görün.

5. Anında sipariş ve QR teslimatı

Neye bakmalı: sipariş yanıtı (veya birkaç saniye sonra gelen bir webhook), bir QR kodu veya tek dokunuşla kurulum bağlantısı gösterebilmeniz için standart LPA formatındaki aktivasyon kodunu içermelidir; örneğin LPA:1$smdp.example.com$ACTIVATION_CODE.

Nasıl test edilir: bir sandbox siparişi verin, LPA dizesinden QR oluşturun ve formatın geçerli olup olmadığını kontrol etmek için bir telefon kamerasıyla tarayın.

6. Her olay için imzalı webhooks

Neye bakmalı: tüm eSIM yaşam döngüsü için saldırganların sahtesini yapamayacağı şekilde imzalanmış anlık bildirimler (push notifications).

TripoSIM sekiz olay türü gönderir: order.completed, order.failed, esim.activated, esim.usage_80, esim.suspended, esim.resumed, esim.depleted ve esim.expired. Her istek, imzalama secret'ınızı kullanarak zaman damgası ve ham gövdenin bir HMAC-SHA256'sı olan bir X-TripoSIM-Signature başlığı taşır:

<pre><code>// reject requests older than 5 minutes (replay protection) if (Math.floor(Date.now() / 1000) - parseInt(timestamp) &gt; 300) throw new Error('Webhook too old'); const expected = crypto .createHmac('sha256', signingSecret) .update(timestamp + '.' + rawBody) .digest('hex'); if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) { throw new Error('Invalid webhook signature'); }</code></pre>

Nasıl test edilir: bir webhook kaydedin, bir sipariş tetikleyin ve imzanın kodunuzdaki doğruluğunu teyit edin. Ardından gövdenin bir baytını değiştirin ve kontrolünüzün bunu reddettiğinden emin olun.

7. Tüm eSIM yaşamını simüle eden bir sandbox

Neye bakmalı: gerçek eSIM'lerin etkinleşmesi ve veri kullanması günler sürer. İyi bir sandbox süreci hızlandırmanıza olanak tanır.

Nasıl test edilir: TripoSIM sandbox ortamında, activate, usage, deplete, expire veya reset eylemleriyle POST /sandbox/esims/{iccid}/simulate komutunu kullanın. Her adım ilgili webhook'u tetikler, böylece "veriniz bitmek üzere" e-postanızı günler yerine dakikalar içinde test edebilirsiniz.

8. Hata simülasyonu

Neye bakmalı: uygulamanızın bunları nasıl yönettiğini bilmek için hataları bilerek zorlamanın bir yolu.

Nasıl test edilir: insufficient_balance, price_changed, rate_limit, provider_unavailable veya timeout gibi modlara sahip X-Sandbox-Simulate başlığını gönderin ve uygulamanızın net bir mesaj gösterip göstermediğini ve yalnızca gerektiğinde tekrar deneyip denemediğini kontrol edin.

9. Aynı eSIM üzerinde yüklemeler (top-ups)

Neye bakmalı: verisi biten müşteriler yeni bir eSIM kurmadan daha fazla veri ekleyebilmelidir.

Nasıl test edilir: sandbox ortamında (bir idempotency anahtarı ile) POST /esims/{iccid}/topup komutunu çağırın, ardından yeni veri bakiyesini kontrol edin. Ayrıca hangi planların yüklemeleri desteklediğini kontrol edin — katalog size bunu söylemelidir.

10. Kullanım ve durum verileri

Neye bakmalı: destek ekibinizin ve uygulamanızın "ne kadar verim kaldı?" sorusuna yanıt verebilmesi için kullanılan veri, kalan veri ve son kullanma tarihi için bir uç nokta.

Nasıl test edilir: simüle edilmiş bir kullanım olayından sonra GET /esims/{iccid}/usage komutunu çağırın. TripoSIM kullanımı 5 dakika boyunca önbelleğe alır, bu nedenle gerçek zamanlı uyarılar için webhooks (esim.usage_80, esim.depleted) kullanın.

11. Askıya alma ve devam ettirme

Neye bakmalı: bir eSIM'i duraklatma yolu — örneğin bir ödeme itiraz edildiğinde veya bir müşteri kayıp telefon bildirdiğinde — ve daha sonra devam ettirme.

Nasıl test edilir: bir sandbox eSIM'ini askıya alın, esim.suspended webhook'unun geldiğini onaylayın, ardından devam ettirin ve esim.resumed onayını alın.

12. Net hız limitleri, hata kodları ve bir değişiklik günlüğü (changelog)

Neye bakmalı: belgelenmiş limitler, size tekrar denemeniz gerekip gerekmediğini söyleyen hata kodları ve güncellemelerin sizi asla şaşırtmaması için halka açık bir değişiklik günlüğü.

Nasıl test edilir: hata listesini okuyun ve her kodu kodunuzda "tekrar dene" veya "tekrar deneme" olarak eşleştirin. TripoSIM, ortak hesap başına dakikada 120 isteğe izin verir (bireysel API anahtarları için daha düşük limitler belirleyebilirsiniz), 429 yanıtlarında bir Retry-After başlığı döndürür, her hata kodunu tekrar denenebilir veya denenemez olarak işaretler ve bir changelog uç noktası yayınlar.

Basit bir lansman planı

1. 1. Gün: sandbox anahtarlarını alın, kimlik doğrulayın, kataloğu çekin.
2. 2. Gün: idempotency anahtarlarıyla sandbox siparişleri verin ve QR kodlarını gösterin.
3. 3. Gün: webhooks ekleyin, yaşam döngüsü ve hata simülatörlerini çalıştırın.
4. 4. Gün: yüklemeleri ve kullanımı ekleyin, ardından gerçek bir telefonda bir canlı eSIM ile test edin.
5. 5. Gün: canlıya geçin.

Çoğu ekip bir haftadan kısa sürede bağlantıyı kurar. Tam [API dokümantasyonunu](https://docs.triposim.com) okuyun veya adım adım [eSIM API entegrasyon kılavuzumuza](/blog/esim-reseller-api-how-to-integrate-travel-esim-sales-into-your-platform) göz atın.

Sıkça sorulan sorular

Bir seyahat eSIM API'si neleri içermelidir?

En azından: token kimlik doğrulaması, idempotency anahtarları, fiyat teklifleri, bir katalog akışı, anında QR/aktivasyon kodları, imzalı webhooks, yaşam döngüsü ve hata simülatörlerine sahip bir sandbox, yüklemeler, kullanım verileri, askıya alma/devam ettirme ve belgelenmiş hız limitleri ile hata kodları.

Idempotency anahtarları bir eSIM API'si için neden önemlidir?

Her eSIM siparişi gerçek para maliyetine sahiptir. Eğer bir istek zaman aşımına uğrarsa ve sisteminiz tekrar denerse, bir idempotency anahtarı, tekrar denemenin ikinci bir eSIM satın almak yerine ilk sonucu döndürmesini sağlar.

eSIM satın almadan bir eSIM API'sini nasıl test ederim?

Sandbox'ı kullanın. İyi bir sandbox; siparişleri, aktivasyonu, veri kullanımını, tükenmeyi ve sürenin dolmasını simüle eder — ve cüzdanınızdan ücret almadan hataları zorlamanıza olanak tanır.

Bir eSIM API entegrasyonu ne kadar sürer?

İyi belgelenmiş bir API ve tam bir sandbox ile çoğu ekip 3–5 iş günü içinde canlıya geçer.

TripoSIM API'si white-label teslimatını destekliyor mu?

Evet. Aktivasyon kodunu ve QR verilerini alırsınız, böylece eSIM'i kendi uygulamanızda veya e-postalarınızda kendi markanız altında sunabilirsiniz. [API programına](/api-program) göz atın.

Özetle

Fiyat önemlidir, ancak bir eSIM API'si için asıl fark lansmandan sonra ortaya çıkar: asla mükerrer ücret almayan denemeler, güvenebileceğiniz webhooks ve her şeyi önce test etmenize olanak tanıyan bir sandbox. Herhangi bir sağlayıcıya bağlılık sözü vermeden önce bu kontrol listesini uygulayın — ve TripoSIM Partner API'sinin nasıl puanlandığını görmek için [sandbox'ımızla başlayın](/api-program).