购买 eSIM
返回概览下载 Postman 集合
简介身份验证获取产品列表创建订单订单状态流量使用情况错误代码

合作伙伴 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/products

获取产品列表

获取英国号码产品及所有有效的旅行 eSIM 套餐（含当前 package_code 和 price_usd），以便在调用创建订单之前始终了解可购买的商品。

Request
curl "https://buyukesim.com/api/v1/products" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
Response
{
  "success": true,
  "data": {
    "discount_pct": 15,
    "uk_number": {
      "type": "uk_number",
      "retail_price_usd": 25,
      "price_usd": 21.25,
      "currency": "USD",
      "min_quantity": 1,
      "max_quantity": 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.09,
        "volume_label": "1 GB",
        "duration": 7,
        "duration_unit": "DAY"
      }
    ]
  }
}

订单

POST/api/v1/orders

创建订单 - 英国号码

创建并立即交付一个英国号码 (+44) 订单，从您的预付余额中扣除。

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,
  "reference": "order-1234"
}'
Response
{
  "success": true,
  "data": {
    "order_id": 98421,
    "reference": "order-1234",
    "status": "paid",
    "product": {
      "type": "uk_number",
      "quantity": 1,
      "retail_price_usd": 25,
      "discount_pct": 15,
      "price_usd": 21.25
    },
    "lookup_code": "K7M9-2XP4",
    "created_at": "2026-07-06T20:00:00+00:00"
  }
}
POST/api/v1/orders

创建订单 - 旅行 eSIM

为指定的 package_code 创建并立即交付一个旅行 eSIM 订单。

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": 15,
      "price_usd": 5.09
    },
    "lookup_code": null,
    "created_at": "2026-07-06T20:00:00+00:00"
  }
}
GET/api/v1/orders/98421

订单状态

查询您创建的订单状态并获取 QR / PUK 详情。

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, "retail_price_usd": 25, "price_usd": 21.25 },
    "lookup_code": "K7M9-2XP4",
    "esim": {
      "ready": true,
      "items": [
        { "qr_code": "https://.../serve_qr.php?...", "iccid": "8944...", "puk_code": "12345678" }
      ]
    }
  }
}
GET/api/v1/orders/98422/usage

旅行 eSIM 流量使用情况

获取旅行 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...",
      "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"
    }
  }
}

错误代码

每个错误响应结构相同：顶层的 success: false，以及包含稳定 code 字段的 error 对象，您的代码可以检查该字段以准确了解发生了什么。

Error shape
{
  "success": false,
  "error": { "code": "insufficient_balance", "message": "..." }
}
HTTPcode含义
401unauthorized缺少或无效的 API 密钥。
402insufficient_balance预付余额不足以支付此订单价格。
404package_not_found未找到旅行 package_code 或已不再有效。
429rate_limit超出速率限制 - 请降低请求频率。