Kod örnekleri Postman koleksiyonunu indir

Giriş Kimlik doğrulama Bakiye Raporlar Ürünleri Listele Sipariş - Travel Sipariş Oluştur - VPN Sipariş Durumu Veri Kullanımı VPN Yapılandırması Hata kodları

Partner API referansı

Tüm endpoint'ler JSON döner. Fiyatı siz göndermezsiniz - sadece ne almak istediğinizi belirtirsiniz, fiyatı her zaman sunucu kendisi hesaplar; böylece fiyat sahtelenemez veya değiştirilemez.

Base URL:

Base URL

https://buyukesim.com/api/v1

Kimlik doğrulama

Aşağıdaki her istekte API anahtarınızı Bearer token olarak gönderin.

Not: bakiye ekleme sadece site üzerinden yapılan bir işlemdir (panel Magic Code'unuzla), bu API'nin parçası değildir - API anahtarınızla bakiye yükleyemezsiniz.

Header

Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Hesap

GET/api/v1/balance

Hesap Bakiyesi

Ön ödemeli hesabınızda kalan tutar. Her sipariş aynı rakamı kendi balance bloğunda zaten döndürür, yani bir satın almanın ne tuttuğunu görmek için buraya istek atmanız gerekmez. Bu uç nokta satın almadan bağımsız kontroller içindir: bakiye alarmı, panel kartı, ödeyemeyeceği işi başlatmayı reddeden toplu iş.

Request

curl "https://buyukesim.com/api/v1/balance" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "success": true,
  "data": {
    "balance_usd": 477.5,
    "currency": "USD",
    "discount_pct": 10,
    "account": {
      "name": "Acme Telecom",
      "status": "active",
      "api_key_prefix": "buk_live_9f2a"
    }
  }
}

GET/api/v1/reports?from=2026-08-01&to=2026-08-31

Satış Raporu

Bir tarih aralığında ne aldığınız ve ne kadara mal olduğu, ürün bazında. Tarihler sipariş tarihine göre UTC takvim günüdür ve iki uçtan da dahildir; boş bırakırsanız son 30 gün raporlanır. Yalnızca ödenmiş siparişler - teslimatı başarısız olan sipariş iptal edilip bakiyenize iade edildiği için hiç para götürmemiştir. Kalem kalem orders dizisi varsayılan olarak 100 satırla sınırlıdır (limit, en fazla 500); daha fazlası için tarih aralığını daraltın.

Request

curl "https://buyukesim.com/api/v1/reports?from=2026-08-01&to=2026-08-31" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "success": true,
  "data": {
    "period": { "from": "2026-08-01", "to": "2026-08-31", "timezone": "UTC" },
    "totals": {
      "orders": 4,
      "units": 4,
      "spend_usd": 25.16,
      "currency": "USD"
    },
    "products": [
      { "type": "travel_data", "orders": 3, "units": 3, "spend_usd": 16.17 },
      { "type": "vpn",         "orders": 1, "units": 1, "spend_usd": 8.99 }
    ],
    "balance": { "remaining_usd": 477.5, "currency": "USD" },
    "orders": [
      {
        "order_id": 98423,
        "type": "vpn",
        "reference": "order-1236",
        "lookup_code": "K7M9-2XP4",
        "units": 1,
        "spend_usd": 8.99,
        "created_at": "2026-08-29 20:00:00",
        "plan": "30d"
      }
    ],
    "orders_truncated": false
  }
}

Ürünler

GET/api/v1/products

Ürünleri Listele

Tüm aktif Travel eSIM paketlerini (güncel package_code ve price_usd ile) ve VPN erişim planları ile sunucularını çekin; böylece Create Order çağırmadan önce neyin satın alınabilir olduğunu bilirsiniz. travel_data dizisi canlı kataloğun tamamıdır (yaklaşık 198 destinasyon - burada bir tanesi gösteriliyor); ?location_code=GB ile daraltılır. Her price_usd SİZİN fiyatınızdır: discount_pct sabit değil, size özel oranınızdır; aşağıdaki örnek sadece %10 kullanıyor.

Request

