Listar prefixos de uma área

Antes de começar

Escolha uma área através de getareas. Copie o ID da área da respetiva resposta ou do valor devolvido em next_function. Para uma área dos Estados Unidos ou do Canadá, utilize getstates se quiser limitar os resultados a um estado ou província.

Interpretar o resultado

Verifique status.code no corpo JSON, bem como o estado HTTP. Os resultados bem-sucedidos encontram-se no array response. Por predefinição, a resposta é ordenada por nome. available é uma estimativa, e os indicadores do catálogo não dispensam a verificação das funcionalidades reais e dos requisitos de registo do número selecionado.

Selecionar o próximo passo

Utilize um resultado não agrupado. Quando returns_numbers é 1, o valor devolvido em next_function aponta para uma pesquisa de números. Quando é 0, os números são atribuídos no momento da encomenda e o caminho aponta para uma operação de encomenda. Examine a operação e os respetivos requisitos antes de enviar o pedido: um pedido de encomenda pode gerar uma cobrança na sua conta. Não execute automaticamente pedidos para todos os caminhos devolvidos.

Não é incluído qualquer preço aqui. Consulte o orçamento aplicável, os documentos necessários e as instruções de encomenda antes de comprar. Conserve os IDs devolvidos do prefixo individual e do orçamento, em vez de os construir a partir de um prefixo telefónico apresentado.

Opções avançadas de apresentação

compact=1 devolve uma amostra em ordem aleatória com, no máximo, 100 linhas, e não uma página de um conjunto maior de resultados. O agrupamento cria linhas de resumo e IDs sintéticos; utilize uma resposta normal não agrupada para selecionar um prefixo individual. Não utilize resultados de amostragem ou agrupados para afirmar que o inventário é exaustivo ou que as funcionalidades são exatas.

Pedido

Utilize as credenciais da sua conta de API ativada através de HTTPS. São suportados a autenticação Basic e os tokens bearer ativados para a conta de API; aplicam-se as restrições da conta.

Utilize GET e envie os parâmetros opcionais na cadeia de consulta. Não dependa do recurso alternativo ao corpo de formulário.

curl --fail-with-body --silent --show-error \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/v3/getprefixes/$AREA_ID?state=NY"

Resposta

O invólucro JSON padrão status/response. status.results conta as linhas devolvidas, incluindo as resultantes de amostragem ou agrupamento. response contém objetos de prefixo. Não são devolvidos campos de preço. Na resposta normal não agrupada, uuid é o ID do prefixo; area_uuid e country_uuid são identificadores devolvidos; prefix e name são informações de apresentação; available é uma estimativa de disponibilidade, não uma reserva; needs_registration e restrictions descrevem informações de registo; sms_coverage, is_mobile e number_type são indicações do catálogo, não uma garantia de uma funcionalidade específica de um número. number_type pode estar vazio ou conter outra cadeia de caracteres do catálogo, pelo que não deve exigir uma enumeração fixa. state é uma cadeia de caracteres e pode estar vazio ou conter formatação do catálogo. latitude e longitude podem estar vazios. metered e overflow são indicadores do catálogo, não valores monetários. returns_numbers seleciona uma rota de listagem de números (1) ou uma rota de atribuição no momento da encomenda (0). next_function identifica essa próxima rota. As respostas agrupadas contêm ainda funcionalidades combinadas, incluindo valores de recurso para funcionalidades; não os interprete como funcionalidades verificadas de todos os números.

Estrutura de resposta ilustrativa; não corresponde a dados da conta em tempo real nem a um orçamento atual.

{
  "status": {
    "code": 200,
    "msg": "",
    "results": 1
  },
  "response": [
    {
      "uuid": "PREFIX_ID_FROM_RESPONSE",
      "area_uuid": "AREA_ID_FROM_RESPONSE",
      "country_uuid": "COUNTRY_ID_FROM_RESPONSE",
      "prefix": "+1212",
      "name": "Example area",
      "metered": 0,
      "overflow": 0,
      "needs_registration": 0,
      "restrictions": "",
      "state": "NY",
      "country_iso": "US",
      "is_mobile": 0,
      "number_type": "local",
      "latitude": "",
      "longitude": "",
      "available": 12,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "next_function": "v3/getnumbers/PREFIX_ID_FROM_RESPONSE"
    }
  ]
}

Erros

• 404: Invalid area ID: obtenha um ID de área atual através das consultas de descoberta.
• 404: State filter is only available for US and CA: omita state para outros países.
• 404: Invalid state: utilize um estado/província devolvido por getstates para este país.
• 404: No prefixes found: não foram devolvidas linhas correspondentes do catálogo. Isto não prova que um determinado número nunca possa ser encomendado.
• 500: Erro: 'Failed loading prefixes': a consulta ao catálogo falhou. Tente novamente mais tarde e contacte o suporte se o problema persistir.

Disponibilidade e efeitos secundários

• Este é um passo de descoberta, não uma confirmação de encomenda. A disponibilidade pode ser atualizada através de consultas adicionais ao catálogo, pelo que o tempo de resposta pode variar.
• Os preços não são devolvidos. Obtenha o orçamento aplicável ao número ou à encomenda e consulte os requisitos de registo antes de efetuar uma encomenda.
• Não interprete available como uma contagem exata de existências, zero como uma proibição universal de encomendar, nem uma consulta bem-sucedida como uma reserva. A disponibilidade pode mudar antes da encomenda.