2026-cı ildə eSIM API inteqrasiyası: tərtibatçılar hazırlamağa başlamazdan əvvəl nələri bilməlidirlər

Məhsula eSIM funksionallığı əlavə etmək sadə görünür. Ancaq sprintin başlanmasından üç həftə keçəndə RSP standartlarının, operator tərəfindəki aktivləşdirmə proseslərinin və QR kodun çatdırılma zəncirlərinin hər birinin özünəməxsus nasazlıq ssenariləri olduğunu anlayırsınız. Bu təlimat 2026-cı ildə bir sətir belə inteqrasiya kodu yazmazdan əvvəl həqiqətən bilməli olduğunuz məsələləri əhatə edir.

eSIM API inteqrasiyası əslində nə deməkdir #

Bu termin dəqiq məna ilə işlədilmir. Praktikada kim olduğunuzdan və nə hazırladığınızdan asılı olaraq, bir neçə fərqli məsələni əhatə edir:

• İstifadəçilərin tətbiqdən çıxmadan internet paketi ala bilməsi üçün eSIM satınalma funksiyasını özünə inteqrasiya edən səyahət tətbiqi
• Paketləri göstərmək, satınalmaları emal etmək və aktivləşdirmə kodlarını çatdırmaq üçün provayderin kataloquna qoşulan reseller və ya referal tərəfdaşlıq platforması
• Cihazlar parkında eSIM profillərini proqram vasitəsilə idarə edən cihaz istehsalçısı və ya MDM təchizatçısı
• SM-DP+ (abunəlik meneceri, verilənlərin hazırlanması) infrastrukturunu sıfırdan quran telekommunikasiya operatoru

Bunlar bir-birindən çox fərqli məsələlərdir. İlk ikisi 2026-cı ildə məhsul hazırlayan şirkətlərdə çalışan tərtibatçılar üçün ən çox rast gəlinən istifadə ssenariləridir və bu məqalə məhz onlara yönəlir. Müvafiq yerlərdə daha aşağı səviyyəli standartlar barədə qeydlər də verilir.

Nəzərə almaya bilməyəcəyiniz standartlar səviyyəsi #

GSMA RSP arxitekturası #

GSMA-nın SIM-in uzaqdan hazırlanması (RSP) spesifikasiyası bütün digər komponentlərin əsaslandığı texniki təməldir. Hazırda istehlakçı profilləri üçün standart SGP.22-dir (M2M üçün SGP.02 istifadə olunur, lakin smartfonlar üçün məhsul hazırlayırsınızsa, əhəmiyyətli olan SGP.22-dir). Bu standart eSIM profillərinin cihazda necə endirildiyini, quraşdırıldığını, aktiv edildiyini və silindiyini müəyyənləşdirir.

Əksər inteqrasiya ssenarilərində SGP.22 standartını özünüz tətbiq etməyinizə ehtiyac olmayacaq. Lakin onun arxitekturanız üçün nə ifadə etdiyini anlamaq vacibdir:

• Aktivləşdirmə kodları müəyyən edilmiş formata uyğun olur: LPA:1$<SM-DP+ address>$<matching ID>
• Profilin endirilməsini sizin serveriniz deyil, cihazın yerli profil köməkçisi (LPA) başladır
• API-nizin vəzifəsi adətən SM-DP+ serverində profili təmin etmək və aktivləşdirmə kodunu istifadəçiyə qaytarmaqdır

Bu ayrım vacibdir, çünki xətaların əslində harada baş verəcəyini göstərir. Uğursuz endirmə demək olar ki, heç vaxt API sorğunuzun uğursuzluğu deyil. Bu, adətən cihaz uyğunluğu problemi, LPA ilə ilkin bağlantının qurulması zamanı şəbəkə kəsilməsi və ya artıq istifadə edilmiş profillə bağlı olur.

QR kodla və push üsulu ilə aktivləşdirmənin müqayisəsi #

İstehlakçılar üçün nəzərdə tutulan eSIM API-lərinin əksəriyyəti istifadəçinin ikinci cihazdan və ya ekran görüntülərindən skan etdiyi aktivləşdirmə QR kodunu çatdırır. Bəzi provayderlər həmçinin istifadəçi eyni cihazdan istifadə edirsə, profilin avtomatik quraşdırıldığı «push» və ya «birbaşa quraşdırma» proseslərini də dəstəkləyir. Birbaşa quraşdırma daha rahat istifadəçi təcrübəsi təqdim edir, lakin daha az cihazı dəstəkləyir və əməliyyat sistemi versiyasına dair daha sərt tələblərə malikdir. Geniş cihaz bazasını hədəfləyirsinizsə, QR kodun çatdırılmasını əsas üsul, birbaşa quraşdırmanı isə mərhələli təkmilləşdirmə kimi qəbul edin.

