API entegrasyonu

API hızlı başlangıç

Hesabınız onaylandıktan sonra satış ekibi fiyatları tanımlar ve API erişimini açar. İş Ortağı Panelinde anahtar oluşturun. Salt okunur anahtarlar sipariş veremez. Hesabınızda satın alma izni de açık olmalıdır.

Her istekte sunucu tarafında bir bearer anahtarı kullanın. Anahtarı tarayıcı koduna veya URL’lere eklemeyin. Anahtarlar İş Ortağı Panelinde iptal edilebilir.

Sipariş oluştur

Idempotency-Key olarak bir UUID gönderin. Zaman aşımı veya bağlantı hatasından sonra aynı UUID’yi yeniden kullanın. Müşterinin onayladığı fiyatı gönderin ve alıcı cihazın eSIM desteklediğini, operatör kilidinin olmadığını doğrulayın. Canlı fiyat değişiklikleri 409 PRICE_CHANGED döndürür. Bu canlı bir API’dir; kabul edilen satın alımlarda gerçek cüzdan bakiyesi kullanılır.

POST /api/partner/v1/orders
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: 83c77d9f-395f-4ff0-8ed6-c461bda46559

{"productId":"PRODUCT_ID_FROM_CATALOG","expectedPrice":"2.25","deviceConfirmed":true}

201 yanıtı orderId ve esim içerir; esim.status ve esim.failure alanlarını kontrol edin. Siparişi 10 saniyede bir sorgulayın. Tutar önce ayrılır, doğrulanmış teslimattan sonra tahsil edilir. Tekrarlanan istek başarısız bir siparişi de döndürebilir. Tedarikçi sonucu belirsizse asıl sipariş uzlaştırılırken tutar ayrılmış kalır. Kurulum bilgileri özeldir ve yalnızca doğrulanmış teslimattan sonra görünür.

Tutarlar USD cinsinden ondalık dizelerdir. Listeler items ve nextCursor döndürür; nextCursor null olana kadar devam edin. Sınırlar: anahtar başına dakikada 120 istek ve kullanıcı başına dakikada 10 satın alma denemesi. 429 yanıtında Retry-After’a uyun. Yaygın hatalar: 401 geçersiz anahtar, 403 yetki yok, 402 yetersiz bakiye, 404 erişilemeyen sipariş, 409 fiyat veya idempotency çakışması, 503 hizmet kullanılamıyor. Başka bir satın alma denemeden önce asıl siparişi sorgulayın.