Comprar números de teléfono a partir de un prefijo

Comprar a partir de un prefijo

Utilice esta operación cuando el catálogo de prefijos le indique que compre una cantidad de números de un prefijo en lugar de elegir números disponibles individualmente. Comience por países, áreas o estados, y prefijos. Conserve el identificador del prefijo y el plan de precios de un mismo resultado recién obtenido. Para un número concreto seleccionado de una lista de números disponibles, utilice Comprar un número de teléfono seleccionado.

Esta solicitud puede comprar números y generar cargos. No es una cotización, una reserva ni una simulación. Antes de enviarla, revise los cargos de alta y mensuales, las tarifas por minuto entrante, los minutos incluidos, los canales, los requisitos de registro y los límites de compra de la cuenta. Un resultado del catálogo no reserva inventario ni fija los precios. Las comprobaciones de financiación de la cuenta pueden realizarse antes de completar la compra; un error no demuestra por sí solo que no se haya realizado una compra o una aportación de fondos a la cuenta.

Enviar la compra

Utilice una cuenta de API habilitada a través de HTTPS desde una dirección IP de origen permitida. Defina las variables según su selección actual del catálogo y su configuración de entrega aprobada. El siguiente comando compra un número.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'quantity=1' \
  --data-urlencode "price_id=$PRICE_ID" \
  --data-urlencode "channels=$CHANNELS" \
  --data-urlencode "reference=$ORDER_REFERENCE" \
  --data-urlencode "uri=$VOICE_URI" \
  "https://api.multitel.net/v3/order/$PREFIX_ID"

Arriba se muestra un envío de formulario mediante POST. El coordinador también lee un objeto JSON cuando Content-Type es application/json. Los campos JSON prevalecen sobre los campos correspondientes del formulario o de la solicitud. Utilice una sola codificación de forma coherente; no envíe valores contradictorios en los parámetros de consulta y en el cuerpo.

Configuración de entrega y renovación

Elija la misma configuración de entrega que utilizaría para el número en el portal. Estos son valores de configuración avanzada, no instrucciones para crear una centralita alojada o una troncal de originación. Reutilice una configuración de cuenta que sepa que funciona y compruebe el número guardado después de la compra. La aceptación de una compra, por sí sola, no verifica que la entrega de voz o SMS funcione.

Estos campos se normalizan y se pasan al proceso de compra, pero su persistencia varía según el flujo de inventario. La ruta actual de pedidos no ofrece los campos de límites estrictos de cotización de la guía de compra de un número seleccionado como protecciones equivalentes. Utilice los permisos de compra y los límites de precio de la cuenta, y revise la configuración resultante del número.

Leer el resultado completo

Analice el cuerpo JSON y revise status.code y status.msg incluso cuando la solicitud HTTP se complete correctamente. Esta ruta genera su propia respuesta JSON, y la función auxiliar compartida de respuestas tampoco asigna necesariamente el código de aplicación al estado HTTP. Los códigos de aplicación pueden ser números JSON o cadenas numéricas. No exija status.results; no está presente en el resultado normal de un pedido.

{
  "status": {"code": "200", "msg": ""},
  "response": {
    "id": "o_fictional_example",
    "numbers": ["12025550123"],
    "price": {
      "per_minute": "0.01",
      "free_minutes": 0,
      "setup_price": "1.25",
      "monthly_price": "2.50",
      "channels": 2
    },
    "features": ["voice"],
    "needs_registration": 0,
    "restrictions": "",
    "registration_requirements": null
  }
}

El identificador, el número y los precios anteriores son ficticios. Trate el ID del pedido como un valor opaco. numbers enumera los números que esta respuesta indica como comprados; compare su longitud con la cantidad que solicitó. Los importes de los precios son cadenas y esta respuesta redondea las tarifas monetarias a dos decimales, incluida per_minute; utilice el catálogo recién obtenido para consultar la precisión original de las tarifas. Los minutos incluidos y los canales pueden recibirse como valores numéricos o cadenas numéricas.

El bloque de precios describe el plan seleccionado utilizado para generar la respuesta, no una factura detallada de cada número ni el total del pedido. Los distintos candidatos del inventario pueden tener planes diferentes. Concilie cada número comprado y las transacciones de la cuenta en lugar de multiplicar los valores de este bloque y suponer que demuestran el total final.

Compras parciales y resultados inciertos

Un código de aplicación 200 puede ir acompañado de una advertencia y de menos números de los solicitados. Un fallo posterior no revierte la compra de los números ya adquiridos. Conserve el ID del pedido, los números y el mensaje devueltos. Concilie esos números con su inventario y las transacciones de la cuenta antes de decidir si compra la cantidad restante.

Un tiempo de espera agotado, una solicitud desconectada, una respuesta mal formada o un error después del envío no demuestran que no haya ocurrido nada. No envíe automáticamente otra compra, ni siquiera con la misma referencia. Conserve la solicitud original, la referencia y cualquier ID de pedido devuelto, compruebe el inventario y las transacciones de la cuenta, y contacte con soporte si el resultado sigue siendo incierto.

Un pedido sin confirmar puede devolver el código de aplicación 400 con un mensaje que indique que aún se está confirmando. Conserve el ID del pedido devuelto y concilie esa compra; esto no es una indicación de que deba enviarla de nuevo. La recuperación de pedidos registrados realiza un seguimiento interno del pedido original. Una nueva solicitud a esta operación crea un intento de compra independiente en lugar de reanudar un pedido mediante su referencia, por lo que puede comprar más números y generar cargos por ellos. No utilice solicitudes de compra repetidas para comprobar el estado o buscar en el inventario.

Registro y activación

Un número comprado o asignado aún puede necesitar registro o activación. Si needs_registration es 1, revise restrictions y registration_requirements. Este último campo puede indicar v3/get_requirements con valores de country y number_type. Complete el procedimiento de identidad y dirección que corresponda y confirme el estado del número antes de contar con las llamadas entrantes o la mensajería.

features describe las capacidades anunciadas; no verifica el enrutamiento real, la aprobación de campañas, la entrega de SMS ni la recepción de fax. Compruebe la configuración de entrega guardada y realice la prueba de servicio correspondiente cuando el número esté activo.

Notificaciones de retorno del pedido

Las notificaciones de retorno envían mediante POST un JSON con el estado y la respuesta del pedido, al que se añade su referencia si la proporcionó. Se envían para las compras notificadas, incluidos los resultados parciales. Un fallo en la notificación de retorno no revierte la compra. La entrega puede reintentarse, por lo que debe gestionar los duplicados por ID de pedido y conciliar los números en lugar de realizar otra compra.

Esta ruta no añade una firma criptográfica a las notificaciones de retorno. Trate una notificación de retorno como un aviso para conciliar los datos con su inventario consultado mediante autenticación, no como una autorización independiente para cobrar, aprovisionar o conceder acceso. No incluya credenciales de API en la URL de notificación de retorno. Enviar otra compra con una URL de notificación de retorno diferente no actualiza el pedido original; crea un intento de compra independiente. Conserve el ID del pedido original cuando solicite a soporte que investigue su notificación de retorno.

Fallos que debe gestionar