--- title: "Gestión de tus números de teléfono" description: "Lista y encuentra los números asignados a tu espacio de trabajo, etiquétalos con un nombre y tu propia referencia, consulta su registro de voz, y cancélalos o libéralos a través de la API." canonical: "https://bird.com/es-es/documentacion/guides/numbers/managing-numbers" --- # 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**](https://bird.com/dashboard/w/numbers) en el panel muestra los mismos números. ## Lista todos los números que tienes [`GET /v1/numbers`](/docs/api/reference/list-workspace-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: **TypeScript** ```typescript for await (const allocated of bird.numbers.list({ country_code: "GB" })) { console.log(allocated.number, allocated.kind, allocated.status); } ``` Examples: [TypeScript](/es-es/documentacion/guides/numbers/managing-numbers.ts.md) · [Python](/es-es/documentacion/guides/numbers/managing-numbers.py.md) · [Go](/es-es/documentacion/guides/numbers/managing-numbers.go.md) · [PHP](/es-es/documentacion/guides/numbers/managing-numbers.php.md) · [MCP](/es-es/documentacion/guides/numbers/managing-numbers.mcp.md) · [cURL](/es-es/documentacion/guides/numbers/managing-numbers.curl.md) 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`](/docs/api/errors/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](/docs/guides/numbers/overview#the-status-of-an-allocated-number) 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](/docs/guides/numbers/ownership-paperwork). 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](/contact-sales) para que le pongan precio. Si no se pudo leer el precio, `pricing.error` contiene [`E14009`](/docs/api/errors/E14009) y los precios son `null`. Reintenta [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number) 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: ```bash 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: ```bash 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}`](/docs/api/reference/update-workspace-number). 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. **TypeScript** ```typescript const allocated = await bird.numbers.update("nda_01krdgeqcxet5s7t44vh8rt9mg", { name: "Support line", reference: "STORE-042", }); console.log(allocated.name, allocated.reference); ``` Examples: [TypeScript](/es-es/documentacion/guides/numbers/managing-numbers.ts.md) · [Python](/es-es/documentacion/guides/numbers/managing-numbers.py.md) · [Go](/es-es/documentacion/guides/numbers/managing-numbers.go.md) · [PHP](/es-es/documentacion/guides/numbers/managing-numbers.php.md) · [MCP](/es-es/documentacion/guides/numbers/managing-numbers.mcp.md) · [cURL](/es-es/documentacion/guides/numbers/managing-numbers.curl.md) 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: ```bash 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`](/docs/api/reference/create-numbers-order). 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: ```bash 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](/docs/guides/voice/receiving-calls) 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}`](/docs/api/reference/cancel-workspace-number) 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`](/docs/api/reference/release-workspace-number) 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](/docs/guides/numbers/buying-numbers#release-a-number) 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`](/docs/api/errors/E01008). [Idempotencia](/docs/guides/idempotency) 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`](/docs/api/reference/list-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](/docs/guides/voice/receiving-calls) enruta un número a un troncal SIP, un desvío o una secuencia. - [Comprar y liberar un número](/docs/guides/numbers/buying-numbers) recorre la compra a través de la API. - [Referencia de API de Numbers](/docs/api/reference/list-workspace-numbers) documenta cada operación y campo. ## Related resources - [What is a virtual phone number (VMN)?](/explained/numbers/what-is-a-virtual-phone-number) (answer) - [SMS numbers](/sms-api/features/numbers) (product) - [Number types](/docs/guides/numbers/number-types) (docs) [Get an implementation brief](/learn/workspace?topic=phone-numbers)