Geliştiriciler

Dört uç nokta, iki webhook, sürpriz yok.

Mağazanın yaptığı her şeyi senin ürünün de yapabilir. Tüm yüzey tek sayfaya sığıyor.

api.orbislo.com üzerinde HTTPS ile REST, bearer kimlik doğrulama, girişte JSON çıkışta JSON. Kataloğu listele, sipariş oluştur, sağlama işini sorgula, kullanımı oku. İki webhook sana bir eSIM ne zaman etkinleşti, ne zaman azaldı haber verir. Sandbox bilgileri aynı iş günü içinde geliyor. Canlı erişim şu an başvuruyla, nedenini de aşağıda anlatıyoruz, formu bir hız sınırıymış gibi göstermek yerine.

Bu API neden var

Bağlantı, yolcunun rezervasyon yaptığı anda, senin kendi ürününün içinde hazırlanmalı. Havaalanında keşfedeceği bir şey olmamalı.

Bir rezervasyon platformu, bir seyahat planına veri ekleyebilir. Bir cihaz üreticisi, ilk kurulum sırasında paketi açabilir. Bir ekip aracı, işe yeni başlayana verisini dizüstü bilgisayarıyla birlikte verebilir.

Üçü de dört çağrı ve tek bir webhook demek. Giriş yapılacak bir iş ortağı paneli yok, yüklenecek bir CSV de yok.

Senin POST isteğinle yolcunun çekim gücüne kavuşması arasında neler oluyor.

Kimlik doğrulama

Anahtarını her istekte bearer token olarak gönder. Anahtarlar sandbox için sk_test, canlı ortam için sk_live önekini taşır.

Yanlış ortama yapıştırılan anahtar, sessizce para harcamak yerine 401 ile başarısız olur. Anahtarların kapsamı vardır, yani salt okunur bir anahtar sipariş oluşturamaz ve bir ekip hesabı için verilen anahtar başka bir hesabı göremez.

İstediğin zaman konsoldan değiştir. Eski anahtar 24 saat daha çalışmaya devam eder, yani hiçbir zaman tek günde topluca geçiş yapmak zorunda kalmazsın.

curl https://api.orbislo.com/v1/catalog?country=jp \
  -H "Authorization: Bearer sk_live_9f2c..." \
  -H "Orbislo-Version: 2026-08-01"

Sürüm başlığı hakkında

Sürüm başlığı isteğe bağlıdır ve yanıtın biçimini tarihli bir sürüme sabitler. Göndermezsen anahtarının oluşturulduğu sürümü alırsın, o da ayağının altından kaymaz.

Alanları haber vermeden ekleriz. Bir sürümün içinde asla alan kaldırmayız, türünü de değiştirmeyiz.

API'nin tamamındaki uç nokta sayısı, ayrıca 2 webhook olayı

90 sn

başarılı bir siparişten etkin bir profile geçişin ortanca süresi

24 sa

tekrarlanan bir idempotency anahtarının özgün yanıtı döndürdüğü süre

Uç noktalar

Yöntem	Yol	Ne yapar	Hız sınırı
GET	/v1/catalog	Sattığımız her paket, fiyatı, veri miktarı, geçerliliği ve kapsadığı ülkelerle.	dakikada 600
POST	/v1/orders	Bir paketi satın alır ve sağlama işi eklenmiş bir sipariş döndürür.	dakikada 60
GET	/v1/provisioning/:id	Tek bir sağlama işinin durumu, queued durumundan activated ya da failed durumuna kadar.	dakikada 600
GET	/v1/usage/:esim_id	Kullanılan bayt, kalan bayt ve bir eSIM'in bağlı olduğu operatör.	dakikada 300

Sınırlar kayan pencerede, anahtar başınadır. Her yanıt kalan hakkı ve sıfırlanma zamanını taşır, 429 ise saniye cinsinden bir bekleme süresi taşır. Kullanım senaryon gerçekten daha büyük bir kova gerektiriyorsa iste, çünkü kovayı büyütmek bir ayar değişikliğidir, pazarlık değil.

Katalog

Neyin var olduğu ve kaça satıldığı konusunda tek doğru kaynak katalogdur. Bugün yayında olan 145 destinasyonu kapsar.

Ülkeye, bölgeye ya da paket ailesine göre süz. Fiyatlar en küçük para biriminde döner, böylece kayan nokta hiçbir zaman senin faturalama koduna ulaşmaz.

GET /v1/catalog?country=jp

