# Kupowanie i zwalnianie numeru

Kupno numeru wymaga dwóch wywołań: wyszukaj w danym kraju, co jest w sprzedaży, a potem zamów wybrany numer. Wszystkie operacje opisane tutaj wymagają klucza API z uprawnieniem `numbers`, a pierwszy zakup w organizacji wymaga weryfikacji tożsamości.

## Wyszukaj kraj

Wyszukiwanie jest zawsze ograniczone do jednego kraju, więc `country_code` jest wymagany. Zawęź wyniki za pomocą `number_type`, `capabilities` lub `prefix` z cyframi krajowymi.

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

Użyj hosta regionalnego odpowiadającego prefiksowi `bk_{region}_` Twojego klucza: `https://us1.platform.bird.com` lub `https://eu1.platform.bird.com`.

Każdy wynik zawiera tylko to, czego potrzebujesz, żeby wybrać numer:

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

Nasz własny inwentarz jest zwracany jako pierwszy i stronicuje się normalnie. Ostatnia strona może zawierać numery oferowane na bieżąco przez operatora, więc numer widoczny chwilę temu może być już niedostępny w momencie składania zamówienia.

Aby potwierdzić, że numer jest wciąż dostępny przed złożeniem zamówienia, odczytaj go za pomocą [`GET /v1/numbers/available/{number}`](/docs/api/reference/get-available-number). `404` oznacza, że numer nie jest obecnie dostępny do zakupu, bez względu na to, czy operator go wycofał, czy nasz własny magazyn ma go zarezerwowany. Ponowne sprawdzenie korzysta z tego samego limitu żądań `numbers_availability` co wyszukiwanie, więc sprawdzaj ponownie tylko kandydata, którego zamierzasz zamówić, a nie każdy wynik.

## Zamów numer

Przekaż numer z wyników wyszukiwania do [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order). Aby zabezpieczyć ponowne próby, zobacz [Idempotentność](/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](/pl-pl/dokumentacja/guides/numbers/buying-numbers.ts.md) · [Python](/pl-pl/dokumentacja/guides/numbers/buying-numbers.py.md) · [Go](/pl-pl/dokumentacja/guides/numbers/buying-numbers.go.md) · [PHP](/pl-pl/dokumentacja/guides/numbers/buying-numbers.php.md) · [MCP](/pl-pl/dokumentacja/guides/numbers/buying-numbers.mcp.md) · [cURL](/pl-pl/dokumentacja/guides/numbers/buying-numbers.curl.md)

Większość zamówień kończy się w ramach żądania i zwraca `201` z numerem już przypisanym do Ciebie:

```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` to identyfikator do wszystkiego, co następuje dalej: odczytu numeru i jego zwolnienia.

## Odpytuj zamówienie, które się nie zakończyło

Zamówienie, które musi czekać na operatora, zwraca `202`, a `number_id` ma nadal wartość `null`. Odpytuj je, aż `status` przyjmie wartość `completed` lub `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](/pl-pl/dokumentacja/guides/numbers/buying-numbers.ts.md) · [Python](/pl-pl/dokumentacja/guides/numbers/buying-numbers.py.md) · [Go](/pl-pl/dokumentacja/guides/numbers/buying-numbers.go.md) · [PHP](/pl-pl/dokumentacja/guides/numbers/buying-numbers.php.md) · [MCP](/pl-pl/dokumentacja/guides/numbers/buying-numbers.mcp.md) · [cURL](/pl-pl/dokumentacja/guides/numbers/buying-numbers.curl.md)

Zamówienie przechodzi przez `charging`, `ordering` i `pending`, zanim się ustabilizuje. Przy `failed` pole `failure_reason` opisuje, co poszło nie tak, prostym językiem. Pobrana opłata konfiguracyjna nie jest zwracana, więc nieudane zamówienie może zostawić po sobie obciążenie. Skontaktuj się z pomocą techniczną, jeśli tak się stanie.

## Zwolnij numer

Zwolnienie zatrzymuje miesięczną opłatę i numer przestaje dla Ciebie działać. Zwolnić można tylko numer ze statusem `dedicated`, a zwolniony numer nie wraca od razu do sprzedaży.

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

Pomyślne zwolnienie zwraca `204` bez treści odpowiedzi.

## Kiedy zamówienie zostaje odrzucone

Cztery rodzaje odrzuceń obejmują niemal każdy nieudany zakup.

`402` z [`E03000`](/docs/api/errors/E03000) oznacza, że portfel nie pokrywa kosztu numeru. Doładuj konto i zamów ponownie. Zamówienie nie zostaje utworzone, więc nic nie jest naliczane.

`412` oznacza, że organizacja nie ukończyła weryfikacji tożsamości wymaganej przy pierwszym zakupie. Ukończ ją, a potem spróbuj ponownie.

`409` z [`E14000`](/docs/api/errors/E14000) oznacza, że numer został zajęty, gdy go wybierałeś. Wyszukaj ponownie i wybierz inny.

`409` z [`E14001`](/docs/api/errors/E14001) oznacza, że zbyt wiele Twoich zamówień jest już w trakcie realizacji. Poczekaj, aż jedno się zakończy, a potem zamów ponownie.

## Następne kroki

- [Przegląd numerów](/docs/guides/numbers/overview) wyjaśnia, co oznaczają poszczególne pola numeru.
- [Dokumentacja API numerów API](/docs/api/reference/create-numbers-order) opisuje każdą operację i pole.
- [Idempotentność](/docs/guides/idempotency) wyjaśnia, jak klucze zabezpieczają ponawiane zamówienie.

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