API 文档
通过编程方式访问虚拟号码、订单和账户余额。
⟩ 认证
所有 API 请求均需 Bearer token。在控制台的账户设置中生成令牌，然后在每个请求中包含它：
Authorization: Bearer YOUR_API_TOKEN
缺少有效令牌的请求将收到 401 UNAUTHORIZED 响应。
⟩ Base URL
以下所有端点路径均相对于：
https://api.smscode.gg/v1
⟩ 响应格式
每个响应返回结构一致的 JSON。所有响应都包含 x-request-id 响应头，用于调试。
成功
{
"success": true,
"data": { ... }
} 错误
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Human-readable message"
}
} GET
/catalog/countries 返回所有可用国家列表。
参数
无
请求示例
curl -s https://api.smscode.gg/v1/catalog/countries \
-H "Authorization: Bearer YOUR_API_TOKEN"const res = await fetch("https://api.smscode.gg/v1/catalog/countries", {
headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();import requests
res = requests.get("https://api.smscode.gg/v1/catalog/countries",
headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()响应示例
200 OK
{
"success": true,
"data": [
{
"id": 6,
"code": "ID",
"name": "Indonesia",
"dial_code": "+62",
"emoji": "🇮🇩",
"active": true
}
]
} GET
/catalog/services 返回可用服务（平台）列表。可按国家筛选。
查询参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
country_id | integer | 否 | 筛选该国家可用的服务 |
请求示例
curl -s "https://api.smscode.gg/v1/catalog/services?country_id=6" \
-H "Authorization: Bearer YOUR_API_TOKEN"const res = await fetch("https://api.smscode.gg/v1/catalog/services?country_id=6", {
headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();import requests
res = requests.get("https://api.smscode.gg/v1/catalog/services",
params={"country_id": 6},
headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()响应示例
200 OK
{
"success": true,
"data": [
{
"id": 3,
"code": "wa",
"name": "WhatsApp",
"active": true
}
]
} GET
/catalog/products 返回分页的可用产品列表。可按国家和/或平台筛选。
查询参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
country_id | integer | 否 | 按国家 ID 筛选 |
platform_id | integer | 否 | 按平台/服务 ID 筛选 |
sort | string | 否 | 排序方式：price_asc（默认）、price_desc、available_asc、available_desc、name_asc、name_desc |
limit | integer | 否 | 每页结果数（1-10,000，默认 1,000） |
page | integer | 否 | 页码（最小 1，默认 1） |
请求示例
curl -s "https://api.smscode.gg/v1/catalog/products?country_id=6&platform_id=3&limit=10&page=1" \
-H "Authorization: Bearer YOUR_API_TOKEN"const params = new URLSearchParams({
country_id: "6", platform_id: "3", limit: "10", page: "1",
});
const res = await fetch(`https://api.smscode.gg/v1/catalog/products?${params}`, {
headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();import requests
res = requests.get("https://api.smscode.gg/v1/catalog/products",
params={"country_id": 6, "platform_id": 3, "limit": 10, "page": 1},
headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()响应示例
200 OK
{
"success": true,
"data": [
{
"id": 142,
"name": "WhatsApp Indonesia",
"country_id": 6,
"platform_id": 3,
"available": 42,
"price": 15000,
"active": true
}
],
"meta": { "page": 1, "limit": 10, "count": 1 }
} GET
/catalog/exchange-rate 返回货币对的当前汇率。用于价格换算。
查询参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
pair | string | 否 | 货币对（默认：USD/IDR） |
请求示例
curl -s "https://api.smscode.gg/v1/catalog/exchange-rate?pair=USD/IDR" \
-H "Authorization: Bearer YOUR_API_TOKEN"const res = await fetch("https://api.smscode.gg/v1/catalog/exchange-rate?pair=USD/IDR", {
headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();import requests
res = requests.get("https://api.smscode.gg/v1/catalog/exchange-rate",
params={"pair": "USD/IDR"},
headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()响应示例
200 OK
{
"success": true,
"data": {
"pair": "USD/IDR",
"base_currency": "USD",
"quote_currency": "IDR",
"rate": 16250
}
} GET
/balance 返回已认证用户的账户余额（单位：IDR）。
参数
无
请求示例
curl -s https://api.smscode.gg/v1/balance \
-H "Authorization: Bearer YOUR_API_TOKEN"const res = await fetch("https://api.smscode.gg/v1/balance", {
headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();import requests
res = requests.get("https://api.smscode.gg/v1/balance",
headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()响应示例
200 OK
{
"success": true,
"data": {
"currency": "IDR",
"balance": 500000
}
} GET
/orders 返回已认证用户的订单列表，按最近排序。支持按状态筛选和通过 offset 分页。
查询参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
limit | integer | 否 | 最大结果数（1-100，默认 20） |
offset | integer | 否 | 跳过的结果数（默认 0） |
status | string | 否 | 按状态筛选：ACTIVE、OTP_RECEIVED、COMPLETED、CANCELED、EXPIRED（不区分大小写） |
请求示例
curl -s "https://api.smscode.gg/v1/orders?limit=5&status=ACTIVE" \
-H "Authorization: Bearer YOUR_API_TOKEN"const params = new URLSearchParams({
limit: "5", status: "ACTIVE", offset: "0",
});
const res = await fetch(`https://api.smscode.gg/v1/orders?${params}`, {
headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();import requests
res = requests.get("https://api.smscode.gg/v1/orders",
params={"limit": 5, "status": "ACTIVE", "offset": 0},
headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()响应示例
200 OK
{
"success": true,
"data": [
{
"id": 1001,
"status": "ACTIVE",
"created_at": "2026-02-25T10:00:00Z",
"product_id": 142,
"phone_number": "+6281234567890",
"amount": 15000,
"otp_code": null,
"otp_received_at": null,
"expires_at": "2026-02-25T10:20:00Z",
"canceled_at": null,
"failed_reason": null
}
]
} GET
/orders/{id} 根据 ID 返回单个订单。仅返回已认证用户的订单。
路径参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 订单 ID（路径参数） |
请求示例
curl -s https://api.smscode.gg/v1/orders/1001 \
-H "Authorization: Bearer YOUR_API_TOKEN"const res = await fetch("https://api.smscode.gg/v1/orders/1001", {
headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();import requests
res = requests.get("https://api.smscode.gg/v1/orders/1001",
headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()响应示例
200 OK
{
"success": true,
"data": {
"id": 1001,
"status": "OTP_RECEIVED",
"created_at": "2026-02-25T10:00:00Z",
"product_id": 142,
"phone_number": "+6281234567890",
"amount": 15000,
"otp_code": "123456",
"otp_received_at": "2026-02-25T10:05:00Z",
"expires_at": "2026-02-25T10:20:00Z",
"canceled_at": null,
"failed_reason": null
}
} GET
/orders/active 列出所有当前活跃的订单（ACTIVE + OTP_RECEIVED）。用于轮询 OTP 状态更新。
参数
无
请求示例
curl -s https://api.smscode.gg/v1/orders/active \
-H "Authorization: Bearer YOUR_API_TOKEN"const res = await fetch("https://api.smscode.gg/v1/orders/active", {
headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();import requests
res = requests.get("https://api.smscode.gg/v1/orders/active",
headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()响应示例
200 OK
{
"success": true,
"data": [
{
"id": 1001,
"status": "OTP_RECEIVED",
"otp_code": "123456",
"otp_message": "Your verification code is 123456",
"otp_received_at": "2026-02-25T10:05:00Z",
"expires_at": "2026-02-25T10:20:00Z",
"failed_reason": null
},
{
"id": 1002,
"status": "ACTIVE",
"otp_code": null,
"otp_message": null,
"otp_received_at": null,
"expires_at": "2026-02-25T10:50:00Z",
"failed_reason": null
}
]
} POST
/orders/create 创建新的虚拟号码订单。自动扣除余额。支持可选的 Idempotency-Key 请求头，防止网络重试时产生重复订单。
请求体
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
product_id | integer | 是 | 要订购的产品 ID |
quantity | integer | 否 | 数量（1-100，默认 1） |
传递 Idempotency-Key 请求头（任意唯一字符串），可安全重试请求而不会创建重复订单。
请求示例
curl -s -X POST https://api.smscode.gg/v1/orders/create \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id-123" \
-d '{"product_id":142,"quantity":1}'const res = await fetch("https://api.smscode.gg/v1/orders/create", {
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_TOKEN",
"Content-Type": "application/json",
"Idempotency-Key": "unique-request-id-123",
},
body: JSON.stringify({ product_id: 142, quantity: 1 }),
});
const data = await res.json();import requests
res = requests.post("https://api.smscode.gg/v1/orders/create",
json={"product_id": 142, "quantity": 1},
headers={
"Authorization": "Bearer YOUR_API_TOKEN",
"Idempotency-Key": "unique-request-id-123",
})
data = res.json()响应示例
200 OK
{
"success": true,
"data": {
"orders": [
{
"id": 1002,
"status": "ACTIVE",
"phone_number": "+6281234567891",
"otp_code": null,
"otp_received_at": null,
"expires_at": "2026-02-25T10:50:00Z",
"failed_reason": null
}
],
"failed_count": 0
}
} POST
/orders/cancel 取消活跃订单。租用费用将退回账户余额。
请求体
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 要取消的订单 ID |
请求示例
curl -s -X POST https://api.smscode.gg/v1/orders/cancel \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id":1001}'const res = await fetch("https://api.smscode.gg/v1/orders/cancel", {
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_TOKEN",
"Content-Type": "application/json",
},
body: JSON.stringify({ id: 1001 }),
});
const data = await res.json();import requests
res = requests.post("https://api.smscode.gg/v1/orders/cancel",
json={"id": 1001},
headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()响应示例
200 OK
{
"success": true,
"data": {
"order_id": 1001,
"status": "CANCELED",
"refund_amount": 15000,
"new_balance": 515000
}
} POST
/orders/finish 在收到 OTP 后将订单标记为已完成。这会立即释放号码，而非等待过期。
请求体
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 要完成的订单 ID |
请求示例
curl -s -X POST https://api.smscode.gg/v1/orders/finish \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id":1001}'const res = await fetch("https://api.smscode.gg/v1/orders/finish", {
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_TOKEN",
"Content-Type": "application/json",
},
body: JSON.stringify({ id: 1001 }),
});
const data = await res.json();import requests
res = requests.post("https://api.smscode.gg/v1/orders/finish",
json={"id": 1001},
headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()响应示例
200 OK
{
"success": true,
"data": {
"order_id": 1001,
"status": "COMPLETED"
}
} POST
/orders/resend 请求平台向租用号码重新发送 SMS。并非所有平台都支持重发 — 请查看响应中的 resent 字段。
请求体
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 要重发 SMS 的订单 ID |
请求示例
curl -s -X POST https://api.smscode.gg/v1/orders/resend \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id":1001}'const res = await fetch("https://api.smscode.gg/v1/orders/resend", {
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_TOKEN",
"Content-Type": "application/json",
},
body: JSON.stringify({ id: 1001 }),
});
const data = await res.json();import requests
res = requests.post("https://api.smscode.gg/v1/orders/resend",
json={"id": 1001},
headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()响应示例
200 OK
{
"success": true,
"data": {
"order_id": 1001,
"status": "ACTIVE",
"resent": true
}
} GET
/webhook 返回您当前的 webhook 通知配置。
参数
无
请求示例
curl -s https://api.smscode.gg/v1/webhook \
-H "Authorization: Bearer YOUR_API_TOKEN"const res = await fetch("https://api.smscode.gg/v1/webhook", {
headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();import requests
res = requests.get("https://api.smscode.gg/v1/webhook",
headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()响应示例
200 OK
{
"success": true,
"data": {
"webhook_url": "https://example.com/webhook",
"webhook_secret": "a1b2c3d4e5f6..."
}
} PATCH
/webhook 更新您的 webhook URL 和/或密钥。首次设置 URL 时会自动生成密钥。发送空字符串可清除。URL 必须使用 HTTPS。
请求体
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
webhook_url | string | 否 | 接收 webhook 事件的 HTTPS URL（空字符串表示清除） |
webhook_secret | string | 否 | 用于 HMAC-SHA256 签名的共享密钥（首次设置时自动生成） |
至少需要一个字段。
请求示例
curl -s -X PATCH https://api.smscode.gg/v1/webhook \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"webhook_url":"https://example.com/webhook"}'const res = await fetch("https://api.smscode.gg/v1/webhook", {
method: "PATCH",
headers: {
Authorization: "Bearer YOUR_API_TOKEN",
"Content-Type": "application/json",
},
body: JSON.stringify({ webhook_url: "https://example.com/webhook" }),
});
const data = await res.json();import requests
res = requests.patch("https://api.smscode.gg/v1/webhook",
json={"webhook_url": "https://example.com/webhook"},
headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()响应示例
200 OK
{
"success": true,
"data": {
"webhook_url": "https://example.com/webhook",
"webhook_secret": "a1b2c3d4e5f6..."
}
} POST
/webhook/test 向已配置的 webhook URL 发送测试事件。返回服务器响应的 HTTP 状态码。可用于在正式使用前验证端点是否正常工作。
参数
无
请求示例
curl -s -X POST https://api.smscode.gg/v1/webhook/test \
-H "Authorization: Bearer YOUR_API_TOKEN"const res = await fetch("https://api.smscode.gg/v1/webhook/test", {
method: "POST",
headers: { Authorization: "Bearer YOUR_API_TOKEN" },
});
const data = await res.json();import requests
res = requests.post("https://api.smscode.gg/v1/webhook/test",
headers={"Authorization": "Bearer YOUR_API_TOKEN"})
data = res.json()响应示例
200 OK
{
"success": true,
"data": {
"status_code": 200
}
}⟩ Webhook 通知
配置 webhook URL 以接收订单事件的实时推送通知，无需轮询。这是机器人脚本的推荐方式。
事件列表
| 事件 | 触发条件 |
|---|---|
order.otp_received | OTP 验证码已送达租用号码 |
order.completed | 订单已标记为完成（手动或到期） |
order.expired | 订单过期且未收到 OTP（余额已退还） |
order.canceled | 订单被用户取消（余额已退还） |
Payload
Webhook POST 请求体
{
"event": "order.otp_received",
"timestamp": "2026-02-25T12:00:00Z",
"data": {
"order_id": 1001,
"phone_number": "+628123456789",
"otp_code": "1234",
"otp_message": "Your verification code is 1234",
"product_id": 42,
"country": "Indonesia",
"platform": "WhatsApp"
}
}签名验证
每个 webhook 请求都包含 X-Webhook-Signature 请求头，其中包含使用您的 webhook_secret 作为密钥对请求体计算的 HMAC-SHA256 签名：
X-Webhook-Signature: sha256={HMAC-SHA256(body, webhook_secret)}
在您的服务器上验证此签名以确保请求的真实性。发送采用即发即忘模式，3 秒超时且不重试。
⟩ 速率限制
API 请求按端点分组进行速率限制。超出限制将返回 429 Too Many Requests，并附带 Retry-After 响应头，指示需要等待的秒数。
| 端点分组 | 限制 | 时间窗口 |
|---|---|---|
| 目录（国家、服务、产品、汇率） | 1,200 次请求 | 60 秒 |
| 余额 | 600 次请求 | 60 秒 |
| 订单查询（列表、详情、活跃） | 1,200 次请求 | 60 秒 |
| 创建订单 | 1,200 次请求 | 60 秒 |
| 取消订单 | 600 次请求 | 60 秒 |
| 订单操作（完成、重发） | 600 次请求 | 60 秒 |
| Webhook 配置（查询、更新、测试） | 120 次请求 | 60 秒 |
⟩ 错误代码
错误响应在 error.code 中包含以下代码之一：
| 代码 | HTTP | 说明 |
|---|---|---|
UNAUTHORIZED | 401 | 缺少或无效的 API 令牌 |
FORBIDDEN | 403 | 访问被拒绝 |
NOT_FOUND | 404 | 资源未找到（订单、汇率等） |
CONFLICT | 409 | 重复请求或资源冲突 |
INSUFFICIENT_BALANCE | 409 | 余额不足，无法创建订单 |
VALIDATION_ERROR | 422 | 请求参数验证失败 |
RATE_LIMIT_EXCEEDED | 429 | 请求过于频繁（请查看 Retry-After 响应头） |
INTERNAL_ERROR | 500 | 服务器内部错误 |
PROVIDER_ERROR | 422 | 上游 SMS 提供商拒绝了请求 |
CANCEL_TOO_EARLY | 409 | 订单创建时间过短，无法取消 — 请等待 2 分钟 |
SERVICE_UNAVAILABLE | 503 | 服务暂时不可用（维护中） |