{
  "object": "list",
  "data": [
    {
      "id": "plan_jp_5gb",
      "name": "Japan 5 GB",
      "countries": ["jp"],
      "data_mb": 5120,
      "price": { "amount": 1150, "currency": "usd" },
      "expires": false,
      "throttle_mbps": null,
      "tethering": true,
      "carriers": ["NTT Docomo", "KDDI", "SoftBank"]
    }
  ],
  "has_more": false
}

İki kez okunmayı hak eden iki alan

expires alanı, sattığımız her ölçümlü pakette false döner, çünkü bizim verimiz sona ermez. Fiyat karşılaştırması kuruyorsan bu alan hesabı fiyattan daha çok değiştirir.

throttle_mbps alanı ölçümlü paketlerde null, sınırsız günlük paketlerde 1 döner. Günlük pakette tam hız günde 2 GB sürer, sonra 1 Mbps seviyesine iner.

Bu kısıtlama sayısını API içine koymamızın nedeni, onu satın alma düğmesine yazdırmamızla aynı. Yolcunun sonradan öğrendiği bir sayı, doğrudan bir destek kaydına dönüşür.

Siparişler

Tek bir POST paketi satın alır ve sağlamayı başlatır. Idempotency-Key başlığı tavsiye değil, zorunludur.

Bu API'deki en kötü sonuç, yolcudan para çekilip çekilmediğini bilemediğin bir zaman aşımıdır. Zorunlu bir anahtar bu durumu tamamen ortadan kaldırır.

POST /v1/orders
Idempotency-Key: 4f1d0f6e-1c3a-4a2b-9d77-1b6a0e7c9f21
Content-Type: application/json

{
  "plan_id": "plan_jp_5gb",
  "traveller_ref": "user_88213",
  "imei": "356938035643809",
  "activate": "on_first_use"
}

201 Created

{
  "id": "ord_7Kd2mQ",
  "status": "provisioning",
  "esim_id": "esim_2xB9Ln",
  "provisioning_id": "prv_5Ttq81",
  "amount": { "amount": 1150, "currency": "usd" },
  "activation": {
    "type": "universal_link",
    "url": "https://orbislo.com/i/2xB9Ln",
    "lpa": "LPA:1$rsp.orbislo.com$K4-9TT-2XB9LN"
  }
}

Cihaz kontrolü ve gecikmeli etkinleştirme

imei alanı isteğe bağlı ama şiddetle öneriyoruz. Gönder, biz de para almadan önce eSIM uyumunu ve operatör kilidini kontrol edelim.

Profil tutamayan bir telefon, satılmış bir paket ve öfkeli bir yolcu yerine device_not_eligible içeren bir 422 alır.

activate alanını on_first_use yaparsan, geçerlilik süresi senin sunucun bizi çağırdığında değil, yolcu indiğinde başlar.

Sağlama durumu

Öbür uçta bir operatör platformu olduğu için sağlama eşzamansızdır. Bu uç noktayı sorgula, ya da webhook'u al ve sorgulamayı hiç yapma.

queued durumundan activated durumuna geçişin ortancası 90 saniyenin altında. 10 dakika sonra hâlâ queued olan her şey başarısızlıktır ve parası kendiliğinden iade edilir.

GET /v1/provisioning/prv_5Ttq81

{
  "id": "prv_5Ttq81",
  "status": "activated",
  "states": [
    { "state": "queued",       "at": "2026-08-24T09:14:02Z" },
    { "state": "provisioning", "at": "2026-08-24T09:14:04Z" },
    { "state": "installed",    "at": "2026-08-24T09:14:41Z" },
    { "state": "activated",    "at": "2026-08-24T09:15:07Z" }
  ],
  "carrier": "KDDI",
  "failure_reason": null
}

Webhook

İki olay var ve ikisi de yolcuya ne söylenmesi gerektiğini değiştiriyor. Bunları herhangi bir HTTPS uç noktasına yönlendir, her ortam için ayrı ayarlanır.

Webhook olayları

Olay	Ne zaman tetiklenir	Onunla ne yapmalı
esim.activated	Profil ilk kez bir şebekeye bağlandığında.	Yolcuya çevrimiçi olduğunu söyle. Satın alma onun için tam bu anda gerçek oluyor.
esim.depleted	Paket bir kullanım eşiğini geçtiğinde, yüzde 80'de bir kez ve yüzde 100'de bir kez daha.	Yolda kalmadan önce ek yükleme öner, sonrasında değil.

POST https://your-app.example/hooks/orbislo
Orbislo-Signature: t=1756032907,v1=6c1b...
Content-Type: application/json

