# Visão geral de números

Um número de telefone é a origem das suas mensagens e chamadas. A Bird vende números nos países que cobre, e um número alocado ao seu espaço de trabalho pode transportar SMS, MMS ou voz, dependendo do que o número suporta. A página [**Numbers**](https://bird.com/dashboard/w/numbers) no dashboard mostra os números alocados a você, e o mesmo ciclo de vida está disponível pela API: pesquise o que está à venda, compre um, consulte o que você tem e libere o que não precisa mais.

## Números dedicados e compartilhados

Todo número alocado a você tem um `kind`, e ele define o que você pode fazer com o número.

Um número `dedicated` pertence exclusivamente ao seu espaço de trabalho. Você o comprou, recebe uma cobrança mensal por ele e pode liberá-lo quando terminar. É isso que a compra de um número dá a você.

Um número `shared` é um short code na infraestrutura gerenciada pela Bird. O uso é concedido a você em vez de comprado, então não há cobrança mensal própria e você não pode liberá-lo. Tentar liberar um falha com [`E14002`](/docs/api/errors/E14002).

## O que um número pode transportar

Dois campos descrevem o que um número é, e eles respondem a perguntas diferentes.

`number_type` é o tipo físico do número: `mobile`, `local`, `national`, `toll_free` ou short code. Ele define como o número se comporta na rede e, em vários países, qual documentação é necessária.

`capabilities` é o que o número pode realmente fazer: `sms`, `mms`, `voice` ou uma combinação. Um número que lista `voice` pode transportar chamadas; um que não lista, não pode. Filtre uma pesquisa por capacidade quando precisar de uma específica, e verifique o campo antes de construir algo sobre um número que você já tem.

Um número alocado nem sempre é suficiente para enviar a partir dele. Alguns países de destino também exigem um registro aprovado para o remetente, que é uma aprovação separada do próprio número.

## O status de um número alocado

`status` indica se um número pode transportar tráfego.

`active` significa que o número está alocado a você e utilizável.

`pending_ownership_registration` significa que o número está alocado para você e cobrado, mas um país exige documentação de titularidade que ainda não foi aceita. O campo `ownership` indica o que ainda está pendente e qual chamada o resolve. A maioria dos números nunca entra nesse estado, porque a maioria dos países não exige nada: o `ownership` deles é `null`.

`released` significa que o número não está mais alocado a você.

## A compra é assíncrona

Comprar um número cria um pedido de compra, e o pedido é o que você acompanha. A maioria é concluída dentro da solicitação e devolve o número imediatamente. Um que precise esperar por uma operadora volta ainda em execução, e você o consulta até que alcance `completed` ou `failed`.

Isso importa por dois motivos. Um número só é seu quando o pedido está `completed`, então nada deve assumir que o número existe antes disso. E uma taxa de configuração já cobrada não é reembolsada quando um pedido falha, por isso a pesquisa e o pedido são chamadas separadas: a pesquisa mostra o que está disponível antes de você se comprometer com a compra.

## Próximos passos

- [Comprar e liberar um número](/docs/guides/numbers/buying-numbers) percorre o ciclo de vida completo pela API.
- [Referência da API de Numbers](/docs/api/reference/list-available-numbers) documenta todas as operações e campos.
- [Idempotência](/docs/guides/idempotency) explica como tornar segura uma compra que precisa ser tentada novamente.

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