Autenticação e respostas de API

Usar credenciais de API

Envie solicitações v3 por HTTPS para https://api.multitel.net. Todos os endpoints deste guia exigem autenticação. Mantenha as credenciais em seu servidor e nunca as coloque em JavaScript de navegador, páginas públicas, capturas de tela ou controle de código-fonte.

Use uma destas formas de credencial:

• HTTP Basic com o nome de usuário e a senha de API configurados para sua conta MultiTEL.
• Token Bearer em um cabeçalho Authorization: Bearer YOUR_API_TOKEN, para uma conta API habilitada configurada para autenticação com token. Solicitações com token são aceitas somente de endereços permitidos para essa conta de API.

Se uma lista de permissões de IP estiver configurada para sua conta API, envie todas as solicitações de endereços permitidos.

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

curl --header "Authorization: Bearer $API_TOKEN" 'https://api.multitel.net/v3/getcountries'

As variáveis nestes exemplos são espaços reservados para credenciais que você armazena de forma privada em seu ambiente.

Tratar falhas de autenticação

Falhas de autenticação são enviadas com status 401 de HTTP. O corpo usa o envelope padrão, com status.code definido como 401 e uma string vazia como response.

• Sem credenciais: status.msg é Username and password are required, e a resposta inclui um desafio de autenticação Basic.
• Token Bearer rejeitado: se o cabeçalho Authorization usa o esquema Bearer e o token é desconhecido, está desabilitado ou não é permitido a partir do seu endereço, status.msg é Invalid bearer token. Nenhuma outra credencial é tentada quando um cabeçalho Bearer está presente.
• Credenciais Basic inválidas: status.msg começa com A valid username and password pair are required., e a resposta inclui um desafio de autenticação Basic. A mensagem pode conter mais texto de diagnóstico, portanto não a analise.

Não tente novamente automaticamente com as mesmas credenciais. Muitas tentativas com falha de um endereço em um curto período podem fazer com que outras solicitações desse endereço sejam bloqueadas.

Ler o corpo da resposta

A maioria dos endpoints v3, incluindo getcountries, getstates, getareas e other, retornam JSON neste envelope:

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "countrycode": "1",
      "name": "United States",
      "description": "United States",
      "isocode": "US",
      "is_mobile": 0,
      "sms_coverage": 1,
      "latitude": "38.0000",
      "longitude": "-97.0000",
      "next_function": "v3/getareas/US"
    }
  ]
}

Esta é uma resposta ilustrativa de lista de países, não uma declaração do inventário ou das capacidades atuais.

Uma resposta de erro se parece com isto:

{
  "status": {
    "code": 404,
    "msg": "No areas found"
  },
  "response": ""
}

Se uma resposta não puder ser codificada, o corpo tem status.code 500, status.msg Response encoding error, e um objeto vazio como response.

O endpoint legado GET /v3/countries retorna {"code": 200, "data": [...]} em vez disso. Verifique a resposta documentada de cada endpoint. Se um corpo não for JSON válido, por exemplo após uma falha inesperada do servidor, trate a solicitação como falha e tente novamente mais tarde.

Códigos de resultado de API e status HTTP

status.code é o código de resultado de API. Não é o status HTTP. Falhas de autenticação são enviadas com HTTP 401. Caso contrário, os endpoints de descoberta relatam resultados como 404 e 500 somente em status.code e não definem um status HTTP correspondente. Um resultado de não encontrado ou de parâmetro ausente pode, portanto, chegar com um status HTTP bem-sucedido. Verifique sempre status.code antes de usar response.

O código de resultado 500 com a mensagem ISO Code parameter is required significa que um parâmetro obrigatório está ausente. Corrija a solicitação em vez de tratá-la como uma interrupção do servidor.

Seguir next_function

Os resultados da descoberta incluem next_function. É um caminho relativo sem barra inicial, às vezes com uma string de consulta, como v3/getareas/US ou v3/getareas/US?state=NY. Prefixe-o com https://api.multitel.net/ para criar a próxima solicitação, e autentique essa solicitação da mesma maneira. Filtros opcionais que você enviou, como pid, não são transportados para next_function. Adicione-os novamente se precisar deles.

Seletor de inventário opcional (pid)

getcountries, getstates e getareas aceitam o parâmetro de consulta opcional pid que limita os resultados a uma fonte de inventário. Use-o somente com um valor fornecido por MultiTEL, em sua forma numérica ou em sua forma hexadecimal de 32 caracteres. Omita-o para uso normal. Envie pid na string de consulta. Se o endpoint não reconhecer nem aceitar o valor, ele o ignora sem erro, e a solicitação se comporta como se pid tivesse sido omitido.

Separar descoberta de pedidos

Consultas de país, estado e área não alteram sua conta. O catálogo de números especiais (other) atualiza os detalhes do catálogo e salva cotações de preços para sua conta, mas não faz nenhum pedido. Nenhuma solicitação de descoberta reserva um número, e o inventário pode mudar entre solicitações. Revise os requisitos e o preço de um número antes de usar um endpoint de pedido.

Para compras, atribuições, mensagens, envios de fax e outras ações, siga as próprias regras de repetição desse endpoint. Se uma ação expirar após o envio, verifique seu status ou os registros de sua conta antes de repeti-la. Uma resposta perdida não prova que a ação falhou.