curl "https://buyukesim.com/api/v1/products" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "success": true,
  "data": {
    "discount_pct": 10,
    "travel_data": [
      {
        "package_code": "GB_1GB_7D",
        "name": "United Kingdom 1GB / 7 Days",
        "location_code": "GB",
        "retail_price_usd": 5.99,
        "price_usd": 5.39,
        "volume_label": "1 GB",
        "duration": 7,
        "duration_unit": "DAY"
      }
    ],
    "vpn": {
      "type": "vpn",
      "available": true,
      "currency": "USD",
      "plans": [
        { "plan": "30d", "days": 30, "label": "30 days", "retail_price_usd": 9.99, "price_usd": 8.99, "currency": "USD" }
      ],
      "protocols": ["wireguard", "openvpn", "vless"],
      "servers": [
        { "id": 42, "country_code": "NL", "city": "Amsterdam", "protocol": "wireguard" }
      ]
    }
  }
}

Siparişler

POST/api/v1/orders

Sipariş Oluştur - Seyahat eSIM

Verilen package_code için bir Seyahat eSIM siparişi oluşturur ve anında teslim eder.

Request

curl -X POST "https://buyukesim.com/api/v1/orders" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "travel_data",
  "package_code": "GB_1GB_7D",
  "reference": "order-1235"
}'

Response

{
  "success": true,
  "data": {
    "order_id": 98422,
    "reference": "order-1235",
    "status": "paid",
    "product": {
      "type": "travel_data",
      "package_code": "GB_1GB_7D",
      "package_name": "United Kingdom 1GB / 7 Days",
      "location_code": "GB",
      "retail_price_usd": 5.99,
      "discount_pct": 10,
      "price_usd": 5.39
    },
    "lookup_code": null,
    "created_at": "2026-07-06T20:00:00+00:00",
    "balance": { "charged_usd": 5.39, "remaining_usd": 472.11, "currency": "USD" }
  }
}

POST/api/v1/orders

Sipariş Oluştur - VPN erişimi

Verilen vpn_plan için bir VPN erişim siparişi oluşturur ve anında sağlar; tutar ön ödemeli bakiyenizden düşülür. Yanıt kullanıcı adını, parolayı ve bitiş tarihini içerir. VPN sağlayıcısına ulaşılamazsa sipariş yine de ödenmiş sayılır ve korunur: HTTP 202 ile "provisioning_pending" durumunu ve sipariş kimliğini alırsınız, ekibimize uyarı gider ve hesap oluşturulduğunda kimlik bilgileri GET /v1/orders/{id} yanıtında görünür.

Request

curl -X POST "https://buyukesim.com/api/v1/orders" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "vpn",
  "vpn_plan": "30d",
  "reference": "order-1236"
}'

Response

{
  "success": true,
  "data": {
    "order_id": 98423,
    "reference": "order-1236",
    "status": "paid",
    "product": {
      "type": "vpn",
      "plan": { "key": "30d", "days": 30, "label": "30 days" },
      "retail_price_usd": 9.99,
      "discount_pct": 10,
      "price_usd": 8.99
    },
    "lookup_code": "K7M9-2XP4",
    "created_at": "2026-08-29T20:00:00+00:00",
    "vpn": {
      "provisioned": true,
      "expires_at": "2026-09-28 00:00:00",
      "username": "bk98423a1c3e",
      "password": "s7Kq2vXpLm4A",
      "protocols": ["wireguard", "openvpn", "vless"],
      "config_endpoint": "https://buyukesim.com/api/v1/orders/98423/vpn-config"
    },
    "success_url": "https://buyukesim.com/en/success?order_id=98423&access_token=...",
    "balance": { "charged_usd": 8.99, "remaining_usd": 463.12, "currency": "USD" }
  }
}

GET/api/v1/orders/98422

Sipariş Durumu ve Teslimat

Teslimat çağrısı: data.esim.ready true olana kadar sorgulayın ve profili data.esim.items içinden alın. Her kalem telefona girmenin iki yolunu da taşır - qr_code, ve elle girilecek SM-DP+ adresi ile aktivasyon kodunu içeren manual_install. İkincisi çok yaygın bir durum içindir: müşteriniz uygulamanızı, profilin kurulacağı telefonun kendisinde okuyordur ve tarayacak ikinci bir ekranı yoktur. Travel eSIM'lerde puk_code null gelir. status alanını sorgulamayın: bakiyeniz düşüldüğü anda "paid" olur, bu bir ödeme durumudur, teslimat durumu değil.

