合作伙伴 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获取产品列表
获取所有在售的旅行 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创建订单 - 旅行 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": 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_plan 创建并立即开通一笔 VPN 访问订单，从你的预付余额中扣款。响应包含用户名、密码和到期时间。若 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，以及包含 SM-DP+ 地址和激活码、可手动输入的 manual_install。后者适用于非常常见的情况：你的客户正在要安装配置文件的那部手机上看你的应用，没有第二块屏幕可以扫描。旅行 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旅行 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...",
"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=42VPN 配置
为你创建的 VPN 订单获取某台服务器的 WireGuard、OpenVPN 或 VLESS 配置。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，以及包含稳定 code 字段的 error 对象，您的代码可以检查该字段以准确了解发生了什么。
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 | 超出速率限制 - 请降低请求频率。 |