> ## 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 per enviar codi OTP per SMS: verificació de telèfon > Envia per SMS un codi d'un sol ús amb POST /v3/phone/send/ de Didit. Reintent automàtic, validesa de 5-min i preu per ús. ## 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): ```json theme={null} { "phone_number": "+14155552671", "options": { "preferred_channel": "sms", "sms_sender_name": "Acme Bank" } } ``` 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](https://docs.didit.me/ca/core-technology/phone-verification/overview.md#enviar-codis-de-whatsapp-des-del-teu-propi-número). Consulta [Missatges de verificació amb marca](https://docs.didit.me/ca/core-technology/phone-verification/overview.md#missatges-de-verificació-de-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: ```json theme={null} { "detail": "The phone verification provider is temporarily unavailable.", "code": "phone_provider_unavailable" } ``` 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. ## OpenAPI ````yaml ca/openapi-25.json POST /v3/phone/send/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificació d'identitat. Autentica't amb la capçalera x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/phone/send/: post: tags: - Standalone APIs summary: Enviar el codi per telèfon description: >- Envia un codi d'un sol ús (OTP) a un número de telèfon a través de WhatsApp, SMS o un altre canal admès, i després verifica'l amb [`POST /v3/phone/check/`](/ca/standalone-apis/phone-check). **Com es vinculen l'enviament i la comprovació.** L'estat de la verificació s'identifica mitjançant la teva aplicació i el `phone_number` en format E.164; la crida de comprovació no accepta `request_id`. Cada nou enviament crea una verificació pendent que dura **5 minuts**: crida la comprovació amb el mateix número i el codi que ha rebut l'usuari abans que es tanqui la finestra. Si tornes a cridar l'enviament per al mateix número mentre hi ha una verificació pendent, es reenvia un codi per a aquesta mateixa verificació (`status: "Retry"`, mateix `request_id`). Com a màxim es vincula un reintent d'aquesta manera (dos enviaments en total); un enviament posterior inicia una nova verificació amb un nou `request_id`. La finestra de 5 minuts es compta a partir del primer enviament i no s'amplia amb els reintents. **Canals de lliurament.** `options.preferred_channel` selecciona el canal (`whatsapp` per defecte; també s'admeten `sms`, `telegram`, `voice`, `rcs`, `viber` i `zalo`). Quan el canal preferit no està disponible per al país o número de destinació, el lliurament canvia automàticament a SMS: l'enviament continua informant de `Success`, i el canal utilitzat realment s'indica a la resposta de comprovació (`phone.verification_method` i els esdeveniments `lifecycle`). **Personalització de marca.** Els codis per SMS inclouen el nom de remitent de SMS de la teva aplicació, configurat a la Business Console, sense cap cost addicional. Passa `options.sms_sender_name` perquè un codi s'enviï amb un altre nom, o `options.use_white_label_customization: true` per recórrer al teu nom públic de marca blanca quan no s'hagi establert cap nom de remitent. Els codis de WhatsApp utilitzen un missatge fix; connecta el teu propi número de WhatsApp Business a la Business Console per enviar-los des del nom i número de la teva empresa, facturats només amb la tarifa de Didit. **Estats d'enviament.** `Success`: OTP enviat per a una nova verificació; `Retry`: OTP reenviat per a la verificació pendent; `Blocked`: la capa antifrau ha refusat l'enviament (consulta `reason`, p. ex., `repeated_attempts`, `suspicious`, `spam`). Un enviament `Blocked` finalitza immediatament la verificació com a `Declined` amb una advertència d'alt risc, de manera que una comprovació posterior retorna `Expired or Not Found`. **Facturació.** El preu depèn del país de destinació i del canal que lliura realment el missatge; consulta [Preus de Verificació de telèfon](/ca/getting-started/phone-verification-pricing). Només els enviaments `Blocked` són garantits com a gratuïts: qualsevol altre intent d'enviament no facturat es cobra en finalitzar o caducar la verificació, fins i tot si el lliurament mai no es va confirmar o el proveïdor de lliurament va informar que el missatge no es podia lliurar. Les comprovacions són sempre gratuïtes. Com a mesura antiabús, la verificació de telèfon està desactivada fins a la primera recàrrega de la teva organització (`403`). **Persistència de sessions.** Cada nova verificació es desa com una sessió de tipus API: `request_id` és un id de sessió real que pots passar a `GET /v3/session/{sessionId}/decision/`, la verificació apareix a la Business Console i els webhooks `status.updated` s'activen a mesura que avança. **Sandbox.** Les claus d'API de sandbox ometen el lliurament i la facturació: després de la validació de la sol·licitud (l'entrada amb format incorrecte continua retornant `400`), l'endpoint retorna un payload estàtic `Success` amb un `request_id` aleatori; no s'envia cap missatge ni es desa res. Utilitza el codi `123456` a la comprovació de sandbox. **Autenticació.** Envia la clau d'API de la teva aplicació a la capçalera `x-api-key`. Les credencials absents o no vàlides retornen `403` (`{"detail": "You do not have permission to perform this action."}`); aquesta API mai no retorna `401`. **Límits de freqüència.** Pressupost d'escriptura compartit de 300 sol·licituds/min per clau d'API a tots els endpoints POST/PATCH/DELETE, més un límit antiabús de 4 intents d'enviament per número de telèfon per hora; superar qualsevol dels dos 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 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`. example: '+14155552671' options: type: object description: >- Opcions de lliurament de l'OTP. Tots els camps són opcionals. properties: code_size: type: integer minimum: 4 maximum: 8 default: 6 description: Nombre de dígits de l'OTP. locale: type: string maxLength: 5 pattern: ^[a-z]{2,3}(-[A-Z]{2,3})?$ description: >- Configuració regional BCP-47 utilitzada per localitzar el missatge de verificació (p. ex., `en-US`, `fr`, `es`). Els formats no vàlids retornen `400`. example: en-US preferred_channel: type: string enum: - whatsapp - sms - telegram - voice - rcs - viber - zalo default: whatsapp description: >- Canal de lliurament preferit. Si el canal no està disponible per al país o número de destinació, el missatge passa automàticament a SMS — l'enviament continua indicant `Success`. use_white_label_customization: type: boolean default: false description: >- Quan és `true`, l'enviament és de marca blanca: si la teva aplicació no té cap nom de remitent d'SMS, l'SMS inclou el teu nom públic de marca blanca ("123456 és el teu codi de verificació per a Acme Bank"). El teu nom de remitent d'SMS, si està configurat, s'utilitza amb aquest indicador o sense. S'aplica als missatges SMS, inclòs el recurs a SMS des d'un altre canal; els codis de WhatsApp s'envien amb un missatge fix i no porten marca. Per defecte és `false`. sms_sender_name: type: string nullable: true maxLength: 30 example: Acme Bank description: >- El nom que porta l'SMS d'aquest codi ("123456 és el teu codi de verificació per a Acme Bank"), en comptes del nom de remitent d'SMS de la teva aplicació. Gratuït. D'1 a 30 caràcters: només lletres, dígits, espais i ' & - !, no només dígits, amb espais simples entre paraules; qualsevol altre valor retorna `400` i no s'envia cap codi. Si s'omet, és `null` o està en blanc, s'utilitza el nom de remitent d'SMS de la teva aplicació. Cada aplicació pot començar a utilitzar fins a dos noms nous per dia (UTC); després d'això, el codi s'envia amb el nom de la teva aplicació. S'aplica als missatges SMS, inclòs un SMS de reserva des d'un altre canal; els codis de WhatsApp no porten marca. pattern: ^$|^(?![\d ]+$)[\p{L}\p{N}'&!-]+( [\p{L}\p{N}'&!-]+)*$ signals: type: object description: >- 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. properties: ip: type: string description: Adreça IP del dispositiu de l'usuari final. IPv4 o IPv6. example: 192.0.2.1 device_id: type: string maxLength: 255 description: >- Identificador únic del dispositiu de l'usuari final. Android: `ANDROID_ID`; iOS: `identifierForVendor`. example: 8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2 device_platform: type: string enum: - android - ios - ipados - tvos - web description: Plataforma del dispositiu de l'usuari final. device_model: type: string maxLength: 255 description: Model del dispositiu de l'usuari final. example: iPhone17,2 os_version: type: string maxLength: 64 description: >- Versió del sistema operatiu del dispositiu de l'usuari final. example: 18.0.1 app_version: type: string maxLength: 64 description: Versió de la teva aplicació. example: 1.2.34 user_agent: type: string maxLength: 512 description: >- Agent d'usuari del navegador o de l'aplicació de l'usuari 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 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: type: object nullable: true description: >- 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. required: - phone_number examples: WhatsApp (default): summary: >- OTP de 6 xifres per WhatsApp, amb commutació automàtica a SMS com a alternativa value: phone_number: '+14155552671' options: preferred_channel: whatsapp locale: en-US vendor_data: user-1234 SMS with custom code length: summary: Força el lliurament per SMS amb un codi de 4 xifres value: phone_number: '+34699999999' options: preferred_channel: sms code_size: 4 locale: es With fraud signals: summary: >- Reenvia senyals del dispositiu per reforçar el cribratge antifrau 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: >- 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`). content: application/json: schema: $ref: '#/components/schemas/PhoneVerificationSendResponse' examples: Success: summary: OTP enviat per a una nova verificació value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Success reason: null vendor_data: user-1234 metadata: null Retry: summary: >- Segon enviament per al mateix número dins de la finestra de 5 minuts — mateix request_id value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Retry reason: null vendor_data: user-1234 metadata: null Blocked: summary: >- Denegació antifrau — verificació finalitzada com a Rebutjada, no s'ha facturat res value: request_id: 0d8af1f4-0c43-46d7-b75c-6e4e22c0a7b3 status: Blocked reason: repeated_attempts vendor_data: user-1234 metadata: null '400': description: >- Error de validació. Les dades d'entrada amb format incorrecte retornen l'embolcall d'errors de camp de DRF (una matriu de missatges per cada camp que conté l'error, anidada sota `options` per a errors d'opcions). Un número que s'analitza correctament però es rebutja en el moment de l'enviament (inaccessible o un tipus de línia no apte com ara un codi curt) retorna en canvi un embolcall `{"detail": ...}`. content: application/json: examples: Invalid phone number (field error): summary: El número no és un número E.164 vàlid value: phone_number: - Invalid phone number provided. Missing phone number: summary: '`phone_number` no s''ha inclòs al cos' value: phone_number: - This field is required. Invalid options: summary: >- `code_size` fora de rang, `locale` mal format, `preferred_channel` desconegut 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: Format E.164 vàlid però el número no pot rebre cap OTP value: detail: Invalid phone number provided. Ineligible line type: summary: El tipus de línia no pot rebre un OTP (p. ex., codi curt) value: detail: Invalid phone line type provided. '403': description: >- Permís denegat. Es retorna quan falta la capçalera `x-api-key` (`{"detail": ...}`); una clau incorrecta, revocada o caducada retorna `401`. També es retorna abans de qualsevol enviament quan l'organització mai no ha recarregat (control contra l'abús) o quan el seu saldo no pot cobrir el preu d'enviament de la destinació (`{"error": ...}`). content: application/json: examples: Missing or invalid API key: summary: >- Sense capçalera `x-api-key`, o la clau no és vàlida/s'ha revocat value: detail: You do not have permission to perform this action. Top-up required: summary: >- La verificació de telèfon roman desactivada fins a la primera recàrrega de l'organització value: detail: >- To protect against abuse, phone verification is disabled until your first top-up. Not enough credits: summary: >- El saldo de l'organització no pot cobrir el preu de l'enviament value: error: You don't have enough credits to perform this request. '429': description: >- S'ha superat el límit de freqüència. Els endpoints POST/PATCH/DELETE comparteixen un pressupost de 300 sol·licituds d'escriptura per minut per clau d'API (la creació de transaccions i la ingesta d'esdeveniments tenen un pressupost independent de 600). A més, a nivell superior s'aplica un límit contra abusos de 4 intents de verificació per número de telèfon i per hora. La resposta inclou les capçaleres `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` i `Retry-After`. Nota: les capçaleres `X-RateLimit-*`/`Retry-After` només acompanyen l'error 429 del límit d'escriptura de 300/min; el 429 del límit per número de telèfon no conté capçaleres de límit de freqüència. content: application/json: examples: Per-number cap: summary: >- Més de 4 intents de verificació per al mateix número en l'ú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: Més de 300 sol·licituds d'escriptura en el minut actual 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: >- Error inesperat en crear la verificació que no correspon a una caiguda coneguda del proveïdor. Es pot reintentar amb seguretat. content: application/json: examples: Provider error: summary: No s'ha pogut iniciar el lliurament de l'OTP value: detail: Error creating phone verification schema: type: object properties: detail: type: string '502': description: >- El proveïdor de verificació de telèfon no està disponible temporalment: una resposta 5xx, un temps d'espera esgotat o un error de connexió que ha persistit després dels reintents integrats. És segur reintentar-ho; no es factura res ni es consumeix cap intent. content: application/json: examples: Provider outage: summary: El proveïdor no ha respost a la sol·licitud d'enviament 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 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: type: string enum: - Success - Retry - Blocked description: >- `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. reason: type: string nullable: true description: >- Per què un enviament ha estat `Blocked` (p. ex., `repeated_attempts`, `suspicious`, `spam`). `null` a `Success` i `Retry`. vendor_data: type: string nullable: true description: >- Ressò de les `vendor_data` emmagatzemades a la sessió (des del primer enviament). metadata: type: object nullable: true description: >- Ressò de les `metadata` emmagatzemades a la sessió (des del primer enviament). securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.