Gestione sus números: buscar, pedir, listar

Antes de empezar

Una clave de prueba ficticia: tq_test_EXEMPLE.
Un proyecto al que asociar el número. Aquí: prj_EXEMPLE_A.
El país y el tipo de número que busca (por ejemplo, un número local en Francia).

Versión de demostración. El diseño puede cambiar. No hay ninguna API de producción abierta y no se pide ningún número real.

Buscar un número

GET /numbers/search acepta como mínimo country y type. Cada resultado indica sus capacidades (voz, SMS) y el campo documents_required: los documentos que deben aportarse antes de la activación. Léalo antes de pedir.

Ejemplo ficticio: búsqueda en un inventario de demostración. Los números pertenecen a un rango ficticio.

curl "https://api.example.test/v1/numbers/search?country=FR&type=local" \
  -H "Authorization: Bearer tq_test_EXEMPLE"

Ejemplo de respuesta a la búsqueda

Ejemplo ficticio de respuesta. El valor de documents_required es ilustrativo.

{
  "data": [
    {
      "e164": "+33199001234",
      "country": "FR",
      "type": "local",
      "capabilities": ["voice", "sms"],
      "documents_required": ["proof_of_address"]
    }
  ]
}

Pedir el número

Elija un resultado de la búsqueda y anote su e164.
Envíe POST /number-orders con e164 y project_id, junto con una Idempotency-Key.
Lea el estado de la respuesta: pending_validation significa que el pedido espera la validación de los documentos y las condiciones. El número aún no se puede usar.
Espere el evento number.activated (webhook) o vuelva a leer la lista de sus números.

Ejemplo ficticio: el pedido es una simulación mientras no haya un proveedor configurado. No se reserva ningún número real.

curl -X POST https://api.example.test/v1/number-orders \
  -H "Authorization: Bearer tq_test_EXEMPLE" \
  -H "Idempotency-Key: c2a97e51-6f08-4b3d-8e14-9d5a0b7c3f28" \
  -H "Content-Type: application/json" \
  -d '{"e164":"+33199001234","project_id":"prj_EXEMPLE_A"}'

Listar su parque de números

GET /numbers devuelve sus números con su proyecto y su estado. La paginación es por cursor: pase limit y luego el next_cursor recibido como parámetro cursor para obtener la página siguiente. Cuando next_cursor es nulo, ya lo ha leído todo.

Ejemplo ficticio: lectura del inventario de demostración.

curl "https://api.example.test/v1/numbers?limit=20" \
  -H "Authorization: Bearer tq_test_EXEMPLE"

Errores frecuentes

Síntoma	Causa probable	Qué hacer
Ningún resultado	Sin inventario para ese país o tipo, o capacidad no validada para ese país.	Pruebe otro tipo o solicite un presupuesto para su país.
404 not_found	El proyecto o el número no existe, o está fuera de su alcance.	Revise el identificador.
409 idempotency_conflict	Misma clave, cuerpo distinto.	Use una clave nueva para un pedido nuevo.
Pedido detenido en pending_validation	Documentos ausentes o en revisión.	Aporte los documentos indicados en documents_required.

Lo que esta guía no hace

No pide ningún número real y no garantiza inventario ni plazo: los plazos se confirman con el proveedor elegido.
No trata la baja de un número ni la portabilidad de uno existente. Para esto último, vea «Preparar una portabilidad».
Un número disponible supone un país y una capacidad aprobados, inventario, una cuenta autorizada y obligaciones cumplidas. Si falta uno de los cuatro, el pedido no prospera.

Hacer una primera llamada con uno de sus números Números virtuales

Gestione sus números por API