API provayderinin seçilməsi #

Operator infrastrukturu qurmursunuzsa, məhsulunuzla arxa plandakı SM-DP+ serverləri arasında vasitəçi olan eSIM API provayderi ilə inteqrasiya edirsiniz. Həmin provayder operatorlarla əlaqələri, profillərin təmin edilməsini və çox vaxt reseller kataloqunu idarə edir.

Öhdəlik götürməzdən əvvəl bunları qiymətləndirin:

Əhatə dairəsi və paket kataloqu #

Provayder neçə ölkəni əhatə edir? Ayrı-ayrı ölkələr üçün, regional və qlobal paketlər təklif edirmi? Kataloqun genişliyi istifadəçilərə nə təqdim edə biləcəyinizə birbaşa təsir göstərir. 200+ ölkə və regionu əhatə edən provayder bir neçə inteqrasiyanı birləşdirməyə ehtiyac olmadan sizə geniş qlobal əhatə imkanı verir.

Qiymət strukturu və mənfəət marjaları #

Provayderin API-yə çıxış üçün qiyməti necə müəyyənləşdirdiyini anlayın. Bəziləri paket qiymətindən əlavə hər aktivləşdirmə üçün ödəniş alır; digərləri isə mənfəət marjası nəzərə alınmış topdansatış qiymətləri təklif edir. Təkrar satış məhsulu hazırlayırsınızsa, mənfəət marjanız tamamilə bu strukturdan asılıdır. Öz mövqeyinizi anlamaq üçün provayderin dərc etdiyi pərakəndə satış qiymətlərini API vasitəsilə təklif etdiyi qiymətlərlə müqayisə edin.

Aktivasiya kodunun çatdırılması #

API aktivasiya QR kodunu sinxron qaytarır, yoxsa webhook vasitəsilə asinxron çatdırır? Provayder kodu yaratmazdan əvvəl profili operatorun SM-DP+ serverində hazırlamalı olduqda asinxron çatdırılma geniş yayılmış üsuldur və istifadəçi təcrübəniz bunu nəzərə almalıdır. Paketi alıb QR kodunu 30 saniyə gözləyən istifadəçiyə aydın yüklənmə göstəricisi lazımdır; 5 dəqiqə gözləyən istifadəçi üçün isə ehtiyat variant olaraq e-poçtla çatdırılma təmin edilməlidir.

İzolyasiya olunmuş sınaq mühiti və test mühiti #

İnteqrasiyaya dəyər hər bir provayderin izolyasiya olunmuş sınaq mühiti var. Onun real kodlara bənzəyən test aktivləşdirmə kodları qaytardığını, webhook vasitəsilə göndərilən məzmunun işlək mühitdəki formata tam uyğun olduğunu və xəta kodlarının sənədləşdirildiyini yoxlayın. İşlək mühitdə «paket tükənib» xətasının 4xx əvəzinə xəta məzmunu ilə 200 qaytardığını aşkar etmək bütün həftənizi korlayacaq.

Webhook-lar və status yeniləmələri #

eSIM aktivasiyası dərhal baş vermir. Aşağıdakılar üçün webhook-lar lazımdır:

• Profilin hazırlanması tamamlanıb (aktivasiya kodu hazırdır)
• Profil cihaz tərəfindən endirilib
• Mobil internet istifadəsi hədləri (provayder onları təqdim edirsə)
• Paketin müddətinin bitməsi

Provayder yalnız vaxtaşırı sorğulamanı dəstəkləyirsə və webhook-lar təklif etmirsə, bu, sadə birdəfəlik satınalma prosesindən daha mürəkkəb hər bir proses üçün xəbərdarlıq əlamətidir.

Dizaynın əsasını təşkil etməli olan əsas API prosesləri #

Paketlərin axtarışı #

İnteqrasiyanız adətən kataloq son nöqtəsi ilə başlayır: ölkə və ya region üzrə mövcud paketləri əldə edin, paket təfərrüatlarını (internet trafikinin həcmi, etibarlılıq müddəti, qiymət, şəbəkə əhatəsi) qaytarın və istifadəçiyə seçim imkanı verin. Bunları mümkün qədər keşdə saxlayın. Kataloqdakı məzmun dəqiqə-dəqiqə dəyişmir və hər səhifə yüklənəndə kataloq son nöqtəsinə təkrar-təkrar sorğu göndərmək lazımsızdır, üstəlik, sorğu tezliyi limitinə məruz qalmağınıza səbəb olacaq.

