Saltar para o conteúdo principal
POST
curl

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):
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. Consulte Mensagens de verificação com 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:
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.

Autorizações

x-api-key
string
header
obrigatório

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.

Corpo

application/json
phone_number
string
obrigatório

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.

Maximum string length: 20
Exemplo:

"+14155552671"

options
object

Opções de entrega do OTP. Todos os campos são opcionais.

signals
object

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.

vendor_data
string

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
object | null

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.

Resposta

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).

request_id
string<uuid>

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
enum<string>

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.

Opções disponíveis:
Success,
Retry,
Blocked
reason
string | null

O motivo pelo qual um envio foi Blocked (por exemplo, repeated_attempts, suspicious, spam). null em Success e Retry.

vendor_data
string | null

Eco do objeto vendor_data armazenado na sessão (do primeiro envio).

metadata
object | null

Eco do objeto metadata armazenado na sessão (do primeiro envio).

Última modificação em 7 de novembro de 2026