Listar os estados dos Estados Unidos ou as províncias do Canadá com números em estoque

Use esta etapa opcional para os Estados Unidos ou o Canadá para restringir a busca por estado ou província. Apenas US e CA são aceitos.

Cada entrada descreve os prefixos em estoque para esse estado no momento da solicitação.
Siga next_function para listar as áreas do estado. O link já inclui o filtro state mas não pid.
A consulta de áreas determina as correspondências das informações de estado de uma forma ligeiramente diferente. Se, para um estado, next_function retornar No areas found, chame getareas sem especificar um estado como alternativa.
Verifique status.code antes de ler response. Um país não aceito, ou um país sem estoque que corresponda aos filtros, retorna o código 404 sem um status HTTP correspondente.
Uma lista vazia com o código 200 significa que existe estoque, mas ele não contém informações de estado. Chame getareas sem especificar um estado.

Solicitação

Obrigatório: autenticação HTTP Basic ou um token Bearer (consulte Autenticação e respostas da API). Se a autenticação falhar, a resposta será HTTP 401 antes da execução da consulta.

GET com isocode no caminho. Se esse segmento do caminho for omitido, será lido, em seu lugar, um campo isocode codificado como formulário. O parâmetro opcional pid é enviado na cadeia de consulta.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getstates/US'

Parâmetros de caminho
Nome	Tipo	Obrigatório	Descrição
`isocode`	cadeia de caracteres	Sim	US ou CA. Não diferencia maiúsculas de minúsculas; os espaços em branco no início e no fim são ignorados.

Parâmetros de consulta
Nome	Tipo	Obrigatório	Descrição
`pid`	cadeia de caracteres	Não	Avançado e opcional. Restringe os prefixos contabilizados a uma única fonte de inventário. Use apenas um valor fornecido pela MultiTEL, em formato numérico ou hexadecimal de 32 caracteres, e omita-o no uso habitual. Sem pid, são contabilizadas todas as fontes atualmente oferecidas para busca. Valores não reconhecidos são ignorados sem gerar erro. Se a fonte selecionada não tiver prefixos em estoque disponíveis para a sua conta, o resultado será 'No states found'.

Resposta

Estrutura de encapsulamento padrão. Em caso de sucesso, status.code é 200, status.msg está vazio e status.results é a quantidade de entradas. response é uma lista ordenada por name (sem diferenciar maiúsculas de minúsculas) e, depois, pelo código state. Campos: state (código do estado ou da província extraído dos dados de estado dos prefixos, normalmente com duas letras; valores incomuns são retornados sem alterações); name (nome no catálogo, ou o código quando o catálogo não tem um nome para ele); country_iso; available (estoque total dos prefixos contabilizados, sempre maior que 0); prefix_count (quantidade de prefixos em estoque contabilizados); is_mobile (1 se algum prefixo contabilizado oferecer suporte à telefonia móvel; sempre 0 para US, a menos que sua conta esteja habilitada para números móveis dos Estados Unidos); sms_coverage (1 se algum prefixo contabilizado tiver cobertura de SMS); returns_numbers (1 se algum prefixo contabilizado tiver o indicador de retorno de números ou não tiver um valor para esse indicador); next_function ('v3/getareas/{isocode}?state={state}'). Se houver prefixos em estoque, mas nenhum contiver informações de estado, o resultado será status.code 200 com uma lista vazia e status.results 0.

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

{
  "status": {
    "code": 200,
    "msg": "",
    "results": 2
  },
  "response": [
    {
      "state": "NY",
      "name": "New York",
      "country_iso": "US",
      "available": 120,
      "prefix_count": 8,
      "is_mobile": 0,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "next_function": "v3/getareas/US?state=NY"
    },
    {
      "state": "TX",
      "name": "Texas",
      "country_iso": "US",
      "available": 45,
      "prefix_count": 3,
      "is_mobile": 0,
      "sms_coverage": 0,
      "returns_numbers": 1,
      "next_function": "v3/getareas/US?state=TX"
    }
  ]
}

Erros

500: msg 'ISO Code parameter is required': isocode está ausente ou em branco. Este é um erro de solicitação que pode ser corrigido. Não é definido um status HTTP correspondente; leia status.code.
404: msg 'getstates is only available for US and CA': qualquer outro código de país. Não é definido um status HTTP correspondente.
404: msg 'No states found': nenhum prefixo em estoque corresponde aos filtros de país e fonte. Não é definido um status HTTP correspondente.
401: autenticação ausente ou com falha. Enviado com o status HTTP 401.

Disponibilidade e efeitos colaterais

Somente consulta. Não reserva, faz pedidos nem altera nada. available é informativo e não retém números.