# Acquistare e rilasciare un numero

Acquistare un numero richiede due chiamate: cerca in un paese cosa è in vendita, poi ordina quello che vuoi. Tutto ciò che segue richiede una chiave API con lo scope `numbers`, e il primo acquisto in un'organizzazione richiede la verifica dell'identità.

## Cercare in un paese

La ricerca è sempre limitata a un singolo paese, quindi `country_code` è obbligatorio. Restringi ulteriormente con `number_type`, `capabilities` o un `prefix` di cifre nazionali.

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

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

Ogni risultato contiene solo ciò che ti serve per sceglierne uno:

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

Il nostro inventario viene restituito per primo e la paginazione funziona normalmente. L'ultima pagina può includere numeri che un operatore sta offrendo in tempo reale, quindi un numero elencato un momento fa potrebbe essere già stato preso quando lo ordini.

Per verificare che un numero sia ancora disponibile prima di ordinarlo, rileggetelo con [`GET /v1/numbers/available/{number}`](/docs/api/reference/get-available-number). Un `404` significa che al momento non è in vendita, sia che l'operatore l'abbia ritirato sia che il nostro inventario lo abbia riservato. La rilettura condivide lo stesso limite di frequenza `numbers_availability` della ricerca: verificate solo il candidato che state per ordinare, non ogni risultato.

## Ordinare il numero

Passa un numero dalla ricerca a [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order). Per la protezione in caso di ripetizione, vedi [Idempotency](/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](/it-it/documentazione/guides/numbers/buying-numbers.ts.md) · [Python](/it-it/documentazione/guides/numbers/buying-numbers.py.md) · [Go](/it-it/documentazione/guides/numbers/buying-numbers.go.md) · [PHP](/it-it/documentazione/guides/numbers/buying-numbers.php.md) · [MCP](/it-it/documentazione/guides/numbers/buying-numbers.mcp.md) · [cURL](/it-it/documentazione/guides/numbers/buying-numbers.curl.md)

La maggior parte degli ordini si conclude entro la richiesta e risponde `201` con il numero già vostro:

```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` è l'identificativo per tutto ciò che segue: leggere il numero e rilasciarlo.

## Interrogare un ordine non concluso

Un ordine che deve attendere un operatore risponde `202`, con `number_id` ancora `null`. Rileggetelo finché `status` non è `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](/it-it/documentazione/guides/numbers/buying-numbers.ts.md) · [Python](/it-it/documentazione/guides/numbers/buying-numbers.py.md) · [Go](/it-it/documentazione/guides/numbers/buying-numbers.go.md) · [PHP](/it-it/documentazione/guides/numbers/buying-numbers.php.md) · [MCP](/it-it/documentazione/guides/numbers/buying-numbers.mcp.md) · [cURL](/it-it/documentazione/guides/numbers/buying-numbers.curl.md)

Un ordine passa attraverso `charging`, `ordering` e `pending` prima di stabilizzarsi. In caso di `failed`, `failure_reason` spiega cosa è andato storto in termini chiari. Un costo di attivazione già addebitato non viene rimborsato, quindi un ordine fallito può lasciare un addebito; contattate il supporto se succede.

## Rilasciare un numero

Il rilascio interrompe l'addebito mensile e il numero smette di funzionare per voi. Solo un numero `dedicated` può essere rilasciato, e un numero rilasciato non torna subito in vendita.

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

Un rilascio riuscito risponde `204` senza corpo.

## Quando un ordine viene rifiutato

Quattro rifiuti coprono quasi tutti gli acquisti falliti.

`402` con [`E03000`](/docs/api/errors/E03000) significa che il saldo non copre il numero. Ricaricate e ordinate di nuovo. Nessun ordine viene creato, quindi nulla viene addebitato.

`412` significa che l'organizzazione non ha completato la verifica dell'identità richiesta per il primo acquisto. Completatela, poi riprovate.

`409` con [`E14000`](/docs/api/errors/E14000) significa che il numero è stato preso mentre lo sceglievate. Cercate di nuovo e scegliete un altro.

`409` con [`E14001`](/docs/api/errors/E14001) significa che troppi ordini sono già in corso. Lasciate che uno si concluda, poi ordinate di nuovo.

## Prossimi passi

- [Panoramica dei numeri](/docs/guides/numbers/overview) spiega il significato dei campi di un numero.
- [Riferimento API dei numeri](/docs/api/reference/create-numbers-order) documenta ogni operazione e campo.
- [Idempotenza](/docs/guides/idempotency) spiega come le chiavi rendono sicuro un ordine ripetuto.

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