# Comprar e liberar um número

Comprar um número exige duas chamadas: pesquisar um país para ver o que está à venda e depois pedir o número desejado. Tudo aqui precisa de uma chave API com o escopo `numbers`, e a primeira compra em uma organização exige verificação de identidade.

## Pesquisar um país

A pesquisa é sempre restrita a um país, então `country_code` é obrigatório. Refine ainda mais com `number_type`, `capabilities` ou um `prefix` de dígitos nacionais.

**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](/pt-br/documentacao/guides/numbers/buying-numbers.ts.md) · [Python](/pt-br/documentacao/guides/numbers/buying-numbers.py.md) · [Go](/pt-br/documentacao/guides/numbers/buying-numbers.go.md) · [PHP](/pt-br/documentacao/guides/numbers/buying-numbers.php.md) · [cURL](/pt-br/documentacao/guides/numbers/buying-numbers.curl.md)

Use o host regional que corresponde ao prefixo `bk_{region}_` da sua chave: `https://us1.platform.bird.com` ou `https://eu1.platform.bird.com`.

Cada resultado traz apenas o que você precisa para escolher um:

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

Nosso próprio inventário é retornado primeiro e pagina normalmente. A última página pode incluir números que uma operadora está oferecendo ao vivo, então um número listado há pouco pode já ter sido vendido quando você fizer o pedido.

Para confirmar que um número ainda está disponível antes de comprá-lo, consulte-o com [`GET /v1/numbers/available/{number}`](/docs/api/reference/get-available-number). Um `404` significa que ele não está disponível para venda no momento, seja porque a operadora o retirou ou porque nosso próprio inventário o reservou. A reverificação consome o mesmo limite de requisições `numbers_availability` da busca, então reverifique apenas o candidato que você vai comprar, não todos os resultados.

## Comprar o número

Passe um número da busca para [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order). Para proteção contra novas tentativas, veja [Idempotência](/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](/pt-br/documentacao/guides/numbers/buying-numbers.ts.md) · [Python](/pt-br/documentacao/guides/numbers/buying-numbers.py.md) · [Go](/pt-br/documentacao/guides/numbers/buying-numbers.go.md) · [PHP](/pt-br/documentacao/guides/numbers/buying-numbers.php.md) · [MCP](/pt-br/documentacao/guides/numbers/buying-numbers.mcp.md) · [cURL](/pt-br/documentacao/guides/numbers/buying-numbers.curl.md)

A maioria dos pedidos termina dentro da própria requisição e responde `201` com o número já sendo seu:

```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` é o identificador para tudo depois disso: consultar o número e liberá-lo.

## Consultar um pedido que não terminou

Um pedido que precisa aguardar uma operadora responde `202`, com `number_id` ainda em `null`. Consulte-o novamente até que `status` seja `completed` ou `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](/pt-br/documentacao/guides/numbers/buying-numbers.ts.md) · [Python](/pt-br/documentacao/guides/numbers/buying-numbers.py.md) · [Go](/pt-br/documentacao/guides/numbers/buying-numbers.go.md) · [PHP](/pt-br/documentacao/guides/numbers/buying-numbers.php.md) · [MCP](/pt-br/documentacao/guides/numbers/buying-numbers.mcp.md) · [cURL](/pt-br/documentacao/guides/numbers/buying-numbers.curl.md)

Um pedido passa por `charging`, `ordering` e `pending` antes de se resolver. Em `failed`, `failure_reason` diz o que deu errado em termos simples. Uma taxa de ativação já cobrada não é reembolsada, então um pedido com falha pode deixar uma cobrança; entre em contato com o suporte se isso acontecer.

## Liberar um número

Liberar encerra a cobrança mensal e o número para de funcionar para você. Apenas um número `dedicated` pode ser liberado, e um número liberado não volta imediatamente para venda.

**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](/pt-br/documentacao/guides/numbers/buying-numbers.ts.md) · [Python](/pt-br/documentacao/guides/numbers/buying-numbers.py.md) · [Go](/pt-br/documentacao/guides/numbers/buying-numbers.go.md) · [PHP](/pt-br/documentacao/guides/numbers/buying-numbers.php.md) · [MCP](/pt-br/documentacao/guides/numbers/buying-numbers.mcp.md) · [cURL](/pt-br/documentacao/guides/numbers/buying-numbers.curl.md)

Uma liberação bem-sucedida responde `204` sem corpo.

## Quando um pedido é recusado

Quatro recusas cobrem quase toda compra com falha.

`402` com [`E03000`](/docs/api/errors/E03000) significa que a carteira não cobre o número. Adicione saldo e compre novamente. Nenhum pedido é criado, então nada é cobrado.

`412` significa que a organização não completou a verificação de identidade que uma primeira compra exige. Complete-a e tente novamente.

`409` com [`E14000`](/docs/api/errors/E14000) significa que o número foi vendido enquanto você escolhia. Busque novamente e escolha outro.

`409` com [`E14001`](/docs/api/errors/E14001) significa que muitos dos seus pedidos já estão em andamento. Aguarde um terminar e compre novamente.

## Próximos passos

- [Visão geral de números](/docs/guides/numbers/overview) explica o que os campos de um número significam.
- [Referência da API de números](/docs/api/reference/create-numbers-order) documenta cada operação e campo.
- [Idempotência](/docs/guides/idempotency) explica como as chaves tornam seguro tentar novamente um 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)