Buscar números de teléfono disponibles

Elija un prefijo individual

Utilice las llamadas de consulta de países y áreas de cobertura y, después, getprefixes sin agrupación. Copie el campo uuid del prefijo seleccionado. Si returns_numbers es 0, el prefijo asigna un número al realizar el pedido; utilice el valor devuelto en next_function en lugar de exigir una lista de números individuales.

Explore un lote de tamaño limitado

Para una búsqueda normal, utilice compact=1 e indique el tamaño de lote deseado tanto en la ruta como en el parámetro de consulta quantity, como se muestra a continuación. No hay ningún parámetro de página ni de cursor. Un resultado compacto es una muestra; repetir una solicitud no garantiza obtener una página siguiente sin coincidencias con la anterior. No interprete un resultado vacío o pequeño como el número total de elementos del inventario.

Busque un patrón de dígitos fácil de recordar

Indique number_filter_mode=contains o ends_with junto con number_filter_value. El valor debe contener 1–15 dígitos. Una búsqueda puede obtener lotes limitados de candidatos antes de aplicar el filtro, por lo que puede omitir otros números del inventario que coincidan. Si necesita una fuente compatible para aplicar la búsqueda requerida, obtenga un selector pid de MultiTEL y utilice filter_required=1; si no hay ninguna selección o esta no es compatible, se devuelve un error de la API.

Revise el número seleccionado

Consulte number, info.uuid, el valor seleccionado de price[].uuid, los nombres de las funciones disponibles y los requisitos de registro en el mismo resultado. La matriz price puede ofrecer varios planes con distintas cantidades de canales y tarifas. Los campos monetarios y las cantidades pueden estar codificados como cadenas de texto. Los metadatos opcionales, incluido info.state, varían entre las fuentes; no exija una estructura universal para el estado ni deduzca precios a partir de un ID.

En el flujo sin transmisión progresiva, se eliminan los candidatos duplicados y se distribuye la asignación entre las fuentes antes de ordenar el lote seleccionado según el precio mensual del primer plan. Otros flujos pueden empezar a transmitir antes, por lo que no existe una garantía global de ordenación ni de eliminación de duplicados aplicable a todas las solicitudes. La ordenación tampoco demuestra que la muestra devuelta contenga el número más barato de todo el catálogo.

Realice el pedido por separado y confirme el resultado

Una búsqueda no compra ni reserva nada. Conserve los identificadores del número y del plan devueltos para el proceso de pedido con la misma cuenta. Revise el plan concreto, los requisitos y los cargos antes de enviar un pedido. Los requisitos de registro pueden retrasar la activación; un resultado de búsqueda no establece ningún plazo fijo de activación.

Solicitud

Utilice una cuenta habilitada para la API de MultiTEL: credenciales HTTP Basic para una cuenta con contraseña, o Authorization: Bearer para una cuenta con token. Se aplican los permisos de la cuenta y sus restricciones de IP. Consulte las indicaciones generales de autenticación.

Parámetros de ruta y parámetros de consulta de la URL. Utilice GET para el proceso de búsqueda público. El controlador también acepta determinados valores de formulario o de solicitud, pero no es una API de búsqueda con un cuerpo JSON.

curl --fail-with-body --get \
  --user "${MULTITEL_API_USERNAME}:${MULTITEL_API_PASSWORD}" \
  --data-urlencode "compact=1" \
  --data-urlencode "quantity=10" \
  "https://api.multitel.net/v3/getnumbers/${PREFIX_ID}/10"

Parámetros de ruta
Nombre	Tipo	Obligatorio	Descripción
`prefix_id`	string	Sí	Un ID de prefijo individual devuelto por una respuesta de getprefixes sin agrupación. Cópielo exactamente; no lo sustituya por un ID de país, de área de cobertura, de prefijo agrupado ni de plan de precios.
`quantity`	integer	No	Cantidad que se intenta obtener; el valor predeterminado es 1. Los valores no positivos se convierten en 1. El parámetro quantity en la ruta, por sí solo, no limita de forma fiable el total de resultados: una búsqueda sin una fuente fijada y sin el parámetro de consulta quantity puede ampliar la obtención y devolver hasta 50 entradas por fuente antes de otros pasos de procesamiento. Para la exploración habitual por lotes limitados, utilice compact=1 y repita la cantidad deseada en la consulta, como en el ejemplo.

