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,
    "discounts": { "uk_number": 10, "travel_data": 10, "vpn": 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 %. Jede Produktlinie kann einen eigenen Satz haben: discounts nennt den Satz für uk_number, travel_data und vpn (ein Top-up wird als travel_data, eine Verlängerung als uk_number berechnet), und discount_pct ist der Kontosatz für jede Linie ohne eigenen Satz.

Request
curl "https://buyukesim.com/api/v1/products" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
Response
{
  "success": true,
  "data": {
    "discount_pct": 10,
    "discounts": { "uk_number": 10, "travel_data": 10, "vpn": 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/98422/topups

Aufladeoptionen für eine eSIM

Die Datenpakete, die der Anbieter derzeit für die eSIM dieser Bestellung anbietet, mit bereits angewendetem Rabatt. Der Katalog gilt je eSIM und ist live, diese Codes stehen also nicht in GET /v1/products und dürfen nicht zwischengespeichert werden: rufen Sie sie ab, wenn Ihr Kunde Daten nachladen möchte. Eine eSIM nimmt insgesamt 8 Aufladungen an, remaining_topups zeigt den Rest.

Request
curl "https://buyukesim.com/api/v1/orders/98422/topups" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
Response
{
  "success": true,
  "data": {
    "order_id": 98422,
    "iccid": "8944...",
    "discount_pct": 10,
    "reloadable": true,
    "used_topups": 1,
    "remaining_topups": 7,
    "max_topups": 8,
    "options": [
      {
        "package_code": "TOPUP_GB_1GB_7D",
        "name": "United Kingdom 1GB / 7 Days",
        "retail_price_usd": 5.99,
        "price_usd": 5.39,
        "volume_label": "1 GB",
        "volume_bytes": 1073741824,
        "duration": 7,
        "duration_unit": "DAY"
      }
    ]
  }
}
POST/api/v1/topups

Daten auf eine eSIM laden

Lädt eine bereits verkaufte Reise-eSIM nach, abgerechnet über Ihr Prepaid-Guthaben mit Ihrem Rabatt. Dasselbe Profil und derselbe QR-Code funktionieren weiter, Ihr Kunde installiert nichts neu. package_code muss einer der Codes sein, die der Listenaufruf für diese eSIM geliefert hat; er wird live erneut geprüft und ein Preis wird niemals aus der Anfrage übernommen. reference ist der Idempotenzschlüssel und teilt sich den Namensraum mit POST /v1/orders.

Request
curl -X POST "https://buyukesim.com/api/v1/topups" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": 98422,
  "package_code": "TOPUP_GB_1GB_7D",
  "reference": "topup-4471"
}'
Response
{
  "success": true,
  "data": {
    "order_id": 98599,
    "reference": "topup-4471",
    "status": "paid",
    "product": {
      "type": "travel_topup",
      "package_code": "TOPUP_GB_1GB_7D",
      "package_name": "United Kingdom 1GB / 7 Days",
      "volume_label": "1 GB",
      "duration": 7,
      "duration_unit": "DAY",
      "retail_price_usd": 5.99,
      "discount_pct": 10,
      "price_usd": 5.39
    },
    "esim": {
      "iccid": "8944...",
      "parent_order_id": 98422,
      "reinstall_required": false,
      "remaining_topups": 8
    },
    "created_at": "2026-07-09T11:20:00+00:00",
    "balance": { "charged_usd": 5.39, "remaining_usd": 466.72, "currency": "USD" }
  }
}
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 = ..."
  }
}

UK-Nummer (+44)

Nur für freigeschaltete Konten

Die UK-Nummer steht nicht jedem Partnerkonto offen: Unser Team schaltet sie auf Anfrage pro Konto frei. Solange sie für Ihr Konto nicht freigeschaltet ist, enthält GET /v1/products keinen uk_number-Block, und sowohl POST /v1/orders mit product_type uk_number als auch POST /v1/renewals antworten mit 403 product_unavailable. Travel eSIM und VPN funktionieren auf jedem Konto. Für den Zugang schreiben Sie unserem Support-Team mit Ihrem Kontonamen.

Auf einem freigeschalteten Konto liefert GET /v1/products zusätzlich einen uk_number-Block. Eine Rufnummer enthält ihre ersten 180 Tage. prepay_packages sind die 6-, 12- und 24-Monats-Pakete, die mit einer neuen Rufnummer verkauft werden (prepay_periods 0, 1 und 3); renewal_packages verlängern eine bereits verkaufte Rufnummer (periods 1, 2 und 4). Jeder price_usd ist Ihr Preis zu Ihrem UK-Satz; das Beispiel nutzt 10%.

GET /api/v1/products - uk_number
"uk_number": {
  "type": "uk_number",
  "retail_price_usd": 25,
  "price_usd": 22.5,
  "currency": "USD",
  "min_quantity": 1,
  "max_quantity": 10,
  "period_days": 180,
  "prepay_packages": [
    { "prepay_periods": 0, "months": 6,  "retail_price_usd": 25,   "price_usd": 22.5 },
    { "prepay_periods": 1, "months": 12, "retail_price_usd": 36,   "price_usd": 32.4 },
    { "prepay_periods": 3, "months": 24, "retail_price_usd": 59.5, "price_usd": 53.55 }
  ],
  "renewal_packages": [
    { "periods": 1, "months": 6,  "retail_price_usd": 15, "price_usd": 13.5 },
    { "periods": 2, "months": 12, "retail_price_usd": 27, "price_usd": 24.3 },
    { "periods": 4, "months": 24, "retail_price_usd": 51, "price_usd": 45.9 }
  ]
}

Sagen Sie es Ihrem Kunden vor dem Kauf: Der QR-Code jeder Rufnummer lässt sich nur einmal installieren. Er wird nicht neu ausgestellt, und eine ausgelieferte UK-Rufnummer wird nicht erstattet. Die Nummer bleibt bis zu ihrem Enddatum aktiv und muss vorher verlängert werden: Eine Rufnummer, deren Enddatum überschritten ist, wird freigegeben und kann nicht wiederhergestellt werden.

POST/api/v1/orders

Bestellung erstellen - UK-Nummer

Erstellt eine Bestellung für eine UK-Nummer (+44) und liefert sie sofort aus dem Bestand aus, abgezogen von Ihrem Guthaben zu Ihrem UK-Satz. quantity liegt zwischen 1 und 10 Rufnummern. Mit prepay_periods verkaufen Sie das längere Paket im selben Aufruf: 0 (oder weggelassen) sind 6 Monate, 1 sind 12 und 3 sind 24. reference ist der Idempotenzschlüssel und teilt sich den Namensraum mit allen anderen POST /v1/orders. Die Auslieferung erfolgt ganz oder gar nicht: Deckt der Bestand nicht die gesamte quantity, wird keine Rufnummer ausgeliefert, die Bestellung storniert und Ihr Guthaben erstattet.

Request
curl -X POST "https://buyukesim.com/api/v1/orders" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "uk_number",
  "quantity": 1,
  "prepay_periods": 0,
  "reference": "order-1234"
}'
Response
{
  "success": true,
  "data": {
    "order_id": 98421,
    "reference": "order-1234",
    "status": "paid",
    "product": {
      "type": "uk_number",
      "quantity": 1,
      "prepay_periods": 0,
      "months": 6,
      "retail_price_usd": 25,
      "discount_pct": 10,
      "price_usd": 22.5
    },
    "lookup_code": "K7M9-2XP4",
    "created_at": "2026-07-06 20:00:00",
    "balance": { "charged_usd": 22.5, "remaining_usd": 449.61, "currency": "USD" }
  }
}
GET/api/v1/orders/98421

