Listar las áreas de cobertura de un país

Después de elegir un país (y, para Estados Unidos o Canadá, opcionalmente un estado de getstates), invoque getareas para ver dónde se ofrecen números. Conserve el identificador de área uuid para el siguiente paso.

Cada área conduce a uno de estos dos pasos siguientes:

• available > 0: next_function es v3/getprefixes/{uuid}, con ?state= añadido si ha filtrado por estado. Utilícelo para consultar los prefijos.
• available = 0: el área tiene prefijos, pero no tiene existencias, y next_function es v3/order/{uuid}. Consulte la documentación de pedidos para conocer los requisitos de este paso.

available es el total de toda el área, incluso al filtrar por estado. El filtro por estado acepta un código o un nombre completo, pero solo funciona para US y CA. Si un filtro por estado devuelve No areas found, vuelva a intentarlo sin ese filtro. Las comprobaciones se realizan en este orden: código de país ausente, país desconocido, filtro por estado para otro país, estado no válido y ausencia de áreas coincidentes. Cada uno de estos casos devuelve el código 500 o 404 en status.code, sin un estado HTTP correspondiente.

Solicitud

Se requiere autenticación HTTP Basic o un token Bearer (consulte Autenticación y respuestas de la API). Si la autenticación falla, se responde con HTTP 401 antes de realizar la consulta.

GET con isocode en la ruta y los parámetros opcionales state y pid en la cadena de consulta. Si se omite el segmento de la ruta, se lee en su lugar un campo isocode codificado como formulario.

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'

Respuesta

Estructura contenedora estándar. Si la solicitud tiene éxito, status.code es 200, status.msg es 'Results: N', status.results es N y response es una lista ordenada por nombre de área. Campos: uuid (identificador opaco del área utilizado en el siguiente paso); country_uuid (identificador opaco del país de 32 caracteres, que no se necesita después); name; area_type y number_type (descriptores del catálogo; las entradas no corresponden necesariamente a tipos de números locales); country_iso; is_mobile (0 o 1, según los indicadores de telefonía móvil del área; siempre es 0 para US, salvo que su cuenta esté habilitada para números móviles de US); available (total de existencias de los prefijos coincidentes del área, sin limitarse al estado solicitado); sms_coverage (0 o 1); returns_numbers (0 o 1, el valor más alto de este indicador entre los prefijos del área); latitude y longitude; state_iso; next_function. state_iso: cuando se aplica un filtro por estado, es el código al que se ha resuelto el filtro. Para US y CA sin filtro, es el estado cuyo nombre coincide con el nombre del área; en su defecto, el valor almacenado del área y, si tampoco existe, un código derivado de los datos de los prefijos del área. Para otros países, es el valor almacenado y puede estar vacío. next_function es 'v3/getprefixes/{uuid}' (con '?state={code}' añadido cuando se aplica un filtro) si available es mayor que 0; en caso contrario, es 'v3/order/{uuid}'. Se omiten las áreas que no tienen ningún prefijo coincidente. Las áreas con prefijos pero sin existencias se devuelven con available igual a 0.

Estructura de respuesta a modo de ejemplo; no son datos de una cuenta en tiempo real ni una cotización actual.

{
  "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"
    }
  ]
}

Errores

• 500: msg 'ISO Code parameter is required': isocode está ausente o vacío. Es un error de solicitud que se puede corregir. No se establece un estado HTTP correspondiente.
• 404: msg 'Error: no such country': el código de país es desconocido. No se establece un estado HTTP correspondiente.
• 404: msg 'State filter is only available for US and CA': se ha enviado un valor de state no vacío para otro país. No se establece un estado HTTP correspondiente.
• 404: msg 'Invalid state': state no es ni un código ni un nombre reconocido para el país. No se establece un estado HTTP correspondiente.
• 404: msg 'No areas found': ninguna área coincide con los filtros de país, fuente y estado. No se establece un estado HTTP correspondiente.
• 401: falta la autenticación o ha fallado. Se envía con el estado HTTP 401.

Disponibilidad y efectos secundarios

• Solo realiza consultas para cuentas de clientes. No reserva, realiza pedidos ni modifica nada.
• available es informativo y puede cambiar antes del siguiente paso.