> ## 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 проверки телефона > Didit: POST /v3/phone/send/ отправляет SMS-код OTP. Автоповтор для заблокированных номеров, действует 5 мин, оплата за использование, без минимумов. ## Укажите бренд в SMS SMS-коды содержат имя отправителя SMS вашего приложения, которое задаётся в Business Console, без дополнительной платы: > 123456, ваш код подтверждения для **Acme Bank** Чтобы подписать код другим именем, передайте `options.sms_sender_name` (от 1 до 30 символов: только буквы, цифры, пробелы и символы ' & - ! и не только цифры): ```json theme={null} { "phone_number": "+14155552671", "options": { "preferred_channel": "sms", "sms_sender_name": "Acme Bank" } } ``` Имя, которое не соответствует этим правилам, возвращает `400`, и код не отправляется. WhatsApp-коды используют фиксированный текст и не брендируются. Чтобы отправлять их от имени вашей компании, подключите собственный номер WhatsApp Business в Business Console. См. [Отправка WhatsApp-кодов с собственного номера](https://docs.didit.me/ru/core-technology/phone-verification/overview.md#отправка-кодов-whatsapp-с-собственного-номера). См. [Брендированные сообщения для верификации](https://docs.didit.me/ru/core-technology/phone-verification/overview.md#брендированные-сообщения-верификации), где описано, какое имя получает код, и дневной лимит на новые имена. ## Обработка сбоев провайдера Если провайдер телефонии временно недоступен, этот endpoint возвращает `502` с устойчивым машиночитаемым кодом: ```json theme={null} { "detail": "The phone verification provider is temporarily unavailable.", "code": "phone_provider_unavailable" } ``` Считайте этот ответ допускающим повторный запрос. Используйте короткую задержку перед повтором и показывайте пользователю сообщение о временной недоступности сервиса, а не просите его изменить корректный номер телефона или код. ## OpenAPI ````yaml ru/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: >- Отправьте одноразовый код (OTP) на номер телефона через WhatsApp, SMS или другой поддерживаемый канал, а затем проверьте его с помощью [`POST /v3/phone/check/`](/ru/standalone-apis/phone-check). **Как связываются отправка и проверка.** Состояние верификации привязано к вашему приложению и `phone_number` в формате E.164 — вызов проверки не принимает `request_id`. Каждая новая отправка создает верификацию в состоянии ожидания, которая действует в течение **5 минут**: вызовите проверку с тем же номером и кодом, полученным пользователем, до закрытия этого окна. Повторный вызов отправки на тот же номер, пока верификация находится в ожидании, повторно отправляет код для этой же верификации (`status: "Retry"`, тот же `request_id`). Таким образом привязывается не более одной повторной попытки (всего две отправки); последующая отправка начинает новую верификацию с новым `request_id`. Окно в 5 минут отсчитывается от первой отправки и не продлевается повторными попытками. **Каналы доставки.** `options.preferred_channel` выбирает канал (по умолчанию `whatsapp`; также поддерживаются `sms`, `telegram`, `voice`, `rcs`, `viber` и `zalo`). Когда предпочтительный канал недоступен для страны назначения или номера, доставка автоматически переключается на SMS — отправка по-прежнему возвращает `Success`, а фактически использованный канал сообщается в ответе проверки (`phone.verification_method` и события `lifecycle`). **Брендинг.** SMS-коды содержат имя отправителя SMS вашего приложения, настроенное в Business Console, без дополнительной платы. Передайте `options.sms_sender_name`, чтобы подписать конкретный код другим именем, или `options.use_white_label_customization: true`, чтобы использовать ваше публичное White label имя, когда имя отправителя не настроено. Коды WhatsApp используют фиксированное сообщение; подключите собственный номер WhatsApp Business в Business Console, чтобы отправлять их от имени и с номера вашей компании с оплатой только комиссии Didit. **Статусы отправки.** `Success` — OTP отправлен для новой верификации; `Retry` — OTP отправлен повторно для верификации в состоянии ожидания; `Blocked` — слой защиты от мошенничества отклонил отправку (см. `reason`, например `repeated_attempts`, `suspicious`, `spam`). Отправка со статусом `Blocked` немедленно завершает верификацию со статусом `Declined` с предупреждением о высоком уровне риска, поэтому последующая проверка возвращает `Expired or Not Found`. **Биллинг.** Цена зависит от страны назначения и канала, который фактически доставляет сообщение — см. [Цены на проверку телефона](/ru/getting-started/phone-verification-pricing). Бесплатными гарантированно являются только отправки со статусом `Blocked`: любая другая неоплаченная попытка отправки списывается при завершении или истечении срока действия верификации, даже если доставка так и не была подтверждена или провайдер доставки сообщил о невозможности доставки сообщения. Проверки всегда бесплатны. В качестве меры защиты от злоупотреблений проверка телефона отключена до первого пополнения баланса вашей организации (`403`). **Сохранение сессии.** Каждая новая верификация сохраняется как сессия типа API: `request_id` является реальным идентификатором сессии, который можно передать в `GET /v3/session/{sessionId}/decision/`, верификация отображается в Business Console, и по мере её выполнения отправляются события webhook `status.updated`. **Песочница.** API-ключи песочницы пропускают доставку и биллинг: после валидации запроса (некорректные данные по-прежнему возвращают `400`) endpoint возвращает статический payload `Success` со случайным `request_id`; сообщение не отправляется и данные не сохраняются. Для проверки в песочнице используйте код `123456`. **Аутентификация.** Передайте API-ключ вашего приложения в заголовке `x-api-key`. Отсутствие или недействительность учетных данных возвращает `403` (`{"detail": "You do not have permission to perform this action."}`) — этот API никогда не возвращает `401`. **Лимиты запросов.** Общий лимит на запись составляет 300 запросов/мин на API-ключ для всех POST/PATCH/DELETE endpoints, плюс ограничение для защиты от злоупотреблений в 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; нераспознаваемые или недействительные номера возвращают `400` с ошибкой поля `phone_number`. example: '+14155552671' options: type: object description: >- Параметры доставки одноразового кода. Все поля необязательны. 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`, отправка выполняется с использованием White label: если у вашего приложения не задано имя отправителя SMS, в SMS вместо него указывается ваше публичное имя White label («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 символов: только буквы, цифры, пробелы и ' & - !, не только цифры, с одиночными пробелами между словами; при любом другом значении возвращается `400`, и код не отправляется. Если опущено, имеет значение `null` или пустое, используется имя отправителя SMS вашего приложения. Каждое приложение может начать использовать до двух новых имен в день (UTC); сверх этого код отправляется с именем вашего приложения. Применяется к 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: >- User-Agent браузера или приложения конечного пользователя. 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: >- Необязательный идентификатор, контролируемый вызывающей стороной (ваш внутренний идентификатор пользователя, email, UUID и т. д.), сохраняемый в сессии и возвращаемый в ответе на отправку, ответе проверки соответствия, webhook и Business Console. Используйте его для сопоставления `request_id` от Didit с вашей записью пользователя. metadata: type: object nullable: true description: >- Необязательный JSON-объект в свободной форме, сохраняемый в сессии и возвращаемый в ответе на отправку, в ответе проверки соответствия, в webhook и в Business Console. required: - phone_number examples: WhatsApp (default): summary: >- 6-значный OTP через WhatsApp с автоматическим переключением на SMS при сбое value: phone_number: '+14155552671' options: preferred_channel: whatsapp locale: en-US vendor_data: user-1234 SMS with custom code length: summary: Принудительная доставка по SMS с 4-значным кодом 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`). content: application/json: schema: $ref: '#/components/schemas/PhoneVerificationSendResponse' examples: Success: summary: Одноразовый код отправлен для новой верификации value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Success reason: null vendor_data: user-1234 metadata: null Retry: summary: >- Повторная отправка на тот же номер в течение 5-минутного окна — тот же 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 (по одному массиву сообщений для каждого некорректного поля, вложенному в `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, но номер не может получить одноразовый код value: detail: Invalid phone number provided. Ineligible line type: summary: >- Тип линии не может получать одноразовый код (например, короткий номер) 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: >- Превышен лимит запросов. Endpoint'ы POST/PATCH/DELETE делят общий лимит в 300 запросов на запись в минуту на один API-ключ (для создания транзакций и отправки событий действует отдельный лимит в 600). Кроме того, выше по цепочке действует лимит для предотвращения злоупотреблений в 4 попытки верификации на один номер телефона в час. Ответ содержит заголовки `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` и `Retry-After`. Примечание: заголовки `X-RateLimit-*`/`Retry-After` сопровождают только ошибку 429 при превышении лимита записи 300/мин; ошибка 429 при превышении лимита на номер телефона не содержит заголовков лимитирования. content: application/json: examples: Per-number cap: summary: >- Более 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: Более 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: Не удалось инициировать доставку одноразового кода 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`). `null` при `Success` и `Retry`. 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-ключ вашего приложения из раздела «Разработчикам» -> «API-ключи» в Business Console. Основной ключ имеет полный доступ. Именованный ключ может иметь ограниченную область действия: без доступа, чтение или запись для каждого ресурса, ограничение определенными сценариями или одобренными сессиями, списком IP-адресов и сроком действия. 401 означает, что ключ неверен, отозван или его срок действия истек; 403 означает, что ключ не был передан, у ключа нет доступа к этому ресурсу или действию, либо запрос поступил с адреса вне его списка IP-адресов; 404 на маршруте сессии означает, что сессия не входит в сценарии или статусы ключа. Ключ без доступа к медиа получает URL изображений, видео и PDF как null, а ключ без прав на запись сессий получает ссылки на сессии и токены как null. См. https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.