API ドキュメント

すべてのリクエストには API key を含める必要があります:

Authorization: Bearer jm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

代替のヘッダー形式: X-API-Key: jm_xxx…

/account/api-keys で key の作成と失効ができます。ユーザーごとに有効な key は最大 10 個まで保持できます。完全な token は作成時に一度だけ表示されますので、安全に保管してください。

すべてのエラーは JSON を返します:

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

レート制限: key 単位、60s のスライディングウィンドウです。書き込み系エンドポイント（orders, cancel, next-sms）は 10 req/min、読み取り系エンドポイント（account, services, prices, list）は 60 req/min です。

現在の残高と基本プロフィールを取得します。

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 },
  ...
] }}

order 作成時には code（またはわかりやすい slug）を service フィールドに指定してください。

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

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

id は upstream の数値 country id で、slug は SEO 用のショートコード（例: "my" / "us"）です。どちらの形式も country フィールドとして利用できます。

指定した service の国別価格と在庫数です。価格には運用側で設定したマークアップ／割引が既に反映されています。

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 },
    ...
  ]
}}

SMS 認証 order を作成します。システムは upstream から電話番号を確保し、課金額をお客様の残高から差し引きます。

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 が null でなくなるまでポーリングしてください。

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（番号アクティブ、SMS 待機中）・RECEIVED（コード到着）・COMPLETED / FAILED / CANCELLED は終了状態です。

推奨ポーリング間隔: 3〜5 秒ごとです。このエンドポイント内で upstream 同期が走るため、バックグラウンドワーカーがビジー状態でもポーリングによって状態が進みます。

まだコードを受け取っていない order をキャンセルします。全額を残高に返金します。

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

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

番号がすでに何らかの SMS を受信している場合は CODE_RECEIVED、ステータスが同時に変更された場合は ALREADY_CHANGED で拒否されます。

RECEIVED の後に呼び出すと、upstream に番号を有効なまま保持してもらい、別の SMS を待ちます（アクティブウィンドウ内であれば追加課金はありません）。

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

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

最近の order を cursor ページングで一覧表示します。

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. Web UI からチャージし → GET /v1/account で残高を確認します。
2. service を選択します: GET /v1/services および GET /v1/prices?service=tg。
3. order を作成します: POST /v1/orders に service + country を渡します。
4. data.phone を読み取り、クライアントから upstream の SMS をトリガーします（例: Telegram の登録に貼り付け）。
5. GET /v1/orders/:id を 3〜5 秒ごとにポーリングします。status === "RECEIVED" になったら smsBody を読み取ります。
6. SMS が間違っていた、または 2 件目のコードが必要な場合: POST /v1/orders/:id/next-sms → WAITING に戻ります。
7. 完了です。SMS が届く前にキャンセルする場合: POST /v1/orders/:id/cancel で全額返金されます。