Escolha um prefixo individual
Utilize as chamadas de descoberta de países e áreas de cobertura e, em seguida, getprefixes sem agrupamento. Copie o valor do prefixo selecionado no campo uuid. Se returns_numbers for 0, o prefixo atribui um número no momento do pedido; utilize o valor devolvido em next_function em vez de exigir uma lista de números individuais.
Consulte um lote de tamanho limitado
Para uma pesquisa normal, utilize compact=1 e indique o tamanho pretendido do lote tanto no caminho como no parâmetro de consulta quantity, conforme apresentado abaixo. Não existe um parâmetro de página ou de cursor. Um resultado compacto é uma amostra; repetir um pedido não garante uma página seguinte sem sobreposição. Não interprete um resultado vazio ou pequeno como a contagem total do inventário.
Encontre um padrão de dígitos fácil de memorizar
Indique number_filter_mode=contains ou ends_with juntamente com number_filter_value. O valor deve conter 1–15 dígitos. Uma pesquisa pode obter lotes limitados de candidatos antes de aplicar o filtro, pelo que pode deixar de encontrar outros números correspondentes no inventário. Se precisar de uma fonte compatível para aplicar a pesquisa exigida, obtenha um seletor pid junto da MultiTEL e utilize filter_required=1; uma seleção ausente ou não suportada devolve um erro da API.
Verifique o número selecionado
Consulte number, info.uuid, o valor selecionado de price[].uuid, os nomes das funcionalidades disponíveis e os requisitos de registo no mesmo resultado. O array price pode apresentar vários planos com diferentes quantidades de canais e tarifas. Os campos monetários e as quantidades podem ser codificados como cadeias de caracteres. Os metadados opcionais, incluindo info.state, variam entre fontes; não exija uma estrutura universal para o estado nem deduza preços a partir de um ID.
No fluxo sem transmissão progressiva, os candidatos são deduplicados e distribuídos entre as fontes antes de o lote selecionado ser ordenado pelo preço mensal do primeiro plano. Outros fluxos podem iniciar a transmissão mais cedo, pelo que não existe uma garantia global de ordenação ou deduplicação aplicável a todos os pedidos. A ordenação também não prova que a amostra devolvida contém o número mais barato de todo o catálogo.
Faça o pedido separadamente e confirme o resultado
Uma pesquisa não compra nem reserva nada. Guarde os identificadores devolvidos do número e do plano para o processo de pedido na mesma conta. Verifique o plano efetivo, os requisitos e os encargos antes de submeter um pedido. Os requisitos de registo podem atrasar a ativação; um resultado de pesquisa não estabelece um prazo fixo de ativação.
Pedido
Utilize uma conta ativa da API MultiTEL: credenciais HTTP Basic para uma conta com palavra-passe, ou Authorization: Bearer para uma conta com token. Aplicam-se as permissões da conta e as respetivas restrições de IP. Consulte as orientações gerais de autenticação.
Parâmetros do caminho e parâmetros de consulta do URL. Utilize GET para o fluxo público de pesquisa. O processamento também aceita determinados valores de formulário/pedido, mas não se trata de uma API de pesquisa com corpo JSON.
curl --fail-with-body --get \
--user "${MULTITEL_API_USERNAME}:${MULTITEL_API_PASSWORD}" \
--data-urlencode "compact=1" \
--data-urlencode "quantity=10" \
"https://api.multitel.net/v3/getnumbers/${PREFIX_ID}/10"| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
prefix_id | string | Sim | ID de um prefixo individual devolvido por uma resposta de getprefixes sem agrupamento. Copie-o exatamente; não o substitua por um ID de país, área de cobertura, prefixo agrupado ou plano de preços. |
quantity | integer | Não | Quantidade pretendida na obtenção, com valor predefinido de 1. Os valores não positivos passam a 1. O parâmetro quantity no caminho, por si só, não é um limite global fiável para os resultados: uma pesquisa sem fonte fixada e sem o parâmetro de consulta quantity pode alargar a obtenção e devolver até 50 entradas por fonte antes de outros processamentos. Para uma consulta normal com tamanho limitado, utilize compact=1 e repita a quantidade pretendida na consulta, como no exemplo. |
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
quantity | integer | Não | Tamanho final solicitado para o lote. Os valores não vazios são convertidos em inteiros, com um mínimo de 1. No fluxo sem fonte fixada e sem transmissão progressiva, isto limita a distribuição final. Não obriga o serviço a encontrar essa quantidade de números. As pesquisas compactas fixadas numa fonte podem devolver o lote compacto dessa fonte em vez de respeitarem este limite. |
compact | string | Não | Utilize 1, true ou on para uma resposta menor sem transmissão progressiva, com até 10 entradas por fonte antes da distribuição final. Os resultados são uma amostra do inventário obtido nesse momento, não um catálogo completo. |
number_filter_mode | string | Não | Modo opcional de padrão de dígitos: contains ou ends_with. Indique também number_filter_value. Os resultados são verificados com base nos dígitos normalizados dos números de telefone; a pesquisa não percorre todo o inventário para garantir todas as correspondências possíveis. |
number_filter_value | string | Não | Entre 1 e 15 dígitos, sem espaços, + ou pontuação. Os zeros iniciais são significativos; envie o valor como texto. |
filter_required | string | Não | Avançado: 1, true, yes ou on exige uma fonte de inventário explicitamente selecionada que suporte o modo de filtro. Caso contrário, a API devolve status.code 422. Isto não é necessário para a consulta normal do catálogo. |
pid | string | Não | Seletor avançado de inventário fornecido pela MultiTEL. São aceites as formas numéricas e as formas hexadecimais suportadas de 32 caracteres; os valores não reconhecidos são ignorados sem aviso. Omita-o na utilização normal. Não deduza seletores a partir de IDs de preços nem presuma que um seletor arbitrário restringe o inventário exclusivamente a essa seleção. |
Resposta
Um objeto JSON que contém status e response. Em caso de sucesso, status.code é 200 e response é um array de entradas de números. status.results é a contagem de elementos do array devolvido; status.msg pode ser Results: N ou OK numa resposta com transmissão progressiva. Sem compact=1, algumas pesquisas escrevem o array response de forma incremental e terminam com status, pelo que deve aguardar o corpo JSON completo. Não se trata de JSON delimitado por quebras de linha. Verifique status.code mesmo quando o transporte HTTP é bem-sucedido. Os campos típicos são apresentados abaixo; os metadados específicos de cada fonte e os campos opcionais variam. Trate todos os identificadores como opacos e guarde em conjunto o número e o respetivo price[].uuid selecionado.
Estrutura de resposta ilustrativa; não representa dados reais da conta nem uma cotação atual.
{
"status": {
"code": 200,
"msg": "Results: 1",
"results": 1
},
"response": [
{
"number": "12125550123",
"info": {
"uuid": "NUMBER_ID_FROM_RESPONSE",
"prefix_uuid": "PREFIX_ID_FROM_RESPONSE",
"area_uuid": "AREA_ID_FROM_RESPONSE",
"country_uuid": "COUNTRY_ID_FROM_RESPONSE",
"country_iso": "US",
"prefix": "+1212",
"name": "Example area",
"state": "US"
},
"price": [
{
"uuid": "PRICE_PLAN_ID_FROM_RESPONSE",
"per_minute": "0.01",
"per_sms": "0",
"per_mms": "0",
"free_minutes": "0",
"setup_price": "1.00",
"monthly_price": "2.00",
"yearly_price": "0",
"channels": "2"
}
],
"contract": {
"term": "1 month",
"renewal": "monthly",
"notice": "none"
},
"restrictions": {
"needs_registration": "0",
"restrictions": ""
},
"features": [
"voice"
],
"overflow": "0"
}
]
}Erros
- 401: Falha na autenticação. Credenciais inválidas ou ausentes e acesso recusado à conta da API não produzem resultados de pesquisa.
- 404: Invalid prefix ID, Invalid country, Invalid area ou No numbers found. Consulte status.msg; uma resposta de erro não é um array de números.
- 400: NUMBER_FILTER_INVALID em response.code: modo inválido, um valor que não seja composto por 1–15 dígitos ou filter_required sem que tanto o modo como o valor estejam presentes.
- 422: NUMBER_FILTER_UNSUPPORTED em response.code: ou o prefixo atribui um número no momento do pedido (reason=order_only_prefix e next_function identifica a rota para fazer o pedido), ou a fonte explicitamente selecionada não suporta o filtro exigido.
Disponibilidade e efeitos secundários
- Este processamento pesquisa e prepara cotações; não submete pedidos de números nem debita encargos de compra de números. Pode atualizar as caches do catálogo, remover inventário desatualizado em cache, guardar planos de preços no âmbito da conta e escrever registos de pesquisa.
- A disponibilidade é um resultado relativo a um determinado momento, não uma reserva. Um pedido posterior pode falhar ou devolver uma disponibilidade diferente. Confira o resultado do pedido antes de voltar a tentar uma compra.
- Os preços são específicos de cada conta. Guarde o ID do plano selecionado para a mesma conta e verifique separadamente os termos e os encargos do pedido; este endpoint, por si só, não prova que um preço permanecerá válido até um pedido posterior.
- O número e os preços apresentados são exemplos fictícios da estrutura da resposta, não uma cotação em tempo real. As funcionalidades, as quantidades de canais, o prazo contratual e as informações de registo devem ser consultados no resultado efetivamente selecionado.
- Algumas descrições de registo contêm texto formatado ou ligações. Trate as cadeias de caracteres devolvidas como dados não fiáveis ao apresentá-las na sua aplicação.
- A disponibilidade de números móveis e os respetivos indicadores dependem da elegibilidade da conta e do inventário. Um prefixo do catálogo ou o indicador is_mobile, por si só, não comprova as funcionalidades móveis de um determinado número.