---
title: "Gestire i numeri di telefono"
description: "Elenca e trova i numeri assegnati al tuo spazio di lavoro, etichettali con un nome e un riferimento personale, consulta il loro record vocale e cancellali o rilasciali tramite API."
canonical: "https://bird.com/it-it/documentazione/guides/numbers/managing-numbers"
---

# Gestire i numeri di telefono

Una volta che un numero è assegnato al tuo spazio di lavoro, API dei numeri ti permette di elencare quelli in tuo possesso, trovare un numero tramite uno qualsiasi dei suoi identificativi, etichettarlo con un nome e un riferimento personale, e cancellarlo o rilasciarlo quando non ti serve più. La lettura richiede una chiave API con lo scope `numbers` a livello di lettura; la modifica, la cancellazione o il rilascio di un numero richiedono il livello di scrittura.

La pagina [**Numbers**](https://bird.com/dashboard/w/numbers) nella dashboard mostra gli stessi numeri.

## Elencare tutti i numeri in tuo possesso

[`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers) restituisce i numeri attualmente assegnati al tuo spazio di lavoro, dal più recente, dedicati e condivisi. Ogni pagina contiene 25 numeri, a meno che tu non ne richieda fino a 100 con `limit`.

La lista è paginata tramite cursore. Passa il `next_cursor` di una pagina come `starting_after` per leggere la pagina successiva, e fermati quando `next_cursor` è `null`. Gli SDK seguono il cursore automaticamente. Gli esempi qui sotto restringono la lista a `country_code: "GB"`; ometti il filtro per scorrere tutti i numeri in tuo possesso:

**TypeScript**

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

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

Usa l'host regionale corrispondente al prefisso `bk_{region}_` della tua chiave: `https://us1.platform.bird.com` o `https://eu1.platform.bird.com`.

La lista non include un totale. Per contare i tuoi numeri, scorri le pagine fino alla fine e conta le voci. Passare `include_total` viene rifiutato con `422` e [`E01029`](/docs/api/errors/E01029).

Ogni voce contiene il proprio `status` e `ownership`. Quando un paese non richiede documentazione di proprietà, `ownership` è `null`. La [panoramica Numbers](/docs/guides/numbers/overview#the-status-of-an-allocated-number) spiega il significato di ogni stato. Per presentare la documentazione che un numero attende, consulta [Presentare la documentazione di proprietà di un numero](/docs/guides/numbers/ownership-paperwork).

Ogni voce contiene anche `pricing`, quanto la tua organizzazione paga per il numero, al netto delle imposte:

- `recurring_price` è la tua tariffa per `recurring_period`, nella valuta in cui viene addebitato il numero. Si tratta della tua valuta di fatturazione, a meno che l'abbonamento del numero non sia iniziato prima di un cambio della tua valuta di fatturazione; in quel caso il numero mantiene la valuta del proprio abbonamento, indicata da `currency_code`.
- `intervals_per_charge` indica quanti `recurring_period` addebita un rinnovo. L'addebito ricorrente al netto delle imposte è `recurring_price` moltiplicato per `intervals_per_charge`. Un prezzo fisso per il numero copre l'intero periodo, quindi il suo `intervals_per_charge` è `1`.

`pricing` è `null` per un numero `shared` e per un numero senza un abbonamento attivo. Quando all'abbonamento di un numero non si applica alcun prezzo, i suoi prezzi sono `null` con `pricing.error: null`; [contatta il team commerciale](/contact-sales) per ottenerne il prezzo. Se non è stato possibile leggere il prezzo, `pricing.error` contiene [`E14009`](/docs/api/errors/E14009) e i prezzi sono `null`. Riprova [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number) con backoff esponenziale. Il numero resta disponibile per la gestione; non ripetere un aggiornamento o una cancellazione già completati per aggiornarne il prezzo.

La dashboard e API usano la stessa risoluzione del prezzo. Un prezzo fisso mantiene le condizioni esistenti; altrimenti si tratta della tariffa corrente, che può cambiare prima del rinnovo. Non riporta quanto ha addebitato un ordine precedente. Un numero con `releases_at` impostato mantiene il suo `pricing` fino al rilascio, e nessun rinnovo segue.

## Trovare un numero nella propria lista

I filtri della lista si combinano, quindi un filtro per paese o funzionalità resta attivo insieme agli altri.

`number` cerca un numero indipendentemente da come è scritto nei tuoi record. `+31612345678` e `0031612345678` puntano allo stesso numero. Un formato nazionale come `0612345678` viene risolto solo quando `country_code` indica il paese:

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

Quando passi un numero completo, o un formato nazionale con il relativo `country_code`, senza altri filtri, un array `data` vuoto significa che il numero non è assegnato al tuo spazio di lavoro, incluso un numero che hai rilasciato. Un formato nazionale senza `country_code`, ad esempio `0612345678` da solo, restituisce anch'esso una lista vuota, quindi non dimostra che il numero non sia tuo.

`search` cerca una corrispondenza parziale nel numero, nel nome o nel riferimento, ignorando maiuscole e minuscole. `reference` restituisce i numeri con esattamente quel riferimento, rispettando maiuscole e minuscole:

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

`prefix` restituisce i numeri che iniziano con le cifre indicate, e il significato di quelle cifre dipende da `country_code`:

- Con `country_code`, le cifre sono nazionali, confrontate subito dopo il prefisso internazionale. `prefix=6&country_code=NL` restituisce i numeri olandesi che iniziano con `+31 6`.
- Senza `country_code`, le cifre sono confrontate dall'inizio del numero completo. `prefix=6` da solo restituisce i numeri il cui prefisso internazionale inizia con 6, come i numeri australiani `+61`, quindi non trova nessuno dei tuoi numeri mobili olandesi. Corrisponde anche agli short code che iniziano con quelle cifre.

## Assegnare un nome a un numero e impostare il proprio riferimento

Un numero porta due etichette personalizzate. `name` distingue i tuoi numeri, ad esempio `Support line`. `reference` contiene un identificatore dai tuoi record, come un id cliente o negozio, e non deve essere univoco. Entrambi si applicano a numeri dedicati e condivisi e possono contenere fino a 100 caratteri.

Impostali con [`PATCH /v1/numbers/{number_id}`](/docs/api/reference/update-workspace-number). Un campo che ometti mantiene il valore corrente, e un campo che invii come `null` viene cancellato. Gli spazi iniziali e finali vengono rimossi.

**TypeScript**

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

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

La risposta è `200` con il numero aggiornato. Per cancellare il riferimento e mantenere il nome, invia il riferimento come `null` e ometti il 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}'
```

Per impostare il riferimento al momento dell'acquisto del numero, passa `reference` su [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order). Un ordine che deve attendere un operatore conserva il riferimento fino all'assegnazione del numero, e da quel momento il numero lo mantiene.

## Trovare il record vocale che instrada un numero

Un numero con funzionalità vocale ha due identificatori. L'`id` su `GET /v1/numbers` inizia con `nda_` per un numero dedicato e `nal_` per uno condiviso, ed è quello accettato dalle operazioni sui numeri. Le operazioni vocali, compresa quella che imposta dove vanno le chiamate in entrata, accettano il record vocale del numero, il cui `id` inizia con `vnu_`. Passare un id `nda_` o `nal_` a un'operazione vocale viene rifiutato con `422`.

Per passare da uno all'altro, cerca i numeri vocali in base al numero di telefono. Serve lo scope `voice_management` a livello di lettura:

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

L'`id` dell'elemento è l'identificatore `vnu_`, e il suo `provider.number_id` è l'identificatore `nda_` o `nal_` dello stesso numero. [Ricevere chiamate](/docs/guides/voice/receiving-calls) mostra come instradare il numero da lì.

Il record vocale ha un `name` proprio. Assegnare un nome a un numero con `PATCH /v1/numbers/{number_id}` non modifica il nome del record vocale, e vale anche il contrario.

## Rilasciare un numero

Puoi restituire un numero dedicato in due modi:

- **Alla fine del periodo già pagato.** [`DELETE /v1/numbers/{number_id}`](/docs/api/reference/cancel-workspace-number) impedisce il rinnovo del numero. Il numero continua a funzionare fino alla fine del periodo di fatturazione corrente e viene rilasciato a quel punto. La risposta `202` restituisce il numero con `releases_at` impostato su quel momento, e una nuova richiesta restituisce lo stesso `releases_at`. Una cancellazione non può essere annullata. Un numero senza abbonamento associato, ad esempio uno assegnato senza addebito, viene rilasciato immediatamente e la risposta è `200` con `status` del numero impostato su `released`.
- **Subito.** [`POST /v1/numbers/{number_id}/release`](/docs/api/reference/release-workspace-number) rilascia il numero immediatamente, anche se già programmato per la cancellazione. Il resto del periodo corrente non viene rimborsato. [Acquistare e rilasciare un numero](/docs/guides/numbers/buying-numbers#release-a-number) mostra la chiamata in ogni SDK.

Mentre un pagamento di rinnovo per il numero è scaduto, entrambe le richieste rispondono `409` fino al saldo.

Qualunque opzione di rilascio tu scelga, invia la richiesta con un `Idempotency-Key` così che un nuovo tentativo sia sicuro: la stessa chiave riproduce la prima risposta con un header `Idempotency-Replay: true`, mentre una nuova richiesta per un numero già rilasciato risponde `404` con [`E01008`](/docs/api/errors/E01008). [Idempotenza](/docs/guides/idempotency) spiega per quanto tempo una chiave viene conservata.

Fino a quando una cancellazione programmata non ha effetto, il numero si legge normalmente e porta `releases_at`. Dopo il rilascio:

- Il numero smette di funzionare per te e il suo abbonamento non si rinnova.
- `GET /v1/numbers/{number_id}` e il record vocale del numero rispondono `404`, e il numero esce da `GET /v1/numbers`.
- L'ordine del numero resta in [`GET /v1/numbers/orders`](/docs/api/reference/list-numbers-orders), e il suo `number_id` ora risponde `404`.
- Il numero entra in un periodo di attesa di 30 giorni prima di poter tornare in vendita, quindi non puoi riacquistare lo stesso numero immediatamente.

## Passaggi successivi

- [Ricevere chiamate](/docs/guides/voice/receiving-calls) instrada un numero verso un trunk SIP, un inoltro o una sequenza.
- [Acquistare e rilasciare un numero](/docs/guides/numbers/buying-numbers) guida l'acquisto tramite la API.
- Il [riferimento API Numbers](/docs/api/reference/list-workspace-numbers) documenta ogni operazione 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)