REST API · v1

Vio eSIM API Referansı

Aynı arka uç üzerinde iki REST yüzeyi: web uygulamamızı ve iOS/Android uygulamalarımızı çalıştıran müşteri API'si, ve Vio eSIM'i programatik olarak satmak için ayrı bir API anahtarıyla doğrulanan Partner API.

Mobil / Web API

https://vioesim.com/api/v1

Partner API

https://vioesim.com/api/public/v1

Mobil uygulama kimlik doğrulaması

Web uygulaması ve native uygulamalar aynı oturum sistemini paylaşır — native uygulama çerez yerine sadece token'ın kendisini taşır.

Kayıt olun veya giriş yapın. Her iki uç nokta da kullanıcı nesnesiyle birlikte bir token alanı döner (web uygulamasının kullandığı bir Set-Cookie başlığıyla birlikte). token'ı Keychain'de (iOS) veya Keystore destekli depoda (Android) saklayın.

Geri gönderin her istekte:

Authorization: Bearer <token>

Token ömrü: Verildiği andan itibaren 30 gün, ya da /api/v1/auth/logout çağrılana kadar. Yenileme (refresh) token adımı yoktur — süresi dolmak üzere olan bir token, kullanıcıdan tekrar giriş yapmasını isteyerek yenilenir.

Askıya alınmış, yasaklanmış veya silinmiş bir hesaba ait oturum, token'ın kendisi süresi dolmamış olsa bile — her istekte sunucu tarafında kontrol edilerek — anında çalışmayı durdurur.

Partner API kimlik doğrulaması

Vio eSIM'i kendi sitesi veya uygulaması üzerinden satan dış işletmeler için. Bir partner, normal bir Vio eSIM hesabıdır: bir anahtar üretin Panel → API Anahtarları (tek seferlik gösterim — saklayın, tekrar gösterilmez), sonra her istekte gönderin:

Authorization: Bearer vio_live_sk_...
# or
X-API-Key: vio_live_sk_...

Yeni bir anahtar üretmek öncekini anında geçersiz kılar.

Faturalandırma modeli: Partner API siparişleri, hesabın ön ödemeli cüzdan bakiyesinden anında düşülür — bu sunucu-sunucu bir çağrı olduğundan ödeme yönlendirmesi yoktur. Sipariş vermeden önce panelden (kart/kripto) bakiye yükleyin; bakiye yetersizse POST /orders 402 döner.

Hızlı başlangıç — Partner API

Kataloğa göz atın ve iki çağrıda bir eSIM satın alın:

curl https://vioesim.com/api/public/v1/destinations \
  -H "Authorization: Bearer vio_live_sk_..."

curl -X POST https://vioesim.com/api/public/v1/orders \
  -H "Authorization: Bearer vio_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "planId": "cus...", "quantity": 1 }'

Hatalar ve hız sınırları

Mobil/Web API { "error": "mesaj" } döner (şu an Türkçe mesajlar). Partner API, code üzerinden dallanabilmeniz için yapılandırılmış bir şekil döner:

{ "error": { "code": "INSUFFICIENT_BALANCE", "message": "Insufficient wallet balance." } }

Durum	Anlamı
401	Eksik/geçersiz/süresi dolmuş token veya API anahtarı
402	Sadece Partner API — cüzdan bakiyesi yetersiz
404	Kaynak bulunamadı veya çağıran tarafından sahiplenilmemiş
409	Çakışan durum (örn. bakiyesi sıfır olmayan bir hesabı silme)
429	Hız sınırına takıldı — saniye cinsinden Retry-After başlığına bakın
502	Ödeme alındı ama eSIM sağlanamadı — ücreti tekrar denemeyin

Hız sınırları (Partner API): Okuma isteklerinde anahtar başına dakikada 120, POST /orders üzerinde dakikada 30.

Mobil / Web API

Kimlik Doğrulama

POST/api/v1/auth/registerDoğrulama yok

Kayıt Ol

Bir hesap ve aktif bir oturum oluşturur.

Request body

{
  "firstName": "Ada",
  "lastName": "Lovelace",
  "email": "[email protected]",
  "password": "min 8 chars"
}

200 OK

{
  "success": true,
  "user": {
    "id", "firstName", "lastName", "fullName", "email",
    "emailVerified", "walletBalance", "currency", "locale", "createdAt"
  },
  "token": "..."
}

POST/api/v1/auth/logoutOturum token'ı

Çıkış Yap

