API de Detecção de Operadora: Adicionando Contexto de Operadora e Tipo de Linha ao Backend de Cadastro

Um guia de integração de backend para chamar uma API de detecção de operadora após o cadastro via telefone, armazenando a operadora original e o tipo de número como contexto de revisão, e tratando falhas de forma segura.

Uma API de detecção de operadora, em um fluxo de cadastro por telefone, é uma chamada feita no lado do servidor que recebe o número enviado e retorna a operadora à qual sua faixa foi originalmente alocada, o tipo de número e a geografia de alocação. Com o CarrierLookup, o backend normaliza o número para o formato E.164, envia-o para POST /api/v1/check com uma chave de API mantida no servidor e armazena o resultado ao lado da conta como contexto de revisão. O melhor posicionamento é após a aceitação do formulário e antes de qualquer decisão de roteamento ou revisão manual, para que uma consulta lenta ou Indeterminado nunca impeça o usuário de concluir o cadastro.

Detecção de operadora via número de telefone vs. baseada em IP

Pesquisas por uma API de detecção de operadora retornam dois tipos diferentes de serviço, e escolher o errado desperdiça um sprint de integração.

Um backend de cadastro que deseja entender o número de telefone que uma pessoa digitou precisa do segundo tipo. Uma consulta de IP não diz nada sobre o número, e uma consulta de número não diz nada sobre a sessão de navegação. Algumas equipes armazenam ambos, mas eles respondem a perguntas diferentes e devem ficar em campos separados com nomes separados.

Onde a chamada da API de detecção de operadora se encaixa no cadastro

Coloque a consulta no backend, após a validação do seu próprio formulário e antes de qualquer decisão que utilize sua saída. Uma sequência que funciona para a maioria dos produtos:

1. Aceite o formulário. Verifique se o campo de telefone está presente e formatado corretamente.
2. Normalize para E.164. Converta a entrada para o sinal de mais, código do país e dígitos do assinante sem espaços, conforme definido na ITU-T E.164. Verificações síncronas não precisam de uma seleção de país separada, portanto, o código do país dentro do número carrega essa informação.
3. Crie a conta em um estado de contexto pendente. Não mantenha a resposta HTTP aberta enquanto aguarda a consulta se a sua página de cadastro tiver um orçamento de latência apertado.
4. Chame POST /api/v1/check a partir de um job ou worker com um número.
5. Armazene o resultado com o horário da consulta e um status como concluído, vazio ou Indeterminado.
6. Aplique suas próprias regras. Roteie a conta, adicione-a a uma fila de revisão manual ou não faça nada.

Executar a chamada em uma fila mantém o cadastro responsivo e oferece um local natural para novas tentativas.

O que armazenar de cada consulta

Uma verificação concluída descreve a alocação do número em termos simples: a operadora original, a operadora subjacente quando uma marca opera em outra rede, o tipo de número como móvel ou linha fixa, o código do país e a região e cidade associadas à faixa. Armazene-os em campos cujos nomes indiquem o que são, por exemplo, original_carrier em vez de carrier, e allocation_region em vez de location. Região e cidade descrevem onde a faixa foi alocada, o que não é onde a pessoa que está se cadastrando se encontra.

Mantenha três valores adicionais ao lado deles:

• Timestamp da consulta, para que os revisores saibam quão antigo é o contexto.
• Resultado: concluído com valores, concluído com valores vazios ou Indeterminado.
• Entrada enviada, a string E.164 exata, o que torna auditorias e novas verificações posteriores simples.

Um resultado concluído pode legitimamente retornar com todos os campos de operadora vazios. Salve-o como concluído-vazio, não como uma falha e não como evidência de qualquer coisa sobre a conta. Essa distinção importa mais tarde, quando alguém criar um painel sobre esses campos.

Lidando com timeouts, resultados Indeterminado e entrada rejeitada

Três tipos de falha exigem caminhos de código diferentes, e mesclá-los é o erro de integração mais comum.