Auslieferung der UK-Nummer

Derselbe Aufruf GET /v1/orders/{id} wie bei jeder anderen Bestellung. data.esim.items enthält einen Eintrag pro Rufnummer. qr_code ist ein signierter Link zum QR-Bild, der nach etwa zwei Stunden abläuft; lesen Sie die Bestellung für einen frischen Link erneut, statt ihn zu speichern. manual_install enthält die SM-DP+-Adresse und den Aktivierungscode für die manuelle Installation (null, wenn für das Profil keine Aktivierungszeichenfolge hinterlegt ist), und puk_code ist die PUK der Rufnummer. Die Telefonnummer selbst steht nicht in dieser Antwort; deshalb verlangt POST /v1/renewals das Feld phone.

Request
curl "https://buyukesim.com/api/v1/orders/98421" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
Response
{
  "success": true,
  "data": {
    "order_id": 98421,
    "reference": "order-1234",
    "status": "paid",
    "product": { "type": "uk_number", "quantity": 1, "prepay_periods": 0, "months": 6, "retail_price_usd": 25, "price_usd": 22.5 },
    "lookup_code": "K7M9-2XP4",
    "created_at": "2026-07-06 20:00:00",
    "esim": {
      "ready": true,
      "items": [
        {
          "qr_code": "https://buyukesim.com/api/serve_qr.php?order_id=98421&file=...&exp=...&sig=...",
          "iccid": "8944...",
          "puk_code": "12345678",
          "assigned_at": "2026-07-06 20:00:00",
          "manual_install": {
            "activation_string": "LPA:1$smdp.example.com$ABCD-1234-EFGH-5678",
            "smdp_address": "smdp.example.com",
            "activation_code": "ABCD-1234-EFGH-5678",
            "confirmation_code_required": false
          }
        }
      ]
    }
  }
}
POST/api/v1/renewals