Gövde yok. Oturumu sunucu tarafında siler — sadece "token'ı yerelde unut" değil, gerçek çıkışta bunu çağırın, böylece çalınan bir token çalışmaya devam edemez.

GET/api/v1/auth/meOturum token'ı · isteğe bağlı

Mevcut kullanıcı

Çıkış yapılmışsa { "user": null } döner (asla hata değil) — uygulama açılışında giriş ekranını gösterip göstermeyeceğinize bunu kullanarak karar verin.

POST/api/v1/auth/forgot-passwordDoğrulama yok

Şifremi unuttum

Gövde: { email, locale }. Adresin var olup olmadığına bakılmaksızın her zaman { success: true } döner, böylece hesapları taramak için kullanılamaz. Sıfırlama bağlantılı/token'lı bir e-posta gönderir (1 saat geçerli).

POST/api/v1/auth/reset-passwordDoğrulama yok

Şifreyi sıfırla

Gövde: { token, newPassword }. Formu göstermeden önce ?token= ile yapılan GET geçerliliği kontrol eder ({ "valid": true|false }).

POST/api/v1/auth/change-passwordOturum token'ı

Şifre değiştir

Gövde: { currentPassword, newPassword }. Hesabın henüz şifresi yoksa (örn. sosyal girişte) currentPassword gerekli değildir.

Hesap

PATCH/api/v1/user/profileOturum token'ı

Profili güncelle

Sadece değiştirmek istediğiniz alanları gönderin.

Field	Notes
firstName, lastName	isteğe bağlı · metin
preferredCurrency	isteğe bağlı · USD EUR GBP TRY değerlerinden biri
locale	isteğe bağlı · 2 harfli kod, örn. tr

200 OK

{ "success": true, "user": { ...same shape as /auth/me } }

POST/api/v1/user/avatarOturum token'ı

Profil fotoğrafını güncelle

Gövde: { "avatarUrl": "data:image/..." } — base64 data URI, en fazla ~1.5MB.

POST/api/v1/user/api-key/generateOturum token'ı

API anahtarı üret

Bu hesap için önceki anahtarın yerine geçen yeni bir Partner API anahtarı verir. Ham anahtar bu cevapta yalnızca bir kez gösterilir — daha sonra sadece öneki alınabilir.

200 OK

{
  "success": true,
  "key": "vio_live_sk_...",
  "apiKeyPrefix": "vio_live_sk_ab12…9f8e",
  "apiKeyGeneratedAt": "2026-08-22T17:00:00.781Z"
}

DELETE/api/v1/user/accountOturum token'ı

Hesabı sil

App Store incelemesi için gereklidir (hesap oluşturan uygulamalar uygulama içi silme sunmalıdır). Satırları kalıcı olarak silmek yerine hesabı anonimleştirir (e-posta karıştırılıp yeniden kayda açılır, ad/avatar/şifre temizlenir), böylece geçmiş siparişler vergi/muhasebe kayıtları için saklanır. Kullanıcının tüm oturumlarını ve kayıtlı push cihazlarını yok eder.

walletBalance > 0 ise 409 döner — uygulama kullanıcıya önce bakiyeyi çekmesini veya destekle iletişime geçmesini söylemeli, bakiyeyi sessizce kaybettirmemelidir.

Katalog

GET/api/v1/destinationsDoğrulama yok

Destinasyonları listele

Aktif paketlere sahip ülkeler ve bölgeler, fiyatlandırılmış ve arayüz için biçimlendirilmiş (mağazanın kendisinin çağırdığı budur). İsteğe bağlı ?filter=popular|regional|global|<arama metni>.

GET/api/v1/destinations/:codeDoğrulama yok

Destinasyon detayı

ISO koduna göre tek bir ülke için tam detay (açıklama, paketler), örn. /api/v1/destinations/jp.

Satın Almalar

POST/api/v1/checkoutOturum token'ı

Ödeme

Önce cüzdana para yatırmak yerine doğrudan bir paket satın alır.

Field	Notes
planId*
quantity	isteğe bağlı · 1–10, varsayılan 1
paymentMethod*	wallet \| stripe \| crypto
successUrl, cancelUrl	isteğe bağlı · stripe/crypto yönlendirmeleri için. Düz bir web URL'si değil, evrensel/uygulama bağlantısı kullanın ki yönlendirme uygulamayı yeniden açsın.

200 OK — wallet (synchronous)

{ "success": true, "orderId": "..." }

200 OK — stripe / crypto (redirect required)

