Migração da API de verificação de números para a Verify Silent Auth

Este guia explica como migrar de um fluxo de autenticação silenciosa, utilizando a API de Habilitação de Rede e a API de Verificação de Número, para a API Verify unificada com Autenticação Silenciosa.

A API Verify oferece suporte a ambos síncrono e assíncrono implementações da Autenticação Silenciosa. Este guia segue o assíncrono fluxo, que é o método recomendado para integrar a Autenticação Silenciosa.

Comparação entre a arquitetura legada e a nova

Antes de iniciar a migração, leia as seções abaixo para entender as diferenças entre a arquitetura antiga e a nova.

Arquitetura legada: habilitação de rede e verificação de números

Na configuração atual, a autenticação silenciosa requer a coordenação de duas APIs distintas. Primeiro, a API de Habilitação de Rede é chamada para verificar se a rede do usuário e o contexto do dispositivo oferecem suporte à autenticação silenciosa. Se houver suporte, a API de Verificação de Número é então utilizada para realizar a verificação silenciosa da identidade móvel propriamente dita.

Essa abordagem apresenta algumas limitações:

• Não há uma alternativa integrada caso a verificação silenciosa não seja compatível.
• Os desenvolvedores devem coordenar manualmente ambas as APIs.
• A lógica de erros e novas tentativas precisa ser implementada no lado do cliente.

Nova arquitetura: Verify com autenticação silenciosa

A nova arquitetura substitui a abordagem em duas etapas por uma única integração que utiliza a API Verify com autenticação silenciosa. Essa abordagem unificada reduz a complexidade, oferece suporte a canais alternativos (como SMS, voz, WhatsApp ou e-mail) quando a verificação silenciosa não é possível e lida automaticamente com callbacks de webhook.

Principais diferenças

A tabela abaixo mostra as principais diferenças entre a abordagem antiga e a nova:

Etapas da migração

Siga as etapas abaixo para migrar da API de Habilitação de Rede e Verificação de Número para a API Verify com Autenticação Silenciosa:

Passo 1: Atualize as configurações do seu aplicativo

Etapa 2: Substituir o fluxo antigo pela API Verify

Etapa 3: Atualizar o método de autenticação

Etapa 4: Atualizar a estrutura da solicitação

Etapa 5: Enviar o check_url para o aplicativo móvel

Etapa 6: Tratar o callback `action_pending`

Etapa 7: O aplicativo móvel segue os redirecionamentos e recebe o código

Etapa 8: Validar o código de verificação

Etapa 9: Tratar o callback de resumo

Atualize as configurações do seu aplicativo

No Painel de controle do aplicativo Vonage, abra as configurações do seu aplicativo. Em Recursos > Registro de rede, atualize a função de retorno de chamada do status do evento “Verify” com a URL na qual seu backend receberá webhook eventos (por exemplo, action_pending, completed).

Substitua o fluxo antigo pela API Verify

Assim que o aplicativo móvel iniciar a autenticação, seu backend deve dar início ao fluxo de autenticação:

Fluxo legado:

1. Chame a API de habilitação de rede.
2. Se a rede for compatível, chame a API de verificação de número para verificar a cobertura.

Novo fluxo:

1. Chame a API do Verify usando o silent_auth fluxo de trabalho.
2. Se a verificação silenciosa falhar, um canal alternativo (por exemplo, SMS, chamada de voz, WhatsApp ou e-mail) é acionado automaticamente, caso esteja definido no fluxo de trabalho (consulte Atualizar a estrutura da solicitação).

Atualizar o método de autenticação

A API Verify oferece suporte a dois métodos de autenticação: Autenticação básica e JWT (token de portador). Consulte o Guia de verificação de autenticação para obter mais detalhes sobre quando usar cada método e como gerar as credenciais.

Atualizar a estrutura da solicitação

A API Verify utiliza um fluxo de trabalho matriz para definir a sequência dos canais de verificação. A autenticação silenciosa deve ser a primeira etapa do fluxo de trabalho, conforme mostrado no exemplo a seguir:

{
  "brand": "ACME",
  "workflow": [
    {
      "channel": "silent_auth",
      "to": "447700900000",
    },
    {
      "channel": "sms",
      "to": "447700900000"
    }
  ]
}   

Passe o check_url para o aplicativo móvel

Após chamar a API Verify, você receberá uma resposta síncrona semelhante a este exemplo:

{
  "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
  "check_url": "https://api.nexmo.com/v2/verify/c11236f4.../silent-auth/redirect"
}   

A resposta inclui o check_url parâmetro, que é semelhante ao auth_url utilizado na verificação de Numbers. O aplicativo móvel deve enviar uma solicitação HTTP GET para esta URL a fim de iniciar o fluxo de autenticação silenciosa.

Você também pode receber o mesmo check_url posteriormente, em um callback de evento (consulte Envie o check_url para o aplicativo móvel), para que você possa passá-lo para o aplicativo a partir de qualquer uma das fontes, dependendo da sua implementação.

Lidar com o action_pending Retorno de chamada

Logo após a solicitação, a Vonage envia uma chamada de retorno de evento para a URL do seu webhook definida em Atualizando as configurações do seu aplicativo.

{
  "request_id": "...",
  "type": "event",
  "channel": "silent_auth",
  "status": "action_pending",
  "action": {
    "type": "check",
    "check_url": "https://eu.api.silent.auth/..."
  }
}   

Você pode usar o check_url a partir da resposta inicial da API (Atualizar a estrutura da solicitação) ou este callback para iniciar a autenticação silenciosa no aplicativo.

O aplicativo móvel acompanha os redirecionamentos e recebe o código

O aplicativo móvel realiza uma GET solicitação à check_url. Ele seguirá um ou mais HTTP 302 é redirecionado e, por fim, recebe uma resposta:

{
  "request_id": "...",
  "code": "si9sfG"
}   

Se for bem-sucedido, esse código deverá ser validado na próxima etapa.

Validar o código de verificação

Envie um POST solicitação do aplicativo móvel à API Verify para validar o código:

POST https://api.nexmo.com/v2/verify/{request_id}
Authorization: Bearer {access_token}
Content-Type: application/json  

Com o seguinte corpo:

{
  "code": "si9sfG"
}   

Se tudo correr bem, a resposta do backend será semelhante a este exemplo:

{
  "request_id": "...",
  "status": "completed"
}   

Tratar o callback de resumo

Assim que a verificação for concluída, a Vonage envia uma resposta final ao seu webhook:

{
  "request_id": "...",
  "type": "event",
  "channel": "silent_auth",
  "status": "completed"
}   

Isso confirma que o fluxo de verificação foi concluído.

Próximos passos

• Teste sua integração em um ambiente de teste. Use números de teste e o Painel do Desenvolvedor para validar tanto os cenários silenciosos quanto os de fallback.
• Confira nosso Guia de Melhores Práticas para Autenticação Silenciosa.
• Monitore eventos de webhook. Certifique-se de que seu backend esteja lidando corretamente com os callbacks de status (por exemplo, action_pending, completed, failed).

Para mais detalhes, consulte o Verify a documentação da API.