---
title: "Gerenciando seus números de telefone"
description: "Liste e encontre os números alocados ao seu espaço de trabalho, rotule-os com um nome e sua própria referência, consulte o registro de voz deles e cancele ou libere-os pela API."
canonical: "https://bird.com/pt-br/documentacao/guides/numbers/managing-numbers"
---

# Gerenciando seus números de telefone

Depois que um número é alocado ao seu espaço de trabalho, a API de números permite listar o que você possui, encontrar um número por qualquer um dos seus identificadores, rotulá-lo com um nome e sua própria referência, e cancelar ou liberá-lo quando não precisar mais. A leitura exige uma chave API com o escopo `numbers` em nível de leitura; alterar, cancelar ou liberar um número exige nível de escrita.

A página [**Numbers**](https://bird.com/dashboard/w/numbers) no dashboard mostra os mesmos números.

## Liste todos os números que você possui

[`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers) retorna os números atualmente alocados ao seu espaço de trabalho, do mais recente ao mais antigo, dedicados e compartilhados. Cada página contém 25 números, a menos que você solicite até 100 com `limit`.

A lista é paginada por cursor. Passe o `next_cursor` de uma página de volta como `starting_after` para ler a próxima página, e pare quando `next_cursor` for `null`. Os SDKs seguem o cursor automaticamente. Os exemplos abaixo restringem a lista a `country_code: "GB"`; remova o filtro para percorrer todos os números que você possui:

**TypeScript**

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

Examples: [TypeScript](/pt-br/documentacao/guides/numbers/managing-numbers.ts.md) · [Python](/pt-br/documentacao/guides/numbers/managing-numbers.py.md) · [Go](/pt-br/documentacao/guides/numbers/managing-numbers.go.md) · [PHP](/pt-br/documentacao/guides/numbers/managing-numbers.php.md) · [MCP](/pt-br/documentacao/guides/numbers/managing-numbers.mcp.md) · [cURL](/pt-br/documentacao/guides/numbers/managing-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`.

A lista não traz um total. Para contar seus números, percorra as páginas até o fim e conte as entradas. Passar `include_total` é recusado com `422` e [`E01029`](/docs/api/errors/E01029).

Cada entrada traz seu `status` e `ownership`. Quando um país não exige documentação de titularidade, `ownership` é `null`. A [Visão geral de Numbers](/docs/guides/numbers/overview#the-status-of-an-allocated-number) explica o que cada status significa. Para enviar a documentação que um número está aguardando, consulte [Enviar a documentação de titularidade de um número](/docs/guides/numbers/ownership-paperwork).

Cada entrada também traz `pricing`, o que a sua organização paga pelo número, líquido de impostos:

- `recurring_price` é a sua tarifa por `recurring_period`, na moeda em que o número é cobrado. Essa é a sua moeda de cobrança, a menos que a assinatura do número tenha começado antes de uma mudança da sua moeda de cobrança; esse número mantém a moeda da assinatura, indicada por `currency_code`.
- `intervals_per_charge` é quantos `recurring_period`s uma renovação cobra. A cobrança recorrente antes de impostos é `recurring_price` multiplicado por `intervals_per_charge`. Um preço fixo para o número cobre todo o período, então seu `intervals_per_charge` é `1`.

`pricing` é `null` para um número `shared` e para um número sem assinatura ativa. Quando nenhum preço se aplica à assinatura de um número, seus preços são `null` com `pricing.error: null`; [fale com vendas](/contact-sales) para que ele receba um preço. Se o preço não pôde ser lido, `pricing.error` contém [`E14009`](/docs/api/errors/E14009) e os preços são `null`. Tente novamente [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number) com backoff exponencial. O número continua disponível para gerenciamento; não repita uma atualização ou cancelamento já concluído para atualizar o preço.

O dashboard e API usam a mesma resolução de preço. Um preço fixo mantém suas condições existentes; caso contrário, é a tarifa atual, que pode mudar antes da renovação. Ele não informa o que um pedido anterior cobrou. Um número com `releases_at` definido mantém seu `pricing` até a liberação, e nenhuma renovação acontece depois.

## Encontre um número na sua lista

Os filtros da lista se combinam, então um filtro de país ou capacidade continua valendo junto com os demais.

`number` busca um número independentemente de como seus registros o escrevem. `+31612345678` e `0031612345678` resolvem para o mesmo número. Uma grafia nacional como `0612345678` só resolve quando `country_code` indica o país:

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

Quando você passa um número completo, ou uma grafia nacional com seu `country_code`, e nenhum outro filtro, um array `data` vazio significa que o número não está alocado ao seu espaço de trabalho, o que inclui um número que você liberou. Uma grafia nacional sem `country_code`, como `0612345678` sozinho, também retorna uma lista vazia, então ela não prova que o número não é seu.

`search` corresponde a parte do número, seu nome ou sua referência, ignorando maiúsculas e minúsculas. `reference` retorna os números com exatamente aquela referência, diferenciando maiúsculas e minúsculas:

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

`prefix` retorna números que começam com os dígitos informados, e o significado desses dígitos depende de `country_code`:

- Com `country_code`, os dígitos são nacionais, correspondidos logo após o código de discagem. `prefix=6&country_code=NL` retorna números holandeses que começam com `+31 6`.
- Sem `country_code`, os dígitos são correspondidos a partir do início do número completo. `prefix=6` sozinho retorna números cujo código de discagem começa com 6, como números australianos `+61`, então não encontra nenhum dos seus celulares holandeses. Também corresponde a short codes que começam com esses dígitos.

## Nomeie um número e defina sua referência

Um número carrega dois rótulos seus. `name` diferencia seus números, como `Support line`. `reference` guarda um identificador dos seus próprios registros, como um id de cliente ou loja, e não precisa ser único. Ambos se aplicam a números dedicados e compartilhados e têm até 100 caracteres.

Defina-os com [`PATCH /v1/numbers/{number_id}`](/docs/api/reference/update-workspace-number). Um campo que você omitir mantém seu valor atual, e um campo que você enviar como `null` é limpo. Espaços em branco no início e no final são removidos.

**TypeScript**

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

Examples: [TypeScript](/pt-br/documentacao/guides/numbers/managing-numbers.ts.md) · [Python](/pt-br/documentacao/guides/numbers/managing-numbers.py.md) · [Go](/pt-br/documentacao/guides/numbers/managing-numbers.go.md) · [PHP](/pt-br/documentacao/guides/numbers/managing-numbers.php.md) · [MCP](/pt-br/documentacao/guides/numbers/managing-numbers.mcp.md) · [cURL](/pt-br/documentacao/guides/numbers/managing-numbers.curl.md)

A resposta é `200` com o número atualizado. Para limpar a referência e manter o nome, envie a referência como `null` e omita o nome:

```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 definir a referência ao comprar o número, passe `reference` em [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order). Um pedido de compra que precisa aguardar a operadora mantém a referência até o número ser alocado, e o número a carrega desse momento em diante.

## Encontre o registro de voz que roteia um número

Um número com voz tem dois identificadores. O `id` em `GET /v1/numbers` começa com `nda_` para um número dedicado e `nal_` para um compartilhado, e as operações de números o utilizam. As operações de voz, incluindo a que define para onde vão as chamadas recebidas, utilizam o registro de voz do número, cujo `id` começa com `vnu_`. Passar um id `nda_` ou `nal_` para uma operação de voz é recusado com `422`.

Para ir de um ao outro, pesquise os números de voz pelo número de telefone. Isso exige o escopo `voice_management` no nível de leitura:

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

O `id` da entrada é o identificador `vnu_`, e o `provider.number_id` dela é o identificador `nda_` ou `nal_` do mesmo número. [Receber chamadas](/docs/guides/voice/receiving-calls) mostra como rotear o número a partir daí.

O registro de voz tem um `name` próprio. Nomear um número com `PATCH /v1/numbers/{number_id}` não altera o nome do registro de voz, e o inverso também vale.

## Liberar um número

Você pode devolver um número dedicado de duas formas:

- **No final do período que você pagou.** [`DELETE /v1/numbers/{number_id}`](/docs/api/reference/cancel-workspace-number) impede a renovação do número. Ele continua funcionando até o período de cobrança atual terminar e é liberado então. A resposta `202` retorna o número com `releases_at` definido para esse horário, e repetir a solicitação retorna o mesmo `releases_at`. Um cancelamento não pode ser desfeito. Um número sem assinatura vinculada, como um alocado para você sem cobrança, é liberado imediatamente, e a resposta é `200` com o `status` do número definido como `released`.
- **Agora.** [`POST /v1/numbers/{number_id}/release`](/docs/api/reference/release-workspace-number) libera o número imediatamente, incluindo um já agendado para cancelamento. O restante do período atual não é reembolsado. [Comprar e liberar um número](/docs/guides/numbers/buying-numbers#release-a-number) mostra a chamada em cada SDK.

Enquanto um pagamento de renovação do número estiver em atraso, ambas as solicitações respondem `409` até que ele seja pago.

Qualquer que seja a opção de liberação escolhida, envie a solicitação com um `Idempotency-Key` para que uma nova tentativa seja segura: a mesma chave reproduz a primeira resposta com um cabeçalho `Idempotency-Replay: true`, enquanto uma nova solicitação para um número já liberado responde `404` com [`E01008`](/docs/api/errors/E01008). [Idempotência](/docs/guides/idempotency) explica por quanto tempo uma chave é mantida.

Até que um cancelamento agendado entre em vigor, o número é lido normalmente e carrega `releases_at`. Após a liberação:

- O número para de funcionar para você e sua assinatura não é renovada.
- `GET /v1/numbers/{number_id}` e o registro de voz do número respondem `404`, e o número sai de `GET /v1/numbers`.
- O pedido do número permanece em [`GET /v1/numbers/orders`](/docs/api/reference/list-numbers-orders), e seu `number_id` agora responde `404`.
- O número entra em um período de espera de 30 dias antes de poder voltar à venda, então você não consegue comprar o mesmo número de volta imediatamente.

## Próximos passos

- [Receber chamadas](/docs/guides/voice/receiving-calls) roteia um número para um tronco SIP, um encaminhamento ou uma sequência.
- [Comprar e liberar um número](/docs/guides/numbers/buying-numbers) percorre a compra pela API.
- [Referência API de Numbers](/docs/api/reference/list-workspace-numbers) documenta cada operação e 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)