NumFlow API 完全ドキュメント

アカウント単位のAPIキー、残高予約、冪等注文、統一エラー応答を使ってSMS認証フローを自動化します。

すべてのAPIリクエストに、現在のアカウントで生成したNumFlow APIキーが必要です。残高、権限、レート制限、リスク制御はそのアカウントに適用されます：X-API-Key + HMAC-SHA256 signature headers

開発者が呼び出すのはNumFlow APIのみです。APIキー、残高、注文、ウォレット履歴はアカウントごとに分離され、機密情報や他アカウントのデータは公開されません。

課金モデル：番号割り当て後に表示価格を予約し、最初のSMSコード受信後に確定します。コードが届かず、キャンセルまたは期限切れ処理が成功した場合は予約額を解放します。リクエスト本文の金額は課金根拠に使用しません。

推奨フロー

1. 残高を照会し、利用可能残高が十分か確認します。

2. 業務注文ごとに一意のIdempotency-Keyを使い、ネットワーク再試行時は同じ値を再利用します。

3. 3〜5秒ごとにSMS結果を照会し、注文のexpires_atを受信期限として使用します。

4. コード受信後は自動で完了・課金されます。有効期間中は同じ注文を照会し、コードがない場合は状態が許可したときだけキャンセルします。

エラー応答は統一されたJSON形式です： { success: false, error: { code, message } }

API_UNAUTHENTICATEDAPIキーがない、無効、または取り消されています。

API_SIGNATURE_REQUIREDリクエスト本文またはパスパラメータが無効です。

API_SIGNATURE_INVALID利用可能残高が不足しています。

API_REPLAY_DETECTEDリクエストが多すぎます。少し待って再試行してください。

IDEMPOTENCY_KEY_REQUIRED選択した国、サービス、回線に利用可能な番号がありません。

IDEMPOTENCY_KEY_REUSED国コードが無効です。

IDEMPOTENCY_RECOVERY_REQUIRED回線・通信事業者コードが無効です。

VALIDATION_ERRORサービスコードが無効です。

INSUFFICIENT_WALLET_BALANCE注文が存在しないか、現在のAPIキーのアカウントに属していません。

RATE_LIMITEDSMSコード受信前に注文を完了できません。

NO_FREE_PHONESコード受信済みまたは終了状態のためキャンセルできません。

BAD_COUNTRYこの環境で番号サービスが設定されていません。

BAD_OPERATOR番号サービスが一時的に利用できません。

NO_PRODUCT番号注文が一時的に利用できません。継続する場合はサポートへ連絡してください。

ORDER_NOT_FOUND処理を完了できませんでした。注文状態を更新して再試行してください。

SMS_CODE_REQUIRED

ORDER_NOT_CANCELABLE

ORDER_STATE_CONFLICT

ORDER_BILLING_CONFLICT

NUMBER_SERVICE_NOT_CONFIGURED

NUMBER_SERVICE_UNAVAILABLE

NUMBER_SERVICE_TEMPORARILY_UNAVAILABLE

BUSINESS_ERROR

アカウントを作成し、チャージコードで残高を追加して、アカウントセンターからAPIキーを生成します。課金、レート制限、注文記録はアカウントごとに分離されます。