{ "success": true, "orderId": "...", "url": "https://checkout.stripe.com/..." }

url'yi düz bir WebView yerine uygulama içi bir tarayıcıda açın (SFSafariViewController / Chrome Custom Tabs) — hem Stripe hem Cryptomus gerçek bir tarayıcı bağlamı bekler.

POST/api/v1/payments/stripe/create-sessionOturum token'ı

Stripe ile cüzdan yükleme

Kartla cüzdana bakiye yükler — Ödeme akışından ayrı bir akıştır. Gövde: { amount (cent, min 200), currency, successUrl, cancelUrl }. { sessionId, url } döner.

POST/api/v1/payments/cryptomus/create-invoiceOturum token'ı

Kripto ile cüzdan yükleme

Gövde: { amount (ondalık metin, min $2), currency, url_return }. url dahil Cryptomus fatura nesnesini döner.

GET/api/v1/user/ordersOturum token'ı

Siparişleri listele

Çağıranın en yeniden en eskiye tüm siparişleri.

GET/api/v1/user/orders/:idOturum token'ı

Sipariş detayı

esimIds dahil tek bir sipariş — tam eSIM detayını (QR, aktivasyon kodu) GET /api/v1/user/esims ile alıp id'ye göre eşleştirin.

GET/api/v1/user/esimsOturum token'ı

eSIM'lerim

Çağıranın sahip olduğu her eSIM: iccid, activationCode, qrCodeUrl, smdpAddress, status, dataUsage/totalVolume (MB), activatedAt, expiresAt. "eSIM'lerim" ekranını ve QR gösterimini bu besler.

GET/api/v1/user/wallet/transactionsOturum token'ı

Cüzdan geçmişi

/auth/me'de gösterilen cüzdan bakiyesi için para yatırma/çekme/satın alma/iade geçmişi.

Destek

GET/api/v1/support/ticketsOturum token'ı

Talepleri listele

Çağıranın en yeniden en eskiye, tüm mesaj dizileriyle birlikte destek talepleri.

POST/api/v1/support/ticketsOturum token'ı

Yeni talep

Gövde: { subject, category, message } (category isteğe bağlı).

POST/api/v1/support/tickets/:id/messagesOturum token'ı

Talebe yanıt ver

Gövde: { message }. RESOLVED/CLOSED bir talebe yanıt vermek otomatik olarak yeniden açar.

Push bildirim cihazları

Sadece cihaz token'larını kaydeder — bildirim göndermek için APNs/FCM kimlik bilgileri gerekir, aşağıdaki uyarıya bakın.

POST/api/v1/user/push-devicesOturum token'ı

Cihazı kaydet

