# Comprar y liberar un número

Comprar un número requiere dos llamadas: buscar en un país lo que está en venta y luego pedir el que quieras. Todo aquí necesita una clave API con el alcance `numbers`, y la primera compra en una organización requiere verificación de identidad.

## Buscar en un país

La búsqueda siempre se limita a un país, así que `country_code` es obligatorio. Acótala con `number_type`, `capabilities` o un `prefix` de dígitos nacionales.

**TypeScript**

```typescript
// The search is always country-scoped, so country_code is required.
const page = await bird.numbers.available.list({
  country_code: "GB",
  capabilities: ["sms", "voice"],
});
for (const candidate of page.data) {
  console.log(candidate.number, candidate.number_type);
}
```

Examples: [TypeScript](/es-es/documentacion/guides/numbers/buying-numbers.ts.md) · [Python](/es-es/documentacion/guides/numbers/buying-numbers.py.md) · [Go](/es-es/documentacion/guides/numbers/buying-numbers.go.md) · [PHP](/es-es/documentacion/guides/numbers/buying-numbers.php.md) · [cURL](/es-es/documentacion/guides/numbers/buying-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`.

Cada resultado incluye solo lo que necesitas para elegir uno:

```json
{
  "data": [
    {
      "number": "+447700900123",
      "country_code": "GB",
      "number_type": "mobile",
      "capabilities": ["sms", "voice"]
    }
  ],
  "next_cursor": null,
  "prev_cursor": null
}
```

Nuestro propio inventario se devuelve primero y pagina con normalidad. La última página puede incluir números que un operador ofrece en tiempo real, así que un número listado hace un momento puede haberse agotado para cuando lo pidas.

Para confirmar que un número sigue disponible antes de pedirlo, consúltalo con [`GET /v1/numbers/available/{number}`](/docs/api/reference/get-available-number). Un `404` significa que no está disponible para la venta en ese momento, ya sea porque el operador lo retiró o porque nuestro propio inventario lo tiene reservado. La nueva consulta comparte el mismo límite de `numbers_availability` que la búsqueda, así que verifica solo el candidato que vas a pedir en lugar de todos los resultados.

## Pedir el número

Pasa un número de la búsqueda a [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order). Para protección ante reintentos, consulta [Idempotencia](/docs/guides/idempotency).

**TypeScript**

```typescript
const order = await bird.numbers.orders.create({ number: "+447700900201" });
// Most orders finish inside the request. One that has to wait on a carrier
// comes back without a number_id. Poll it until it is completed or failed.
if (order.status === "completed") {
  console.log("allocated as", order.number_id);
} else {
  console.log("still", order.status, "; poll", order.id);
}
```

Examples: [TypeScript](/es-es/documentacion/guides/numbers/buying-numbers.ts.md) · [Python](/es-es/documentacion/guides/numbers/buying-numbers.py.md) · [Go](/es-es/documentacion/guides/numbers/buying-numbers.go.md) · [PHP](/es-es/documentacion/guides/numbers/buying-numbers.php.md) · [MCP](/es-es/documentacion/guides/numbers/buying-numbers.mcp.md) · [cURL](/es-es/documentacion/guides/numbers/buying-numbers.curl.md)

La mayoría de los pedidos terminan dentro de la solicitud y responden `201` con el número ya asignado a ti:

```json
{
  "id": "nor_01m0da22b0e39anhzyhtw3gzdg",
  "number": "+447700900123",
  "country_code": "GB",
  "number_type": "mobile",
  "status": "completed",
  "number_id": "nda_7eqywfwzxwa1za9n8wp7e1xkr8",
  "failure_reason": null,
  "completed_at": "2026-08-19T15:25:56.479320Z",
  "created_at": "2026-08-19T15:25:56.448051Z",
  "updated_at": "2026-08-19T15:25:56.479320Z"
}
```

`number_id` es el identificador para todo lo que sigue: consultar el número y liberarlo.

## Consultar un pedido que no terminó

Un pedido que debe esperar a un operador responde `202` en su lugar, con `number_id` aún en `null`. Consúltalo de nuevo hasta que `status` sea `completed` o `failed`.

**TypeScript**

```typescript
const order = await bird.numbers.orders.get("nor_01krdgeqcxet5s7t44vh8rt9mg");
// failure_reason says what went wrong, and only ever on a failed order.
console.log(order.status, order.failure_reason ?? "");
```

Examples: [TypeScript](/es-es/documentacion/guides/numbers/buying-numbers.ts.md) · [Python](/es-es/documentacion/guides/numbers/buying-numbers.py.md) · [Go](/es-es/documentacion/guides/numbers/buying-numbers.go.md) · [PHP](/es-es/documentacion/guides/numbers/buying-numbers.php.md) · [MCP](/es-es/documentacion/guides/numbers/buying-numbers.mcp.md) · [cURL](/es-es/documentacion/guides/numbers/buying-numbers.curl.md)

Un pedido pasa por `charging`, `ordering` y `pending` antes de resolverse. En `failed`, `failure_reason` indica qué salió mal en términos claros. Una tarifa de activación ya cobrada no se reembolsa, así que un pedido fallido puede dejar un cargo pendiente; contacta a soporte si eso ocurre.

## Liberar un número

Liberar un número detiene el cargo mensual y el número deja de funcionar para ti. Solo un número `dedicated` se puede liberar, y un número liberado no vuelve a ponerse en venta de inmediato.

**TypeScript**

```typescript
// Releasing stops the monthly charge and the number stops working for you.
// Only a dedicated number can be released; a shared one answers E14002.
await bird.numbers.release("nda_01krdgeqcxet5s7t44vh8rt9mg");
```

Examples: [TypeScript](/es-es/documentacion/guides/numbers/buying-numbers.ts.md) · [Python](/es-es/documentacion/guides/numbers/buying-numbers.py.md) · [Go](/es-es/documentacion/guides/numbers/buying-numbers.go.md) · [PHP](/es-es/documentacion/guides/numbers/buying-numbers.php.md) · [MCP](/es-es/documentacion/guides/numbers/buying-numbers.mcp.md) · [cURL](/es-es/documentacion/guides/numbers/buying-numbers.curl.md)

Una liberación exitosa responde `204` sin cuerpo.

## Cuando un pedido es rechazado

Cuatro rechazos cubren casi todas las compras fallidas.

`402` con [`E03000`](/docs/api/errors/E03000) significa que el saldo no alcanza para cubrir el número. Recarga y vuelve a pedir. No se crea ningún pedido, así que no se cobra nada.

`412` significa que la organización no ha completado la verificación de identidad que requiere una primera compra. Complétala y reintenta.

`409` con [`E14000`](/docs/api/errors/E14000) significa que el número se fue mientras lo elegías. Busca de nuevo y elige otro.

`409` con [`E14001`](/docs/api/errors/E14001) significa que demasiados de tus pedidos ya están en curso. Espera a que uno termine y vuelve a pedir.

## Próximos pasos

- [Descripción general de números](/docs/guides/numbers/overview) explica qué significan los campos de un número.
- [Referencia API de números](/docs/api/reference/create-numbers-order) documenta cada operación y campo.
- [Idempotencia](/docs/guides/idempotency) explica cómo las claves hacen seguro reintentar un pedido.

## 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)