Saltar al contingut principal
POST
curl

Posa el nom de la teva marca a l’SMS

Els codis per SMS porten el nom del remitent d’SMS de la teva aplicació, configurat a la Business Console, sense cost addicional:
123456 és el teu codi de verificació per a Acme Bank
Per enviar un codi amb un nom diferent, passa options.sms_sender_name (d’1 a 30 caràcters: lletres, dígits, espais i només els símbols ’ & - !, i no pot contenir només dígits):
Un nom que no compleixi aquestes regles retorna 400 i no s’envia cap codi. Els codis de WhatsApp fan servir un missatge fix i no porten marca; connecta el teu propi número de WhatsApp Business a la Business Console per enviar-los amb el nom de la teva empresa. Consulta Envia codis de WhatsApp des del teu propi número. Consulta Missatges de verificació amb marca per saber quin nom porta cada codi i el límit diari de noms nous.

Gestiona les interrupcions del proveïdor

Si el proveïdor de telefonia no està disponible temporalment, aquest endpoint retorna 502 amb un codi estable llegible per màquina:
Considera que cal reintentar aquesta sol·licitud. Fes una espera curta abans de reintentar i mostra a l’usuari un missatge que indiqui que el servei no està disponible temporalment, en lloc de demanar-li que canviï un número de telèfon o un codi vàlids.

Autoritzacions

x-api-key
string
header
requerit

La clau d'API de la teva aplicació, des de Developers -> API keys a la Business Console. La clau primària té accés complet. Una clau amb nom pot tenir l'abast limitat: cap, lectura o escriptura per recurs, limitada a determinats fluxos de treball o a sessions aprovades, a una llista d'adreces IP i a una data de caducitat. 401 significa que la clau és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap clau, que la clau no té accés a aquest recurs o acció, o que la sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una ruta de sessió significa que la sessió està fora dels fluxos de treball o estats de la clau. Una clau sense accés a fitxers multimèdia rep els URL d'imatge, vídeo i PDF com a null, i una clau sense permís d'escriptura de sessions rep els enllaços de sessió i els tokens com a null. Consulta https://docs.didit.me/console/api-keys.

Cos

application/json
phone_number
string
requerit

Número de telèfon del destinatari en format E.164 — amb + inicial i codi de país (p. ex., +14155552671). Els números es validen i es normalitzen a E.164; els números invàlids o que no es poden analitzar retornen 400 amb un error al camp phone_number.

Maximum string length: 20
Exemple:

"+14155552671"

options
object

Opcions de lliurament de l'OTP. Tots els camps són opcionals.

signals
object

Senyals opcionals de dispositiu i xarxa sobre l'usuari final, reenviats a la capa antifrau per millorar la detecció de trànsit abusiu o automatitzat. Tots els camps són opcionals.

vendor_data
string

Identificador opcional controlat per qui fa la crida (el teu id d'usuari intern, un correu electrònic, un UUID, etc.) que es manté a la sessió i es retorna a la resposta d'enviament, a la resposta de comprovació de coincidències, als webhooks i a la Business Console. Utilitza'l per correlacionar el request_id de Didit amb el teu registre d'usuari.

metadata
object | null

Objecte JSON opcional de format lliure que es desa a la sessió i es retorna a la resposta d'enviament, a la resposta de la comprovació de coincidència, als webhooks i a la Business Console.

Resposta

Enviament confirmat. Revisa status: Success i Retry indiquen que s'està enviant un codi; Blocked significa que la capa antifrau ho ha refusat i la verificació ja s'ha finalitzat com a Declined. request_id és l'identificador de sessió persistit (el mateix identificador en un Retry).

request_id
string<uuid>

ID de sessió de la verificació. Un enviament Retry retorna el mateix request_id que l'enviament original. Aquest id apareix a la Business Console, el torna a retornar un POST /v3/phone/check/ finalitzat i es pot transmetre a GET /v3/session/{sessionId}/decision/.

status
enum<string>

Success — OTP enviat a una nova verificació. Retry — OTP reenviat per a la verificació pendent creada per un enviament anterior. Blocked — la capa antifrau ha rebutjat l'enviament; la verificació es finalitza immediatament com a Declined i no es factura res.

Opcions disponibles:
Success,
Retry,
Blocked
reason
string | null

Per què un enviament ha estat Blocked (p. ex., repeated_attempts, suspicious, spam). null a Success i Retry.

vendor_data
string | null

Ressò de les vendor_data emmagatzemades a la sessió (des del primer enviament).

metadata
object | null

Ressò de les metadata emmagatzemades a la sessió (des del primer enviament).

Darrera modificació el 7 de novembre del 2026