Codebeispiele Postman-Sammlung herunterladen

Einführung Authentifizierung Guthaben Berichte Produkte auflisten Bestellung - Travel Bestellung anlegen - VPN Bestellstatus Datennutzung VPN-Konfiguration Fehlercodes

Partner-API-Referenz

Alle Endpunkte geben JSON zurück. Sie senden nie einen Preis - Sie geben nur an, was Sie kaufen möchten, und der Server berechnet den Preis immer selbst, sodass er nicht gefälscht oder manipuliert werden kann.

Basis-URL:

Base URL

https://buyukesim.com/api/v1

Authentifizierung

Senden Sie Ihren API-Schlüssel bei jeder folgenden Anfrage als Bearer-Token.

Hinweis: Guthaben aufladen ist eine reine Website-Aktion (mit Ihrem Dashboard Magic Code), nicht Teil dieser API - Ihr API-Schlüssel kann keine Aufladungen erstellen oder finanzieren.

Header

Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Konto

GET/api/v1/balance

Kontoguthaben

Was auf Ihrem Prepaid-Konto übrig ist. Jede Bestellung liefert dieselbe Zahl bereits im eigenen balance-Block, Sie müssen also nie hier anfragen, nur um zu sehen, was ein Kauf gekostet hat. Dieser Endpunkt ist für Prüfungen abseits eines Kaufs gedacht: ein Aufladealarm, eine Dashboard-Kachel, ein Batch-Job, der nicht startet, was er nicht bezahlen kann.

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

Verkaufsbericht

Was Sie in einem Zeitraum gekauft haben und was es gekostet hat, nach Produkt aufgeschlüsselt. Daten sind UTC-Kalendertage auf dem Bestelldatum und an beiden Enden inklusive; ohne Angabe werden die letzten 30 Tage berichtet. Nur bezahlte Bestellungen - eine Bestellung, deren Bereitstellung fehlschlägt, wird storniert und Ihrem Guthaben zurückgeschrieben, hat also nie etwas gekostet. Das orders-Array ist standardmäßig auf 100 Zeilen begrenzt (limit, maximal 500); grenzen Sie für mehr den Zeitraum ein.

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
  }
}

Produkte

GET/api/v1/products

Produkte auflisten

Alle aktiven Travel-eSIM-Pakete (mit aktuellem package_code und price_usd) sowie die VPN-Zugangspläne und -Server abrufen, damit Sie vor Create Order immer wissen, was kaufbar ist. Das travel_data-Array ist der gesamte Livekatalog (rund 198 Ziele - hier ist ein Eintrag gezeigt); ?location_code=GB grenzt ein. Jeder price_usd ist IHR Preis: discount_pct ist Ihr eigener Satz, kein fester, das Beispiel nutzt nur 10 %.

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" }
      ]
    }
  }
}

Bestellungen

POST/api/v1/orders

Bestellung erstellen - Reise-eSIM

Erstellt und wickelt sofort eine Reise-eSIM-Bestellung für den angegebenen package_code ab.

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

Bestellung anlegen - VPN-Zugang

Legt eine VPN-Zugangsbestellung für den angegebenen vpn_plan an und stellt sie sofort bereit, abgebucht von deinem vorausbezahlten Guthaben. Die Antwort enthält Benutzername, Passwort und Ablaufdatum. Ist der VPN-Anbieter nicht erreichbar, bleibt die Bestellung trotzdem bezahlt und bestehen: du erhältst HTTP 202 mit dem Status "provisioning_pending" und der Bestell-ID, unser Team wird alarmiert, und die Zugangsdaten erscheinen unter GET /v1/orders/{id}, sobald das Konto angelegt ist.

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

Bestellstatus & Auslieferung

Der Auslieferungsaufruf: fragen Sie ihn ab, bis data.esim.ready true ist, und nehmen Sie das Profil aus data.esim.items. Jede Position enthält beide Wege auf ein Telefon - qr_code sowie manual_install mit SM-DP+-Adresse und Aktivierungscode zum manuellen Eintippen, für den sehr häufigen Fall, dass Ihr Kunde Ihre App auf genau dem Telefon liest, auf das das Profil soll, und keinen zweiten Bildschirm zum Scannen hat. Bei Travel-eSIMs ist puk_code null. Fragen Sie nicht status ab: er steht auf "paid", sobald Ihr Guthaben belastet wurde - das ist ein Zahlungs-, kein Lieferstatus.

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

Reise-eSIM-Datennutzung

Live verbleibende/genutzte Daten, Aktivierungs- und Ablaufstatus für eine Reise-eSIM-Bestellung, bei jedem Aufruf frisch vom Anbieter abgerufen.

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-Konfiguration

Holt eine WireGuard-, OpenVPN- oder VLESS-Konfiguration für einen Server einer von dir angelegten VPN-Bestellung. Die server_id stammt aus der Serverliste in Produkte auflisten. WireGuard-Server liefern auch OpenVPN; VLESS-Server nur VLESS. Beliebig oft aufrufbar, bis zu 20 Mal pro Minute.

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 = ..."
  }
}

Fehlercodes

Jede Fehlerantwort hat dieselbe Form: ein übergeordnetes success: false, plus ein error-Objekt mit einem stabilen code-Feld, das Ihr Code prüfen kann, um genau zu wissen, was schiefgelaufen ist.

Error shape

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

HTTP	code	Bedeutung
401	unauthorized	Fehlender oder ungültiger API-Schlüssel.
402	insufficient_balance	Unzureichendes Guthaben für den Preis dieser Bestellung.
404	package_not_found	Reise-package_code nicht gefunden oder nicht mehr aktiv.
409	provisioning_pending	Das VPN-Konto für diese Bestellung ist noch nicht angelegt, oder der Tarif ist abgelaufen.
429	rate_limit	Ratenlimit überschritten - Anfragen verlangsamen.