Autenticación y respuestas de API

Usar credenciales de API

Envíe solicitudes de v3 por HTTPS a https://api.multitel.net. Todos los endpoints de esta guía requieren autenticación. Mantenga las credenciales en su servidor y nunca las ponga en JavaScript del navegador, páginas públicas, capturas de pantalla o control de código fuente.

Utilice una de estas formas de credenciales:

• HTTP Basic con el nombre de usuario y la contraseña de API configurados para su cuenta de MultiTEL.
• Token de Bearer en un encabezado Authorization: Bearer YOUR_API_TOKEN, para una cuenta de API habilitada configurada para la autenticación con token. Las solicitudes con token solo se aceptan desde las direcciones permitidas para esa cuenta de API.

Si hay una lista de permitidos de IP configurada para su cuenta de API, envíe todas las solicitudes desde direcciones permitidas.

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

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

Las variables de estos ejemplos son marcadores de posición para las credenciales que usted almacena de forma privada en su entorno.

Gestionar los fallos de autenticación

Los fallos de autenticación se envían con el estado 401 de HTTP. El cuerpo utiliza el sobre estándar, con status.code establecido en 401 y una cadena vacía como response.

• Sin credenciales: status.msg es Username and password are required, y la respuesta incluye un desafío de autenticación Basic.
• Token de Bearer rechazado: si el encabezado Authorization usa el esquema Bearer y el token es desconocido, está deshabilitado o no está permitido desde su dirección, status.msg es Invalid bearer token. No se prueban otras credenciales cuando hay un encabezado Bearer presente.
• Credenciales Basic no válidas: status.msg comienza con A valid username and password pair are required., y la respuesta incluye un desafío de autenticación Basic. El mensaje puede contener más texto de diagnóstico, por lo que no lo analice.

No reintente automáticamente con las mismas credenciales. Muchos intentos fallidos desde una dirección en un período corto pueden provocar el bloqueo de más solicitudes de esa dirección.

Leer el cuerpo de la respuesta

La mayoría de los endpoints de v3, incluidos getcountries, getstates, getareas y other, devuelven JSON en este sobre:

{
  "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 es una respuesta ilustrativa de lista de países, no una declaración del inventario o las capacidades actuales.

Una respuesta de error tiene este aspecto:

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

Si una respuesta no se puede codificar, el cuerpo tiene status.code 500, status.msg Response encoding error, y un objeto vacío como response.

El endpoint heredado GET /v3/countries devuelve {"code": 200, "data": [...]} en su lugar. Compruebe la respuesta documentada de cada endpoint. Si un cuerpo no es JSON válido, por ejemplo tras un fallo inesperado del servidor, considere la solicitud como fallida y reinténtela más tarde.

Códigos de resultado de API y estado de HTTP

status.code es el código de resultado de API. No es el estado de HTTP. Los fallos de autenticación se envían con HTTP 401. De lo contrario, los endpoints de descubrimiento informan resultados como 404 y 500 solo en status.code y no establecen un estado HTTP coincidente. Por tanto, un resultado de no encontrado o de parámetro faltante puede llegar con un estado HTTP satisfactorio. Compruebe siempre status.code antes de usar response.

El código de resultado 500 con el mensaje ISO Code parameter is required significa que falta un parámetro obligatorio. Corrija la solicitud en lugar de tratarla como una interrupción del servidor.

Seguir next_function

Los resultados de descubrimiento incluyen next_function. Es una ruta relativa sin barra inicial, a veces con una cadena de consulta, como v3/getareas/US o v3/getareas/US?state=NY. Añada como prefijo https://api.multitel.net/ para crear la siguiente solicitud, y autentique esa solicitud de la misma manera. Los filtros opcionales que envió, como pid, no se trasladan a next_function. Añádalos de nuevo si los necesita.

Selector de inventario opcional (pid)

getcountries, getstates y getareas aceptan el parámetro de consulta opcional pid que limita los resultados a una fuente de inventario. Úselo solo con un valor proporcionado por MultiTEL, ya sea en su forma numérica o en su forma hexadecimal de 32 caracteres. Omítalo para el uso normal. Envíe pid en la cadena de consulta. Si el endpoint no reconoce ni acepta el valor, lo ignora sin error, y la solicitud se comporta como si pid se hubiera omitido.

Separar el descubrimiento de los pedidos

Las búsquedas de países, estados y áreas no cambian su cuenta. El catálogo de números especiales (other) actualiza los detalles del catálogo y guarda cotizaciones de precios para su cuenta, pero no realiza ningún pedido. Ninguna solicitud de descubrimiento reserva un número, y el inventario puede cambiar entre solicitudes. Revise los requisitos y el precio de un número antes de usar un endpoint de pedido.

Para compras, asignaciones, mensajes, envíos de fax y otras acciones, siga las propias reglas de reintento de ese endpoint. Si se agota el tiempo de espera de una acción tras enviarla, compruebe su estado o los registros de su cuenta antes de repetirla. Una respuesta perdida no demuestra que la acción haya fallado.