Listar los estados de Estados Unidos o las provincias de Canadá con números disponibles

Use este paso opcional para Estados Unidos o Canadá para limitar la búsqueda por estado o provincia. Solo se aceptan US y CA.

• Cada entrada describe los prefijos con existencias disponibles para ese estado en el momento de la solicitud.
• Siga next_function para listar las áreas del estado. Ya incluye el filtro state pero no pid.
• La consulta de áreas determina las coincidencias de la información del estado de una forma ligeramente distinta. Si, para un estado, next_function devuelve No areas found, llame a getareas sin especificar un estado como alternativa.
• Compruebe status.code antes de leer response. Un país no admitido, o un país sin existencias que coincidan con los filtros, devuelve el código 404 sin un estado HTTP correspondiente.
• Una lista vacía con el código 200 significa que hay existencias, pero no contienen información del estado. Llame a getareas sin especificar un estado.

Solicitud

Obligatorio: 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 ejecutar la consulta.

GET con isocode en la ruta. Si se omite ese segmento de la ruta, se lee en su lugar un campo isocode codificado como formulario. El parámetro opcional pid se envía en la cadena de consulta.

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

Respuesta

Estructura contenedora estándar. Si la solicitud se realiza correctamente, status.code es 200, status.msg está vacío y status.results es el número de entradas. response es una lista ordenada por name (sin distinguir entre mayúsculas y minúsculas) y, después, por el código state. Campos: state (código de estado o provincia tomado de los datos de estado de los prefijos, normalmente de dos letras; los valores poco habituales se devuelven sin cambios); name (nombre del catálogo, o el código cuando el catálogo no tiene un nombre para él); country_iso; available (existencias totales de los prefijos contabilizados, siempre superiores a 0); prefix_count (número de prefijos con existencias disponibles contabilizados); is_mobile (1 si alguno de los prefijos contabilizados admite telefonía móvil; siempre 0 para US, salvo que su cuenta esté habilitada para números móviles de Estados Unidos); sms_coverage (1 si alguno de los prefijos contabilizados tiene cobertura de SMS); returns_numbers (1 si alguno de los prefijos contabilizados tiene el indicador de devolución de números o no tiene un valor para dicho indicador); next_function ('v3/getareas/{isocode}?state={state}'). Si existen prefijos con existencias disponibles pero ninguno contiene información del estado, el resultado es status.code 200 con una lista vacía y status.results 0.

Estructura de respuesta ilustrativa; no son datos de la cuenta en tiempo real ni una cotización actual.

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

Errores

• 500: msg 'ISO Code parameter is required': falta isocode o está en blanco. Es un error de la solicitud que se puede corregir. No se establece un estado HTTP correspondiente; lea status.code.
• 404: msg 'getstates is only available for US and CA': cualquier otro código de país. No se establece un estado HTTP correspondiente.
• 404: msg 'No states found': ningún prefijo con existencias disponibles coincide con los filtros de país y fuente. 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 consulta. No reserva, realiza pedidos ni cambia nada. available es informativo y no retiene números.