2026'da eSIM API Entegrasyonu: Geliştiricilerin İnşa Etmeden Önce Bilmesi Gerekenler

Bir ürüne eSIM işlevselliği eklemek kulağa basit geliyor - ta ki bir sprintin üç haftasına girip RSP standartlarının, operatör tarafı aktivasyon akışlarının ve QR kod teslimat hatlarının her birinin kendi hata modlarına sahip olduğunu fark edene kadar. Bu rehber, 2026'da entegrasyon kodu yazmaya başlamadan önce gerçekten bilmeniz gerekenleri kapsar.

eSIM API Entegrasyonunun Gerçek Anlamı #

Bu terim gevşek bir şekilde kullanılıyor. Pratikte, kim olduğunuz ve ne inşa ettiğinize bağlı olarak birkaç farklı sorunu kapsar:

• Bir seyahat uygulaması kullanıcıların uygulamadan çıkmadan veri planı satın alabilmesi için eSIM satın almayı entegre ediyor
• Bir bayi veya bağlı platform sağlayıcının kataloğuna bağlanarak planları gösteriyor, satın alımları yönetiyor ve aktivasyon kodlarını teslim ediyor
• Bir cihaz üreticisi veya MDM satıcısı bir filo genelinde eSIM profillerini programlı olarak yönetiyor
• Bir telekom operatörü sıfırdan SM-DP+ (Abonelik Yöneticisi Veri Hazırlama) altyapısı inşa ediyor

Bunlar çok farklı zorluklar. İlk ikisi, 2026'da ürün şirketlerindeki geliştiriciler için en yaygın kullanım durumlarıdır ve bu makale de bu konulara odaklanıyor - ilgili olduklarında daha alt düzey standartlar hakkında notlarla.

Göz Ardı Edemeyeceğiniz Standartlar Katmanı #

GSMA RSP Mimarisi #

GSMA'nın Uzaktan SIM Sağlama (RSP) spesifikasyonu, her şeyin üzerine oturduğu teknik temeldir. Mevcut tüketici profil standardı SGP.22'dir (M2M için SGP.02 kullanılır, ancak akıllı telefonlar için inşa ediyorsanız, SGP.22 önemlidir). Bu, eSIM profillerinin bir cihaza nasıl indirildiğini, yüklendiğini, etkinleştirildiğini ve silindiğini tanımlar.

Çoğu entegrasyon senaryosunda SGP.22'yi kendiniz uygulamanız gerekmeyecek. Ancak bunun mimariniz için ne anlama geldiğini anlamak önemlidir:

• Aktivasyon kodları tanımlı bir formatı takip eder: LPA:1$<SM-DP+ adresi>$<eşleşen ID>
• Profil indirmeleri cihazın Yerel Profil Asistanı (LPA) tarafından başlatılır, sunucunuz tarafından değil
• API'nizin görevi genellikle profili SM-DP+ sunucusunda sağlamak ve aktivasyon kodunu kullanıcıya geri döndürmektir

Bu ayrım önemlidir çünkü hataların aslında nerede meydana geleceğini size söyler. Başarısız bir indirme neredeyse hiçbir zaman API çağrınızın başarısız olması değildir - genellikle bir cihaz uyumluluk sorunu, LPA el sıkışması sırasında bir ağ kesintisi veya zaten tüketilmiş bir profildir.

QR Kod vs. Anında Aktivasyon #

Çoğu tüketici eSIM API'si, kullanıcının ikinci bir cihazdan taradığı veya ekran görüntüsü aldığı bir aktivasyon QR kodu sunar. Bazı sağlayıcılar ayrıca, kullanıcı aynı cihazda ise profilin otomatik olarak yüklendiği "anında" veya "doğrudan yükleme" akışlarını destekler. Doğrudan yükleme daha temiz bir kullanıcı deneyimi sunar, ancak daha dar cihaz desteği ve daha sıkı işletim sistemi sürüm gereksinimleri vardır. Geniş bir cihaz tabanını hedefliyorsanız, QR kodu teslimatını birincil yolunuz olarak ve doğrudan yüklemeyi aşamalı bir iyileştirme olarak ele alın.

