Introdução à API do Verify

Verify permite que você confirme o número de telefone de um usuário enviando uma senha de uso único (OTP) por meio de diversos canais, como SMS, e-mail, mensagem de voz e WhatsApp. Você pode definir um fluxo de trabalho para controlar quais canais serão utilizados e em que ordem.

Este guia mostra como chamar a API Verify de forma síncrona, utilizando um fluxo de trabalho que primeiro tenta enviar uma mensagem SMS e, caso isso falhe, recorre a uma chamada de voz. Você também aprenderá a personalizar o comprimento do código OTP e os intervalos de espera entre as etapas.

Pré-requisitos

Este guia pressupõe que:

• Você tem um account na Vonage. Caso contrário, pode criar um gratuitamente aqui.
• Você tem cURL instalado no seu sistema.

Criar um novo aplicativo

Para começar, precisamos criar um novo aplicativo. Esse aplicativo conterá as credenciais necessárias para autenticar as chamadas à API. Siga estas etapas:

1. Acesse o Painel de controle do aplicativo Vonage.
2. Clique Criar um novo aplicativo.
3. No Nome campo, digite um nome para o seu aplicativo.
4. No Autenticação seção, clique em Gerar chave pública e chave privada para gerar um novo par de chaves. Um arquivo de chave privada (.key) será baixado automaticamente. Salve esse arquivo em um local seguro, pois ele é necessário para autenticar suas chamadas de API.
5. Agora vá para o Recursos seção. Como não queremos receber atualizações assíncronas de status, você pode deixar o Verify função desativada.
6. Por fim, clique no Criar um novo pedido botão para concluir o processo de criação.

Depois que o aplicativo for criado, copie o ID do aplicativo exibido no painel. Você precisará desse ID do aplicativo, juntamente com o arquivo da chave privada, para gerar JWTs para autenticação de solicitações de API.

Verify usuários finais com OTP

Para verificar os usuários finais por meio de uma senha de uso único (OTP), siga estas duas etapas:

1. Solicitar um código de verificação. O usuário final receberá o código por meio de um dos canais especificados na sua chamada de API.
2. Verifique o código de verificação fornecido. Uma segunda chamada à API validará o código inserido pelo usuário.

Solicitar um código de verificação

De acordo com o Especificação da API, o primeiro passo é enviar uma solicitação POST para o /v2/verify ponto de extremidade. Essa chamada de API inicializa o fluxo de trabalho de verificação que tenta enviar a OTP por SMS e, caso isso falhe, por chamada de voz.

curl -X POST "https://api.nexmo.com/v2/verify" \
    -H "Authorization: Bearer $JWT" \
    -H 'Content-Type: application/json' \
    -d $'{
        "brand": "TestVerify",
        "code_length": 5,
        "channel_timeout": 30,
        "workflow": [
        {
            "channel": "sms",
            "to": "'$PHONE_NUMBER'"
        },
        {
            "channel": "voice",
            "to": "'$PHONE_NUMBER'"
        }
    ]
}'

Vamos dar uma olhada nos cabeçalhos e no corpo da solicitação para entender melhor a chamada à API.

Se a solicitação for bem-sucedida, você receberá um 200 Ok resposta contendo um request_id no corpo:

{
   "request_id":"3b4363c9-1234-567a-90ab-c45a134561bc"
}

Ao mesmo tempo, o usuário final deve receber um SMS contendo um código de verificação de 5 dígitos. Se o usuário não concluir a verificação em 30 segundos (conforme definido por channel_timeout), receberão automaticamente uma ligação de voz na qual o código será lido em voz alta.

Você precisará tanto do request_id e o código digitado pelo usuário para concluir a verificação na próxima etapa.

Verifique o código de verificação fornecido

Assim que o usuário final receber o código, você deve enviar uma solicitação POST para o /v2/verify/{request_id} ponto final, substituindo {request_id} com o número de identificação que você recebeu na ligação anterior:

curl -X POST "https://api.nexmo.com/v2/verify/$VERIFY_REQUEST_ID" \
  -H "Authorization: Bearer $JWT"\
  -H 'Content-Type: application/json' \
  -d $'{
    "code": "'$VERIFY_CODE'"
  }'

Cabeçalhos da solicitação:

Corpo da solicitação:

Se a solicitação for bem-sucedida, você receberá um 200 OK resposta informando que o processo de verificação foi concluído:

{
   "request_id":"3b4363c9-1234-567a-90ab-c45a134561bc",
   "status":"completed"
}

Conclusão

Neste guia, você aprendeu a implementar a verificação do usuário final usando a API Verify com uma configuração multicanal: começando com SMS e recorrendo a Voz se necessário.

Os exemplos do cURL apresentados aqui têm exclusivamente fins didáticos. Em uma implementação real, você deve integrar o Verify diretamente ao seu backend, usando o seu preferido linguagem de programação.

E agora?

Agora que você já entende como funciona a API Verify e o quanto a abordagem multicanal é eficaz, explore os diferentes canais compatíveis que você pode usar na sua verificação fluxo de trabalho.

Melhore seu processo de verificação implementando Autenticação silenciosa, o que permite que você verifique usuários por meio do tráfego móvel sem que eles precisem digitar uma senha de uso único (OTP).

Por fim, não se esqueça de conferir o Especificação da API, onde você encontrará mais parâmetros úteis para aproveitar ao máximo a API do Verify.