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:
https://buyukesim.com/api/v1Authentifizierung
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.
Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxxKonto
/api/v1/balanceKontoguthaben
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.
curl "https://buyukesim.com/api/v1/balance" \
-H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"{
"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"
}
}
}/api/v1/reports?from=2026-08-01&to=2026-08-31Verkaufsbericht
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.
curl "https://buyukesim.com/api/v1/reports?from=2026-08-01&to=2026-08-31" \
-H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"{
"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
/api/v1/productsProdukte 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.
curl "https://buyukesim.com/api/v1/products" \
-H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"{
"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
/api/v1/ordersBestellung erstellen - Reise-eSIM
Erstellt und wickelt sofort eine Reise-eSIM-Bestellung für den angegebenen package_code ab.
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"
}'{
"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" }
}
}/api/v1/ordersBestellung 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.
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"
}'{
"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" }
}
}/api/v1/orders/98422Bestellstatus & 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.
curl "https://buyukesim.com/api/v1/orders/98422" \
-H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"{
"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
}
}
]
}
}
}/api/v1/orders/98422/usageReise-eSIM-Datennutzung
Live verbleibende/genutzte Daten, Aktivierungs- und Ablaufstatus für eine Reise-eSIM-Bestellung, bei jedem Aufruf frisch vom Anbieter abgerufen.
curl "https://buyukesim.com/api/v1/orders/98422/usage" \
-H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"{
"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"
}
}
}/api/v1/orders/98422/topupsAufladeoptionen 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.
curl "https://buyukesim.com/api/v1/orders/98422/topups" \
-H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"{
"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"
}
]
}
}/api/v1/topupsDaten 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.
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"
}'{
"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" }
}
}/api/v1/orders/98423/vpn-config?protocol=wireguard&server_id=42VPN-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.
curl "https://buyukesim.com/api/v1/orders/98423/vpn-config?protocol=wireguard&server_id=42" \
-H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"{
"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%.
"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.
/api/v1/ordersBestellung 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.
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"
}'{
"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" }
}
}/api/v1/orders/98421Auslieferung 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.
curl "https://buyukesim.com/api/v1/orders/98421" \
-H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"{
"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
}
}
]
}
}
}/api/v1/renewalsUK-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.
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"
}'{
"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.
{
"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. |
| 403 | product_unavailable | Dieses Konto kann das Produkt nicht verkaufen: die UK-Nummer auf einem Konto, für das sie nicht freigeschaltet ist. |
| 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. |
