> ## 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 código OTP por SMS para telefone > Envie códigos SMS de uso único com POST /v3/phone/send/ da Didit. Repete automaticamente em números bloqueados, validade 5 min, sem mínimos mensais. ## Atribuir o nome da sua marca ao SMS Os códigos SMS incluem o nome do remetente de SMS da sua aplicação, definido na Business Console, sem custo adicional: > 123456 é o seu código de verificação para **Acme Bank** Para enviar um código com um nome diferente, envie `options.sms_sender_name` (entre 1 e 30 caracteres: apenas letras, algarismos, espaços e ' & - !, e não apenas algarismos): ```json theme={null} { "phone_number": "+14155552671", "options": { "preferred_channel": "sms", "sms_sender_name": "Acme Bank" } } ``` Um nome que não cumpra estas regras devolve `400` e nenhum código é enviado. Os códigos WhatsApp usam uma mensagem fixa e não incluem a marca; para os enviar a partir do nome da sua empresa, ligue o seu próprio número WhatsApp Business na Business Console. Consulte [Enviar códigos WhatsApp a partir do seu próprio número](https://docs.didit.me/pt/core-technology/phone-verification/overview.md#enviar-códigos-de-whatsapp-a-partir-do-seu-próprio-número). Consulte [Mensagens de verificação com marca](https://docs.didit.me/pt/core-technology/phone-verification/overview.md#mensagens-de-verificação-com-a-sua-marca) para saber que nome um código inclui e o limite diário de novos nomes. ## Gerir indisponibilidades do fornecedor Se o fornecedor de serviços telefónicos estiver temporariamente indisponível, este endpoint devolve `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" } ``` Trate esta resposta como passível de nova tentativa. Aguarde um breve intervalo antes de repetir o pedido e mostre ao utilizador uma mensagem a indicar que o serviço está temporariamente indisponível, em vez de lhe pedir que altere um número de telefone ou um código válidos. ## OpenAPI ````yaml pt/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 utilização única (OTP) para um número de telefone através do WhatsApp, SMS ou outro canal suportado e, em seguida, verifique-o com [`POST /v3/phone/check/`](/pt/standalone-apis/phone-check). **Como o envio e a verificação se articulam.** O estado da verificação tem como chave a sua aplicação e o `phone_number` em formato E.164 — a chamada de verificação não recebe `request_id`. Cada novo envio cria uma verificação pendente que dura **5 minutos**: chame a verificação com o mesmo número e o código que o utilizador recebeu antes do fecho da janela. Chamar o envio novamente para o mesmo número enquanto uma verificação estiver pendente volta a enviar um código para essa mesma verificação (`status: "Retry"`, o mesmo `request_id`). No máximo, uma nova tentativa é associada desta forma (dois envios no total); um envio adicional inicia uma nova verificação com um novo `request_id`. A janela de 5 minutos é contada a partir do primeiro envio e não é prolongada por novas tentativas. **Canais de entrega.** `options.preferred_channel` seleciona o canal (`whatsapp` por predefinição; `sms`, `telegram`, `voice`, `rcs`, `viber` e `zalo` também são suportados). Quando o canal preferencial não estiver disponível para o país ou número de destino, a entrega recorre automaticamente ao SMS como alternativa — o envio continua a indicar `Success` e o canal efetivamente utilizado é indicado pela resposta de verificação (`phone.verification_method` e os eventos de `lifecycle`). **Marca.** Os códigos por SMS incluem o nome de remetente de SMS da sua aplicação, configurado na Business Console, sem custos adicionais. Passe `options.sms_sender_name` para enviar um código com outro nome, ou `options.use_white_label_customization: true` para recorrer ao seu nome público de marca branca quando nenhum nome de remetente estiver definido. Os códigos do WhatsApp utilizam uma mensagem fixa; associe o seu próprio número de WhatsApp Business na Business Console para os enviar a partir do nome e número da sua empresa, sendo faturado apenas pela tarifa da Didit. **Estados 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 risco elevado, pelo que uma verificação posterior devolve `Expired or Not Found`. **Faturação.** 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/getting-started/phone-verification-pricing). Apenas os envios `Blocked` têm garantia de gratuitidade: qualquer outra tentativa de envio não faturada é cobrada na finalização ou expiração da verificação, mesmo que a entrega nunca tenha sido confirmada ou o fornecedor de entrega tenha reportado a mensagem como impossível de entregar. As verificações são sempre gratuitas. Como medida antiabuso, a verificação de telefone fica desativada até ao primeiro carregamento de saldo da sua organização (`403`). **Persistência da sessão.** Cada nova verificação é persistida como uma sessão do tipo API: `request_id` é um ID de sessão real que pode passar para `GET /v3/session/{sessionId}/decision/`, a verificação é apresentada na Business Console e os webhooks `status.updated` são disparados à medida que progride. **Sandbox.** As chaves de API da sandbox ignoram a entrega e a faturação: após a validação do pedido (dados de entrada com formato incorreto continuam a devolver `400`), o endpoint devolve um payload estático de `Success` com um `request_id` aleatório; nenhuma mensagem é enviada e nada é persistido. Utilize 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 em falta ou inválidas devolvem `403` (`{"detail": "You do not have permission to perform this action."}`) — esta API nunca devolve `401`. **Limites de pedidos.** Orçamento de escrita partilhado de 300 pedidos/min por chave de API em 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 devolve `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 — `+` inicial e código do país (por exemplo, `+14155552671`). Os números são validados e normalizados para o formato E.164; números inválidos ou que não possam ser analisados devolvem `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 no OTP. locale: type: string maxLength: 5 pattern: ^[a-z]{2,3}(-[A-Z]{2,3})?$ description: >- Localidade BCP-47 utilizada para localizar a mensagem de verificação (por exemplo, `en-US`, `fr`, `es`). Formatos inválidos devolvem `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 de destino ou número, a mensagem reverte automaticamente para SMS — o envio continua a reportar `Success`. use_white_label_customization: type: boolean default: false description: >- Quando `true`, o envio é efetuado em marca branca: se a sua aplicação não tiver um nome de remetente de SMS, o SMS menciona o seu nome público de marca branca ("123456 é o seu código de verificação para o Acme Bank"). O seu nome de remetente de SMS, quando configurado, é utilizado com ou sem este indicador. Aplica-se a mensagens SMS, incluindo uma alternativa por SMS a partir de outro canal; os códigos por WhatsApp são enviados com uma mensagem fixa e não têm marca. Por predefinição, é `false`. sms_sender_name: type: string nullable: true maxLength: 30 example: Acme Bank description: >- O nome que o SMS deste código apresenta ("123456 é o seu código de verificação para o Acme Bank"), em vez do nome de remetente de SMS da sua aplicação. Gratuito. 1 a 30 carateres: apenas letras, dígitos, espaços e ' & - !, não apenas dígitos, com espaços simples entre palavras; qualquer outro valor devolve `400` e nenhum código é enviado. Omitido, `null` ou em branco, é utilizado o nome de remetente de SMS da sua aplicação. Cada aplicação pode começar a utilizar até dois novos nomes por dia (UTC); a partir daí, o código é enviado com o nome da sua aplicação. Aplica-se a mensagens SMS, incluindo um fallback para SMS a partir de outro canal; os códigos do WhatsApp não têm marca personalizada. pattern: ^$|^(?![\d ]+$)[\p{L}\p{N}'&!-]+( [\p{L}\p{N}'&!-]+)*$ signals: type: object description: >- Sinais opcionais de dispositivo e rede sobre o utilizador final, encaminhados para a camada antifraude para melhorar a deteção de tráfego abusivo ou automatizado. Todos os campos são opcionais. properties: ip: type: string description: >- Endereço IP do dispositivo do utilizador final. IPv4 ou IPv6. example: 192.0.2.1 device_id: type: string maxLength: 255 description: >- Identificador único do dispositivo do utilizador 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 utilizador final. device_model: type: string maxLength: 255 description: Modelo do dispositivo do utilizador final. example: iPhone17,2 os_version: type: string maxLength: 64 description: >- Versão do sistema operativo do dispositivo do utilizador 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: >- Agente do utilizador do navegador ou da aplicação do utilizador 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 pelo chamador (o seu ID de utilizador interno, um e-mail, um UUID, etc.) guardado na sessão e devolvido na resposta de envio, na resposta de verificação de correspondência, nos webhooks e na Business Console. Utilize-o para correlacionar o `request_id` da Didit com o registo do seu utilizador. metadata: type: object nullable: true description: >- Objeto JSON de formato livre opcional persistido na sessão e devolvido na resposta de envio, na resposta de verificação de correspondência, nos webhooks e na Business Console. required: - phone_number examples: WhatsApp (default): summary: >- OTP de 6 dígitos via WhatsApp, recorrendo a SMS automaticamente value: phone_number: '+14155552671' options: preferred_channel: whatsapp locale: en-US vendor_data: user-1234 SMS with custom code length: summary: Forçar 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: >- Reencaminhar 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. Inspecione `status`: `Success` e `Retry` significam que um código está a caminho; `Blocked` significa que a camada antifraude recusou e a verificação já foi finalizada como `Declined`. `request_id` é o ID persistido da sessão (o mesmo ID num `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 faturado 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. Dados de entrada malformados devolvem o envelope de erro de campo do DRF (um array de mensagens por campo afetado, aninhado sob `options` para erros de opções). Um número que é analisado com sucesso, mas rejeitado no momento do envio (inacessível ou um tipo de linha não elegível, como um short code) devolve um envelope `{"detail": ...}`. content: application/json: examples: Invalid phone number (field error): summary: O número não é válido segundo a norma E.164 value: phone_number: - Invalid phone number provided. Missing phone number: summary: '`phone_number` não incluído no corpo' value: phone_number: - This field is required. Invalid options: summary: >- `code_size` fora dos limites, `locale` mal formatado, `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 consegue 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. Devolvido quando o cabeçalho `x-api-key` está em falta (`{"detail": ...}`); uma chave incorreta, revogada ou expirada devolve `401`. Também é devolvido antes de qualquer envio quando a organização nunca carregou saldo (controlo antiabuso) ou quando o seu saldo não consegue cobrir o preço de envio do destino (`{"error": ...}`). content: application/json: examples: Missing or invalid API key: summary: Sem 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é ao primeiro carregamento de saldo 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 de envio value: error: You don't have enough credits to perform this request. '429': description: >- Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). Adicionalmente, aplica-se a montante um limite antiabuso de 4 tentativas de verificação por número de telefone por hora. A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`. Nota: os cabeçalhos `X-RateLimit-*`/`Retry-After` acompanham apenas o 429 do limite de escrita de 300/min; o 429 do limite por número não inclui cabeçalhos de limite de pedidos. 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 pedidos 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 é uma interrupção conhecida do fornecedor. Pode tentar novamente em segurança. 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 fornecedor de verificação de telefone está temporariamente indisponível - uma resposta 5xx, timeout ou falha de ligação que persistiu após as tentativas automáticas integradas. É seguro tentar novamente; nada é faturado e nenhuma tentativa é consumida. content: application/json: examples: Provider outage: summary: O fornecedor não respondeu ao pedido 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 de sessão da verificação. Um envio de `Retry` devolve o mesmo `request_id` que o envio original. Este id surge na Business Console, é devolvido 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 é imediatamente finalizada como `Declined` e nada é faturado. reason: type: string nullable: true description: >- O motivo pelo qual um envio foi `Blocked` (por exemplo, `repeated_attempts`, `suspicious`, `spam`). `null` em `Success` e `Retry`. vendor_data: type: string nullable: true description: >- Eco do objeto `vendor_data` armazenado na sessão (do primeiro envio). metadata: type: object nullable: true description: Eco do objeto `metadata` armazenado na sessão (do primeiro envio). securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, 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á incorreta, 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 o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.