Bir API Sağlayıcısı Seçmek #

Eğer operatör altyapısı inşa etmiyorsanız, ürününüz ile altta yatan SM-DP+ sunucuları arasında yer alan bir eSIM API sağlayıcısıyla entegre oluyorsunuz. Bu sağlayıcı, operatör ilişkilerini, profil sağlama işlemlerini ve genellikle bayi kataloğunu yönetir.

Taahhüt etmeden önce değerlendirmeniz gerekenler:

Kapsama ve Plan Kataloğu #

Sağlayıcı kaç ülkeyi kapsıyor? Tek ülke, bölgesel ve küresel planlar sunuyorlar mı? Katalog genişliği, kullanıcılara sunabileceğiniz şeyleri doğrudan etkiler. 200'den fazla ülke ve bölgeyi kapsayan bir sağlayıcı, birden fazla entegrasyonu bir araya getirmeden anlamlı bir küresel erişim sağlar.

Fiyatlandırma Yapısı ve Marjlar #

Sağlayıcının API erişimini nasıl fiyatlandırdığını anlayın. Bazıları plan maliyetlerinin üzerine aktivasyon başına ücret alır; diğerleri marj dahil toptan fiyatlar sunar. Eğer bir bayi ürünü inşa ediyorsanız, marjınız tamamen bu yapıya bağlıdır. Sağlayıcının yayınladığı perakende fiyatları ile API üzerinden sunduklarını karşılaştırarak nerede durduğunuzu anlayın.

Aktivasyon Kodu Teslimatı #

API, aktivasyon QR kodunu senkron mu yoksa bir webhook ile asenkron mu döndürüyor? Sağlayıcının profili operatörün SM-DP+ sunucusunda sağlamak zorunda olduğu durumlarda asenkron teslimat yaygındır - ve kullanıcı deneyiminiz bunu hesaba katmalıdır. Bir QR kodu için 30 saniye bekleyen bir kullanıcı net bir yükleme durumu gerektirir; 5 dakika bekleyen biri ise bir e-posta yedeği gerektirir.

Sandbox ve Test Ortamı #

Entegre olmaya değer herhangi bir sağlayıcının bir sandbox'ı vardır. Gerçekçi test aktivasyon kodları döndürdüğünü, webhook yüklerinin üretim formatıyla tam olarak eşleştiğini ve hata kodlarının belgelenmiş olduğunu doğrulayın. Üretimde "plan tükendi" hatasının 4xx yerine bir hata gövdesiyle 200 döndürdüğünü keşfetmek haftanızı mahveder.

Webhooklar ve Durum Güncellemeleri #

eSIM aktivasyonu anlık değildir. Şunlar için webhooklara ihtiyacınız var:

• Profil sağlama tamamlandı (aktivasyon kodu hazır)
• Profil cihaz tarafından indirildi
• Veri kullanımı eşikleri (sağlayıcı bunları sunuyorsa)
• Plan süresi dolma tarihi

Bir sağlayıcı yalnızca anketlemeyi destekliyor ve web kancaları sunmuyorsa, bu basit bir tek seferlik satın alma akışının ötesinde bir şey için kırmızı bayraktır.

Tasarım Etrafında Çekirdek API Akışları #

Plan Keşfi #

Entegrasyonunuz genellikle bir katalog uç noktasıyla başlar: Ülke veya bölgeye göre mevcut planları alın, plan detaylarını döndürün (veri miktarı, geçerlilik, fiyat, ağ kapsama alanı) ve kullanıcının seçmesine izin verin. Bunu agresif bir şekilde önbelleğe alın. Katalog verileri dakika dakika değişmez ve her sayfa yüklemesinde bir katalog uç noktasını zorlamak gereksizdir - ve bu sizi hız sınırına takar.

