Esta API pode verificar ou recuperar o número de telefone celular atualmente alocado pela operadora de rede ao SIM no dispositivo do usuário final

Number Verification

(Stable CAMARA APIs)

Descrição da API

A API “Verificação de Número” é um serviço que permite que empresas confirmem facilmente a propriedade de um número de telefone celular e recuperem o número diretamente do dispositivo do usuário.
Dois mecanismos são utilizados para obter as informações:

Baseado em rede: a operadora de rede sabe a qual assinante um telefone móvel conectado à rede pertence e qual é o seu número de telefone associado ou,
Baseado em SIM: Mecanismo de autenticação baseado na identificação do SIM do assinante instalado no dispositivo do usuário.

Esta API garante que o número de telefone fornecido ou obtido corresponda ao associado ao dispositivo do usuário, permitindo uma autenticação segura e confiável. Esta API elimina a necessidade de entradas manuais, como códigos SMS, simplificando processos como criação de conta, login ou validação de transações. Ela oferece uma solução prática para setores que exigem verificação e recuperação precisas de números de telefone, aprimorando a experiência do usuário, a prevenção de fraudes e a eficiência operacional.

Como a API de verificação de número ajuda a facilitar a autenticação?

A API de Verificação de Número utiliza mecanismos de telecomunicações para autenticar usuários perfeitamente com base na conexão de seus dispositivos à rede. Este método contrasta com as soluções de autenticação tradicionais, aumentando a conveniência e a segurança do usuário. Ao contrário de processos manuais ou códigos de texto simples, a validação baseada em rede não requer interação do usuário, reforçando a proteção contra acesso não autorizado.
Esta API verifica se o número de telefone celular fornecido (MSISDN) corresponde ao dispositivo que inicia a comunicação de dados, garantindo que os usuários interajam com serviços digitais de dispositivos autenticados.

Casos de uso

Funcionalidade da API

A API define um endpoint de serviço:

POST /verify

Recebe o identificador da assinatura da rede (por exemplo, o número de telefone celular de um assinante da rede móvel) e verifica se a idade do assinante é superior ao limite de idade na solicitação. Além disso, como função opcional, fornece

(1) se a verificação da idade é feita com base em outra forma de identificação oficial ou não (verifiedStatus),
(2) uma pontuação geral de quão certa é a resposta usando as informações fornecidas na solicitação e as informações que a operadora possui (identityMatchScore),
(3) um indicador sobre se a assinatura possui algum tipo de bloqueio de conteúdo (contentLock) e
(4) um indicador sobre se a assinatura possui algum tipo de controle parental ativado (parentalControl).

Entradas

O corpo da solicitação do endpoint é um objeto JSON com os seguintes parâmetros:

phoneNumber: O identificador de assinatura da rede (ou seja, o número de telefone do assinante). [Obrigatório apenas caso um fluxo de duas etapas tenha sido acordado entre o Provedor da API e o Consumidor da API, seguindo as diretivas da CAMARA; caso contrário, o número de telefone não deve ser incluído]
ageThreshold: O limite de idade a partir do qual a idade do usuário deve ser comparada. [Obrigatório]
qualquer um dos idDocument, name, givenName, familyName, middleNames, familyNameAtBirth, birthdate, email; informações adicionais do assinante a serem verificadas para confirmar que o assinante é o proprietário do contrato [Opcional]
includeContentLock e includeParentalControl: Essas duas sinalizações permitem que o Cliente da API indique que as propriedades de resposta correspondentes contentLock e parentalControl devem ser retornadas. Sua implementação é opcional para o Provedor da API, portanto, nesses casos, esses parâmetros serão ignorados. [Opcional]

Exemplo de Request body:

<syntaxhighlight lang="json"> {

 "ageThreshold": 18,
 "phoneNumber": "+34629255833",
 "idDocument": "66666666q",
 "name": "Federica Sanchez Arjona",
 "givenName": "Federica",
 "familyName": "Sanchez Arjona",
 "middleNames": "Sanchez",
 "familyNameAtBirth": "YYYY",
 "birthdate": "1978-08-22",
 "email": "federicaSanchez.Arjona@example.com",
 "includeContentLock": true,
 "includeParentalControl": true

} </syntaxhighlight>

Saídas

Se bem-sucedido, um objeto JSON será retornado contendo os seguintes dados:

ageCheck: Indique 'true' quando a idade do usuário for igual ou superior ao limite de idade (idade >= limite de idade) e 'false' caso contrário (idade < limite de idade). Caso contrário, 'not_available'.
verifiedStatus: verdadeiro se as informações fornecidas foram verificadas com outra forma de identificação oficial; caso contrário, falso.
identityMatchScore: A pontuação geral das informações de identidade disponíveis no Operador, informações fornecidas no corpo da solicitação, comparando-as com as que o MNO possui, ou utilizando diretamente informações internas do MNO. É opcional para o Operador retornar a pontuação de correspondência de identidade.
contentLock: Indica se a assinatura associada ao número de telefone tem algum tipo de bloqueio de conteúdo (ou seja, determinado conteúdo da web bloqueado).
parentalControl: Indica se a assinatura associada ao número de telefone tem algum tipo de controle parental ativado.

Exemplo de Response 200 OK:

<syntaxhighlight lang="json"> {

 "ageCheck": "true",
 "verifiedStatus": true,
 "identityMatchScore": 90,
 "contentLock": "false",
 "parentalControl": "true"

} </syntaxhighlight>

Erros

Se o token de acesso de autenticação não for válido, um 401 UNAUTHENTICATED erro será retornado
Se a chamada da API contiver um erro de formatação ou qualquer outro erro sintático, um 400 INVALID_ARGUMENT erro será retornado.
Se a assinatura da rede não puder ser identificada a partir dos parâmetros fornecidos (por exemplo, o identificador da assinatura não estiver associado a nenhum cliente do CSP), um 404 IDENTIFIER_NOT_FOUND erro será retornado.
Se o consumidor da API tiver um token de acesso válido que não tenha o escopo necessário para obter informações de verificação de idade para a assinatura de rede especificada, um 403 PERMISSION_DENIED erro será retornado.
Outros erros podem ser retornados conforme especificado abaixo.