> ## 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. # API de envio de OTP por telefone: verificação por SMS > Envie um código SMS de uso único via POST /v3/phone/send/ da Didit. Validade de 5-min, retentativa automática, pago por uso, sem mínimo mensal. ## Exiba o nome da sua marca no SMS Os códigos por SMS levam o nome de remetente de SMS da sua aplicação, definido no Business Console, sem custo adicional: > 123456 é o seu código de verificação da **Acme Bank** Para assinar um código específico com outro nome, envie `options.sms_sender_name` (de 1 a 30 caracteres: apenas letras, dígitos, espaços e ' & - !, e não apenas dígitos): ```json theme={null} { "phone_number": "+14155552671", "options": { "preferred_channel": "sms", "sms_sender_name": "Acme Bank" } } ``` Um nome fora dessas regras retorna `400` e nenhum código é enviado. Os códigos por WhatsApp usam uma mensagem fixa e não levam a sua marca; conecte o seu próprio número do WhatsApp Business no Business Console para enviá-los com o nome da sua empresa. Consulte [Envie códigos por WhatsApp a partir do seu próprio número](https://docs.didit.me/pt-br/core-technology/phone-verification/overview.md#envie-códigos-por-whatsapp-do-seu-próprio-número). Consulte [Mensagens de verificação com a sua marca](https://docs.didit.me/pt-br/core-technology/phone-verification/overview.md#mensagens-de-verificação-com-a-sua-marca) para saber qual nome um código leva e qual é o limite diário de novos nomes. ## Lide com indisponibilidades do provedor Se o provedor de telefonia estiver temporariamente indisponível, este endpoint retorna `502` com um código estável e legível por máquina: ```json theme={null} { "detail": "The phone verification provider is temporarily unavailable.", "code": "phone_provider_unavailable" } ``` Considere que esta resposta permite uma nova tentativa. Use um backoff curto e mostre ao usuário uma mensagem informando que o serviço está temporariamente indisponível, em vez de pedir que ele altere um número de telefone ou código válido. ## OpenAPI ````yaml pt-br/openapi-25.json POST /v3/phone/send/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificação de identidade. Autentique-se com o cabeçalho x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/phone/send/: post: tags: - Standalone APIs summary: Enviar código por telefone description: >- Envie um código de uso único (OTP) para um número de telefone por WhatsApp, SMS ou outro canal compatível e depois verifique-o com [`POST /v3/phone/check/`](/pt-br/standalone-apis/phone-check). **Como o envio e a verificação se relacionam.** O estado da verificação é identificado pela sua aplicação e pelo `phone_number` no formato E.164. A chamada de verificação não recebe `request_id`. Cada novo envio cria uma verificação pendente com validade de **5 minutos**: chame a verificação com o mesmo número e o código que o usuário recebeu antes do fim desse prazo. Se você chamar o envio de novo para o mesmo número enquanto houver uma verificação pendente, um código será reenviado para essa mesma verificação (`status: "Retry"`, mesmo `request_id`). No máximo uma nova tentativa é vinculada dessa forma (dois envios no total). Um envio adicional inicia uma nova verificação com um novo `request_id`. O prazo de 5 minutos é contado a partir do primeiro envio e não é estendido pelas novas tentativas. **Canais de entrega.** `options.preferred_channel` define o canal (`whatsapp` por padrão; `sms`, `telegram`, `voice`, `rcs`, `viber` e `zalo` também são compatíveis). Quando o canal preferido não está disponível para o país ou número de destino, a entrega passa automaticamente para SMS. O envio continua retornando `Success`, e o canal efetivamente usado é informado na resposta da verificação (`phone.verification_method` e os eventos de `lifecycle`). **Identidade da marca.** Os códigos por SMS levam o nome de remetente de SMS da sua aplicação, configurado no Business Console, sem custo adicional. Envie `options.sms_sender_name` para assinar um código com outro nome, ou `options.use_white_label_customization: true` para usar o nome público da sua marca própria quando nenhum nome de remetente estiver configurado. Os códigos por WhatsApp usam uma mensagem fixa. Conecte seu próprio número do WhatsApp Business no Business Console para enviá-los com o nome e o número da sua empresa, cobrados apenas pela tarifa da Didit. **Status de envio.** `Success`: OTP enviado para uma nova verificação; `Retry`: OTP reenviado para a verificação pendente; `Blocked`: a camada antifraude recusou o envio (consulte `reason`, por exemplo `repeated_attempts`, `suspicious`, `spam`). Um envio `Blocked` finaliza imediatamente a verificação como `Declined` com um aviso de alto risco, então uma verificação posterior retorna `Expired or Not Found`. **Faturamento.** O preço depende do país de destino e do canal que efetivamente entrega a mensagem. Consulte [Preços da Verificação de telefone](/pt-br/getting-started/phone-verification-pricing). Apenas os envios `Blocked` são garantidamente gratuitos: qualquer outra tentativa de envio não faturada é cobrada na finalização ou na expiração da verificação, mesmo que a entrega nunca tenha sido confirmada ou que o provedor de entrega tenha informado que a mensagem não pôde ser entregue. As verificações de código são sempre gratuitas. Como medida antiabuso, a verificação de telefone fica desativada até a primeira recarga da sua organização (`403`). **Persistência da sessão.** Toda nova verificação é persistida como uma sessão do tipo API: `request_id` é um ID de sessão real que você pode passar para `GET /v3/session/{sessionId}/decision/`, a verificação aparece no Business Console e webhooks `status.updated` são disparados conforme ela avança. **Sandbox.** As chaves de API de sandbox ignoram a entrega e o faturamento: após a validação da requisição (entradas malformadas continuam retornando `400`), o endpoint retorna um payload estático `Success` com um `request_id` aleatório. Nenhuma mensagem é enviada e nada é persistido. Use o código `123456` na verificação em sandbox. **Autenticação.** Envie a chave de API da sua aplicação no cabeçalho `x-api-key`. Credenciais ausentes ou inválidas retornam `403` (`{"detail": "You do not have permission to perform this action."}`). Esta API nunca retorna `401`. **Limites de requisições.** Cota de escrita compartilhada de 300 requisições/min por chave de API entre todos os endpoints POST/PATCH/DELETE, além de um limite antiabuso de 4 tentativas de envio por número de telefone por hora. Exceder qualquer um deles retorna `429`. operationId: post_v3phone_send requestBody: required: true content: application/json: schema: type: object properties: phone_number: type: string maxLength: 20 description: >- Número de telefone do destinatário no formato E.164, com `+` inicial e código do país (por exemplo, `+14155552671`). Os números são validados e normalizados para E.164; números que não podem ser interpretados ou inválidos retornam `400` com um erro no campo `phone_number`. example: '+14155552671' options: type: object description: Opções de entrega do OTP. Todos os campos são opcionais. properties: code_size: type: integer minimum: 4 maximum: 8 default: 6 description: Número de dígitos do OTP. locale: type: string maxLength: 5 pattern: ^[a-z]{2,3}(-[A-Z]{2,3})?$ description: >- Locale BCP-47 usado para localizar a mensagem de verificação (por exemplo, `en-US`, `fr`, `es`). Formatos inválidos retornam `400`. example: en-US preferred_channel: type: string enum: - whatsapp - sms - telegram - voice - rcs - viber - zalo default: whatsapp description: >- Canal de entrega preferencial. Se o canal não estiver disponível para o país ou número de destino, a mensagem recorre automaticamente ao SMS, e o envio ainda informa `Success`. use_white_label_customization: type: boolean default: false description: >- Quando `true`, o envio usa marca própria: se a sua aplicação não tiver um nome de remetente de SMS, o SMS cita o nome público da sua marca própria ("123456 é o seu código de verificação do Acme Bank"). O seu nome de remetente de SMS, quando definido, é usado com ou sem esta flag. Aplica-se a mensagens SMS, incluindo um fallback por SMS a partir de outro canal; os códigos por WhatsApp são enviados com uma mensagem fixa e não levam a sua marca. O padrão é `false`. sms_sender_name: type: string nullable: true maxLength: 30 example: Acme Bank description: >- O nome que o SMS deste código exibe ("123456 is your verification code for Acme Bank"), em vez do nome de remetente de SMS da sua aplicação. Gratuito. De 1 a 30 caracteres: apenas letras, dígitos, espaços e ' & - !, não somente dígitos, com espaços simples entre as palavras; qualquer outro valor retorna `400` e nenhum código é enviado. Se omitido, `null` ou em branco, é usado o nome de remetente de SMS da sua aplicação. Cada aplicação pode começar a usar até dois nomes novos por dia (UTC); acima disso, o código é enviado com o nome da sua aplicação. Aplica-se a mensagens SMS, incluindo um fallback por SMS a partir de outro canal; os códigos por WhatsApp não levam marca. pattern: ^$|^(?![\d ]+$)[\p{L}\p{N}'&!-]+( [\p{L}\p{N}'&!-]+)*$ signals: type: object description: >- Sinais opcionais de dispositivo e rede sobre o usuário final, encaminhados à camada antifraude para melhorar a detecção de tráfego abusivo ou automatizado. Todos os campos são opcionais. properties: ip: type: string description: >- Endereço IP do dispositivo do usuário final. IPv4 ou IPv6. example: 192.0.2.1 device_id: type: string maxLength: 255 description: >- Identificador único do dispositivo do usuário final. Android: `ANDROID_ID`; iOS: `identifierForVendor`. example: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2 device_platform: type: string enum: - android - ios - ipados - tvos - web description: Plataforma do dispositivo do usuário final. device_model: type: string maxLength: 255 description: Modelo do dispositivo do usuário final. example: iPhone17,2 os_version: type: string maxLength: 64 description: >- Versão do sistema operacional do dispositivo do usuário final. example: 18.0.1 app_version: type: string maxLength: 64 description: Versão da sua aplicação. example: 1.2.34 user_agent: type: string maxLength: 512 description: User agent do navegador ou app do usuário final. 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: >- Identificador opcional controlado por quem faz a chamada (seu id interno de usuário, um e-mail, um UUID etc.), persistido na sessão e devolvido na resposta do envio, na resposta da verificação correspondente, nos webhooks e no Business Console. Use-o para correlacionar o `request_id` da Didit com o registro do seu usuário. metadata: type: object nullable: true description: >- Objeto JSON livre e opcional, persistido na sessão e devolvido na resposta de envio, na resposta da verificação correspondente, nos webhooks e no Business Console. required: - phone_number examples: WhatsApp (default): summary: >- OTP de 6 dígitos via WhatsApp, com fallback automático para SMS value: phone_number: '+14155552671' options: preferred_channel: whatsapp locale: en-US vendor_data: user-1234 SMS with custom code length: summary: Forçar a entrega por SMS com um código de 4 dígitos value: phone_number: '+34699999999' options: preferred_channel: sms code_size: 4 locale: es With fraud signals: summary: >- Encaminhe sinais do dispositivo para reforçar a triagem antifraude 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: >- Envio confirmado. Verifique `status`: `Success` e `Retry` significam que um código está a caminho; `Blocked` significa que a camada antifraude recusou o envio e a verificação já foi finalizada como `Declined`. `request_id` é o id da sessão persistida (o mesmo id em um `Retry`). content: application/json: schema: $ref: '#/components/schemas/PhoneVerificationSendResponse' examples: Success: summary: OTP enviado para uma nova verificação value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Success reason: null vendor_data: user-1234 metadata: null Retry: summary: >- Segundo envio para o mesmo número dentro da janela de 5 minutos — mesmo request_id value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Retry reason: null vendor_data: user-1234 metadata: null Blocked: summary: >- Recusa antifraude: verificação finalizada como recusada, nada é cobrado value: request_id: 0d8af1f4-0c43-46d7-b75c-6e4e22c0a7b3 status: Blocked reason: repeated_attempts vendor_data: user-1234 metadata: null '400': description: >- Erro de validação. Uma entrada malformada retorna o envelope de erros de campo do DRF (um array de mensagens por campo com problema, aninhado em `options` para erros de opção). Um número que é interpretado corretamente, mas é rejeitado no momento do envio (inalcançável ou com um tipo de linha não elegível, como um código curto), retorna em vez disso um envelope `{"detail": ...}`. content: application/json: examples: Invalid phone number (field error): summary: O número não é um E.164 válido value: phone_number: - Invalid phone number provided. Missing phone number: summary: '`phone_number` não foi incluído no corpo' value: phone_number: - This field is required. Invalid options: summary: >- `code_size` fora do intervalo, `locale` malformado, `preferred_channel` desconhecido 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: Formato E.164 válido, mas o número não pode receber um OTP value: detail: Invalid phone number provided. Ineligible line type: summary: >- O tipo de linha não pode receber um OTP (por exemplo, código curto) value: detail: Invalid phone line type provided. '403': description: >- Permissão negada. Retornado quando o cabeçalho `x-api-key` está ausente (`{"detail": ...}`); uma chave incorreta, revogada ou expirada retorna `401`. Também é retornado antes de qualquer envio quando a organização nunca fez uma recarga (barreira antiabuso) ou quando o saldo dela não cobre o preço de envio para o destino (`{"error": ...}`). content: application/json: examples: Missing or invalid API key: summary: Nenhum cabeçalho `x-api-key`, ou a chave é inválida/revogada value: detail: You do not have permission to perform this action. Top-up required: summary: >- A verificação de telefone permanece desativada até a primeira recarga da organização value: detail: >- To protect against abuse, phone verification is disabled until your first top-up. Not enough credits: summary: O saldo da organização não cobre o preço do envio value: error: You don't have enough credits to perform this request. '429': description: >- Limite de requisições excedido. Todos os endpoints POST/PATCH/DELETE compartilham uma cota de 300 requisições de escrita por minuto por chave de API. Além disso, um teto antiabuso de 4 tentativas de verificação por número de telefone por hora é aplicado na origem. A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`. Observação: os cabeçalhos `X-RateLimit-*`/`Retry-After` acompanham apenas o 429 do limite de escrita de 300/min; o 429 do teto por número não inclui cabeçalhos de limite de requisições. content: application/json: examples: Per-number cap: summary: >- Mais de 4 tentativas de verificação para o mesmo número na última hora 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: Mais de 300 requisições de escrita no minuto atual 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: >- Falha inesperada ao criar a verificação que não corresponde a uma indisponibilidade conhecida do provedor. É seguro tentar novamente. content: application/json: examples: Provider error: summary: Não foi possível iniciar a entrega do OTP value: detail: Error creating phone verification schema: type: object properties: detail: type: string '502': description: >- O provedor de verificação de telefone está temporariamente indisponível - uma resposta 5xx, timeout ou falha de conexão que persistiu após as novas tentativas automáticas. É seguro tentar novamente; nada é cobrado e nenhuma tentativa é consumida. content: application/json: examples: Provider outage: summary: O provedor não respondeu à requisição de envio 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 da sessão da verificação. Um envio `Retry` retorna o mesmo `request_id` do envio original. Este ID aparece no Business Console, é retornado novamente por um `POST /v3/phone/check/` finalizado e pode ser passado para `GET /v3/session/{sessionId}/decision/`. status: type: string enum: - Success - Retry - Blocked description: >- `Success`: OTP enviado para uma nova verificação. `Retry`: OTP reenviado para a verificação pendente criada por um envio anterior. `Blocked`: a camada antifraude recusou o envio; a verificação é finalizada imediatamente como `Declined` e nada é cobrado. reason: type: string nullable: true description: >- Motivo pelo qual um envio ficou `Blocked` (por exemplo, `repeated_attempts`, `suspicious`, `spam`). `null` em `Success` e `Retry`. vendor_data: type: string nullable: true description: Eco do `vendor_data` armazenado na sessão (do primeiro envio). metadata: type: object nullable: true description: Eco do `metadata` armazenado na sessão (do primeiro envio). securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Chave de API da sua aplicação, em Developers -> API keys no Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter escopo restrito: nenhum acesso, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está errada, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que a requisição veio de um endereço fora da sua lista de IPs; 404 em uma rota de sessão significa que a sessão está fora dos fluxos ou status da chave. Uma chave sem acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave sem permissão de escrita em sessões recebe links e tokens de sessão como null. Consulte https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.