Parámetros de consulta
Nombre	Tipo	Obligatorio	Descripción
`quantity`	integer	No	Tamaño solicitado del lote final. Los valores no vacíos se convierten en enteros, con un mínimo de 1. En el flujo sin transmisión progresiva y sin una fuente fijada, esto limita la asignación final. No obliga al servicio a encontrar esa cantidad de números. Las búsquedas compactas con una fuente fijada pueden devolver el lote compacto de esa fuente en lugar de aplicar este límite.
`compact`	string	No	Utilice 1, true u on para obtener una respuesta más pequeña sin transmisión progresiva, con hasta 10 entradas por fuente antes de la asignación final. Los resultados son una muestra del inventario obtenido en ese momento, no un catálogo completo.
`number_filter_mode`	string	No	Modo opcional de patrón de dígitos: contains o ends_with. Indique también number_filter_value. Los resultados se comprueban con los dígitos normalizados de los números de teléfono; la búsqueda no recorre todo el inventario para garantizar todas las coincidencias posibles.
`number_filter_value`	string	No	Entre 1 y 15 dígitos, sin espacios, + ni signos de puntuación. Los ceros iniciales son significativos; envíelo como texto.
`filter_required`	string	No	Avanzado: los valores 1, true, yes u on exigen una fuente de inventario seleccionada explícitamente y compatible con el modo de filtro. De lo contrario, la API devuelve status.code 422. Esto no es necesario para la exploración habitual del catálogo.
`pid`	string	No	Selector avanzado de inventario proporcionado por MultiTEL. Se aceptan formatos numéricos y los formatos hexadecimales compatibles de 32 caracteres; los valores no reconocidos se ignoran sin aviso. Omítalo para el uso normal. No derive selectores a partir de ID de precios ni suponga que un selector arbitrario restringe el inventario de forma exclusiva.

Respuesta

Un objeto JSON que contiene status y response. Si la operación tiene éxito, status.code es 200 y response es una matriz de entradas de números. status.results indica la cantidad de elementos de la matriz devuelta; status.msg puede ser Results: N o OK en una respuesta con transmisión progresiva. Sin compact=1, algunas búsquedas escriben la matriz response de forma incremental y terminan con status, por lo que debe esperar a recibir el cuerpo JSON completo. No se trata de JSON delimitado por saltos de línea. Compruebe status.code incluso cuando el transporte HTTP tenga éxito. A continuación se muestran los campos habituales; los metadatos específicos de cada fuente y los campos opcionales varían. Trate cada identificador como opaco y conserve juntos el número y el valor de price[].uuid seleccionado para él.

Ejemplo ilustrativo de la estructura de la respuesta; no son datos reales de una cuenta ni una cotización vigente.

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "number": "12125550123",
      "info": {
        "uuid": "NUMBER_ID_FROM_RESPONSE",
        "prefix_uuid": "PREFIX_ID_FROM_RESPONSE",
        "area_uuid": "AREA_ID_FROM_RESPONSE",
        "country_uuid": "COUNTRY_ID_FROM_RESPONSE",
        "country_iso": "US",
        "prefix": "+1212",
        "name": "Example area",
        "state": "US"
      },
      "price": [
        {
          "uuid": "PRICE_PLAN_ID_FROM_RESPONSE",
          "per_minute": "0.01",
          "per_sms": "0",
          "per_mms": "0",
          "free_minutes": "0",
          "setup_price": "1.00",
          "monthly_price": "2.00",
          "yearly_price": "0",
          "channels": "2"
        }
      ],
      "contract": {
        "term": "1 month",
        "renewal": "monthly",
        "notice": "none"
      },
      "restrictions": {
        "needs_registration": "0",
        "restrictions": ""
      },
      "features": [
        "voice"
      ],
      "overflow": "0"
    }
  ]
}

Errores

401: Error de autenticación. Las credenciales no válidas o ausentes y el acceso rechazado a la cuenta de la API no generan resultados de búsqueda.
404: Invalid prefix ID, Invalid country, Invalid area o No numbers found. Consulte status.msg; una respuesta de error no es una matriz de números.
400: NUMBER_FILTER_INVALID en response.code: modo no válido, un valor que no consta de 1–15 dígitos o filter_required sin especificar tanto el modo como el valor.
422: NUMBER_FILTER_UNSUPPORTED en response.code: el prefijo asigna un número al realizar el pedido (reason=order_only_prefix y next_function identifica la ruta de pedido), o la fuente seleccionada explícitamente no admite el filtro requerido.

Disponibilidad y efectos secundarios

Este controlador realiza búsquedas y prepara cotizaciones; no envía pedidos de números ni carga importes por la compra de números. Puede actualizar las cachés del catálogo, eliminar inventario obsoleto almacenado en caché, guardar planes de precios específicos de la cuenta y escribir registros de búsqueda.
La disponibilidad es un resultado correspondiente a un momento concreto, no una reserva. Un pedido posterior puede fallar o devolver una disponibilidad diferente. Verifique y concilie el resultado del pedido antes de volver a intentar una compra.
Los precios son específicos de cada cuenta. Conserve el ID del plan seleccionado para utilizarlo con la misma cuenta y revise por separado las condiciones y los cargos del pedido; este endpoint, por sí solo, no demuestra que un precio vaya a seguir siendo válido hasta un pedido posterior.
El número y los precios del ejemplo son datos ficticios que ilustran la estructura de la respuesta, no una cotización real vigente. Las capacidades, las cantidades de canales, el plazo contractual y la información de registro deben consultarse en el resultado concreto seleccionado.
Algunas descripciones de registro contienen texto con formato o enlaces. Trate las cadenas devueltas como datos no confiables al mostrarlas en su propia aplicación.
La disponibilidad de números móviles y los indicadores correspondientes dependen de que la cuenta cumpla los requisitos y del inventario. Un prefijo del catálogo o el indicador is_mobile, por sí solos, no determinan las capacidades móviles de un número concreto.