Encontrar números móveis disponíveis

Confirme que o inventário móvel está ativado

Use esta pesquisa somente depois de o inventário de números móveis ter sido ativado para a sua conta de cliente. Obtenha um prefixo móvel individual atual por meio do fluxo de descoberta da conta. O caminho suportado solicita o inventário sem fio para esse prefixo. Ele não depende de um registro correspondente de metadados de roteamento fixo. Contacte o suporte se não tiver a certeza de se a sua conta ou o seu prefixo está ativado.

A rota legada atual não rejeita de forma confiável todos os pedidos inelegíveis. Uma conta sem o inventário móvel ativado pode receber inventário comum enquanto a resposta ainda diz info.is_mobile: 1. Um prefixo gratuito também pode chegar ao ramo de inventário gratuito com essa etiqueta. Não use essa etiqueta sozinha para identificar o serviço móvel e não envie prefixos comuns ou gratuitos para este endpoint. Use o catálogo móvel confirmado da conta e o fluxo ativado.

Mantenha cada número com a sua própria seleção de preço

Para cada candidato, mantenha number, info.uuid e a lista price dessa mesma entrada juntos. A resposta também contém metadados de prefixo/área/país, termos contratuais e restrições de registro. Os candidatos são ordenados pelo preço mensal da primeira opção de preço, em ordem crescente; não há uma ordem estável garantida para preços iguais. Não substitua o ID do número devolvido por um ID de área ou de prefixo, nem o combine com o ID de preço de outro candidato.

A resposta completa pode incluir campos adicionais de metadados e de preço. Os campos features, os valores de canal e as restrictions devolvidas descrevem o candidato; não são uma garantia de que chamadas, SMS, MMS ou fax já estão utilizáveis. As permissões da conta, o registro e o plano de serviço selecionado continuam a aplicar-se. Não trate os marcadores do exemplo como IDs ou preços válidos.

Use uma quantidade pequena e positiva

Comece com uma quantidade de 1. O pedido normal ao fornecedor normaliza uma quantidade não positiva para 1 e limita o valor a montante em 300, mas o tratamento posterior dos resultados ainda usa a entrada original. Uma quantidade zero pode, por isso, solicitar inventário a montante e não devolver candidatos. Outros ramos legados não impõem de forma consistente a contagem de resultados pedida. Não dependa de um único máximo universal nem envie valores negativos, fracionários ou não numéricos. Nenhum filtro público de pesquisa suportado nem parâmetro de corpo com ID de preço está documentado para esta rota.

Distinga a falta de estoque de uma falha de consulta

Uma resposta 404 pode representar inventário indisponível, serviço desativado, falha na consulta ao fornecedor ou registos de catálogo inválidos. Trate um tempo limite ou uma falha do fornecedor como disponibilidade desconhecida, e não como estoque zero confirmado. Atualize a seleção e tente novamente com um intervalo de espera entre tentativas (backoff) quando apropriado. Evite consultar repetidamente todas as centrais. O endpoint separado de contagem de inventário móvel é uma dica de instantâneo e não precisa de corresponder ao comprimento da lista de candidatos desta conta.

Verifique novamente antes de comprar

A pesquisa não reserva estoque. O ramo revisto tenta excluir os números já comprados, mas uma falha na consulta local de reservas pode deixar tal candidato no resultado. A disponibilidade, a propriedade, os preços aprovados e o registro devem ser verificados pelo fluxo de compra. Use uma seleção nova com o pedido de compra protegido e reconcilie o inventário da conta após qualquer resultado de compra incerto antes de tentar novamente. Nunca compre apenas porque um candidato foi devolvido.

Pedido

Use uma conta de API ativada por HTTPS a partir de um endereço IP de origem permitido. O inventário móvel também deve estar ativado para a conta do cliente; a autenticação de API por si só não o ativa.

GET com o identificador atual do prefixo individual e uma quantidade positiva inteira no caminho do URL. A quantidade assume 1 por omissão se for omitida. Use o exemplo com 1; esta rota não valida nem impõe de forma consistente um limite universal de resultados.

curl --fail-with-body --silent --show-error \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/v3/getmobiles/$PREFIX_ID/1"

Resposta

Inspecione status.code e status.msg no corpo JSON, além do estado HTTP. Em caso de sucesso, response é uma lista de candidatos a número, status.msg é Results: seguido do número devolvido e status.results é o comprimento serializado da lista. Os preços dos candidatos são específicos da conta. O exemplo abreviado e ilustrativo usa marcadores em vez de inventário real ou de uma cotação de tarifas. Os números contêm o código do país sem sinal de mais; os identificadores são cadeias opacas.

Forma ilustrativa da resposta; não são dados reais da conta nem uma cotação atual.

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "number": "12025550123",
      "info": {
        "uuid": "NUMBER_ID",
        "prefix_uuid": "PREFIX_ID",
        "country_iso": "US",
        "is_mobile": 1
      },
      "price": [
        {
          "uuid": "PRICE_ID",
          "monthly_price": "ACCOUNT_MONTHLY_PRICE",
          "setup_price": "ACCOUNT_SETUP_PRICE",
          "per_minute": "ACCOUNT_INCOMING_RATE",
          "channels": "PLAN_CHANNELS"
        }
      ],
      "features": [
        "voice",
        "sms",
        "mms",
        "t38"
      ]
    }
  ]
}

Erros

• 404: ID de prefixo, país ou área inválido: atualize a seleção do prefixo móvel individual.
• 404: Nenhum número encontrado: pode significar falta de estoque utilizável, serviço desativado, falha na consulta ao fornecedor, seleção não suportada ou limitações da conta. Não é prova de uma contagem autoritativa de inventário zero.

Disponibilidade e efeitos colaterais

• A pesquisa não aluga nem reserva um número e o caminho revisto não debita um valor de compra. Contacta o fornecedor de inventário e pode demorar.
• As pesquisas bem-sucedidas gravam entradas de cache de números e preços relacionadas com a conta e registos de consultas. Repetir uma pesquisa não é uma reserva, um bloqueio de preço nem uma compra.
• Os preços, termos, restrições e capacidades devolvidos devem ser revistos para a conta e o número selecionados. Uma etiqueta de funcionalidade não estabelece a ativação, a aprovação de mensagens nem a funcionalidade testada do serviço.