{
  "id": "evt_9pQ4rz",
  "type": "esim.depleted",
  "created": "2026-08-24T11:41:33Z",
  "data": {
    "esim_id": "esim_2xB9Ln",
    "threshold": 80,
    "used_mb": 4096,
    "remaining_mb": 1024,
    "country": "jp"
  }
}

Bir teslimatı doğrulamak

Zaman damgası, bir nokta ve isteğin ham gövdesi üzerinde, uç nokta gizli anahtarınla HMAC SHA-256 hesapla. Karşılaştırmayı sabit zamanda yap.

Zaman damgası 5 dakikadan eski olan her şeyi reddet, bu tekrar saldırısını durdurur. Teslimat en az bir kez yapılır ve 24 saat içinde 8 kez yeniden denenir, bu yüzden işleyicini olay kimliğine göre kur.

Hata kodları

HTTP	Kod	Ne anlama gelir	Ne yapmalı
400	invalid_request	Bir alan eksik ya da türü yanlış. Gövde alanın adını veriyor.	İsteği düzelt. Yeniden denemek işe yaramaz.
401	invalid_token	bearer token yanlış, iptal edilmiş ya da diğer ortamdan.	Sandbox anahtarını canlı sunucuya göndermediğinden emin ol.
402	insufficient_balance	Hesap bakiyen siparişi karşılamıyor.	Yükleme yap, sonra aynı idempotency anahtarıyla yeniden dene.
404	not_found	Bu ortamda o kimliğe sahip bir nesne yok.	Sandbox kimlikleriyle canlı kimlikler birbirinin yerine geçmez.
409	idempotency_conflict	Aynı idempotency anahtarı farklı bir gövdeyle yeniden kullanıldı.	Yeni bir anahtar kullan ya da özgün gövdeyi bayt bayt aynı şekilde gönder.
422	device_not_eligible	Cihaz eSIM desteklemiyor ya da operatör kilidi var.	Parayı almadan önce cihaz kontrolünü çalıştır.
429	rate_limited	O uç noktanın kovasını aştın.	Başlıktaki bekleme süresi kadar geri çekil. Döngüye girme.
500	internal_error	Bizden kaynaklı. Zaten uyarı sistemimizde.	2 saniye sonra aynı idempotency anahtarıyla yeniden dene.
503	provider_unavailable	Yukarıdaki bir operatör platformu çalışmıyor.	10 dakikaya kadar yeniden dene. İkinci bir operatörün olduğu yerde otomatik geçiş yaparız.

Her hata gövdesi bir kod, insanın okuyabileceği bir mesaj ve bir istek kimliği taşır. İstek kimliğini destek ekibine söyle, ilk dört soruyu atlamış ol.

Canlı erişim bugün başvuruyla veriliyor ve bu gerçek bir kısıt.Gece ikide kayıt olup üçte sağlama yapamazsın, bu da kendi kendine açılan bir API'den açıkçası daha kötü. Bunu özenle hazırlanmış bir katılım deneyimi diye anlatmayacağız. Canlı anahtar para hareket ettirir ve operatör tarafında profil oluşturur, biz de sızmış bir anahtarın ardını toplamaktansa ne geliştirdiğine dair bir paragraf okumayı tercih ediyoruz. Sandbox bilgileri aynı iş günü geliyor, yani biz okurken entegrasyonu yazmanın önünde hiçbir engel yok.

Sandbox ile canlı ortam

Aynı sunucu, aynı yollar, aynı yanıt biçimleri. sk_test önekli bir anahtar paraya hiç dokunmaz ve operatör tarafında profil oluşturmaz.

Sağlama işleri tüm durum makinesini yaklaşık 4 saniyede geçer, yani testlerin her biri için 90 saniye beklemez.

Nedeniyle birlikte başarısız bir iş almak için plan_test_fail paketini sipariş et. provisioning durumunda 11 dakika bekleyen bir iş almak ve zaman aşımı yolunu denemek için plan_test_slow siparişi ver.

webhook teslimatları sandbox içinde de tetiklenir, her ortam için ayarladığın bir URL adresine gider.

Hiçbir şey geliştirmek istemiyorsan

Ortaklık programı hiçbir entegrasyon olmadan yönlendirilen siparişler üzerinden ödeme yapar, içerik siteleri için doğru cevap çoğunlukla budur.

MCP uç noktası, kapsama veri kümemizi ve fiyat endeksimizi tek satır ayarla ve hiç kod yazmadan bir yapay zeka asistanına açar.

Satacağın paketler, kataloğun arkasındaki ölçülmüş hız verileri ve tam ülke listesi, hepsi bu sitede açıkça yayınlanıyor.

Geliştiricilerin sorduğu sorular