A API pública documenta limites de timeout para solicitações únicas e múltiplas, e um número limitado de slots síncronos compartilhados em trânsito por conta. Mantenha a concorrência do seu worker abaixo desse orçamento compartilhado em vez de disparar uma solicitação por cadastro em paralelo durante picos de tráfego. Consultas falhas ou Indeterminado não geram cobrança, portanto, uma política de nova tentativa não precisa se preocupar com cobrança dupla, mas ainda deve limitar as tentativas, por exemplo, três tentativas distribuídas ao longo de uma hora, e então deixar a conta com um status Indeterminado para um revisor.

Mantendo a chave da API no servidor

A API REST autentica com um cabeçalho X-API-Key, que deve ser enviado apenas a partir de um servidor confiável. Nunca chame a consulta a partir de JavaScript do navegador ou de um pacote de aplicativo móvel; qualquer pessoa pode extrair uma chave enviada a um cliente e gastar seu saldo com ela.

Controles práticos, em conformidade com o OWASP Secrets Management Cheat Sheet:

• Carregue a chave de um gerenciador de segredos ou do armazenamento de segredos da plataforma de implantação, não do código-fonte.
• Dê acesso de leitura a ela apenas ao worker de consulta.
• Faça a rotação da chave em um cronograma e imediatamente após uma suspeita de vazamento.
• Nunca escreva a chave, ou cabeçalhos de solicitação completos, nos logs da aplicação.
• Monitore o saldo da conta com GET /api/v1/balance, que lê o saldo sem cobrar, e crie alertas para quedas repentinas que não correspondam ao volume de cadastros.

Proteja também o gatilho em si. Limite a taxa do seu próprio endpoint de cadastro para que envios de formulários automatizados não se transformem em um fluxo de consultas pagas.

Usando o resultado no roteamento e revisão

Trate a operadora e o tipo de número como entradas para regras que sua equipe possui, não como vereditos. Alguns exemplos que as equipes usam:

• Testes de roteamento. Agrupe novas contas pela operadora original e compare como diferentes provedores de mensagens funcionam para cada grupo em suas próprias métricas.
• Filas de revisão. Envie contas cujo tipo de número esteja fora do que o produto espera, como um número de linha fixa em um aplicativo mobile-first, para um revisor com o contexto anexado.
• Qualidade de dados. Marque cadastros onde o código do país do número e o país escolhido no formulário discordam, para que o suporte possa solicitar uma correção.

Escreva as regras e mantenha-as reversíveis. Um revisor olhando para uma conta marcada deve ver os valores da consulta, o horário da consulta e a regra que foi acionada. Como a operadora reflete a alocação original, um resultado nunca se sustenta sozinho como prova de que um telefone pode receber um código ou pertence à pessoa que está se cadastrando; combine-o com sua etapa de verificação existente.

FAQ

Como as equipes podem verificar muitas contas existentes que se cadastraram antes da integração?

Use POST /api/v1/batch-check para o catálogo anterior em grupos de até 100 números E.164 por solicitação. Os resultados retornam na ordem de entrada, e cada linha diz se um resultado normal existe. Linhas sem um resultado normal devem ser marcadas para uma nova tentativa posterior, em vez de registradas como vazias. Listas históricas muito grandes são melhor tratadas como uma tarefa de arquivo em lote assíncrona enviada por país.

Como um backend pode evitar pagar pelo mesmo número duas vezes?

Mantenha um cache indexado pela string E.164 normalizada com o horário da consulta. Quando um número já possui um resultado concluído de uma verificação recente, reutilize-o em vez de chamar a API novamente. O contexto de alocação muda lentamente, então muitas equipes atualizam apenas quando um registro é editado ou quando o resultado armazenado é mais antigo do que um período escolhido, como vários meses.

Como os desenvolvedores podem testar a integração antes de entrar em produção?

Aponte o worker para uma configuração de staging com sua própria chave de API e um pequeno saldo, então execute um conjunto de casos roteirizados: um número móvel válido, um número de linha fixa, uma entrada que falha na normalização E.164 e um timeout forçado. Confirme se cada caminho escreve o status de resultado esperado e se nenhuma chave ou cabeçalho aparece nos logs antes de ativar o tráfego de produção.

Saiba Mais

Escolha as informações do produto que se ajustam à próxima etapa do seu fluxo de trabalho.

• Ver a documentação do produto →
• Falar com a equipe →