Bir APNs veya FCM token'ı aldıktan sonra çağırın. Gövde: { platform: "IOS"|"ANDROID", pushToken, appVersion }. Token'a göre upsert yapar, bu yüzden her uygulama açılışında tekrar çağırmak sorunsuzdur ve önerilir (token'lar değişebilir).

DELETE/api/v1/user/push-devicesOturum token'ı

Cihaz kaydını sil

Gövde: { pushToken }. Paylaşılan/sıfırlanan bir cihazın başka bir kullanıcının bildirimlerini almaya devam etmemesi için çıkışta çağırın.

Partner API

Aşağıdakilerin tümü yukarıda açıklanan API anahtarı başlığını gerektirir — burada oturum çerezi geçerli değildir.

Katalog

GET/api/public/v1/destinationsAPI anahtarı

Destinasyonları listele

Partnere yönelik bir şekilde tam katalog (mağazanın arayüz şekli değil).

200 OK

{
  "countries": [
    {
      "code": "JP",
      "name": { "en": "Japan", "tr": "Japonya", "...": "..." },
      "flagEmoji": "🇯🇵",
      "continent": "Asia",
      "plans": [
        { "id": "cus...", "dataAmountMb": 1024, "durationDays": 7, "priceUsd": 4.25, "isTopUp": false }
      ]
    }
  ],
  "regions": [ { "code": "...", "name": {...}, "countryCount": 15, "plans": [...] } ]
}

GET/api/public/v1/destinations/:codeAPI anahtarı

Destinasyon detayı

ISO koduna göre tek bir ülke (örn. /api/public/v1/destinations/JP), yukarıdakiyle aynı paket şekli.

Siparişler

POST/api/public/v1/ordersAPI anahtarı

Sipariş oluştur

Çağıranın cüzdan bakiyesinden düşerek bir paket satın alır ve eSIM'i eşzamanlı olarak sağlar — cevap, son müşterinize vermeye hazır QR/aktivasyon verisini zaten içerir. Normal senaryoda yoklama (polling) gerekmez.

Request body

{ "planId": "cus...", "quantity": 1 }

201 Created

{
  "id": "...", "orderNumber": "VIO-API-...", "status": "COMPLETED", "amountUsd": 4.25,
  "esims": [
    { "id": "...", "iccid": "...", "activationCode": "...",
      "qrCodeUrl": "https://...", "smdpAddress": "...", "status": "PENDING" }
  ]
}

Hata durumları: 402 INSUFFICIENT_BALANCE (önce bakiye yükleyin), 404 PLAN_NOT_FOUND, veya 502 FULFILLMENT_FAILED (ücret alındı ama sağlayıcı eSIM'i veremedi — sipariş id'si dahildir, destek otomatik bilgilendirilir; ücreti tekrar almak yerine GET /orders/:id ile yoklayın).

GET/api/public/v1/ordersAPI anahtarı

Siparişleri listele

İsteğe bağlı ?limit= (varsayılan 25, en fazla 100). Özet şekli — eSIM verisi için detay uç noktasını kullanın.

GET/api/public/v1/orders/:idAPI anahtarı

Sipariş detayı

Her eSIM'in QR/aktivasyon verisi ve canlı kullanımı (dataUsageMb / totalVolumeMb) dahil tam sipariş detayı — müşterinize kalan verisini göstermek için bunu yoklayın.

Cüzdan

GET/api/public/v1/walletAPI anahtarı

Cüzdan bakiyesi

Büyük bir sipariş grubu vermeden önce yoklayın veya bakiye azaldığında kendinizi uyarın.

200 OK

{ "balanceUsd": 128.40, "currency": "USD" }

Henüz yapılmayanlar

Böylece burada, çalışmadığı halde çalışıyor varsayılan bir şey olmuyor.

Push bildirim gönderimi

Token kaydı çalışıyor; gerçekten göndermek için APNs/FCM kimlik bilgileri gerekiyor.

Partnere özel fiyatlandırma

Partner API şu anda mağazayla aynı perakende fiyatı uygular. Toptan/anlaşmalı fiyatlandırma bir şema değişikliği ve bir iş kararı gerektirir.

Yenileme token'ları

Oturumlar, kısa ömürlü erişim + yenileme token'ı çifti değil, uzun ömürlü (30 gün) düz token'lardır. Şimdilik yeterli; daha katı bir güvenlik duruşu için ileride gözden geçirilebilir.

Native Stripe ödeme ekranı

Stripe entegrasyonu barındırılan Checkout'tur (yönlendirme/webview). Native bir kart girişi arayüzü, bunun yerine PaymentIntents + Stripe SDK'sını kullanırdı.

Partnerler için webhook'lar

Partnerler durum için GET /orders/:id'yi yoklamalıdır; henüz giden bir webhook (örn. "eSIM aktive edildi") yoktur.

Entegrasyon hakkında sorularınız mı var? [email protected]

Vio eSIM API Referansı

Mobil uygulama kimlik doğrulaması

Partner API kimlik doğrulaması

Hızlı başlangıç — Partner API

Hatalar ve hız sınırları

Mobil / Web API

Kimlik Doğrulama

Kayıt Ol

Giriş Yap

Çıkış Yap

Mevcut kullanıcı

Şifremi unuttum

Şifreyi sıfırla

Şifre değiştir

Hesap

Profili güncelle

Profil fotoğrafını güncelle

API anahtarı üret

Hesabı sil

Katalog

Destinasyonları listele

Destinasyon detayı

Satın Almalar

Ödeme

Stripe ile cüzdan yükleme

Kripto ile cüzdan yükleme

Siparişleri listele

Sipariş detayı

eSIM'lerim

Cüzdan geçmişi

Destek

Talepleri listele

Yeni talep

Talebe yanıt ver

Push bildirim cihazları

Cihazı kaydet

Cihaz kaydını sil

Partner API

Katalog

Destinasyonları listele

Destinasyon detayı

Siparişler

Sipariş oluştur

Siparişleri listele

Sipariş detayı

Cüzdan

Cüzdan bakiyesi

Henüz yapılmayanlar

Push bildirim gönderimi

Partnere özel fiyatlandırma

Yenileme token'ları

Native Stripe ödeme ekranı

Partnerler için webhook'lar