Satın Alma ve Sağlama #

Satın alma akışı genellikle şöyle görünür:

1. Kullanıcı bir plan seçer
2. Arka ucunuz, plan kimliği ve kullanıcı referansı ile sağlayıcının sipariş/satın alma uç noktasını çağırır
3. Sağlayıcı bir sipariş kimliği döndürür ve sağlama işlemine başlar
4. Aktivasyon kodu hazır olduğunda web kancası tetiklenir (veya sağlayıcı destekliyorsa yanıt eşzamanlıdır)
5. Arka ucunuz aktivasyon kodunu saklar ve kullanıcıya iletir

Aktivasyon kodunu istemci tarafı bir API çağrısında asla açığa çıkarmayın. Kod tek kullanımlıktır. Sızarsa, plan kaybolur.

Aktivasyon Kodu Teslimatı #

QR kodunu işlenmiş bir resim olarak teslim edin - sağlayıcı genellikle size ya bir base64 PNG ya da kendinizin işlediği ham bir aktivasyon dizesi verir. QR kodunun yanında manuel giriş dizesini her zaman ekleyin. Bazı kullanıcılar etkinleştirmeye çalıştıkları cihazda olacak ve kendi ekranlarını tarayamayacaklar.

Hata Yönetimi #

En sık karşılaşacağınız hata modları:

• Cihaz uyumsuz: Kullanıcının cihazı eSIM'i desteklemiyor veya profil sınırına ulaşmış. Bunu net bir şekilde belirtin - genel bir hata göstermeyin.
• Plan mevcut değil: Stok veya taşıyıcı tarafında bir kullanılabilirlik sorunu. Alternatifler sunun.
• Aktivasyon kodu zaten kullanılmış: Kullanıcı iki kez yüklemeye çalıştı. Yeniden teslimatı nazikçe yönetin, bu genellikle sağlayıcının destek API'si ile iletişime geçmek veya manuel inceleme için işaretlemek anlamına gelir.
• LPA indirme sırasında ağ hatası: Bu cihazda, entegrasyonunuzda değil. Kullanıcıya kararlı bir bağlantıda tekrar denemesini söyleyin.

Cihaz Uyumluluk Dikkatleri #

API entegrasyonunuz kusursuz olabilir ve yine de cihaz nedeniyle başarısız olabilir. Satın almadan önce iletilmesi gereken önemli uyumluluk noktaları:

• Cihaz eSIM uyumlu olmalıdır (tüm bütçe Android telefonlar değildir)
• Cihaz operatör kilitsiz olmalıdır
• iOS cihazlar temel eSIM için iOS 12.1 veya daha yenisine ihtiyaç duyar; desteklenen modellerde çift eSIM için iOS 16+ gereklidir
• Çoğu cihaz, üreticiye bağlı olarak 5 ile 20 arasında bir yerde saklanan eSIM profillerini sınırlar
• Çin anakarasında satın alınan cihazlar, modelden bağımsız olarak genellikle donanım seviyesinde eSIM devre dışı bırakılmıştır

Satın alma akışınıza bir cihaz kontrolü veya uyumluluk SSS'si ekleyin. Uyumsuz cihazlardan kaynaklanan satın alma sonrası destek taleplerini azaltmak, UX yatırımına değer.

Güvenlik Dikkatleri #

Tartışmasız birkaç uygulama:

Aktivasyon kodlarını sunucu tarafında saklayın. Yalnızca kimliği doğrulanmış kullanıcılara geri döndürün. Erişimi kaydedin.

Webhook imzalarını doğrulayın. Her güvenilir sağlayıcı webhook yüklerini imzalar. İşleme başlamadan önce imzayı doğrulayın - doğrulanmamış bir webhook uç noktası, sahte sipariş tamamlamaları için kolay bir saldırı vektörüdür.

