Введение Аутентификация Баланс Отчёты Список товаров Заказ - Travel Создать заказ - VPN Статус заказа Использование данных Конфигурация VPN Коды ошибок

Справочник Partner API

Все эндпоинты возвращают JSON. Вы никогда не отправляете цену - вы только указываете, что хотите купить, а цену всегда рассчитывает сам сервер, поэтому её нельзя подделать или изменить.

Базовый URL:

Base URL

https://buyukesim.com/api/v1

Аутентификация

Отправляйте ваш API-ключ как Bearer токен в каждом из следующих запросов.

Примечание: пополнение баланса - это действие только на сайте (через ваш Magic Code панели), а не часть этого API - ваш API-ключ не может создавать или финансировать пополнения.

Header

Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Аккаунт

GET/api/v1/balance

Баланс аккаунта

Сколько осталось на предоплаченном счёте. Каждый заказ уже возвращает то же число в своём блоке balance, поэтому вызывать этот метод только ради стоимости покупки не нужно. Эта точка нужна для проверок вне покупки: оповещение о пополнении, плитка в панели, пакетная задача, которая не начнёт то, что не сможет оплатить.

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

Отчёт о продажах

Что вы купили за период и сколько это стоило, с разбивкой по продуктам. Даты - календарные дни UTC по дате заказа, обе границы включаются; без них отчёт за последние 30 дней. Только оплаченные заказы: заказ с неудавшейся выдачей отменяется и возвращается на баланс, то есть он ничего не стоил. Массив orders по умолчанию ограничен 100 строками (limit, максимум 500); чтобы увидеть больше, сузьте период.

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

Товары

GET/api/v1/products

Список товаров

Получите все активные пакеты Travel eSIM (с актуальными package_code и price_usd), а также тарифы и серверы VPN-доступа, чтобы всегда знать, что можно купить, до вызова Create Order. Массив travel_data - это весь живой каталог (около 198 направлений, здесь показана одна запись); ?location_code=GB сужает его. Каждый price_usd - ВАША цена: discount_pct это ваша собственная ставка, а не фиксированная, в примере просто взято 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" }
      ]
    }
  }
}

Заказы

POST/api/v1/orders

Создать заказ - Travel eSIM

Создаёт и мгновенно обрабатывает заказ Travel eSIM для указанного package_code.

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

Создать заказ - доступ к VPN

Создаёт и сразу выдаёт заказ на доступ к VPN по указанному vpn_plan, списывая сумму с предоплаченного баланса. В ответе приходят логин, пароль и дата окончания. Если поставщик VPN недоступен, заказ всё равно считается оплаченным и сохраняется: вы получаете HTTP 202 со статусом "provisioning_pending" и id заказа, наша команда получает оповещение, а учётные данные появятся в GET /v1/orders/{id}, как только аккаунт будет создан.

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

Статус заказа и выдача

Это вызов выдачи: опрашивайте его, пока data.esim.ready не станет true, и берите профиль из data.esim.items. Каждая позиция содержит оба способа попасть в телефон - qr_code и manual_install с адресом SM-DP+ и кодом активации для ручного ввода, для очень частого случая, когда клиент читает ваше приложение на том же телефоне, куда нужно установить профиль, и второго экрана для сканирования нет. У travel eSIM puk_code равен null. Не опрашивайте status: он становится "paid" в момент списания баланса, это состояние оплаты, а не выдачи.

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

Использование данных Travel eSIM

Актуальные остаток/использованные данные, статус активации и срок действия заказа Travel eSIM, получаемые напрямую от провайдера при каждом запросе.

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

Получает конфигурацию WireGuard, OpenVPN или VLESS для одного сервера по вашему заказу VPN. server_id берите из списка серверов в разделе «Список продуктов». Серверы WireGuard также отдают OpenVPN; серверы VLESS - только VLESS. Вызывайте сколько нужно, до 20 раз в минуту.

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

Коды ошибок

Каждый ответ с ошибкой имеет одинаковую структуру: success: false на верхнем уровне и объект error со стабильным полем code, которое ваш код может проверить, чтобы точно понять, что произошло.

Error shape

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

HTTP	code	Значение
401	unauthorized	Отсутствует или недействителен API-ключ.
402	insufficient_balance	Недостаточно предоплаченного баланса для цены этого заказа.
404	package_not_found	package_code для путешествия не найден или больше не активен.
409	provisioning_pending	Аккаунт VPN для этого заказа ещё не создан, либо тариф истёк.
429	rate_limit	Превышен лимит запросов - снизьте частоту запросов.