Gestión de tus números de teléfono

Una vez que un número está asignado a tu espacio de trabajo, la API de números te permite listar los que tienes, buscar un número por cualquiera de sus identificadores, etiquetarlo con un nombre y tu propia referencia, y cancelarlo o liberarlo cuando termines. La lectura requiere una clave API con el alcance numbers en nivel de lectura; modificar, cancelar o liberar un número requiere nivel de escritura.

La página Numbers en el panel muestra los mismos números.

Lista todos los números que tienes

GET /v1/numbers devuelve los números asignados actualmente a tu espacio de trabajo, del más reciente al más antiguo, tanto dedicados como compartidos. Cada página contiene 25 números a menos que solicites hasta 100 con limit.

La lista se pagina por cursor. Pasa el next_cursor de una página como starting_after para leer la página siguiente, y detente cuando next_cursor sea null. Los SDK siguen el cursor por ti. Los ejemplos a continuación limitan la lista a country_code: "GB"; omite el filtro para recorrer todos los números que tienes:

for await (const allocated of bird.numbers.list({ country_code: "GB" })) {
  console.log(allocated.number, allocated.kind, allocated.status);
}

for allocated in client.numbers.list(country_code="GB"):
    print(allocated.number, allocated.kind, allocated.status)

for allocated, err := range client.Numbers.List(context.Background(), bird.NumbersListParams{
	CountryCode: "GB",
}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(allocated.Number, allocated.Kind, allocated.Status)
}

$page = $bird->numbers->list(['country_code' => 'GB']);
foreach ($page as $allocated) {
    echo $allocated->getNumber(), ' ', $allocated->getKind(), ' ', $allocated->getStatus(), "\n";
}

curl "https://us1.platform.bird.com/v1/numbers?country_code=GB" \
  -H "Authorization: Bearer bk_us1_..."

Usa el host regional que coincida con el prefijo bk_{region}_ de tu clave: https://us1.platform.bird.com o https://eu1.platform.bird.com.

La lista no incluye un total. Para contar tus números, recorre las páginas hasta el final y cuenta las entradas. Pasar include_total se rechaza con 422 y E01029.

Cada entrada incluye su status y ownership. Cuando un país no requiere documentación de titularidad, ownership es null. La descripción general de Numbers explica qué significa cada estado. Para presentar la documentación que espera un número, consulta Presentar la documentación de titularidad de un número.

Cada entrada también incluye pricing, lo que tu organización paga por el número, neto de impuestos:

• recurring_price es tu tarifa por recurring_period, en la moneda en la que se cobra el número. Es tu moneda de facturación, salvo que la suscripción del número empezara antes de que cambiara tu moneda de facturación; ese número conserva la moneda de su suscripción, que indica currency_code.
• intervals_per_charge es cuántos recurring_period cobra una renovación. El cargo recurrente antes de impuestos es recurring_price multiplicado por intervals_per_charge. Un precio fijo para el número cubre todo su período, por lo que su intervals_per_charge es 1.

pricing es null para un número shared y para un número sin suscripción activa. Cuando la suscripción de un número no tiene ningún precio aplicable, sus precios son null con pricing.error: null; contacta con ventas para que le pongan precio. Si no se pudo leer el precio, pricing.error contiene E14009 y los precios son null. Reintenta GET /v1/numbers/{number_id} con retroceso exponencial. El número sigue disponible para gestionar; no repitas una actualización o cancelación ya completada para refrescar su precio.

El panel y API usan la misma resolución de precios. Un precio fijo conserva sus condiciones actuales; en otro caso, es la tarifa vigente, que puede cambiar antes de la renovación. No indica lo que cobró un pedido anterior. Un número con releases_at definido conserva su pricing hasta la liberación, y no le sigue ninguna renovación.

Buscar un número en tu lista

Los filtros de la lista se combinan, así que un filtro de país o de capacidad sigue aplicándose junto con los demás.

number busca un número sin importar cómo lo tengas escrito en tus registros. +31612345678 y 0031612345678 resuelven al mismo número. Una forma nacional como 0612345678 solo resuelve cuando country_code indica el país:

curl "https://us1.platform.bird.com/v1/numbers?number=0612345678&country_code=NL" \
  -H "Authorization: Bearer bk_us1_..."

Cuando pasas un número completo, o una forma nacional con su country_code, y ningún otro filtro, un array data vacío significa que el número no está asignado a tu espacio de trabajo, lo que incluye un número que hayas liberado. Una forma nacional sin country_code, como 0612345678 solo, también devuelve una lista vacía, así que no demuestra que el número no sea tuyo.

search coincide con parte del número, su nombre o su referencia, sin distinguir mayúsculas. reference devuelve los números con exactamente esa referencia, distinguiendo mayúsculas:

curl "https://us1.platform.bird.com/v1/numbers?reference=STORE-042" \
  -H "Authorization: Bearer bk_us1_..."

prefix devuelve números que empiezan con los dígitos que indiques, y lo que esos dígitos significan depende de country_code:

• Con country_code, los dígitos son nacionales, coincidiendo justo después del código de marcación. prefix=6&country_code=NL devuelve números neerlandeses que empiezan por +31 6.
• Sin country_code, los dígitos se comparan desde el inicio del número completo. prefix=6 solo devuelve números cuyo código de marcación empieza por 6, como los números +61 australianos, así que no encuentra ninguno de tus móviles neerlandeses. También coincide con códigos cortos que empiezan por esos dígitos.

