Listar as áreas de cobertura de um país

Depois de escolher um país (e, para os EUA ou o Canadá, opcionalmente um estado através de getstates), faça uma chamada a getareas para ver onde são disponibilizados números. Guarde o valor de uuid da área para o próximo passo.

Cada área conduz a um de dois passos seguintes:

• available > 0: next_function é v3/getprefixes/{uuid}, com ?state= acrescentado quando tiver aplicado um filtro por estado. Utilize-o para consultar os prefixos.
• available = 0: a área tem prefixos, mas não tem stock, e next_function é v3/order/{uuid}. Consulte a documentação de pedidos para saber o que este passo exige.

available é o total de toda a área, mesmo quando aplica um filtro por estado. O filtro por estado aceita um código ou um nome completo, mas só funciona para US e CA. Se um filtro por estado devolver No areas found, tente novamente sem o filtro. As verificações são executadas nesta ordem: código de país em falta, país desconhecido, filtro por estado para outro país, estado inválido, nenhuma área correspondente. Cada uma destas situações devolve o código 500 ou 404 em status.code, sem um estado HTTP correspondente.

Requisição

Obrigatório: autenticação HTTP Basic ou token Bearer (consulte Autenticação e respostas da API). Uma falha de autenticação recebe uma resposta HTTP 401 antes de a consulta ser executada.

GET com isocode no caminho e os parâmetros opcionais state e pid na cadeia de consulta. Se o segmento do caminho for omitido, é lido, em alternativa, um campo isocode codificado como formulário.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US'
curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US?state=NY'

Resposta

Estrutura padrão da resposta. Em caso de sucesso, status.code é 200, status.msg é 'Results: N', status.results é N e response é uma lista ordenada pelo nome da área. Campos: uuid (identificador opaco da área utilizado no próximo passo); country_uuid (identificador opaco do país com 32 caracteres, que não é necessário posteriormente); name; area_type e number_type (descritores do catálogo; as entradas não correspondem necessariamente a tipos de números locais); country_iso; is_mobile (0 ou 1, obtido dos indicadores de números móveis da área; sempre 0 para US, a menos que a sua conta esteja habilitada para números móveis de US); available (stock total dos prefixos correspondentes da área, sem se limitar ao estado solicitado); sms_coverage (0 ou 1); returns_numbers (0 ou 1, o valor mais alto deste indicador entre os prefixos da área); latitude e longitude; state_iso; next_function. state_iso: com um filtro por estado, é o código obtido ao resolver o filtro. Para US e CA sem filtro, é o estado cujo nome é igual ao nome da área; caso contrário, é o valor armazenado para a área ou, na sua ausência, um código derivado dos dados dos prefixos da área. Para os outros países, é o valor armazenado e pode estar vazio. next_function é 'v3/getprefixes/{uuid}' (com '?state={code}' acrescentado quando é aplicado um filtro) quando available é superior a 0; caso contrário, é 'v3/order/{uuid}'. As áreas sem qualquer prefixo correspondente são omitidas. As áreas com prefixos, mas sem stock, são devolvidas com available igual a 0.

Estrutura de resposta meramente ilustrativa; não representa dados da conta em tempo real nem uma cotação atual.

{
  "status": {
    "code": 200,
    "msg": "Results: 2",
    "results": 2
  },
  "response": [
    {
      "uuid": "0000000000000000000000000000a001",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Example City",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 58,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "latitude": "40.0000",
      "longitude": "-75.0000",
      "state_iso": "NY",
      "next_function": "v3/getprefixes/0000000000000000000000000000a001"
    },
    {
      "uuid": "0000000000000000000000000000a002",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Sample Town",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 0,
      "sms_coverage": 0,
      "returns_numbers": 0,
      "latitude": "41.0000",
      "longitude": "-76.0000",
      "state_iso": "PA",
      "next_function": "v3/order/0000000000000000000000000000a002"
    }
  ]
}

Erros

• 500: msg 'ISO Code parameter is required': isocode está em falta ou em branco. Trata-se de um erro da requisição que pode ser corrigido. Não é definido um estado HTTP correspondente.
• 404: msg 'Error: no such country': o código do país é desconhecido. Não é definido um estado HTTP correspondente.
• 404: msg 'State filter is only available for US and CA': foi enviado um valor não vazio de state para outro país. Não é definido um estado HTTP correspondente.
• 404: msg 'Invalid state': state não é um código nem um nome conhecido para o país. Não é definido um estado HTTP correspondente.
• 404: msg 'No areas found': nenhuma área corresponde aos filtros de país, fonte e estado. Não é definido um estado HTTP correspondente.
• 401: autenticação em falta ou falhada. Enviado com o estado HTTP 401.

Disponibilidade e efeitos secundários

• Apenas consulta, para contas de clientes. Não reserva, não efetua pedidos nem altera nada.
• available é meramente informativo e pode mudar antes do próximo passo.