---
title: "Zarządzanie numerami telefonów"
description: "Wyświetlaj i wyszukuj numery przypisane do Twojego obszaru roboczego, oznaczaj je nazwą i własnym identyfikatorem, sprawdzaj ich rekord głosowy oraz anuluj lub zwolnij je przez API."
canonical: "https://bird.com/pl-pl/dokumentacja/guides/numbers/managing-numbers"
---

# Zarządzanie numerami telefonów

Gdy numer zostanie przypisany do Twojego obszaru roboczego, API numerów pozwala wyświetlić posiadane numery, wyszukać jeden numer po dowolnym identyfikatorze, oznaczyć go nazwą i własnym identyfikatorem oraz anulować lub zwolnić go, gdy nie jest już potrzebny. Odczyt wymaga klucza API z uprawnieniem `numbers` na poziomie odczytu; zmiana, anulowanie lub zwolnienie numeru wymaga poziomu zapisu.

Strona [**Numbers**](https://bird.com/dashboard/w/numbers) w panelu wyświetla te same numery.

## Wyświetl wszystkie posiadane numery

[`GET /v1/numbers`](/docs/api/reference/list-workspace-numbers) zwraca numery aktualnie przypisane do Twojego obszaru roboczego, od najnowszych, dedykowane i współdzielone. Każda strona zawiera 25 numerów, chyba że zażądasz do 100 za pomocą `limit`.

Lista jest stronicowana kursorem. Przekaż `next_cursor` strony z powrotem jako `starting_after`, aby odczytać następną stronę, i zatrzymaj się, gdy `next_cursor` wynosi `null`. SDK podążają za kursorem automatycznie. Poniższe przykłady zawężają listę do `country_code: "GB"`; pomiń filtr, aby przejść przez wszystkie posiadane numery:

**TypeScript**

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

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

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

Lista nie zawiera sumy. Aby policzyć numery, przejdź strony do końca i zlicz wpisy. Przekazanie `include_total` jest odrzucane z `422` i [`E01029`](/docs/api/errors/E01029).

Każdy wpis zawiera `status` i `ownership`. Jeśli dany kraj nie wymaga dokumentów potwierdzających własność, `ownership` ma wartość `null`. [Przegląd numerów](/docs/guides/numbers/overview#the-status-of-an-allocated-number) wyjaśnia znaczenie każdego statusu. Aby złożyć dokumenty, na które czeka numer, zobacz [Złóż dokumenty potwierdzające własność numeru](/docs/guides/numbers/ownership-paperwork).

Każdy wpis zawiera także `pricing`, czyli to, ile Twoja organizacja płaci za numer, netto:

- `recurring_price` to Twoja stawka za `recurring_period`, w walucie, w której naliczana jest opłata za numer. Jest to Twoja waluta rozliczeniowa, chyba że subskrypcja numeru rozpoczęła się przed zmianą Twojej waluty rozliczeniowej; taki numer zachowuje walutę swojej subskrypcji, którą podaje `currency_code`.
- `intervals_per_charge` określa, ile `recurring_period` nalicza jedno odnowienie. Opłata cykliczna przed opodatkowaniem to `recurring_price` pomnożona przez `intervals_per_charge`. Cena ustalona dla numeru obejmuje cały okres, więc `intervals_per_charge` wynosi `1`.

`pricing` ma wartość `null` dla numeru `shared` oraz dla numeru bez aktywnej subskrypcji. Gdy dla subskrypcji numeru nie obowiązuje żadna cena, jego ceny mają wartość `null` z `pricing.error: null`; [skontaktuj się z działem sprzedaży](/contact-sales), aby ustalić cenę. Jeśli nie udało się odczytać ceny, `pricing.error` zawiera [`E14009`](/docs/api/errors/E14009), a ceny mają wartość `null`. Spróbuj ponownie [`GET /v1/numbers/{number_id}`](/docs/api/reference/get-workspace-number) z wykładniczym wycofaniem. Numer pozostaje dostępny do zarządzania; nie powtarzaj zakończonej aktualizacji ani anulowania, aby odświeżyć jego cenę.

Panel i API korzystają z tego samego mechanizmu ustalania ceny. Cena stała zachowuje dotychczasowe warunki; w przeciwnym razie jest to bieżąca stawka, która może się zmienić przed odnowieniem. Nie pokazuje, ile zostało naliczone przy wcześniejszym zamówieniu. Numer z ustawionym `releases_at` zachowuje swoje `pricing` do momentu zwolnienia, a odnowienie już nie następuje.

## Znajdź numer na swojej liście

Filtry listy łączą się, więc filtr kraju lub funkcji nadal działa obok pozostałych.

`number` wyszukuje jeden numer niezależnie od tego, jak jest zapisany w Twoich danych. `+31612345678` i `0031612345678` prowadzą do tego samego numeru. Zapis krajowy, taki jak `0612345678`, jest rozpoznawany tylko wtedy, gdy `country_code` wskazuje kraj:

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

Gdy przekazujesz pełny numer lub zapis krajowy z jego `country_code` i żaden inny filtr, pusta tablica `data` oznacza, że numer nie jest przypisany do Twojego obszaru roboczego, w tym numer, który zwolniłeś. Zapis krajowy bez `country_code`, na przykład samo `0612345678`, również zwraca pustą listę, więc nie dowodzi, że numer nie jest Twój.

`search` dopasowuje część numeru, jego nazwę lub referencję, ignorując wielkość liter. `reference` zwraca numery z dokładnie taką referencją, z uwzględnieniem wielkości liter:

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

`prefix` zwraca numery zaczynające się od podanych cyfr, a ich znaczenie zależy od `country_code`:

- Z `country_code` cyfry są krajowe, dopasowywane zaraz po numerze kierunkowym kraju. `prefix=6&country_code=NL` zwraca holenderskie numery zaczynające się od `+31 6`.
- Bez `country_code` cyfry są dopasowywane od początku pełnego numeru. Sam `prefix=6` zwraca numery, których numer kierunkowy kraju zaczyna się od 6, na przykład australijskie numery `+61`, więc nie znajdzie żadnego z Twoich holenderskich numerów komórkowych. Dopasowuje też krótkie numery zaczynające się od tych cyfr.

## Nadaj numerowi nazwę i ustaw swoją referencję

Numer posiada dwie własne etykiety. `name` pozwala odróżniać numery, na przykład `Support line`. `reference` przechowuje identyfikator z Twoich własnych danych, na przykład id klienta lub sklepu, i nie musi być unikalny. Oba dotyczą numerów dedykowanych i współdzielonych i mogą mieć do 100 znaków.

Ustaw je za pomocą [`PATCH /v1/numbers/{number_id}`](/docs/api/reference/update-workspace-number). Pominięte pole zachowuje bieżącą wartość, a pole wysłane jako `null` jest czyszczone. Początkowe i końcowe białe znaki są usuwane.

**TypeScript**

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

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

Odpowiedź to `200` ze zaktualizowanym numerem. Aby wyczyścić referencję i zachować nazwę, wyślij referencję jako `null` i pomiń nazwę:

```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}'
```

Aby ustawić referencję podczas zakupu numeru, przekaż `reference` w [`POST /v1/numbers/orders`](/docs/api/reference/create-numbers-order). Zamówienie, które musi czekać na operatora, zachowuje referencję do momentu przydzielenia numeru, a numer nosi ją od tego momentu.

## Znajdź rekord głosowy, który kieruje numer

Numer obsługujący głos ma dwa identyfikatory. `id` w `GET /v1/numbers` zaczyna się od `nda_` dla numeru dedykowanego i `nal_` dla współdzielonego, i operacje na numerach go przyjmują. Operacje głosowe, w tym ta ustawiająca, dokąd trafiają połączenia przychodzące, przyjmują rekord głosowy numeru, którego `id` zaczyna się od `vnu_`. Przekazanie identyfikatora `nda_` lub `nal_` do operacji głosowej jest odrzucane z `422`.

Aby przejść od jednego do drugiego, wyszukaj numery głosowe po numerze telefonu. Wymaga to uprawnienia `voice_management` na poziomie odczytu:

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

`id` wpisu to identyfikator `vnu_`, a jego `provider.number_id` to identyfikator `nda_` lub `nal_` tego samego numeru. [Odbieranie połączeń](/docs/guides/voice/receiving-calls) pokazuje, jak stamtąd skierować numer.

Rekord głosowy ma własne `name`. Nadanie nazwy numerowi za pomocą `PATCH /v1/numbers/{number_id}` nie zmienia nazwy rekordu głosowego i odwrotnie.

## Zwolnij numer

Możesz zwrócić dedykowany numer na dwa sposoby:

- **Na koniec opłaconego okresu.** [`DELETE /v1/numbers/{number_id}`](/docs/api/reference/cancel-workspace-number) zatrzymuje odnawianie numeru. Numer działa do końca bieżącego okresu rozliczeniowego i jest wtedy zwalniany. Odpowiedź `202` zwraca numer z `releases_at` ustawionym na ten moment, a ponowne żądanie zwraca to samo `releases_at`. Anulowania nie można cofnąć. Numer bez subskrypcji, na przykład przydzielony bez opłaty, jest zwalniany natychmiast, a odpowiedź to `200` z `status` numeru ustawionym na `released`.
- **Teraz.** [`POST /v1/numbers/{number_id}/release`](/docs/api/reference/release-workspace-number) zwalnia numer natychmiast, w tym numer już zaplanowany do anulowania. Pozostała część bieżącego okresu nie jest zwracana. [Kup i zwolnij numer](/docs/guides/numbers/buying-numbers#release-a-number) pokazuje wywołanie w każdym SDK.

Gdy płatność za odnowienie numeru jest zaległa, oba żądania zwracają `409`, dopóki nie zostanie opłacona.

Niezależnie od wybranego sposobu zwolnienia wysyłaj żądanie z `Idempotency-Key`, aby ponowna próba była bezpieczna: ten sam klucz odtwarza pierwszą odpowiedź z nagłówkiem `Idempotency-Replay: true`, a nowe żądanie dotyczące numeru już zwolnionego zwraca `404` z [`E01008`](/docs/api/errors/E01008). [Idempotentność](/docs/guides/idempotency) wyjaśnia, jak długo klucz jest przechowywany.

Do momentu, gdy zaplanowane anulowanie wejdzie w życie, numer odczytuje się jak zwykle i zawiera `releases_at`. Po zwolnieniu:

- Numer przestaje działać dla Ciebie, a jego subskrypcja nie jest odnawiana.
- `GET /v1/numbers/{number_id}` i rekord głosowy numeru zwracają `404`, a numer znika z `GET /v1/numbers`.
- Zamówienie numeru pozostaje w [`GET /v1/numbers/orders`](/docs/api/reference/list-numbers-orders), a jego `number_id` zwraca teraz `404`.
- Numer przechodzi w 30-dniowy okres karencji, zanim będzie mógł wrócić do sprzedaży, więc nie możesz od razu kupić tego samego numeru ponownie.

## Kolejne kroki

- [Odbieranie połączeń](/docs/guides/voice/receiving-calls) kieruje numer do trunka SIP, przekierowania lub sekwencji.
- [Kup i zwolnij numer](/docs/guides/numbers/buying-numbers) przeprowadza zakup przez API.
- [Dokumentacja Numbers API](/docs/api/reference/list-workspace-numbers) opisuje każdą operację i pole.

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