Nombrar un número y establecer tu referencia

Un número lleva dos etiquetas propias. name distingue tus números entre sí, por ejemplo Support line. reference guarda un identificador de tus propios registros, como un id de cliente o tienda, y no necesita ser único. Ambos se aplican a números dedicados y compartidos y admiten hasta 100 caracteres.

Establécelos con PATCH /v1/numbers/{number_id}. Un campo que omitas conserva su valor actual, y un campo que envíes como null se borra. Los espacios en blanco al inicio y al final se eliminan.

const allocated = await bird.numbers.update("nda_01krdgeqcxet5s7t44vh8rt9mg", {
  name: "Support line",
  reference: "STORE-042",
});
console.log(allocated.name, allocated.reference);

allocated = client.numbers.update(
    "nda_01krdgeqcxet5s7t44vh8rt9mg", name="Support line", reference="STORE-042"
)
print(allocated.name, allocated.reference)

allocated, err := client.Numbers.Update(ctx, "nda_01krdgeqcxet5s7t44vh8rt9mg", bird.NumbersUpdateParams{
	Name:      bird.Value("Support line"),
	Reference: bird.Value("STORE-042"),
})
if err != nil {
	log.Fatal(err)
}
if allocated.Name != nil {
	fmt.Println(*allocated.Name)
}
if allocated.Reference != nil {
	fmt.Println(*allocated.Reference)
}

$allocated = $bird->numbers->update(
    'nda_01krdgeqcxet5s7t44vh8rt9mg',
    (new \MessageBird\Wire\Model\NumberUpdate())->setName('Support line')->setReference('STORE-042'),
);
echo $allocated->getName(), ' ', $allocated->getReference(), "\n";

curl -X PATCH "https://{region}.platform.bird.com/v1/numbers/{number_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support line",
    "reference": "STORE-042"
  }'

La respuesta es 200 con el número actualizado. Para borrar la referencia y conservar el nombre, envía la referencia como null y omite el nombre:

curl -X PATCH "https://us1.platform.bird.com/v1/numbers/nda_01krdgeqcxet5s7t44vh8rt9mg" \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{"reference": null}'

Para establecer la referencia al comprar el número, pasa reference en POST /v1/numbers/orders. Un pedido que debe esperar al operador conserva la referencia hasta que el número se asigna, y a partir de entonces el número la lleva consigo.

Encontrar el registro de voz que enruta un número

Un número con voz tiene dos identificadores. El id en GET /v1/numbers empieza con nda_ para un número dedicado y nal_ para uno compartido, y las operaciones de números lo utilizan. Las operaciones de voz, incluida la que establece adónde van las llamadas entrantes, usan el registro de voz del número, cuyo id empieza con vnu_. Pasar un id nda_ o nal_ a una operación de voz se rechaza con 422.

Para pasar de uno al otro, busca los números de voz por el número de teléfono. Esto requiere el alcance voice_management en nivel de lectura:

curl "https://us1.platform.bird.com/v1/voice/numbers?search=%2B31612345678" \
  -H "Authorization: Bearer bk_us1_..."

El id de la entrada es el identificador vnu_, y su provider.number_id es el identificador nda_ o nal_ del mismo número. Recibir llamadas muestra cómo enrutar el número a partir de ahí.

El registro de voz tiene un name propio. Nombrar un número con PATCH /v1/numbers/{number_id} no cambia el nombre del registro de voz, y a la inversa también.

Liberar un número

Puedes devolver un número dedicado de dos formas:

• Al final del período que pagaste. DELETE /v1/numbers/{number_id} detiene la renovación del número. Sigue funcionando hasta que termine el período de facturación actual y se libera entonces. La respuesta 202 devuelve el número con releases_at establecido en ese momento, y solicitarlo de nuevo devuelve el mismo releases_at. Una cancelación no se puede deshacer. Un número sin suscripción detrás, como uno asignado sin cargo, se libera de inmediato, y la respuesta es 200 con el status del número establecido en released.
• Ahora. POST /v1/numbers/{number_id}/release libera el número de inmediato, incluido uno ya programado para cancelación. El resto del período actual no se reembolsa. Comprar y liberar un número muestra la llamada en cada SDK.

Mientras un pago de renovación del número esté vencido, ambas solicitudes responden 409 hasta que se pague.

Elijas la opción de liberación que elijas, envía la solicitud con un Idempotency-Key para que un reintento sea seguro: la misma clave reproduce la primera respuesta con una cabecera Idempotency-Replay: true, mientras que una solicitud nueva para un número ya liberado responde 404 con E01008. Idempotencia explica cuánto tiempo se conserva una clave.

Hasta que una cancelación programada surta efecto, el número se consulta con normalidad y lleva releases_at. Después de la liberación:

• El número deja de funcionar para ti y su suscripción no se renueva.
• GET /v1/numbers/{number_id} y el registro de voz del número responden 404, y el número desaparece de GET /v1/numbers.
• El pedido del número permanece en GET /v1/numbers/orders, y su number_id ahora responde 404.
• El número entra en un período de espera de 30 días antes de poder volver a la venta, así que no puedes comprar el mismo número de inmediato.

Siguientes pasos

• Recibir llamadas enruta un número a un troncal SIP, un desvío o una secuencia.
• Comprar y liberar un número recorre la compra a través de la API.
• Referencia de API de Numbers documenta cada operación y campo.