Satın alma uç noktalarınızı hız sınırlayın. eSIM planları, gerçek maliyeti olan dijital ürünlerdir. Hız sınırlaması olmadan, kimlik bilgisi doldurma saldırısı veya hatalı bir istemci yeniden deneme döngüsü hızlı bir şekilde gerçek ücretler oluşturabilir.

Aktivasyon kodlarını düz metin olarak kaydetmeyin. Onları ödeme jetonları gibi ele alın.

Bir Bayi veya Ortak Entegrasyonu Oluşturma #

Bir karşılaştırma sitesi, seyahat uygulaması veya gömülü eSIM mağazası yerine birinci taraf bir ürün oluşturuyorsanız, entegrasyon modeli değişir. Genellikle bir sağlayıcının satın alma akışını gömüyorsunuz veya kendi markanız altında planları göstermek için beyaz etiketli bir API kullanıyorsunuz.

Gibi platformlar Roamify geliştiricilerin ve ortakların tam sağlama yığını oluşturmadan eSIM plan erişimini gömmesine olanak tanıyan bir ortaklık ve bayi programı yürütmektedir (partner.getroamify.com adresinde). Katalog, 200'den fazla ülke ve bölgeyi kapsar ve planlar 2 dolardan başlar - bu, fiyat duyarlı bir karşılaştırma ürünü oluştururken ve kullanıcılara göstermek için rekabetçi bir taban gerektiğinde önemlidir.

Bu tür bir entegrasyon için teknik kapsamınız daha dardır: katalog görüntüleme, derin bağlantılar veya gömülü ödeme ve atıf. Sağlama karmaşıklığı sağlayıcıda kalır. Takas, satın alma kullanıcı deneyimi ve marj yapısı üzerinde daha az kontrol sağlamaktır.

Göndermeden Önce Test Etme #

Başlatmadan önce gözden geçirilmeye değer bir kontrol listesi:

• Gerçek bir planı sanal ortamda satın alın ve uçtan uca aktivasyon kodu teslimatını doğrulayın
• Webhook teslimatını, üretime bağlamadan önce ngrok gibi bir araç veya bir webhook test hizmeti ile test edin
• Başarısız bir satın alma simüle edin (hata tetikleyen bir test planı kimliği kullanın) ve hata kullanıcı arayüzünüzü doğrulayın
• Gerçek eSIM uyumlu cihazlarla hem iOS hem de Android'de test yapın
• Zaten teslim edilmiş bir aktivasyon kodunu yeniden talep etmenin aynı kodu döndürdüğünü, yeni bir kod olmadığını doğrulayın
• Aktivasyon kodu görüntülemenizin küçük ekranlarda çalıştığını doğrulayın - eSIM satın alımlarının %64'ü mobilde gerçekleşiyor
• QR kodunuzun gerçekten taranabilir bir boyutta (minimum 200×200px, ideal olarak daha büyük) oluşturulduğunu kontrol edin

SSS #

Bir eSIM API'si ile bir eSIM pazaryeri arasındaki fark nedir?
Bir eSIM API'si, eSIM plan satın alma ve sağlama işlemlerini kendi ürününüze entegre etmek için programatik bir arayüzdür. Bir eSIM pazaryeri ise tüketiciye yönelik bir vitrin. Bazı sağlayıcılar her ikisini de sunar: doğrudan tüketiciler için bir perakende vitrini ve aynı envanteri gömmek isteyen geliştiriciler için bir API veya bayi programı.

eSIM işlevselliği oluşturmak için doğrudan taşıyıcılarla çalışmam gerekiyor mu?
Çoğu ürün kullanım durumu için hayır. eSIM API sağlayıcıları taşıyıcı ilişkilerini ve SM-DP+ altyapısını yönetir - siz onların API'si ile entegre olursunuz ve onlar sağlama katmanını yönetir. Doğrudan taşıyıcı entegrasyonu, yalnızca kendi MVNO'nuzu oluşturuyorsanız veya kurumsal cihaz filoları için eSIM profillerini ölçekli olarak yönetiyorsanız gereklidir.

