Orientação de produto
Integrando a API de Consulta da operadora original: Fluxos de trabalho de operadora original e tipo de linha
Aprenda a integrar a API de Consulta da operadora original para obter dados de operadora, tipo de linha e geografia de alocação em fluxos em tempo real e em lote.
Integre a API de Consulta da operadora original para inspecionar a alocação da operadora original, o tipo de linha e a geografia de numeração usando endpoints REST em tempo real e processamento de arquivos em lote.
A API de Consulta da operadora original fornece contexto sobre a operadora original e a alocação de números para o gerenciamento de dados de telecomunicações. Quando as organizações consultam um número de telefone usando a API, o serviço retorna dados que indicam a operadora à qual o bloco de números foi inicialmente atribuído, juntamente com o tipo de linha e a geografia de alocação. Essas informações representam a atribuição administrativa definida pelos planos de numeração, fornecendo um contexto de telecomunicações estável para fluxos de trabalho internos de roteamento e avaliação de risco. Como reflete a alocação inicial em vez do roteamento de rede do assinante ativo, as equipes integram a CarrierLookup para inspecionar parâmetros fundamentais de números por meio de endpoints únicos em tempo real, consultas síncronas de múltiplos itens ou arquivos de lote em massa assíncronos.
Atributos de dados de alocação principal e tipo de linha
Os arranjos de numeração de telecomunicações seguem padrões internacionais, como a ITU-T Recommendation E.164, que define planos de numeração globais com códigos de país e números de assinante. Dentro dessas estruturas, as autoridades reguladoras atribuem blocos de números específicos às operadoras de rede. A CarrierLookup expõe essas propriedades fundamentais por meio de sua capacidade de consulta da operadora original.
O esquema de resposta organiza o contexto de telecomunicações em pontos de dados distintos:
- carrier: O provedor de comunicação ao qual a faixa de numeração foi originalmente alocada.
- underlying_carrier: O provedor de infraestrutura subjacente associado à faixa atribuída.
- number_type: A classificação da linha, como atribuição móvel ou fixa.
- country_code: O prefixo de discagem internacional correspondente ao território de alocação.
- region e city: O território geográfico administrativo designado no plano de atribuição de numeração.
Esses pontos de dados estabelecem atributos de faixa estáticos. Como os números mantêm suas definições de faixa iniciais independentemente da atividade do assinante, esses dados atuam como uma referência consistente para filtragem, análise de telecomunicações e organização de registros internos.
Integração de verificação única e múltipla em tempo real
A integração de consultas em tempo real permite que os sistemas de backend avaliem números de telefone de forma síncrona durante fluxos de trabalho de entrada ou revisão de aplicativos. As solicitações são autenticadas usando o cabeçalho HTTP X-API-Key enviado de um servidor de aplicativo seguro.
Fluxo de trabalho de verificação de número único
Para verificar um identificador individual, envie uma solicitação para POST /api/v1/check. O payload requer um número de telefone formatado na sintaxe E.164 padrão internacional, apresentando um sinal de mais inicial, código do país e dígitos do assinante sem espaços ou pontuação.
Após o processamento, o servidor retorna uma resposta JSON contendo code, msg e um objeto data simples. O payload de dados contém service_type, identifier, carrier, underlying_carrier, number_type, country_code, region e city. Campos de alocação opcionais podem retornar vazios se detalhes específicos não estiverem listados para essa faixa, mas a consulta é registrada como concluída.
Fluxo de trabalho de verificação múltipla síncrona
Para lotes que exigem avaliação imediata, as organizações chamam POST /api/v1/batch-check. Este endpoint processa vários números E.164 de forma síncrona em uma única chamada. A resposta retorna métricas de execução de alto nível ao lado de uma matriz ordenada:
service_type: Confirma o serviço de consulta executado.total: A contagem de identificadores enviados.succeeded: O número de itens avaliados com sucesso.failed: O número de itens que encontraram falhas de processamento.results: Uma coleção ordenada de itens, cada um contendoidentifiereexists.
Nesta resposta múltipla síncrona, um valor exists=false indica que nenhum registro de alocação padrão foi retornado, em vez de afirmar uma linha desconectada ou malformada.
Fluxo de trabalho de processamento de arquivos em lote assíncronos
Ao processar inventários extensos de registros de telecomunicações, as equipes utilizam o serviço assíncrono carrier_batch. Este fluxo de trabalho lida com envios baseados em arquivos sem manter as conexões do cliente abertas.
Envio e estrutura da tarefa
Envie solicitações de lote via POST /api/v1/bulk-tasks usando dados de formulário multipart. O upload requer um arquivo TXT ou CSV simples contendo um identificador por linha, juntamente com um parâmetro de país ISO especificado. Limites por produto se aplicam aos tamanhos das tarefas, e os leitores podem revisar os parâmetros operacionais atuais na documentação oficial da API.
Durante a ingestão, o pré-processamento automatizado revisa o conteúdo da lista para filtrar duplicatas, entradas malformadas e linhas correspondentes a países fora do alvo selecionado. O processamento exclui essas entradas não conformes da contabilidade de consultas.
Ciclo de vida e recuperação da tarefa
Os clientes monitoram o progresso do lote consultando GET /api/v1/bulk-tasks/{id}. Os cronogramas de sondagem devem seguir uma cadência medida, verificando não mais do que uma vez a cada 30 segundos. O ciclo de vida da tarefa transita por três estados formais:
processing: O arquivo está passando por avaliação do sistema.failed: A tarefa encontrou um erro de execução ou falhou nos requisitos de entrada.success: A avaliação da faixa está concluída e a saída está disponível.
Quando uma tarefa termina com success, o endpoint fornece um único arquivo CSV. A estrutura de saída contém sete cabeçalhos padronizados: identifier, carrier, underlying_carrier, number_type, country_code, region e city. O identificador neste arquivo é renderizado como dígitos com o código do país, omitindo símbolos de mais.
Limites operacionais e especificações de cobertura
Implementar uma integração de consulta de operadora requer alinhar a arquitetura técnica com a simultaneidade do sistema e parâmetros geográficos.
| Parâmetro Operacional | Detalhes da Especificação |
|---|---|
| Slots de simultaneidade | 5 solicitações em tempo real compartilhadas em trânsito |
| Tempo limite de verificação única | 60 segundos de duração máxima |
| Tempo limite de verificação múltipla | 300 segundos de duração máxima |
| Simultaneidade de solicitação múltipla | 1 solicitação múltipla ativa por conta |
| Endpoint de saldo da conta | GET /api/v1/balance (retorna balance_micros) |
A cobertura geográfica apresenta regras regionais distintas. As consultas de número único em tempo real acomodam solicitações na China continental (+86), Hong Kong (+852) e Macau (+853) para volumes operacionais modestos. No entanto, arquivos de lote em massa não aceitam números dessas três regiões. O status de cobertura para Taiwan (+886) permanece não confirmado.
Para verificar o status da conta antes de invocar verificações, consulte GET /api/v1/balance para recuperar o saldo atual sem consumir consultas. Além disso, usuários recém-registrados podem entrar em contato com o suporte para receber 100 verificações gratuitas para validar seus fluxos de trabalho de integração em relação aos endpoints de produção.
FAQ
Como a API lida com números que foram portados entre redes?
A CarrierLookup relata a operadora à qual a faixa de numeração foi originalmente atribuída pelas autoridades administrativas. Em telecomunicações, os consumidores podem trocar de provedor mantendo seu número, conforme descrito em Porting: Keeping Your Phone Number When You Change Providers. Consequentemente, o campo da operadora reflete essa alocação histórica de faixa em vez da operadora de serviço atual, mantendo um atributo estrutural inalterado para análise de numeração.
O que distingue a verificação múltipla em tempo real do serviço de lote em massa?
O endpoint de verificação múltipla em tempo real POST /api/v1/batch-check avalia números de forma síncrona, retornando um payload JSON imediato com service_type, total, succeeded, failed e resultados ordenados mostrando o identificador e um booleano exists. Em contraste, o serviço de lote em massa processa listas de forma assíncrona a partir de arquivos CSV ou TXT enviados. Assim que a análise em segundo plano termina, as tarefas em lote fornecem um CSV para download contendo colunas de alocação completas, incluindo carrier, underlying_carrier, number_type, country_code, region e city.
Os campos de região e cidade indicam a localização física do dispositivo?
Os campos de região e cidade designam o limite geográfico da alocação do plano de numeração inicial, correspondendo à atribuição administrativa da central telefônica. Esses valores fornecem contexto territorial para o bloco de números do assinante. Eles representam atribuições de numeração estáticas, em vez de posicionamento de dispositivo móvel em tempo real, conexões de torre celular ao vivo ou o paradeiro físico de um assinante individual.
Saiba mais
Escolha as informações do produto que se ajustam ao próximo passo em seu fluxo de trabalho.