API 文档

每次请求必须包含你的 API key：

Authorization: Bearer jm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

也可以用替代头： X-API-Key: jm_xxx…

在 /account/api-keys 创建与撤销 key。每个用户最多 10 个有效 key。完整 token 仅在创建时显示一次 —— 请妥善保管。

所有错误返回 JSON：

{ "ok": false, "code": "RATE_LIMITED", "message": "..." }

限流: 按 key 维度，60 秒滑动窗口。写入接口（下单 / 取消 / next-sms）10 次/分；查询接口（账户 / 服务 / 价格 / 列表）60 次/分。

查询当前余额与基本信息。

curl https://jiema.my/api/v1/account \
  -H "Authorization: Bearer jm_xxx"

# 200 OK
{ "ok": true, "data": {
  "id": "clxxxxxxxxxxx",
  "balanceCents": "1200",       // string to preserve precision; $12.00
  "referralCode": "abc123",
  "displayName": "Alice",
  "lang": "en"
}}

可下单的服务列表 + 库存。服务端缓存约 5 分钟。

curl https://jiema.my/api/v1/services -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "items": [
  { "code": "tg", "slug": "telegram", "name": "Telegram",
    "minCostUsd": 0.18, "totalCount": 1234, "countryCount": 24 },
  ...
] }}

下单时 service 参数可填上游 code，也可填友好的 slug。

curl https://jiema.my/api/v1/countries -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "items": [
  { "id": 7, "slug": "my", "name": "Malaysia" },
  ...
] }}

id 是上游数字国家 id；slug 是 SEO 短码（如 my / us）。下单时 country 参数两种都接受。

给定服务的各国价格 + 库存数。价格已经包含运营在后台配置的加价 / 折扣。

curl "https://jiema.my/api/v1/prices?service=tg" -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": {
  "service": "tg",
  "items": [
    { "countryId": 7, "countrySlug": "my", "priceCents": "32", "count": 540 },
    ...
  ]
}}

创建一笔短信验证订单。系统从上游锁一个号码，并从你的余额扣相应金额。

curl -X POST https://jiema.my/api/v1/orders \
  -H "Authorization: Bearer jm_xxx" \
  -H "content-type: application/json" \
  -d '{ "service": "tg", "country": 7 }'

{ "ok": true, "data": {
  "id": "ckxxxxx",
  "status": "WAITING",
  "service": "tg",
  "country": "7",
  "phone": "+60123456789",
  "expiresAt": "2026-05-22T08:30:00.000Z",
  "chargedCents": "32"
}}

除 service / country 外无可选字段。

常见错误码：INSUFFICIENT（余额不足）、NO_NUMBERS、BAD_SERVICE、BAD_COUNTRY。

轮询直到 status 变成 RECEIVED 且 smsBody 不为空。

curl https://jiema.my/api/v1/orders/ckxxxxx -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": {
  "id": "ckxxxxx",
  "status": "RECEIVED",
  "phone": "+60123456789",
  "smsBody": "Your verification code is 123456",
  "smsHistory": [
    { "body": "Your verification code is 123456", "receivedAt": "..." }
  ],
  "smsReceivedAt": "2026-05-22T08:12:34.000Z",
  ...
}}

状态机：WAITING（号码激活中，等待短信）· RECEIVED（已收到验证码）· COMPLETED / FAILED / CANCELLED 是终态。

建议轮询间隔 3–5 秒。本接口内部会触发上游同步，即使后台 worker 繁忙，你的轮询也能推进状态。

取消尚未收到验证码的订单。金额全额退回余额。

curl -X POST https://jiema.my/api/v1/orders/ckxxxxx/cancel \
  -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "id": "ckxxxxx", "status": "CANCELLED" }}

若号码已收到任何短信，返回 CODE_RECEIVED；若状态已被并发改变，返回 ALREADY_CHANGED。

在 RECEIVED 之后调用，让上游保留号码继续等待下一条短信（在窗口期内不再额外收费）。

curl -X POST https://jiema.my/api/v1/orders/ckxxxxx/next-sms \
  -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "id": "ckxxxxx", "status": "WAITING" }}

光标分页列出你的近期订单。

curl "https://jiema.my/api/v1/orders?limit=20" -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": {
  "items": [ { "id": "ck...", "status": "RECEIVED", "service": "tg", ... }, ... ],
  "nextCursor": "ck..." | null
}}

可选查询参数：status · limit 1–100（默认 20）· cursor = 上一页的 nextCursor。

1. 通过网页充值 → 调 GET /v1/account 确认余额。
2. 选择服务：GET /v1/services 和 GET /v1/prices?service=tg。
3. 下单：POST /v1/orders 传 service + country。
4. 拿到 data.phone，从你的客户端触发上游发短信（比如填到 Telegram 注册流程里）。
5. 每 3–5 秒轮询 GET /v1/orders/:id。当 status === "RECEIVED" 时读取 smsBody。
6. 如果收到的短信不是想要的，或想等下一条：调 POST /v1/orders/:id/next-sms → 状态回到 WAITING。
7. 完成。如果还没收到任何短信就要取消：调 POST /v1/orders/:id/cancel，全额退款。