# Membeli dan melepas nomor

Membeli nomor membutuhkan dua panggilan: cari nomor yang dijual di suatu negara, lalu pesan yang Anda inginkan. Semua langkah di sini memerlukan kunci API dengan scope `numbers`, dan pembelian pertama dalam organisasi memerlukan verifikasi identitas.

## Cari di suatu negara

Pencarian selalu dibatasi pada satu negara, jadi `country_code` wajib diisi. Persempit lebih lanjut dengan `number_type`, `capabilities`, atau `prefix` dari digit nasional.

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

Gunakan host regional yang sesuai dengan prefiks `bk_{region}_` kunci Anda: `https://us1.platform.bird.com` atau `https://eu1.platform.bird.com`.

Setiap hasil hanya berisi informasi yang Anda butuhkan untuk memilih satu nomor:

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

Inventaris kami sendiri ditampilkan lebih dulu dan dipaginasi seperti biasa. Halaman terakhir dapat menyertakan nomor yang ditawarkan langsung oleh operator, sehingga nomor yang baru saja tercantum mungkin sudah tidak tersedia saat Anda memesannya.

Untuk memastikan nomor masih tersedia sebelum memesannya, baca kembali dengan [`GET /v1/numbers/available/{number}`](/docs/api/reference/get-available-number). `404` berarti nomor tersebut saat ini tidak tersedia untuk dijual, baik karena operator menariknya maupun inventaris kami sudah mencadangkannya. Pengecekan ulang ini menggunakan batas laju `numbers_availability` yang sama dengan pencarian, jadi cek ulang hanya kandidat yang akan Anda pesan, bukan semua hasil.

## Pesan nomor

Kirimkan nomor dari hasil pencarian ke [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order). Untuk perlindungan percobaan ulang, lihat [Idempotensi](/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](/id-id/dokumentasi/guides/numbers/buying-numbers.ts.md) · [Python](/id-id/dokumentasi/guides/numbers/buying-numbers.py.md) · [Go](/id-id/dokumentasi/guides/numbers/buying-numbers.go.md) · [PHP](/id-id/dokumentasi/guides/numbers/buying-numbers.php.md) · [MCP](/id-id/dokumentasi/guides/numbers/buying-numbers.mcp.md) · [cURL](/id-id/dokumentasi/guides/numbers/buying-numbers.curl.md)

Sebagian besar pesanan selesai dalam permintaan dan menjawab `201` dengan nomor yang sudah menjadi milik Anda:

```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` adalah handle untuk semua langkah selanjutnya: membaca nomor dan melepasnya.

## Polling pesanan yang belum selesai

Pesanan yang harus menunggu operator menjawab `202`, dengan `number_id` masih `null`. Baca kembali hingga `status` bernilai `completed` atau `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](/id-id/dokumentasi/guides/numbers/buying-numbers.ts.md) · [Python](/id-id/dokumentasi/guides/numbers/buying-numbers.py.md) · [Go](/id-id/dokumentasi/guides/numbers/buying-numbers.go.md) · [PHP](/id-id/dokumentasi/guides/numbers/buying-numbers.php.md) · [MCP](/id-id/dokumentasi/guides/numbers/buying-numbers.mcp.md) · [cURL](/id-id/dokumentasi/guides/numbers/buying-numbers.curl.md)

Pesanan melewati `charging`, `ordering`, dan `pending` sebelum selesai. Pada `failed`, `failure_reason` menjelaskan kesalahan yang terjadi secara ringkas. Biaya setup yang sudah ditagih tidak dikembalikan, sehingga pesanan gagal bisa menyisakan tagihan; hubungi dukungan jika ini terjadi.

## Lepas nomor

Melepas nomor menghentikan tagihan bulanan dan nomor berhenti berfungsi untuk Anda. Hanya nomor `dedicated` yang dapat dilepas, dan nomor yang dilepas tidak langsung kembali dijual.

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

Pelepasan yang berhasil menjawab `204` tanpa body.

## Ketika pesanan ditolak

Empat penolakan mencakup hampir semua pembelian gagal.

`402` dengan [`E03000`](/docs/api/errors/E03000) berarti saldo wallet tidak cukup untuk nomor tersebut. Isi ulang dan pesan lagi. Tidak ada pesanan yang dibuat, jadi tidak ada yang ditagih.

`412` berarti organisasi belum menyelesaikan verifikasi identitas yang diperlukan untuk pembelian pertama. Selesaikan verifikasi, lalu coba lagi.

`409` dengan [`E14000`](/docs/api/errors/E14000) berarti nomor tersebut sudah tidak tersedia saat Anda memilihnya. Cari lagi dan pilih nomor lain.

`409` dengan [`E14001`](/docs/api/errors/E14001) berarti terlalu banyak pesanan Anda yang masih berjalan. Tunggu salah satu selesai, lalu pesan lagi.

## Langkah selanjutnya

- [Ikhtisar Numbers](/docs/guides/numbers/overview) menjelaskan arti setiap field pada sebuah nomor.
- [Referensi API Numbers](/docs/api/reference/create-numbers-order) mendokumentasikan setiap operasi dan field.
- [Idempotency](/docs/guides/idempotency) menjelaskan bagaimana key membuat pesanan yang dicoba ulang tetap aman.

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