SMS認証を自動化する: API完全ガイド

たまに登録する程度なら、Webサイトで十分です。数回クリックして1件のSMSを待つだけで済みます。しかし自動テストや一括登録スクリプト、CIパイプライン、無人で動くボットが認証コードを取得する必要がある場面では、それでは足りません。Webサイトにはできないことですが、APIならできます。この記事では、ゼロから実際に動くフローを構築するために必要なことをすべて説明します。

ステップ1: APIキーを取得する

ログイン後、/account/api-keysにアクセスして作成します。キーはjm_のあとにランダムな文字列が続く形式です。平文が表示されるのは作成時の一度きりです——保存されるのはキー自体ではなくハッシュ値なので、「キーを復元する」機能はありません。失くした場合は削除して新しく作り直してください。

すべてのリクエストは標準的なBearer認証を使用します:

Authorization: Bearer jm_your_key

キーはパスワードと同様に扱ってください——公開リポジトリにコミットしたり、デバッグのためにチャットに貼り付けて他人に渡したりしないこと。漏洩の疑いがある場合は/account/api-keysに戻って削除し、新しいキーを発行してください。古いキーは即座に無効になります。

ステップ2: サービスと国を選ぶ

注文には2つの情報が必要です:service(サービスコード)とcountry(国のID)。まずはカタログを一覧取得しましょう:

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

各項目にはcodeフィールドがあります(Telegramならtg)。これを注文エンドポイントにそのまま渡すのが、自分でslugを組み立てるより確実です。特定サービスの国別リアルタイム価格と在庫を見るには、serviceパラメータを追加します:

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

items内の各エントリにはcountryId / priceCents / count(現在利用可能な番号数)が含まれます。注文前にcountを確認してください——0の場合は注文が確実に失敗するので、わざわざ呼び出して痛い目を見る必要はありません。

ステップ3: 注文する

curl -X POST https://jiema.my/api/v1/orders \
  -H "Authorization: Bearer jm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"service":"tg","country":"6"}'

注文が成功すると、電話番号と有効期限が返されます:

{
  "ok": true,
  "data": {
    "id": "cm...",
    "status": "WAITING",
    "phone": "62812xxxxxxx",
    "expiresAt": "2026-08-01T12:15:00.000Z",
    "chargedCents": "40"
  }
}

この時点で課金が発生します——chargedCentsは実際に差し引かれた金額(セント単位)です。この番号を対象アプリに渡して認証コードを受信させ、次のステップに進みましょう。

ステップ4: コードをポーリングする

WebSocketやwebhookによるプッシュ通知はありません——SMSの内容はGET /api/v1/orders/:idをポーリングし、smsBodyがnullでなくなるまで待つことで取得します:

while true; do
  RESP=$(curl -s https://jiema.my/api/v1/orders/$ORDER_ID \
    -H "Authorization: Bearer jm_your_key")
  BODY=$(echo "$RESP" | jq -r '.data.smsBody')
  if [ "$BODY" != "null" ]; then
    echo "Code received: $BODY"
    break
  fi
  sleep 5
done

5秒間隔がひとまず妥当な出発点です——番号は15分間有効で、クエリのレート制限(1分あたり60リクエスト)にも十分な余裕があります。待ちきれないなら3秒でも問題ありません。ただ1秒間隔でポーリングしてもコードが早く届くわけではなく、レート制限を無駄に消費するだけです。

落とし穴

• レート制限はユーザー単位で、キー単位ではありません。書き込み系エンドポイント(order / cancel / next-sms)はユーザーごとに10回/分、クエリ系は60回/分に制限されます。キーを追加で発行しても上限は上がりません——すべて同じ上限を共有します。
• 番号は15分で失効します。コードを受信せずに失効した未使用の番号は自動的に返金されます——申請の必要はありません。ただし、自分のパイプライン側で番号を実際に使うまで時間がかかりすぎる場合(たとえばキューで待たされているなど)、使う頃には番号が既に失効していることになります。
• 1つの番号で複数のコードを受信できます。対象アプリが2段階でSMSを送る場合(登録確認、そして別のログインコード)、1件目を受信したらPOST /api/v1/orders/:id/next-smsを呼び出して「この分は完了、引き続き待機して」と伝えてください。新しい番号のために新規注文する必要はありません。
• コードが届いた後はキャンセルできません。POST /api/v1/orders/:id/cancelは番号がまだコード待ちの間であれば即座に返金しますが、smsBodyが一度でもnullでなくなった後に同じ呼び出しを行うと、代わりにCODE_RECEIVEDエラーが返されます——支払った分の対価は既に受け取っているため、取り消すことはできません。
• statusを一度確認しただけで諦めないでください。statusはWAITINGからRECEIVEDに変化します。失効するまでWAITINGのままの場合、たいていはその国/サービスの組み合わせにおける到達率の問題です——別の国で新しく注文し直す方が、待ち続けるより早く解決することが多いです。

この先へ

以上で、注文からコード受信までの主要なフローはカバーできました。全エンドポイントの完全なフィールド一覧、エラーコード、エッジケースについては/api-docsを参照してください。数十のアカウントの認証フローを同時に維持するような大規模運用の場合は、各注文のポーリングループを個別に管理してください。単一の直列ループでキューイングすると、最初の番号の結果を待っている間に、後続の番号が失効してしまいます。