Satınalma və profilin təmin edilməsi #

Satınalma prosesi adətən belə olur:

1. İstifadəçi paket seçir
2. Server tərəfiniz paket ID-si və istifadəçi istinadı ilə provayderin sifariş/satınalma son nöqtəsinə sorğu göndərir
3. Provayder sifariş ID-si qaytarır və profilin hazırlanmasına başlayır
4. Aktivasiya kodu hazır olduqda webhook işə düşür (yaxud provayder dəstəkləyirsə, cavab sinxron verilir)
5. Server tərəfiniz aktivasiya kodunu saxlayır və istifadəçiyə çatdırır

Aktivasiya kodunu heç vaxt müştəri tərəfindəki API çağırışında açıq göstərməyin. Kod birdəfəlikdir. Sızarsa, paket əldən çıxır.

Aktivasiya kodunun çatdırılması #

QR kodunu yaradılmış şəkil kimi çatdırın: provayder adətən sizə ya base64 PNG, ya da şəklə özünüz çevirdiyiniz xam aktivasiya sətri verir. QR kodu ilə yanaşı həmişə əl ilə daxil etmək üçün sətri də təqdim edin. Bəzi istifadəçilər aktivləşdirməyə çalışdıqları cihazdan istifadə edəcək və öz ekranlarını skan edə bilməyəcəklər.

Xətaların idarə edilməsi #

Ən çox qarşılaşacağınız uğursuzluq halları:

• Cihaz uyğun deyil: İstifadəçinin cihazı eSIM-i dəstəkləmir və ya profil limitinə çatıb. Bunu aydın göstərin, ümumi xəta göstərməyin.
• Paket mövcud deyil: Paket ehtiyatı və ya operator tərəfində mövcudluqla bağlı problem var. Alternativlər təklif edin.
• Aktivasiya kodu artıq istifadə olunub: İstifadəçi iki dəfə quraşdırmağa çalışıb. Təkrar çatdırılmanı problemsiz idarə edin; bu, adətən provayderin dəstək API-si ilə əlaqə saxlamaq və ya əl ilə yoxlama üçün işarələmək deməkdir.
• LPA vasitəsilə endirmə zamanı şəbəkə xətası: Bu problem inteqrasiyanızda deyil, cihazdadır. İstifadəçiyə sabit bağlantı ilə yenidən cəhd etməsini bildirin.

Cihaz uyğunluğu ilə bağlı məqamlar #

API inteqrasiyanız qüsursuz olsa da, cihaz səbəbindən uğursuz ola bilər. Satınalmadan əvvəl bildirilməli əsas uyğunluq məqamları:

• Cihaz eSIM-i dəstəkləməlidir (bütün büdcə Android telefonları bunu dəstəkləmir)
• Cihazın operator kilidi açıq olmalıdır
• iOS cihazlarında əsas eSIM funksiyası üçün iOS 12.1 və ya daha yeni versiya, dəstəklənən modellərdə iki eSIM üçün isə iOS 16+ tələb olunur
• Əksər cihazlarda saxlanılan eSIM profillərinin sayı istehsalçıdan asılı olaraq 5 ilə 20 arasında məhdudlaşdırılır
• Çinin materik hissəsində alınmış cihazlarda modelindən asılı olmayaraq eSIM çox vaxt aparat səviyyəsində deaktiv olur

Satınalma prosesinizə cihaz yoxlaması və ya uyğunluq barədə tez-tez verilən suallar bölməsi əlavə edin. Uyğun olmayan cihazlar səbəbindən satınalmadan sonra yaranan dəstək müraciətlərini azaltmaq istifadəçi təcrübəsinə qoyulan sərmayəyə dəyər.

Təhlükəsizliklə bağlı məqamlar #

Güzəştə gedilməməli bir neçə iş üsulu:

Aktivasiya kodlarını server tərəfində saxlayın. Onları yalnız autentifikasiyadan keçmiş istifadəçilərə qaytarın. Girişləri jurnalda qeydə alın.

Webhook imzalarını yoxlayın. Hər bir etibarlı provayder webhook vasitəsilə göndərilən məzmunu imzalayır. Emal etməzdən əvvəl imzanı yoxlayın: yoxlanılmayan webhook son nöqtəsi sifarişləri saxtakarlıqla tamamlanmış kimi göstərmək üçün asan hücum yoludur.

Satınalma son nöqtələrinizdə sorğu tezliyini məhdudlaşdırın. eSIM paketləri real xərci olan rəqəmsal məhsuldur. Sorğu tezliyi məhdudiyyəti olmadan giriş məlumatlarının kütləvi sınağı hücumu və ya xətalı müştəri tətbiqindəki təkrar cəhd dövrü sürətlə real ödənişlər yarada bilər.