UK-Rufnummer verlängern

Verlängert eine bereits verkaufte UK-Rufnummer, abgezogen von Ihrem Guthaben zu Ihrem UK-Satz. periods zählt 180-Tage-Blöcke: 1 sind 6 Monate, 2 sind 12 (10% Rabatt) und 4 sind 24 (15% Rabatt), danach kommt Ihr Rabatt hinzu. order_id ist Pflicht und muss eine Ihrer eigenen UK-Bestellungen sein. Senden Sie zusätzlich phone, sofern uns die Nummer für diese Bestellung noch nicht vorliegt. active_until in der Antwort ist das neue Enddatum der Rufnummer. reference funktioniert genau wie bei POST /v1/orders: Derselbe Wert erneut gesendet liefert die erste Verlängerung zurück und berechnet nichts.

Request
curl -X POST "https://buyukesim.com/api/v1/renewals" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": 98421,
  "phone": "+447700900123",
  "periods": 2,
  "reference": "renewal-5501"
}'
Response
{
  "success": true,
  "data": {
    "renewal_id": 412,
    "order_id": 98421,
    "reference": "renewal-5501",
    "status": "completed",
    "phone_number": "+447700900123",
    "periods": 2,
    "months": 12,
    "price_usd": 24.3,
    "active_until": "2027-07-01",
    "created_at": "2026-07-06 20:05:00",
    "completed_at": "2026-07-06 20:05:00",
    "balance": { "charged_usd": 24.3, "remaining_usd": 425.31, "currency": "USD" }
  }
}

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": "..." }
}
HTTPcodeBedeutung
401unauthorizedFehlender oder ungültiger API-Schlüssel.
402insufficient_balanceUnzureichendes Guthaben für den Preis dieser Bestellung.
403product_unavailableDieses Konto kann das Produkt nicht verkaufen: die UK-Nummer auf einem Konto, für das sie nicht freigeschaltet ist.
404package_not_foundReise-package_code nicht gefunden oder nicht mehr aktiv.
409provisioning_pendingDas VPN-Konto für diese Bestellung ist noch nicht angelegt, oder der Tarif ist abgelaufen.
429rate_limitRatenlimit überschritten - Anfragen verlangsamen.