Kullanıcıların aktivasyon QR kodunu kaybetmeleri durumunda nasıl bir yol izlemeliyim?
Aktivasyon kodunu sunucu tarafında, kullanıcının hesabına ve sipariş kimliğine bağlı olarak saklayın ve kimliği doğrulanmış kullanıcıların bunu almasına izin verin. Çoğu sağlayıcı, aynı aktivasyon kodunun birden çok kez görüntülenmesine izin verir; izin vermedikleri şey, profili birden fazla kez yüklemek için kullanılmasıdır.

Başarılı bir satın alma işleminden sonra bir eSIM aktivasyonunun başarısız olmasına ne sebep olur?
En yaygın nedenler: cihazın eSIM uyumlu olmaması veya taşıyıcı kilitli olması, cihaz profil depolama alanının dolu olması, kullanıcının QR kodunu etkinleştirilen aynı cihazda taramaya çalışması (ikinci bir cihaz veya manuel giriş gerektirir) veya LPA indirme sırasında ağ kesintisi. Bunlar cihaz tarafı sorunlardır, API hataları değildir.

Küresel olarak çalışan bir eSIM entegrasyonu oluşturabilir miyim?
Evet, sağlayıcınız yeterli ülke kapsamına sahipse. 200'den fazla ülke ve bölgeyi kapsayan sağlayıcılar arayın. Kapsama kalitesinin değişken olduğunu unutmayın - bir plan teknik olarak bir destinasyon için mevcut olabilir ancak zayıf kırsal kapsama sahip tek bir yerel taşıyıcıya dayanabilir. Kullanıcılarınız keşfedilmemiş yerlere seyahat ediyorsa, destinasyon başına ağ ortağı ayrıntılarını kontrol edin.

2026'da eSIM API entegrasyonu önceki yıllara göre önemli ölçüde farklı mı?
GSMA SGP.22 standardı istikrarlı kaldı, ancak sağlayıcı API'leri önemli ölçüde olgunlaştı. Webhook güvenilirliği, sanal ortamlar ve dokümantasyon kalitesi birkaç yıl öncesine göre anlamlı derecede daha iyi. Doğrudan yükleme akışları daha fazla cihaz modeline genişledi, ancak QR kodu teslimi en evrensel uyumlu yaklaşım olmaya devam ediyor.

Birinci taraf bir ürün yerine bir bayi entegrasyonu oluşturuyorsam neye öncelik vermeliyim?
Katalog tazeliğine, fiyat doğruluğuna ve atıf takibine odaklanın. Sağlama karmaşıklığı sağlayıcı tarafından yönetilir. Farklılığınız, belirli bir destinasyon için doğru planı ne kadar iyi sunduğunuzdan, uyumluluk gereksinimlerini ne kadar net ilettiğinizden ve fiyatlandırmanızın alternatiflere göre ne kadar rekabetçi göründüğünden gelir.

Nereden Başlamalı #

Çalışan bir entegrasyona en hızlı yol, temiz bir API'ye, gerçek bir sanal ortama ve kullanıcılarınızın destinasyonlarını kapsayan bir kataloğa sahip bir sağlayıcı seçmektir. Herhangi bir kullanıcı arayüzü oluşturmadan önce satın alma-aktivasyon akışının tamamını kendiniz test edin. Cihaz uyumluluğu kenar durumları ve asenkron sağlama desenleri, çoğu entegrasyonun takıldığı yerlerdir - ve bunları üretimde değil, testte bulmak istersiniz.

Bayi veya beyaz etiket yolunu değerlendiriyorsanız, Roamify doğrudan sağlama altyapısını yönetmeden eSIM erişimini gömmek isteyen geliştiriciler için bakmaya değer bir ortaklık programı sunar.