Aktivasiya kodlarını jurnalda açıq mətn kimi qeydə almayın. Onlara ödəniş tokenləri kimi yanaşın.

Reseller və ya tərəfdaş inteqrasiyasının qurulması #

Öz məhsulunuz əvəzinə müqayisə saytı, səyahət tətbiqi və ya daxilə yerləşdirilmiş eSIM mağazası qurursunuzsa, inteqrasiya modeli dəyişir. Adətən provayderin satınalma prosesini daxil edirsiniz və ya paketləri öz brendiniz altında təqdim etmək üçün öz brendinizlə istifadəyə imkan verən API-dən istifadə edirsiniz.

Roamify kimi platformalar tərtibatçılara və referal tərəfdaşlara profillərin təmin edilməsi üçün bütün texniki infrastrukturu özləri qurmadan eSIM paketlərinə çıxışı məhsullarına daxil etməyə imkan verən tərəfdaşlıq və reseller proqramı (partner.getroamify.com ünvanında) həyata keçirir. Kataloq $2 qiymətindən başlayan paketlərlə 200+ ölkə və regionu əhatə edir. Qiymətə həssas müqayisə məhsulu qurduğunuz və istifadəçilərə göstərmək üçün rəqabətqabiliyyətli minimum qiymətə ehtiyacınız olduğu zaman bu vacibdir.

Bu inteqrasiya növündə texniki işinizin əhatəsi daha dardır: kataloqun göstərilməsi, dərin keçidlər və ya daxilə yerləşdirilmiş ödəniş prosesi və nəticələrin mənbələr üzrə izlənib aid edilməsi. Profillərin təmin edilməsi ilə bağlı mürəkkəb işlər provayderin üzərinə düşür. Bunun əvəzində satınalma zamanı istifadəçi təcrübəsi və mənfəət marjasının strukturu üzərində nəzarətiniz daha az olur.

İstifadəyə verməzdən əvvəl testlər #

İstifadəyə verməzdən əvvəl nəzərdən keçirməyə dəyər yoxlama siyahısı:

• Sınaq mühitində real paket alın və aktivasiya kodunun çatdırılmasını əvvəldən sona qədər təsdiqləyin
• İşlək mühitə qoşmazdan əvvəl ngrok kimi bir alət və ya webhook test xidməti ilə webhook çatdırılmasını yoxlayın
• Uğursuz satınalmanı simulyasiya edin (xətaya səbəb olan test paketinin ID-sindən istifadə edin) və xəta göstərən istifadəçi interfeysinizi yoxlayın
• eSIM-i dəstəkləyən real cihazlarla həm iOS, həm də Android üzərində test edin
• Artıq çatdırılmış aktivasiya kodu təkrar tələb edildikdə yeni kodun deyil, eyni kodun qaytarıldığını təsdiqləyin
• Aktivasiya kodunun göstərilməsinin kiçik ekranlarda işlədiyini yoxlayın: eSIM satınalmalarının 64% hissəsi mobil cihazlarda baş verir
• QR kodunuzun həqiqətən skan edilə bilən ölçüdə göstərildiyini yoxlayın (minimum 200×200px, ideal halda daha böyük)

Tez-tez verilən suallar #

eSIM API-si ilə eSIM satış platforması arasındakı fərq nədir?
eSIM API-si eSIM paketlərinin satın alınmasını və profillərin hazırlanmasını öz məhsulunuza inteqrasiya etmək üçün proqram interfeysidir. eSIM satış platforması isə istehlakçılara xidmət edən mağazadır. Bəzi provayderlər hər ikisini təklif edir: birbaşa istehlakçılar üçün pərakəndə mağaza və eyni məhsul çeşidini öz məhsullarına daxil etmək istəyən tərtibatçılar üçün API və ya reseller proqramı.

eSIM funksionallığını qurmaq üçün operatorlarla birbaşa işləməliyəm?
Məhsulların əksər istifadə ssenariləri üçün buna ehtiyac yoxdur. eSIM API provayderləri operatorlarla əlaqələri və SM-DP+ infrastrukturunu idarə edir: siz onların API-si ilə inteqrasiya edirsiniz, onlar isə profillərin hazırlanması qatını idarə edirlər. Operatorla birbaşa inteqrasiya yalnız öz MVNO-nuzu qurursunuzsa və ya müəssisələrin cihaz parkları üçün eSIM profillərini geniş miqyasda idarə edirsinizsə zəruridir.

