> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # SMS認証コード送信API：電話番号OTPを送信 > DiditのPOST /v3/phone/send/でSMSのワンタイムコードを送信できます。ブロックされた番号は自動で再試行され、有効期間は5分です。従量課金制で月額の最低料金はありません。 ## SMSにブランド名を表示する SMSのコードには、Business Consoleで設定したアプリケーションのSMS送信者名が追加料金なしで表示されます。 > **Acme Bank**の認証コードは123456です 特定のコードだけを別の名前で送信するには、`options.sms_sender_name`を指定します(1〜30文字。使用できるのは英字、数字、スペース、' & - !のみで、数字だけの名前は使用できません)。 ```json theme={null} { "phone_number": "+14155552671", "options": { "preferred_channel": "sms", "sms_sender_name": "Acme Bank" } } ``` この規則に合わない名前を指定すると`400`が返され、コードは送信されません。 WhatsAppのコードは固定のメッセージを使用するため、ブランド名は表示されません。自社の名前で送信するには、Business Consoleで自社のWhatsApp Business番号を接続してください。詳しくは[自社の番号からWhatsAppコードを送信する](https://docs.didit.me/ja/core-technology/phone-verification/overview.md#自社の番号からwhatsappコードを送信する)を参照してください。 コードにどの名前が表示されるか、および新しい名前の1日あたりの上限については、[ブランド名入りの認証メッセージ](https://docs.didit.me/ja/core-technology/phone-verification/overview.md#ブランド名入りの認証メッセージ)を参照してください。 ## プロバイダー障害への対応 電話サービスプロバイダーが一時的に利用できない場合、このエンドポイントは`502`と、固定の機械可読コードを返します。 ```json theme={null} { "detail": "The phone verification provider is temporarily unavailable.", "code": "phone_provider_unavailable" } ``` このレスポンスは再試行可能として扱ってください。短いバックオフを設け、有効な電話番号やコードの変更をユーザーに求めるのではなく、サービスが一時的に利用できない旨のメッセージを表示してください。 ## OpenAPI ````yaml ja/openapi-25.json POST /v3/phone/send/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: 本人確認API。x-api-keyヘッダーで認証します。 servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/phone/send/: post: tags: - Standalone APIs summary: 電話番号コードを送信 description: >- WhatsApp、SMS、またはその他の対応チャネルで電話番号にワンタイムパスコード(OTP)を送信し、[`POST /v3/phone/check/`](/ja/standalone-apis/phone-check)で検証します。 **送信とチェックの対応関係。** 検証の状態は、アプリケーションとE.164形式の`phone_number`の組み合わせで管理されます。チェックの呼び出しは`request_id`を受け取りません。新しい送信ごとに保留中の検証が作成され、その有効期間は**5分間**です。期間が終わる前に、同じ電話番号とユーザーが受け取ったコードでチェックを呼び出してください。検証が保留中の間に同じ番号に対して再度送信を呼び出すと、同じ検証のコードが再送信されます(`status: "Retry"`、同じ`request_id`)。この方法で紐づけられる再試行は最大1回(送信は合計2回)です。それ以降の送信では、新しい`request_id`で新規の検証が開始されます。5分間の期間は最初の送信から計測され、再試行によって延長されることはありません。 **配信チャネル。** `options.preferred_channel`でチャネルを選択します(デフォルトは`whatsapp`で、`sms`、`telegram`、`voice`、`rcs`、`viber`、`zalo`にも対応しています)。優先チャネルが宛先の国または番号で利用できない場合、配信は自動的にSMSにフォールバックします。この場合も送信は`Success`を返し、実際に使用されたチャネルはチェックのレスポンス(`phone.verification_method`および`lifecycle`イベント)で報告されます。 **ブランディング。** SMSのコードには、Business Consoleで設定したアプリケーションのSMS送信者名が追加料金なしで付与されます。`options.sms_sender_name`を渡すと1件のコードを別の名前で署名でき、`options.use_white_label_customization: true`を渡すと、送信者名が設定されていない場合にホワイトラベルの公開名が使用されます。WhatsAppのコードは固定メッセージを使用します。Business Consoleで自社のWhatsApp Business番号を接続すると、自社のビジネス名と番号から送信でき、請求はDiditの手数料のみとなります。 **送信ステータス。** `Success`は新しい検証に対してOTPが送信されたこと、`Retry`は保留中の検証に対してOTPが再送信されたこと、`Blocked`は不正防止レイヤーが送信を拒否したことを示します(`reason`を参照してください。例として`repeated_attempts`、`suspicious`、`spam`があります)。`Blocked`となった送信は、高リスクの警告とともに検証を直ちに`Declined`として確定するため、その後のチェックは`Expired or Not Found`を返します。 **請求。** 料金は宛先の国と、実際にメッセージを配信したチャネルによって異なります。[電話番号検証の料金](/ja/getting-started/phone-verification-pricing)を参照してください。無料が保証されるのは`Blocked`の送信のみです。それ以外の未請求の送信試行は、配信が確認されなかった場合や、配信プロバイダーがメッセージを配信不能と報告した場合であっても、検証の確定時または期限切れ時に課金されます。チェックは常に無料です。不正利用防止策として、電話番号検証は組織の初回チャージまで無効になっています(`403`)。 **セッションの永続化。** 新しい検証はすべてAPIタイプのセッションとして永続化されます。`request_id`は`GET /v3/session/{sessionId}/decision/`に渡せる実際のセッションIDであり、検証はBusiness Consoleに表示され、進行に応じて`status.updated`のWebhookが送信されます。 **サンドボックス。** サンドボックスのAPIキーでは配信と請求がスキップされます。リクエストの検証後(不正な形式の入力には引き続き`400`が返されます)、エンドポイントはランダムな`request_id`を含む静的な`Success`ペイロードを返します。メッセージは送信されず、何も永続化されません。サンドボックスのチェックではコード`123456`を使用してください。 **認証。** アプリケーションのAPIキーを`x-api-key`ヘッダーで送信してください。認証情報がない場合または無効な場合は`403`(`{"detail": "You do not have permission to perform this action."}`)が返されます。このAPIが`401`を返すことはありません。 **レート制限。** すべてのPOST/PATCH/DELETEエンドポイントで共有される書き込み枠としてAPIキーごとに毎分300リクエスト、さらに不正利用防止の上限として電話番号ごとに1時間あたり4回の送信試行が適用されます。いずれかを超えると`429`が返されます。 operationId: post_v3phone_send requestBody: required: true content: application/json: schema: type: object properties: phone_number: type: string maxLength: 20 description: >- 受信者の電話番号。E.164形式で、先頭の`+`と国番号を含めます（例: `+14155552671`）。番号は検証されたうえでE.164に正規化されます。解析できない番号や無効な番号の場合は、`phone_number`フィールドのエラーとともに`400`が返されます。 example: '+14155552671' options: type: object description: OTP配信のオプション。すべてのフィールドは任意です。 properties: code_size: type: integer minimum: 4 maximum: 8 default: 6 description: OTPの桁数。 locale: type: string maxLength: 5 pattern: ^[a-z]{2,3}(-[A-Z]{2,3})?$ description: >- 認証メッセージのローカライズに使用するBCP-47ロケール（例：`en-US`、`fr`、`es`）。形式が無効な場合は`400`が返されます。 example: en-US preferred_channel: type: string enum: - whatsapp - sms - telegram - voice - rcs - viber - zalo default: whatsapp description: >- 優先する配信チャネル。宛先の国または番号でそのチャネルが利用できない場合、メッセージは自動的にSMSにフォールバックします。この場合も送信結果は`Success`と報告されます。 use_white_label_customization: type: boolean default: false description: >- `true`の場合、ホワイトラベルで送信されます。アプリケーションにSMS送信者名がない場合、SMSには代わりにホワイトラベルの公開名が記載されます（「123456はAcme Bankの認証コードです」）。SMS送信者名を設定している場合は、このフラグの有無にかかわらずその名前が使用されます。他のチャネルからのSMSフォールバックを含め、SMSメッセージに適用されます。WhatsAppのコードは固定メッセージで送信され、ブランディングされません。デフォルトは`false`です。 sms_sender_name: type: string nullable: true maxLength: 30 example: Acme Bank description: >- このコードのSMSに表示される名前です("123456 is your verification code for Acme Bank")。アプリケーションのSMS送信者名の代わりに使用されます。無料です。1〜30文字で、使用できるのは英字、数字、スペース、および' & - !のみです。数字のみは不可で、単語間のスペースは1つにする必要があります。それ以外の値の場合は`400`が返され、コードは送信されません。省略した場合、`null`または空白の場合は、アプリケーションのSMS送信者名が使用されます。各アプリケーションが新しい名前を使い始められるのは、1日(UTC)あたり2つまでです。それを超えると、コードはアプリケーションの名前で送信されます。他のチャネルからのSMSフォールバックを含め、SMSメッセージに適用されます。WhatsAppのコードにはブランド名は付きません。 pattern: ^$|^(?![\d ]+$)[\p{L}\p{N}'&!-]+( [\p{L}\p{N}'&!-]+)*$ signals: type: object description: >- エンドユーザーに関するデバイスおよびネットワークの任意のシグナルで、不正利用や自動化されたトラフィックの検出精度を高めるために不正対策レイヤーへ転送されます。すべてのフィールドは任意です。 properties: ip: type: string description: エンドユーザーのデバイスのIPアドレス。IPv4またはIPv6。 example: 192.0.2.1 device_id: type: string maxLength: 255 description: >- エンドユーザーのデバイスの一意の識別子。Android:`ANDROID_ID`、iOS:`identifierForVendor`。 example: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2 device_platform: type: string enum: - android - ios - ipados - tvos - web description: エンドユーザーのデバイスのプラットフォーム。 device_model: type: string maxLength: 255 description: エンドユーザーのデバイスの機種。 example: iPhone17,2 os_version: type: string maxLength: 64 description: エンドユーザーのデバイスのオペレーティングシステムのバージョンです。 example: 18.0.1 app_version: type: string maxLength: 64 description: アプリケーションのバージョン。 example: 1.2.34 user_agent: type: string maxLength: 512 description: エンドユーザーのブラウザまたはアプリのユーザーエージェント。 example: >- Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1 vendor_data: type: string description: >- 呼び出し側が管理する任意の識別子（社内のユーザーid、メールアドレス、UUIDなど）です。セッションに保存され、送信レスポンス、対応するチェックレスポンス、Webhook、Business Consoleでそのまま返されます。Diditの`request_id`を自社のユーザーレコードと関連付けるために使用してください。 metadata: type: object nullable: true description: >- セッションに保存される任意の自由形式のJSONオブジェクトです。送信レスポンス、対応するチェックのレスポンス、Webhook、Business Consoleでそのまま返されます。 required: - phone_number examples: WhatsApp (default): summary: WhatsAppで送信される6桁のOTP。届かない場合は自動的にSMSにフォールバックします value: phone_number: '+14155552671' options: preferred_channel: whatsapp locale: en-US vendor_data: user-1234 SMS with custom code length: summary: 4桁のコードでSMS配信を強制する value: phone_number: '+34699999999' options: preferred_channel: sms code_size: 4 locale: es With fraud signals: summary: デバイスシグナルを転送して不正対策スクリーニングを強化します value: phone_number: '+14155552671' signals: ip: 192.0.2.1 device_id: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2 device_platform: ios device_model: iPhone17,2 os_version: 18.0.1 app_version: 1.2.34 vendor_data: user-1234 responses: '200': description: >- 送信を受け付けました。`status`を確認してください。`Success`と`Retry`はコードが送信中であることを示し、`Blocked`は不正防止レイヤーが拒否し、認証がすでに`Declined`として確定済みであることを示します。`request_id`は永続化されたセッションIDです（`Retry`の場合も同じIDです）。 content: application/json: schema: $ref: '#/components/schemas/PhoneVerificationSendResponse' examples: Success: summary: 新規認証のためにOTPを送信しました value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Success reason: null vendor_data: user-1234 metadata: null Retry: summary: 5分間のウィンドウ内での同じ番号への2回目の送信（request_idは同じ） value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Retry reason: null vendor_data: user-1234 metadata: null Blocked: summary: 不正防止による拒否：認証は却下として確定され、請求は発生しません value: request_id: 0d8af1f4-0c43-46d7-b75c-6e4e22c0a7b3 status: Blocked reason: repeated_attempts vendor_data: user-1234 metadata: null '400': description: >- バリデーションエラー。不正な形式の入力では、DRFのフィールドエラーエンベロープ（問題のあるフィールドごとにメッセージの配列1つ。選択肢のエラーは`options`の下にネスト）が返されます。解析はできても送信時に拒否される番号（到達不能、またはショートコードなど対象外の回線種別）の場合は、代わりに`{"detail": ...}`エンベロープが返されます。 content: application/json: examples: Invalid phone number (field error): summary: 番号が有効なE.164形式ではありません value: phone_number: - Invalid phone number provided. Missing phone number: summary: '`phone_number`がボディに含まれていない' value: phone_number: - This field is required. Invalid options: summary: 範囲外の`code_size`、不正な形式の`locale`、不明な`preferred_channel` value: options: code_size: - Ensure this value is less than or equal to 8. locale: - Ensure this field has no more than 5 characters. preferred_channel: - '"carrier_pigeon" is not a valid choice.' Number rejected at send time: summary: E.164形式としては有効だが、その番号ではOTPを受信できない value: detail: Invalid phone number provided. Ineligible line type: summary: 'この回線種別ではOTPを受信できません（例: ショートコード）' value: detail: Invalid phone line type provided. '403': description: >- 権限がありません。`x-api-key`ヘッダーがない場合に返されます（`{"detail": ...}`）。誤った、取り消された、または期限切れのキーの場合は`401`が返されます。また、組織が一度もチャージしたことがない場合（不正利用防止のゲート）や、残高が送信先の送信料金を賄えない場合にも、送信前に返されます（`{"error": ...}`）。 content: application/json: examples: Missing or invalid API key: summary: '`x-api-key`ヘッダーがないか、キーが無効または失効しています' value: detail: You do not have permission to perform this action. Top-up required: summary: 組織の初回チャージまで、電話番号検証は無効のままです value: detail: >- To protect against abuse, phone verification is disabled until your first top-up. Not enough credits: summary: 組織の残高で送信料金を賄えません value: error: You don't have enough credits to perform this request. '429': description: >- レート制限を超過しました。すべてのPOST/PATCH/DELETEエンドポイントは、APIキーごとに1分あたり300件の書き込みリクエストという共通の上限を共有します。さらに、上流では不正利用防止のため、電話番号ごとに1時間あたり4回の認証試行という上限が適用されます。レスポンスには`X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset`、`Retry-After`ヘッダーが含まれます。注: `X-RateLimit-*`/`Retry-After`ヘッダーが付くのは1分あたり300件の書き込み制限による429のみです。電話番号ごとの上限による429にはレート制限ヘッダーは含まれません。 content: application/json: examples: Per-number cap: summary: 直近1時間に同じ番号に対して4回を超える認証試行 value: detail: >- Maximum verification attempts reached for this phone number. Only 4 authentication attempts are allowed per hour. Try again later or use a different number. Write rate limit exceeded: summary: 現在の1分間に300件を超える書き込みリクエスト value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '500': description: 検証の作成中に発生した、既知のプロバイダー障害ではない予期しない障害。安全に再試行できます。 content: application/json: examples: Provider error: summary: OTPの配信を開始できませんでした value: detail: Error creating phone verification schema: type: object properties: detail: type: string '502': description: >- 電話番号検証のプロバイダーが一時的に利用できません。組み込みの再試行後も5xxレスポンス、タイムアウト、または接続失敗が解消しなかった状態です。安全に再試行できます。課金は発生せず、試行回数も消費されません。 content: application/json: examples: Provider outage: summary: プロバイダーが送信リクエストに応答しませんでした value: detail: >- Phone verification is temporarily unavailable. Please try again shortly. code: phone_provider_unavailable schema: type: object properties: detail: type: string code: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/phone/send/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "phone_number": "+14155552671", "options": { "code_size": 6, "preferred_channel": "whatsapp", "locale": "en-US" }, "vendor_data": "user-1234" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.phone.send_code( phone_number="+14155552671", options={ "locale": "en-US", "preferred_channel": "whatsapp", }, vendor_data="user-1234", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.phone.sendCode({ phone_number: "+14155552671", options: { locale: "en-US", preferred_channel: "whatsapp", }, vendor_data: "user-1234", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.SendCode(ctx, didit.PhoneSendCodeParams{\n\tPhoneNumber: \"+14155552671\",\n\tOptions: didit.Some(didit.PhoneSendCodeParamsOptions{\n\t\tLocale: didit.String(\"en-US\"),\n\t\tPreferredChannel: didit.Some(didit.PhoneSendCodeParamsOptionsPreferredChannel(\"whatsapp\")),\n\t}),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: |- import me.didit.Didit; import me.didit.types.PhoneSendCodeParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.phone().sendCode(PhoneSendCodeParams.builder() .phoneNumber("+14155552671") .options(PhoneSendCodeParams.Options.builder() .locale("en-US") .preferredChannel(PhoneSendCodeParams.Options.PreferredChannel.of("whatsapp")) .build()) .vendorData("user-1234") .build()); System.out.println(result); - lang: php label: PHP source: |- phone->sendCode([ 'phone_number' => '+14155552671', 'options' => [ 'locale' => 'en-US', 'preferred_channel' => 'whatsapp', ], 'vendor_data' => 'user-1234', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.phone.send_code( phone_number: "+14155552671", options: { locale: "en-US", preferred_channel: "whatsapp", }, vendor_data: "user-1234" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Phone.SendCodeAsync(new PhoneSendCodeParams { PhoneNumber = "+14155552671", Options = new PhoneSendCodeParamsOptions { Locale = "en-US", PreferredChannel = new PhoneSendCodeParamsOptionsPreferredChannel("whatsapp"), }, VendorData = "user-1234", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: PhoneVerificationSendResponse: type: object properties: request_id: type: string format: uuid description: >- 認証のセッションID。`Retry`による送信では、元の送信と同じ`request_id`が返されます。このIDはBusiness Consoleに表示され、確定済みの`POST /v3/phone/check/`でも再度返され、`GET /v3/session/{sessionId}/decision/`に渡すことができます。 status: type: string enum: - Success - Retry - Blocked description: >- `Success`：新しい認証にOTPを送信しました。`Retry`：以前の送信で作成された保留中の認証に対して、OTPを再送信しました。`Blocked`：不正防止レイヤーが送信を拒否しました。認証は直ちに`Declined`として確定し、課金は発生しません。 reason: type: string nullable: true description: >- 送信が`Blocked`となった理由です（例：`repeated_attempts`、`suspicious`、`spam`）。`Success`および`Retry`の場合は`null`です。 vendor_data: type: string nullable: true description: セッションに保存されている`vendor_data`（最初の送信時のもの）のエコー。 metadata: type: object nullable: true description: セッションに保存されている`metadata`（最初の送信時のもの）のエコー。 securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- お客様のアプリケーションのAPIキーです。Business ConsoleのDevelopers -> API keysで取得できます。プライマリキーはフルアクセス権を持ちます。名前付きキーにはスコープを設定できます。リソースごとのアクセス権（なし、読み取り、書き込み）、一部のワークフローまたは承認済みセッションへの限定、IPアドレスのリストへの限定、有効期限の設定です。401は、キーが誤っている、失効している、または期限切れであることを意味します。403は、キーが送信されていない、キーにこのリソースやアクションへのアクセス権がない、またはIPリスト外のアドレスからリクエストが送信されたことを意味します。セッションのルートでの404は、セッションがキーのワークフローまたはステータスの対象外であることを意味します。メディアへのアクセス権がないキーでは、画像、動画、PDFのURLがnullで返されます。セッションの書き込み権限がないキーでは、セッションのリンクとトークンがnullで返されます。詳細は次を参照してください: https://docs.didit.me/console/api-keys ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.