CheckNumber.AI · 8 min read
Strings de números de telefone na serialização de API: preserve cada dígito
Um plano de teste para desenvolvedores para preservar valores de telefone como strings, desde a captura até a exportação em lote.
As strings de números de telefone na serialização de API devem permanecer como texto desde a captura até o JSON, armazenamento e exportação. Um valor de telefone é um identificador, não uma quantidade para cálculo; portanto, a conversão numérica pode resultar na perda de um zero à esquerda, do sinal de mais ou de dígitos significativos de baixa ordem. Antes do envio em lote, utilize um teste de ida e volta (round-trip) que compare o texto original do telefone com o valor final legível por máquina e sinalize qualquer alteração inexplicável.
Por que as strings de números de telefone são importantes em um fluxo de trabalho de API
Um desenvolvedor pode ver um campo cheio de dígitos e escolher um tipo numérico por hábito. Isso é arriscado porque o campo é um identificador. A aritmética não é significativa, e a conversão para um número pode remover um zero à esquerda ou rejeitar um sinal de mais inicial. O JavaScript possui um limite de precisão específico: a referência de Number do MDN explica que números inteiros além de sua faixa segura podem ser corrompidos quando analisados de JSON para valores Number. O FAQ da libphonenumber do Google documenta um caso de análise de telefone onde os dígitos menores foram alterados devido à precisão numérica do JavaScript.
Até mesmo valores mais curtos podem ser alterados pelo manuseio de dados. Um campo de CRM pode omitir um código de país, um número local pode ter um zero à esquerda significativo e uma planilha pode exibir um valor arredondado. O invariante para o desenvolvedor não é “todas as entradas são números de telefone válidos”. É “a aplicação consegue identificar qual texto recebeu e qual texto enviou posteriormente”. A validação e a normalização podem seguir, com cada alteração registrada separadamente.
Este artigo trata do pipeline de dados do cliente antes de um fluxo de trabalho em lote do CheckNumber. O CheckNumber oferece suporte à verificação em lote de listas de números de telefone suportadas por upload de CSV ou TXT e acesso via API REST. Suas capacidades de produto documentadas não implicam que o serviço repare um número já corrompido no JSON ou banco de dados do cliente.
Rastreie o valor através de cada limite
Anote o caminho que um valor de telefone percorre: formulário de lead ou arquivo de origem, solicitação de aplicação, análise de JSON, coluna de banco de dados, leitura de aplicação, transformação de exportação, bytes finais de CSV ou TXT e envio em lote. Em cada etapa, identifique o tipo de dado e se alguma função de formatação pode alterar caracteres. Um rótulo de exibição em uma interface de usuário não é suficiente; o texto armazenado subjacente e a exportação final são o que importa.
Armazene o texto original e um valor preparado separadamente. Se uma etapa de normalização que reconhece o país alterar a pontuação ou adicionar um código de país confirmado, o valor preparado pode diferir legitimamente, mas o original deve permanecer disponível para comparação. Não sobrescreva a única cópia do valor de origem enquanto depura uma conversão. Se um número já estiver arredondado quando chegar de um campo numérico upstream, converter esse valor arredondado para uma string não pode recuperar os dígitos perdidos. Retorne à fonte autoritativa em vez de inventar caracteres ausentes.
A ITU-T E.164 recommendation descreve o plano de numeração internacional. O painel gratuito do CheckNumber, Number Cleaner, pode normalizar números de telefone para E.164 e remover duplicatas e entradas inválidas antes de uma verificação paga. Essa preparação é distinta da obrigação do desenvolvedor de preservar o texto de origem. A normalização que reconhece o país deve ser revisada em relação ao contexto de país conhecido antes que um arquivo em lote seja criado.
Crie um teste de ida e volta para desenvolvedores sem assumir um esquema de produto
Crie um teste do lado do cliente com um ID de registro de teste estável, string de telefone original, país confirmado e string preparada esperada. Crie vários casos sintéticos: um valor com um sinal de mais inicial, um valor local com um zero à esquerda, uma longa string de dígitos escolhida para revelar erros de precisão numérica, um valor com separadores e um valor duplicado associado a dois IDs de registro separados. Use valores de teste reservados ou que não sejam de contato no ambiente da própria equipe e rotule-os como sintéticos. Este teste verifica a serialização e o mapeamento; ele não afirma que qualquer valor de teste é um número real, válido ou registrado.
Para cada caso, afirme o seguinte caminho na aplicação do cliente: o campo capturado é texto; a representação JSON permanece uma string; a ida e volta do banco de dados retorna caracteres originais idênticos; e a exportação final contém o texto preparado pretendido. Se a normalização fizer parte do pipeline, compare sua saída com uma expectativa revisada separadamente e mantenha a string original. Uma verificação de contagem de dígitos e uma comparação caractere por caractere podem detectar uma conversão que uma visualização de planilha oculta.
Adicione um teste para um número compartilhado entre dois IDs de registro. A exportação pode desduplicar uma entrada de consulta, mas o mapeamento do lado do cliente ainda deve conectar a observação final no nível do número a ambos os registros de origem. Não presuma que uma exportação de verificador retém IDs personalizados ou a ordem de origem, a menos que o contrato atual do produto selecionado diga isso. O teste deve exercitar o processo de mapeamento do cliente sem fabricar uma solicitação de API ou um exemplo de resposta de verificador.
Inspecione a exportação final como dados, não como visualização de planilha
Um CSV aberto em um software de planilha pode ser reformatado para exibição. O arquivo final deve ser inspecionado como texto legível por máquina antes de ser enviado. Verifique os caracteres exatos em cada linha de telefone, especialmente o sinal de mais, zeros à esquerda, código de país e últimos dígitos. Se a exportação for gerada a partir de uma consulta de banco de dados, compare uma amostra de linhas com os valores originais e preparados armazenados sob os mesmos IDs de teste.
Para uploads de listas de telefone do CheckNumber, use um país por arquivo e um número por linha com o código do país; o sinal de mais inicial é opcional. Os uploads suportados usam CSV ou TXT. Essas regras de upload não devem ser copiadas cegamente para uma solicitação REST não documentada. Os desenvolvedores devem usar a documentação de API atual para o produto suportado selecionado e confirmar sua interface e limites reais antes da implementação.
Mantenha registros com evidências de país ausentes ou alterações de dígitos inexplicáveis em uma fila de revisão gerenciada pelo cliente. Uma exportação limpa que contém o número errado é pior do que uma exceção explícita, porque a verificação pode ser concluída enquanto o resultado é atribuído ao registro de origem incorreto. Mantenha o motivo da exceção e o ID de origem para que o proprietário dos dados upstream possa corrigi-lo.
Torne a preservação uma condição de lançamento
Execute o teste de ida e volta sempre que o código alterar um analisador, modelo JSON, tipo de banco de dados, mapeamento de importação ou exportador de arquivos. Compare os valores originais e preparados em limites fixos em vez de verificar apenas se a aplicação terminou sem erro. Um teste deve falhar quando um caractere inexplicável desaparece, aparece ou muda de posição. Ele também deve falhar quando uma linha exportada final não puder ser vinculada ao registro de origem pretendido.
Para listas de produção, reconcilie linhas de origem, números preparados distintos, exceções retidas, linhas enviadas e resultados correspondentes posteriormente. Essas são contagens de auditoria do lado do cliente, não números de desempenho esperados do verificador. Uma incompatibilidade pode revelar linhas descartadas ou desduplicação que perdeu o mapeamento. Quando a questão posterior diz respeito a um sinal de validade documentado, revise o Phone Number Checker como uma etapa separada. Os resultados específicos do verificador podem ser exportados para revisão e segmentação controladas pelo cliente, mas sua interpretação depende do produto nomeado selecionado após a preparação da entrada.
A regra de desenvolvimento principal é simples: preserve identificadores como texto, torne a normalização explícita e verifique os bytes finais que entram no fluxo de trabalho em lote. Isso protege o significado de uma verificação subsequente sem afirmar que a serialização por si só estabelece a validade, propriedade ou registro em plataforma do número.
FAQ
Como os desenvolvedores podem evitar que os dígitos do telefone mudem no JSON?
Mantenha o valor como uma string de ponta a ponta e teste uma ida e volta através da análise, armazenamento e exportação. Uma conversão numérica pode perder caracteres significativos ou precisão.
Converter um número arredondado de volta para texto pode recuperar dígitos perdidos?
Não. A fonte autoritativa deve ser verificada quando o valor já tiver sido alterado antes de chegar à aplicação.
O que um teste de string de telefone deve incluir?
Use casos sintéticos para sinais de mais iniciais, zeros à esquerda, longas strings de dígitos, separadores e valores duplicados mapeados para IDs de origem distintos, então compare a exportação final com as expectativas revisadas.
Onde os desenvolvedores devem encontrar o formato de entrada da API do CheckNumber?
Consulte a documentação de API atual para o produto em lote suportado selecionado. Este artigo descreve um teste de preservação do lado do cliente, em vez de um esquema de solicitação de API.
