> ## 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 verificação de telefone: validar código SMS > Valide códigos OTP por telefone com a Didit: operadora, números virtuais e descartáveis. POST /v3/phone/check/. Sem mínimos mensais. ## Lidar com interrupções do fornecedor Se o fornecedor de telefonia estiver temporariamente indisponível, este endpoint devolve `502` com um código estável 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. Use um intervalo de espera progressivo curto e mostre ao utilizador uma mensagem de indisponibilidade temporária do serviço, em vez de lhe pedir que altere um número de telefone ou um código válidos. ## Complemento de inteligência Defina `enable_enrichment` como `true` para executar também a inteligência telefónica sobre o número: uma pontuação de risco, o tipo de linha, se o número foi portado recentemente e um índice de confiança. O complemento é faturado a \$0.05 por pedido ao preço de tabela, além do preço da verificação. O pedido devolve `403` quando o seu saldo não cobre esse valor. Quatro campos determinam o efeito dos sinais. Cada um pode ser `NO_ACTION` (o valor predefinido) ou `DECLINE`, e cada um só tem efeito quando `enable_enrichment` é `true`. | Campo | Recusa quando | | - | - | | `phone_intelligence_score_action` | A pontuação de risco está acima do limiar. | | `phone_type_risk_action` | O número é de um tipo de linha de alto risco. | | `recent_port_action` | O número foi portado para outra operadora recentemente. | | `low_phone_trust_action` | O índice de confiança é igual ou inferior ao limiar. | Com `NO_ACTION`, o sinal continua a ser devolvido em `phone.phone_intelligence`, para que possa aplicar a sua própria regra. ## OpenAPI ````yaml pt/openapi-25.json POST /v3/phone/check/ 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/check/: post: tags: - Standalone APIs summary: Verificar código de telefone description: >- Verifique o OTP entregue por [`POST /v3/phone/send/`](/pt/standalone-apis/phone-send) e obtenha o resultado final da verificação, além de informações sobre o telefone: nome da operadora e tipo de linha, flags de número virtual (VoIP) e descartável, e utilização duplicada do número nas suas sessões. **Como a verificação localiza o registo.** A correspondência é feita pela sua aplicação juntamente com o `phone_number` em formato E.164 (o `request_id` não é um parâmetro de entrada). É verificada a verificação pendente mais recente criada há menos de **5 minutos**. Se não existir nenhuma (nunca enviada, já finalizada ou com mais de 5 minutos), o endpoint devolve `200` com `status: "Expired or Not Found"`. **Limite de tentativas.** Cada verificação permite **3 tentativas de código**. As duas primeiras tentativas incorretas devolvem `status: "Failed"` com as tentativas restantes e `phone: null`; a terceira tentativa incorreta finaliza a verificação como `Declined` com um aviso `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` e devolve o relatório telefónico completo. **Resultados.** `Approved` — código correto e sem riscos de recusa. `Declined` — terminal: o código estava correto, mas foi detetado um risco de recusa (uma ação `DECLINE` abaixo, um número na lista de bloqueio ou de alto risco), ou o limite de tentativas foi esgotado. `Failed` — código incorreto, com tentativas restantes. `Expired or Not Found` — nada a verificar. Em `Approved`/`Declined`, o `request_id` é igual ao `request_id` do envio (o id da sessão) e `phone` inclui o relatório completo (`carrier`, `is_virtual`, `is_disposable`, `warnings`, `lifecycle`, `matches`); em `Failed` e `Expired or Not Found`, o `request_id` é um UUID aleatório e único. **Ações de risco.** `duplicated_phone_number_action`, `disposable_number_action` e `voip_number_action` decidem o que acontece quando o risco correspondente é detetado num código correto: `DECLINE` altera o estado final para `Declined`; `NO_ACTION` (predefinição) regista o risco em `phone.warnings` sem afetar o estado. **Faturação.** As verificações são gratuitas — a entrega é faturada no lado do envio (consulte [Preços da verificação de telefone](/pt/getting-started/phone-verification-pricing)). **Persistência da sessão.** Uma verificação finalizada atualiza a sessão criada pelo envio (visível na Business Console, consultável através de `GET /v3/session/{sessionId}/decision/`) e aciona um webhook `status.updated`. **Sandbox.** As chaves de API de sandbox ignoram todo o processamento: qualquer código bem formatado (4–8 dígitos, incluindo `123456`) devolve um payload estático `Approved` com um objeto simples `phone` (`status`, `phone_number`, `country_code`, `carrier_name`, `line_type`, `flags`); entradas mal formatadas continuam a devolver `400`. Nada é persistido. **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.** Limite partilhado de escrita de 300 pedidos/min por chave de API, mais o limite antiabuso upstream de 4 tentativas por número por hora; ultrapassar qualquer um deles devolve `429`. **Pegada social.** Defina `enable_social` como `true` para adicionar um bloco `phone_social`: as plataformas online onde este número está registado, com contagens por categoria e quaisquer detalhes de perfil disponíveis. `profiles_registered: 0` significa que as plataformas foram verificadas e o número não foi encontrado em nenhuma delas — uma resposta válida e faturável. O bloco está ausente quando o add-on não foi solicitado ou a verificação não pôde ser concluída, e não é faturado nesse caso. A faturação adiciona uma unidade de `phone_social` por pedido além do preço próprio deste endpoint. operationId: post_v3phone_check requestBody: required: true content: application/json: schema: type: object properties: phone_number: type: string maxLength: 20 description: >- O mesmo número de telefone utilizado na chamada [`POST /v3/phone/send/`](/pt/standalone-apis/phone-send) correspondente, no formato E.164. É isto que associa a verificação ao envio. example: '+14155552671' code: type: string minLength: 4 maxLength: 8 pattern: ^[0-9]{4,8}$ description: >- O OTP que o utilizador final recebeu. Deve ter entre 4 e 8 dígitos numéricos — qualquer outro valor devolve `400` sem consumir uma tentativa. Um código bem formatado mas incorreto devolve `200` com `status: "Failed"` e consome uma das 3 tentativas. example: '123456' duplicated_phone_number_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- O que fazer quando o mesmo número já foi utilizado por um utilizador diferente (com um `vendor_data` diferente) da sua aplicação. `DECLINE` altera o `status` final para `Declined`; `NO_ACTION` regista o risco em `phone.warnings` e preenche `phone.matches`. disposable_number_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- O que fazer quando a consulta de operadora sinalizar o número como uma linha temporária/descartável (`phone.is_disposable`). `DECLINE` altera o `status` final para `Declined`; `NO_ACTION` regista o risco em `phone.warnings`. voip_number_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- O que fazer quando a consulta de operadora indicar um tipo de linha virtual — `voip`, `isp` ou `vpn` (`phone.is_virtual`). `DECLINE` altera o `status` final para `Declined`; `NO_ACTION` regista o risco em `phone.warnings`. enable_enrichment: type: boolean default: false description: >- Quando `true`, executa também inteligência telefónica sobre o número: uma pontuação de risco, o tipo de linha, se foi recentemente portado e um índice de confiança. Faturado como uma unidade `phone_intelligence_api` por pedido ($0.05 ao preço de tabela), além do próprio preço deste endpoint. O pedido devolve `403` quando o seu saldo não for suficiente para cobri-lo. example: false phone_intelligence_score_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Ação quando a pontuação de risco da inteligência de telefone está acima do limiar. `DECLINE` altera o `status` final para `Declined`; `NO_ACTION` regista o sinal sem recusar. Apenas tem efeito quando `enable_enrichment` é `true`. phone_type_risk_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Ação quando o número é de um tipo de linha de alto risco. `DECLINE` altera o `status` final para `Declined`; `NO_ACTION` regista o sinal sem recusar. Apenas tem efeito quando `enable_enrichment` é `true`. recent_port_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Ação quando o número foi recentemente portado para outra operadora. `DECLINE` altera o `status` final para `Declined`; `NO_ACTION` regista o sinal sem recusar. Apenas tem efeito quando `enable_enrichment` é `true`. low_phone_trust_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Ação quando o índice de confiança da inteligência de telefone está no limiar ou abaixo dele. `DECLINE` altera o `status` final para `Declined`; `NO_ACTION` regista o sinal sem recusar. Apenas tem efeito quando `enable_enrichment` é `true`. enable_social: type: boolean default: false description: >- Quando for true, consulta também a pegada social do número: as plataformas de mensagens, redes sociais, de comércio eletrónico e profissionais nas quais está registado. Faturado como uma unidade `phone_social` por pedido, além do preço do próprio endpoint. example: true phone_no_social_presence_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Ação quando a verificação da pegada social deteta que o número não está registado em nenhuma das plataformas abrangidas. Apenas NO_ACTION e DECLINE são aceites neste endpoint; REVIEW está disponível na chave de configuração do fluxo com o mesmo nome. required: - phone_number - code examples: Default: summary: Registar quaisquer riscos, mas nunca recusar automaticamente value: phone_number: '+14155552671' code: '123456' Strict risk policy: summary: Recusar automaticamente linhas VoIP e descartáveis value: phone_number: '+14155552671' code: '123456' voip_number_action: DECLINE disposable_number_action: DECLINE responses: '200': description: >- Verificação concluída — códigos errados e verificações em falta também devolvem `200`; inspecione `status`, não o código HTTP. `phone` é preenchido apenas em resultados finalizados (`Approved`/`Declined`), `null` em `Failed` e ausente em `Expired or Not Found`. content: application/json: schema: $ref: '#/components/schemas/PhoneVerificationCheckResponse' examples: Approved: summary: >- Código correto — relatório telefónico completo com operadora, ciclo de vida e correspondências value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Approved message: The verification code is correct. phone: status: Approved phone_number_prefix: '+1' phone_number: '4155552671' full_number: '+14155552671' country_code: US country_name: United States carrier: name: AT&T type: mobile is_disposable: false is_virtual: false verification_method: whatsapp verification_attempts: 1 verified_at: '2026-06-12T01:24:47.311323Z' warnings: [] lifecycle: - type: PHONE_VERIFICATION_MESSAGE_SENT timestamp: '2026-06-12T01:23:39.580554+00:00' details: status: Success reason: null channel: whatsapp actual_channel: whatsapp fee: 0.0509 - type: PHONE_DELIVERY_DELIVERED timestamp: '2026-06-12T01:23:43.118220+00:00' details: channel: whatsapp status: delivered fee: 0 - type: VALID_CODE_ENTERED timestamp: '2026-06-12T01:24:47.311201+00:00' details: code_tried: '123456' status: Approved fee: 0 - type: PHONE_VERIFICATION_APPROVED timestamp: '2026-06-12T01:24:47.384292+00:00' details: null fee: 0 matches: [] vendor_data: user-1234 metadata: null created_at: '2026-06-12T01:24:47.401719+00:00' Failed (attempts remaining): summary: >- Código incorreto — o utilizador pode tentar novamente; o request_id aqui é um UUID de utilização única value: request_id: 11111111-2222-3333-4444-555555555555 status: Failed message: 'The verification code is incorrect. Attempts remaining: 2' phone: null vendor_data: user-1234 metadata: null created_at: '2026-06-12T01:24:21.512340+00:00' Declined (max attempts): summary: >- Terceiro código errado — verificação finalizada como Recusada value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Declined message: >- The verification code is incorrect. Maximum attempts reached. phone: status: Declined phone_number_prefix: '+1' phone_number: '4155552671' full_number: '+14155552671' country_code: US country_name: United States carrier: name: AT&T type: mobile is_disposable: false is_virtual: false verification_method: whatsapp verification_attempts: 1 verified_at: null warnings: - feature: PHONE risk: VERIFICATION_CODE_ATTEMPTS_EXCEEDED additional_data: null log_type: error short_description: Verification code attempts exceeded long_description: >- The system detected that the phone number has exceeded the maximum number of verification code attempts. lifecycle: - type: PHONE_VERIFICATION_MESSAGE_SENT timestamp: '2026-06-12T01:23:39.580554+00:00' details: status: Success reason: null channel: whatsapp actual_channel: whatsapp fee: 0.0509 - type: INVALID_CODE_ENTERED timestamp: '2026-06-12T01:24:01.118220+00:00' details: code_tried: '111111' status: Failed fee: 0 - type: INVALID_CODE_ENTERED timestamp: '2026-06-12T01:24:21.512340+00:00' details: code_tried: '222222' status: Failed fee: 0 - type: INVALID_CODE_ENTERED timestamp: '2026-06-12T01:24:47.311201+00:00' details: code_tried: '333333' status: Failed fee: 0 - type: PHONE_VERIFICATION_DECLINED timestamp: '2026-06-12T01:24:47.384292+00:00' details: reason: VERIFICATION_CODE_ATTEMPTS_EXCEEDED fee: 0 matches: [] vendor_data: user-1234 metadata: null created_at: '2026-06-12T01:24:47.401719+00:00' Declined (risk policy): summary: >- Código correto, mas a linha é VoIP e voip_number_action=DECLINE value: request_id: 7f1c9d2e-44a1-4b6e-9a3e-5b8e6f1c2d3a status: Declined message: The verification code is correct. phone: status: Declined phone_number_prefix: '+1' phone_number: '5005550006' full_number: '+15005550006' country_code: US country_name: United States carrier: name: CLEC LLC type: voip is_disposable: false is_virtual: true verification_method: sms verification_attempts: 1 verified_at: '2026-06-12T01:24:47.311323Z' warnings: - feature: PHONE risk: VOIP_NUMBER_DETECTED additional_data: null log_type: error short_description: VoIP number detected long_description: >- The system detected that the phone number is a VoIP number, which is not allowed. lifecycle: - type: PHONE_VERIFICATION_MESSAGE_SENT timestamp: '2026-06-12T01:23:39.580554+00:00' details: status: Success reason: null channel: whatsapp actual_channel: sms fee: 0.0509 - type: VALID_CODE_ENTERED timestamp: '2026-06-12T01:24:47.311201+00:00' details: code_tried: '123456' status: Approved fee: 0 - type: PHONE_VERIFICATION_DECLINED timestamp: '2026-06-12T01:24:47.384292+00:00' details: reason: VOIP_NUMBER_DETECTED fee: 0 matches: [] vendor_data: user-1234 metadata: null created_at: '2026-06-12T01:24:47.401719+00:00' Expired or Not Found: summary: >- Nenhuma verificação pendente para este número nos últimos 5 minutos value: request_id: 69cc35c6-280a-47a6-ab8c-4f32abc02ed0 status: Expired or Not Found message: No pending phone verification found in the last 5 minutes. vendor_data: null metadata: null created_at: '2026-06-12T01:24:47.311323+00:00' '400': description: >- Erro de validação — envelope de erro de campo do DRF: um array de mensagens por campo com problemas. content: application/json: examples: Invalid code format: summary: '`code` não tem entre 4 e 8 dígitos numéricos' value: code: - Invalid code format. Enter 4 to 8 numeric digits. Invalid phone number: summary: '`phone_number` não é um número E.164 válido' value: phone_number: - Invalid phone number provided. Invalid action: summary: As ações de risco aceitam apenas NO_ACTION ou DECLINE value: voip_number_action: - '"REVIEW" is not a valid choice.' '403': description: >- Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta; uma chave incorreta, revogada ou expirada devolve `401`. As verificações são gratuitas, pelo que não existe qualquer verificação de crédito aqui. 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. '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 verificar o código a montante que não é uma interrupção conhecida do fornecedor. Pode tentar novamente em segurança; o limite de tentativas só é consumido por verificações concluídas. content: application/json: examples: Provider error: summary: Não foi possível concluir a verificação do código value: detail: Error checking 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; o orçamento de tentativas não é consumido. content: application/json: examples: Provider outage: summary: O fornecedor não respondeu ao pedido de verificação 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/check/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "phone_number": "+14155552671", "code": "123456", "voip_number_action": "DECLINE" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.phone.check_code( phone_number="+14155552671", code="123456", ) 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.checkCode({ phone_number: "+14155552671", code: "123456", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.CheckCode(ctx, didit.PhoneCheckCodeParams{\n\tPhoneNumber: \"+14155552671\",\n\tCode: \"123456\",\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.PhoneCheckCodeParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.phone().checkCode(PhoneCheckCodeParams.builder() .phoneNumber("+14155552671") .code("123456") .build()); System.out.println(result); - lang: php label: PHP source: |- phone->checkCode([ 'phone_number' => '+14155552671', 'code' => '123456', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.phone.check_code( phone_number: "+14155552671", code: "123456" ) 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.CheckCodeAsync(new PhoneCheckCodeParams { PhoneNumber = "+14155552671", Code = "123456", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: PhoneVerificationCheckResponse: type: object properties: request_id: type: string format: uuid description: >- Em `Approved`/`Declined`: o id da sessão da verificação correspondente — idêntico ao `request_id` devolvido por `POST /v3/phone/send/`. Em `Failed` e `Expired or Not Found`: um UUID pontual aleatório que não pode ser consultado mais tarde. status: type: string enum: - Approved - Declined - Failed - Expired or Not Found description: >- `Approved` — código correto, sem risco de recusa. `Declined` — terminal: um risco de recusa correspondeu ou o limite de tentativas (3) esgotou-se. `Failed` — código incorreto, tentativas restantes. `Expired or Not Found` — nenhuma verificação pendente para este número nos últimos 5 minutos. message: type: string description: >- Explicação legível do resultado, incluindo o número de tentativas restantes após um código incorreto. phone: type: object nullable: true description: >- Relatório telefónico completo. Presente (não nulo) apenas em resultados finalizados (`Approved`/`Declined`); `null` em `Failed` e ausente em `Expired or Not Found`. properties: status: type: string enum: - Approved - Declined - In Review - Not Finished - Expired description: >- Estado final da verificação de telefone. Corresponde ao `status` de nível superior para verificações finalizadas. phone_number_prefix: type: string description: 'Indicativo telefónico do país com `+` inicial (ex.: `+1`).' example: '+1' phone_number: type: string description: Número nacional sem o indicativo do país. example: '4155552671' full_number: type: string description: Número completo no formato E.164. example: '+14155552671' country_code: type: string nullable: true description: País ISO 3166-1 alfa-2 do número. example: US country_name: type: string description: Nome completo do país derivado de `country_code`. example: United States carrier: type: object description: >- Rede atual que serve o número, a partir da consulta de operadora executada na finalização. properties: name: type: string description: >- Nome da operadora. Cadeia vazia quando a pesquisa não a conseguiu identificar. type: type: string description: >- Tipo de linha comunicado pela consulta: `mobile`, `fixed_line`, `voip`, `isp`, `vpn`, `toll_free`, `premium_rate`, `pager`, `payphone`, `satellite`, `service`, `shared_cost`, `short_codes_commercial`, `calling_cards`, `local_rate`, `universal_access`, `voice_mail`, `other` ou `unknown`. is_disposable: type: boolean description: >- `true` quando o número pertence a um serviço de números temporários/descartáveis. is_virtual: type: boolean description: >- `true` quando o tipo de linha é virtual (`voip`, `isp` ou `vpn`). verification_method: type: string description: >- Canal que efetivamente entregou o OTP após a confirmação da entrega (por exemplo, `whatsapp`, `sms`); até lá, o canal solicitado. verification_attempts: type: integer description: >- Número de envios de OTP para esta verificação (1, ou 2 após tentar novamente). verified_at: type: string format: date-time nullable: true description: >- Quando o código correto foi introduzido. `null` se a verificação nunca tiver sido aprovada. warnings: type: array description: >- Avisos de risco registados durante a verificação (duplicado, descartável, VoIP, tentativas excedidas, lista de bloqueio, etc.). Array vazio quando não existirem. items: type: object properties: feature: type: string description: Funcionalidade que gerou o aviso. Aqui é sempre `PHONE`. risk: type: string description: Código de risco legível por máquina. additional_data: type: object nullable: true description: >- Contexto específico do risco (por exemplo, o ID de sessão duplicado para riscos de duplicado). `null` quando o risco não contiver dados adicionais. log_type: type: string enum: - error - warning - information description: >- Gravidade. Os riscos `error` levam à recusa da verificação, `warning` sinaliza-a para revisão e `information` é registada sem afetar o estado. short_description: type: string description: Resumo de uma linha legível por humanos sobre o risco. long_description: type: string description: Explicação legível do risco. lifecycle: type: array description: >- Registo de auditoria cronológico da verificação. O `type` de evento é um dos seguintes: `PHONE_VERIFICATION_MESSAGE_SENT`, `PHONE_VERIFICATION_RETRY_MESSAGE_SENT`, `PHONE_VERIFICATION_BLOCKED`, `PHONE_DELIVERY_DELIVERED`, `PHONE_DELIVERY_UNDELIVERABLE`, `VALID_CODE_ENTERED`, `INVALID_CODE_ENTERED`, `PHONE_VERIFICATION_APPROVED`, `PHONE_VERIFICATION_DECLINED`, `PHONE_VERIFICATION_IN_REVIEW`, `PHONE_VERIFICATION_EXPIRED`. items: type: object properties: type: type: string description: Tipo de evento. timestamp: type: string format: date-time description: Quando o evento aconteceu. details: type: object nullable: true description: >- Payload específico do evento. Eventos de envio: `{status, reason, channel, actual_channel}` (`actual_channel` é preenchido assim que a entrega for confirmada). Eventos de entrega: `{channel, status}`. Eventos de introdução de código: `{code_tried, status}`. Eventos de estado final: `null`, ou `{reason}` quando recusada ou em análise. fee: type: number description: >- Montante em USD faturado por este evento. Diferente de zero apenas em eventos de envio (o preço de entrega); 0 para introduções de código, confirmações de entrega e eventos de estado. matches: type: array description: >- Outras sessões da sua aplicação (KYC, KYB ou API) onde o mesmo número de telefone foi utilizado por um utilizador diferente (`vendor_data` diferente). Até 5 entradas; uma correspondência sintética de entrada na lista de bloqueio surge primeiro, quando presente (correspondências derivadas de sessões mantêm a ordem da consulta). Array vazio quando não existirem correspondências. items: type: object properties: session_id: type: string format: uuid description: >- ID de sessão da outra verificação que utilizou este número de telefone. session_number: type: integer description: Número sequencial legível da sessão. vendor_data: type: string nullable: true description: '`vendor_data` dessa sessão.' verification_date: type: string description: Quando essa sessão foi criada (`YYYY-MM-DDTHH:MM:SSZ`). phone_number: type: string description: O número de telefone correspondido. status: type: string description: >- Estado dessa sessão (por exemplo, `Approved`, `Declined`, `In Progress`). is_blocklisted: type: boolean description: >- Se o número de telefone está na lista de bloqueio da sua aplicação. api_service: type: string nullable: true description: >- Para sessões do tipo API, a API autónoma que a criou (por exemplo, `PHONE_VERIFICATION`); `null` para sessões de verificação normais. source: type: string description: >- Onde a correspondência foi encontrada. Habitualmente `session`; uma ocorrência na lista de bloqueio através de uma entrada de lista da organização prefixa uma correspondência sintética com `source: "list_entry"` e `session_id`/`session_number` nulos. phone_social: $ref: '#/components/schemas/PhoneSocialFootprint' phone_intelligence: allOf: - $ref: '#/components/schemas/PhoneIntelligence' description: >- Sinais de inteligência telefónica. Presente apenas quando `enable_enrichment` foi `true` na verificação. vendor_data: type: string nullable: true description: >- `vendor_data` da sessão da verificação correspondente. `null` em `Expired or Not Found`. metadata: type: object nullable: true description: >- `metadata` da sessão da verificação correspondente. `null` em `Expired or Not Found`. created_at: type: string format: date-time description: Carimbo de data/hora desta resposta de verificação. PhoneSocialFootprint: type: object nullable: true description: >- Presença social (social footprint) do número de telefone: as plataformas online em que está registado. Presente apenas quando `enable_social` foi definido e a verificação foi concluída. Cada contagem pode ser nula quando não foram devolvidos dados para ela. `profiles_registered: 0` significa que as plataformas foram verificadas e o número de telefone não foi encontrado em nenhuma delas - uma resposta válida, faturável e um sinal comum de identidade sintética. properties: profiles_registered: type: integer nullable: true description: >- Plataformas onde o número de telefone está confirmado como registado. example: 5 profiles_checked: type: integer nullable: true description: Plataformas avaliadas quanto ao registo. example: 14 names_found: type: integer nullable: true description: Plataformas que devolveram um nome associado. example: 0 photos_found: type: integer nullable: true description: Plataformas que devolveram uma fotografia de perfil. example: 0 communication_breadth: type: integer nullable: true description: Plataformas de comunicação com presença detetada. example: 2 digital_footprint_diversity: type: integer nullable: true description: Categorias de plataforma distintas com presença detetada. example: 5 digital_sophistication_index: type: integer nullable: true description: Indicador composto de maturidade digital, 0-10. example: 5 engagement_depth_index: type: integer nullable: true description: Indicador do nível de detalhe do perfil, 0-10. example: 3 subscription_affordability_index: type: integer nullable: true description: Distribuição da plataforma gratuita vs paga, 0-10. example: 2 free_platforms: type: integer nullable: true description: Registos em plataformas gratuitas. example: 4 full_paid_platforms: type: integer nullable: true description: Registos em plataformas totalmente pagas. example: 0 partial_paid_platforms: type: integer nullable: true description: Registos em plataformas freemium. example: 1 whatsapp_profile_completeness: type: string nullable: true enum: - Basic - Partial - Complete - Not Present - null description: >- Grau de preenchimento do perfil do WhatsApp. Apenas para telefone; nulo para e-mail. example: Partial registered_platforms: type: array description: Plataformas onde o registo está confirmado. items: $ref: '#/components/schemas/SocialFootprintPlatform' not_registered_platforms: type: array description: Plataformas verificadas com resultado negativo. items: $ref: '#/components/schemas/SocialFootprintPlatform' categories: type: object description: Contagem e proporção de registos por categoria de plataforma. additionalProperties: $ref: '#/components/schemas/SocialFootprintCategorySummary' profiles: type: object description: >- Detalhes de perfil por plataforma, indexados por plataforma, quando a plataforma os disponibiliza. additionalProperties: $ref: '#/components/schemas/SocialFootprintProfile' PhoneIntelligence: type: object description: >- Bloco de inteligência de telefone normalizado. Presente apenas quando o suplemento de inteligência foi executado para esta consulta; quando presente, também é exposto sob o alias `enrichment` com valores idênticos. properties: score: type: number nullable: true description: Pontuação de risco normalizada de 0-100. Mais alto é mais arriscado. phone_type_risk: type: string nullable: true description: '`Low`, `Medium` ou `High`, derivado da pontuação.' phone_trust_index: type: number nullable: true description: >- Inverso da pontuação, para painéis que preferem que quanto maior, melhor. network_stability_index: type: number nullable: true description: Estabilidade da rede associada à linha. is_disposable: type: boolean nullable: true description: '`true` quando o número parece descartável ou virtual.' is_ported: type: boolean nullable: true description: '`true` quando o número mudou de operadora.' is_recently_ported: type: boolean nullable: true description: '`true` quando a portabilidade ocorreu recentemente.' carrier_type: type: string nullable: true description: >- Classificação da linha comunicada pela consulta (por exemplo, `mobile`). reason_codes: type: array items: type: object properties: code: type: string description: >- Identificador Didit estável do sinal, por exemplo `IR-5AC67A32`. Opaco: agrupe e filtre por ele, não tente analisá-lo. value: nullable: true description: >- Para um sinalizador de risco (por exemplo, `voip`, `leaked`, `disposable`, `spam_trap`), o respetivo valor: um booleano, um nível ou uma data. Nulo para um código de motivo com pontuação. direction: type: string enum: - risk - trust description: Se o sinal aumentou o risco ou adicionou confiança. message: type: string description: Explicação legível do sinal, em inglês. impact_level: type: string nullable: true description: >- Com que intensidade o sinal influenciou a pontuação, por exemplo `low`, `medium` ou `high`. description: >- Sinais que explicam a pontuação, cada um com um código Didit estável, uma direção, uma mensagem e um nível de impacto. Podem surgir novos códigos ao longo do tempo, pelo que não deve rejeitar códigos desconhecidos. SocialFootprintPlatform: type: object properties: platform: type: string description: Identificador da plataforma. example: whatsapp category: type: string description: >- Categoria da plataforma, por exemplo, MESSAGING, SOCIAL_MEDIA, ECOMMERCE, PROFESSIONAL, EMAIL_PROVIDER. example: MESSAGING scope: type: string enum: - global - local description: >- `global` para plataformas mundiais, `local` para plataformas específicas de uma região. example: global SocialFootprintCategorySummary: type: object properties: registered: type: integer nullable: true description: Plataformas nesta categoria onde o registo está confirmado. example: 2 ratio: type: number format: float nullable: true description: >- Percentagem de plataformas verificadas da categoria com registo, 0.0-1.0. example: 0.6667 SocialFootprintProfile: type: object properties: name: type: string nullable: true description: Nome do perfil, quando a plataforma o disponibiliza. photo: type: string nullable: true description: URL da fotografia de perfil, quando a plataforma o disponibiliza. about: type: string nullable: true description: >- Texto de biografia/apresentação do perfil, quando a plataforma o disponibiliza. privacy_status: type: string nullable: true enum: - PUBLIC - PRIVATE - null description: Visibilidade do perfil, quando a plataforma a disponibiliza. business_account: type: boolean nullable: true description: >- Se o perfil é uma conta empresarial, quando a plataforma o disponibiliza. 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.