Bugün API anahtarı alabilir miyim?

Kendi kendine değil. Erişim şu an başvuruyla veriliyor ve bu, açmayı unuttuğumuz bir sıra değil, bilinçli bir tercih. Her canlı anahtar gerçek para hareket ettirebilir ve gerçek bir operatör platformunda gerçek bir profil oluşturabilir, çalınan bir anahtar da bir yolcunun bağlantısına mal olur. Bu yüzden başvuruları biz okuyoruz. Sandbox farklı: iste, aynı iş günü içinde sandbox bilgilerini al, sözleşme de yok taahhüt de.

Onay ne kadar sürüyor?

İlk yanıt için iki iş günü, baştan sona genelde bir haftanın altı. Ne geliştirdiğini, ayda kabaca kaç etkinleştirme beklediğini ve hangi ülkeleri hedeflediğini bilmek istiyoruz. Anlattığın iş için API'nin doğru araç olmadığını düşünürsek bunu açıkça söyler ve seni hiç mühendislik gerektirmeden ödeme yapan ortaklık programına yönlendiririz.

Sandbox ile canlı ortam arasındaki fark ne?

Sandbox aynı sunucuyu sk_test önekli bir anahtarla kullanır. Gerçek kataloğu döndürür, siparişleri kabul eder ve bir sağlama işini queued, provisioning ve activated aşamalarından yaklaşık 4 saniyeye sıkıştırılmış bir zaman çizgisinde geçirir. Para hareket etmez, operatör profili oluşmaz. plan_test_fail paketini sipariş ederek istediğin hata durumunu zorlayabilirsin. Canlı anahtarlar sk_live önekini taşır ve orada her şey gerçektir.

Idempotency anahtarına ihtiyacım var mı?

Sipariş oluştururken evet, uç nokta anahtarsız isteği reddediyor. Bir siparişte yaşanan ağ zaman aşımı, bu API'deki en pahalı belirsizliktir, çünkü körlemesine yeniden denemek paketi iki kez satın alır. Idempotency-Key başlığında bir UUID gönder. Anahtarı yanıtla birlikte 24 saat saklarız, yani bu süre içindeki bir deneme ikinci bir sipariş oluşturmak yerine özgün sonucu döndürür.

Hız sınırları nedir?

Okuma uç noktalarında dakikada 600 istek, kullanımda dakikada 300 ve sipariş oluşturmada dakikada 60, anahtar başına, kayan pencerede. Her yanıt kalan hakkı ve sıfırlanma zamanını taşır. 429 saniye cinsinden bekleme süresi taşır. Kullanım senaryon gerçekten daha fazlasını gerektiriyorsa iste, çünkü kovayı büyütmek bir ayar değişikliğidir, pazarlık değil.

Webhook'lar ne kadar güvenilir?

2xx olmayan bir yanıtı 10 saniyeden başlayan üstel geri çekilmeyle 24 saat içinde 8 kez yeniden deneriz. Her teslimat, uç nokta gizli anahtarınla ham gövde üzerinde HMAC SHA-256 ile imzalanır, ayrıca tekrar saldırılarını durdurmak için 5 dakikalık bir pencereye karşı kontrol etmen gereken bir zaman damgası taşır. Teslimat en az bir kez yapılır, o yüzden işleyicini olay kimliğine göre tekrara dayanıklı yaz.

SDK var mı?

Bir TypeScript istemcisi ve bir Python istemcisi var, ikisi de aynı dört uç noktanın ince birer sarmalayıcısı. İkisi de hiçbir şey saklamıyor. Aktarım biçimi curl'ü makul bir canlı istemci yapacak kadar kararlı. On bir SDK'yı kötü sürdürmektense aktarım biçimini iyi belgelemeyi tercih ederiz.

Sağlama başarısız olursa ne olur?

İş nedeniyle birlikte failed durumuna geçer, o durumu taşıyan etkinleştirme webhook'unu göndeririz ve sipariş kimse istemeden 60 saniye içinde kendi kendine iade edilir. Bu durum için bir iade akışı geliştirmene gerek yok. Ama failed durumunu işlemen gerekiyor, çünkü yolcunun hâlâ verisi yok ve bunu hemen öğrenmeli.

Sandbox ile başla, ya da kodu tamamen atla

Sandbox bilgileri aynı iş günü içinde geliyor. Bir entegrasyon yazmak istemiyorsan, ne ortaklık programı ne de MCP uç noktası bir şey geliştirmeni gerektiriyor.

Mağazaya göz at Tüm fiyatları gör Ölçülmüş hızlara bak Destinasyonlara göz at