Request

curl "https://buyukesim.com/api/v1/orders/98422" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "success": true,
  "data": {
    "order_id": 98422,
    "reference": "order-1235",
    "status": "paid",
    "product": { "type": "travel_data", "package_code": "GB_1GB_7D", "retail_price_usd": 5.99, "price_usd": 5.39 },
    "lookup_code": "K7M9-2XP4",
    "esim": {
      "ready": true,
      "items": [
        {
          "_comment": "hosts below are placeholders - the real ones differ per profile",
          "qr_code": "https://qr.example-provider.net/8e2bba37e8b94ca49bf23be334a0a57f.png",
          "iccid": "8944...",
          "puk_code": null,
          "manual_install": {
            "activation_string": "LPA:1$rsp.example-provider.com$1173094A3D3A473D84695E0D6C404B34",
            "smdp_address": "rsp.example-provider.com",
            "activation_code": "1173094A3D3A473D84695E0D6C404B34",
            "confirmation_code_required": false
          }
        }
      ]
    }
  }
}

GET/api/v1/orders/98422/usage

Seyahat eSIM Veri Kullanımı

Bir Seyahat eSIM siparişinin kalan/kullanılan verisini, aktivasyon ve son kullanma durumunu her çağrıda sağlayıcıdan canlı olarak alın.

Request

curl "https://buyukesim.com/api/v1/orders/98422/usage" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "success": true,
  "data": {
    "order_id": 98422,
    "status": "paid",
    "package": {
      "package_code": "GB_1GB_7D",
      "name": "United Kingdom 1GB / 7 Days",
      "location_code": "GB",
      "volume_label": "1 GB",
      "duration": 7,
      "duration_unit": "DAY"
    },
    "usage": {
      "iccid": "8944...",
      "apn": "cmlink",
      "esim_status": "IN_USE",
      "smdp_status": "ENABLED",
      "total_volume_bytes": 1073741824,
      "used_volume_bytes": 214748364,
      "remaining_volume_bytes": 858993459,
      "usage_percent": 20.0,
      "total_duration": 7,
      "duration_unit": "DAY",
      "expired_time": "2026-07-13T20:00:00+00:00"
    }
  }
}

GET/api/v1/orders/98423/vpn-config?protocol=wireguard&server_id=42

VPN yapılandırması

Oluşturduğunuz bir VPN siparişi için tek bir sunucuya ait WireGuard, OpenVPN veya VLESS yapılandırmasını getirir. server_id değerini Ürünleri Listele yanıtındaki sunucu listesinden alın. WireGuard sunucuları aynı zamanda OpenVPN sunar; VLESS sunucuları yalnızca VLESS sunar. Dakikada 20 çağrıya kadar istediğiniz sıklıkta çağırabilirsiniz.

Request

curl "https://buyukesim.com/api/v1/orders/98423/vpn-config?protocol=wireguard&server_id=42" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "success": true,
  "data": {
    "order_id": 98423,
    "protocol": "wireguard",
    "server": { "id": 42, "country_code": "NL", "city": "Amsterdam" },
    "name": "buyukesim-nl-amsterdam.conf",
    "content": "[Interface]\nPrivateKey = ...\nAddress = ...",
    "qr_payload": "[Interface]\nPrivateKey = ...\nAddress = ..."
  }
}

Hata kodları

Her hata yanıtı aynı yapıdadır: üst seviyede success: false, ve ne olduğunu anlamak için kontrol edebileceğiniz sabit bir code alanı içeren bir error nesnesi.

Error shape

{
  "success": false,
  "error": { "code": "insufficient_balance", "message": "..." }
}

HTTP	code	Anlamı
401	unauthorized	API anahtarı eksik veya geçersiz.
402	insufficient_balance	Bu siparişin fiyatı için yetersiz ön ödemeli bakiye.
404	package_not_found	Seyahat package_code bulunamadı veya artık aktif değil.
409	provisioning_pending	Bu siparişin VPN hesabı henüz oluşturulmadı veya plan sona erdi.
429	rate_limit	Rate limit aşıldı - istekleri yavaşlatın.