Aktivləşdirmə QR kodunu itirən istifadəçilərə necə kömək edə bilərəm?
Aktivləşdirmə kodunu istifadəçinin hesabı və sifariş ID-si ilə əlaqələndirərək server tərəfində saxlayın və autentifikasiyadan keçmiş istifadəçilərə onu yenidən əldə etmək imkanı verin. Əksər provayderlər eyni aktivləşdirmə kodunun bir neçə dəfə göstərilməsinə icazə verir; icazə vermədikləri isə həmin koddan profili bir dəfədən çox quraşdırmaq üçün istifadə etməkdir.

Uğurlu alışdan sonra eSIM-in aktivləşdirilməsinin uğursuz olmasına nə səbəb olur?
Ən çox rast gəlinən səbəblər: cihazın eSIM-i dəstəkləməməsi və ya operatora bağlı kilidinin olması, cihazda profillər üçün yaddaşın dolması, istifadəçinin QR kodunu aktivləşdirilən cihazın özündə skan etməyə çalışması (ikinci cihaz və ya əl ilə daxiletmə tələb olunur), yaxud LPA vasitəsilə endirmə zamanı şəbəkə bağlantısının kəsilməsi. Bunlar API nasazlıqları deyil, cihaz tərəfindəki problemlərdir.

Bütün dünyada işləyən eSIM inteqrasiyası yarada bilərəmmi?
Bəli, əgər provayderiniz kifayət qədər ölkəni əhatə edirsə. 200+ ölkə və regionu əhatə edən provayderləri axtarın. Nəzərə alın ki, əhatə keyfiyyəti dəyişir: paket müəyyən istiqamət üçün texniki baxımdan mövcud ola bilər, lakin kənd yerlərində əhatəsi zəif olan tək bir yerli operatordan asılı ola bilər. İstifadəçiləriniz az ziyarət edilən yerlərə səyahət edirlərsə, hər istiqamət üzrə şəbəkə tərəfdaşları haqqında təfərrüatları yoxlayın.

2026-cı ildə eSIM API inteqrasiyası əvvəlki illərlə müqayisədə əhəmiyyətli dərəcədə fərqlənirmi?
GSMA SGP.22 standartı sabit qalıb, lakin provayderlərin API-ləri xeyli təkmilləşib. Webhook etibarlılığı, sınaq mühitləri və sənədləşmənin keyfiyyəti bir neçə il əvvəlki ilə müqayisədə nəzərəçarpacaq dərəcədə yaxşılaşıb. Birbaşa quraşdırma prosesləri də daha çox cihaz modelini əhatə edir, baxmayaraq ki, QR kodunun təqdim edilməsi hələ də ən geniş uyğunluğa malik yanaşmadır.

Öz məhsulumu yaratmaq əvəzinə təkrar satış inteqrasiyası qururamsa, nəyə üstünlük verməliyəm?
Kataloqun aktuallığına, qiymətlərin dəqiqliyinə və satışların hansı mənbədən gəldiyinin izlənməsinə diqqət yetirin. Profillərin hazırlanıb təqdim edilməsinin mürəkkəbliyini provayder öz üzərinə götürür. Sizi fərqləndirən cəhətlər müəyyən istiqamət üçün uyğun paketi nə dərəcədə yaxşı təqdim etməyiniz, uyğunluq tələblərini nə dərəcədə aydın çatdırmağınız və qiymətlərinizin alternativlərlə müqayisədə nə dərəcədə rəqabətədavamlı görünməsidir.

Haradan başlamalı #

İşlək inteqrasiyaya aparan ən sürətli yol aydın və səliqəli API-si, həqiqi izolyasiya olunmuş sınaq mühiti və istifadəçilərinizin səyahət istiqamətlərini əhatə edən kataloqu olan provayder seçməkdir. Bunun üçün hər hansı istifadəçi interfeysi yaratmazdan əvvəl alışdan aktivləşdirməyə qədər bütün prosesi özünüz sınaqdan keçirin. Əksər inteqrasiyalar cihaz uyğunluğu ilə bağlı qeyri-standart hallarda və profillərin asinxron təmin edilməsi sxemlərində çətinliklə üzləşir. Bunları real istifadə mühitində deyil, sınaq zamanı aşkar etmək istəyərsiniz.

Təkrar satış və ya xidməti öz brendiniz altında təqdim etmək variantını qiymətləndirirsinizsə, Roamify profillərin hazırlanıb təqdim edilməsi infrastrukturunu birbaşa idarə etmədən eSIM-ə çıxışı inteqrasiya etmək istəyən proqramçılar üçün nəzərdən keçirməyə dəyər tərəfdaşlıq proqramı təklif edir.