Sign inGet Started

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.

Przeszukaj 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.

// 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);
}

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 opisuje numer:

Przykład kodu
{
  "data": [
    {
      "number": "+447700900123",
      "country_code": "GB",
      "number_type": "mobile",
      "capabilities": ["sms", "voice"],
      "pricing": {
        "setup_price": { "amount": "0.00995", "currency_code": "USD" },
        "recurring_price": { "amount": "0.00995", "currency_code": "USD" },
        "recurring_period": { "unit": "month", "count": 1 },
        "intervals_per_charge": 12
      }
    }
  ],
  "next_cursor": null,
  "prev_cursor": null
}

Każdy wynik zawiera też obiekt pricing z ceną dla Twojej organizacji, bez podatku i w Twojej walucie rozliczeniowej:

  • setup_price jest pobierana jednorazowo: za numer z naszego inwentarza w momencie przypisania go do Twojego obszaru roboczego, a za numer operatora zwykle wtedy, gdy operator go dostarczy. Opublikowana opłata zerowa ma amount o wartości "0". Samo pole ma wartość null, gdy opłata aktywacyjna nie obowiązuje, a także zawsze wtedy, gdy recurring_price ma wartość null, ponieważ takiego numeru nie można zamówić.
  • recurring_price to stawka za recurring_period.
  • intervals_per_charge określa, ile jednostek recurring_period obejmuje jedno naliczenie. Opłata cykliczna przed opodatkowaniem to recurring_price pomnożona przez intervals_per_charge, pobierana w momencie przypisania numeru do Twojego obszaru roboczego i przy każdym odnowieniu. W przypadku zamówienia, które czeka na operatora, przypisanie następuje po zakończeniu zamówienia. recurring_period równy jednemu miesiącowi z intervals_per_charge: 12 nalicza opłatę za 12 miesięcy naraz.

Dokumentacja API pokazuje przykładowy wynik z cenami. Wynik wyszukiwania z pricing.recurring_price: null nie podaje ceny cyklicznej. Skontaktuj się z działem sprzedaży, aby uzyskać cenę dla tego kraju i typu numeru przed złożeniem zamówienia.

Panel i API korzystają z tej samej ceny dla organizacji, łącznie z przeliczeniem na Twoją walutę rozliczeniową. Odczyt ceny nie gwarantuje stałej wyceny: zmiany taryfy lub kursu wymiany przed późniejszym naliczeniem mogą zmienić jego kwotę. Jeśli pobranie ceny się nie powiedzie, wyszukiwanie zwraca 503 z E14009. Spróbuj ponownie odczytać cenę z wykładniczo rosnącym odstępem; niepowodzenie pobrania ceny nigdy nie oznacza, że numer nic nie kosztuje.

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}. 404 oznacza, że numer nie jest obecnie dostępny do zakupu, bez względu na to, czy operator go wycofał, czy nasz własny inwentarz 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.

Numer z ownership_registration_required nie może wysyłać SMS ani wykonywać połączeń, dopóki dokumenty potwierdzające własność numeru nie zostaną zatwierdzone; składasz te dokumenty po jego zakupie. Numer może też zawierać ownership_address_scope, które określa, gdzie musi znajdować się adres Twojej firmy na potrzeby tych dokumentów. W przypadku number_area pole ownership_address_area_name podaje obszar, jeśli jest znany, na przykład Amsterdam dla numeru z Amsterdamu (020). Adres nie jest sprawdzany pod kątem tej reguły przed zakupem numeru: adres spoza tego obszaru zostaje odrzucony po zakupie, a rejestrację można ukończyć tylko z adresem, który spełnia tę regułę. Numer z ownership_address_scope zostaje usunięty, jeśli jego dokumenty nie zostaną zatwierdzone przed terminem rejestracji: opłata aktywacyjna, jeśli była pobrana, zostaje zwrócona jako środki na koncie, a pierwsza opłata cykliczna nie podlega zwrotowi.

Zamów numer

Przekaż numer z wyników wyszukiwania do POST /v1/numbers/orders. Aby zabezpieczyć ponowne próby, zobacz Idempotentność.

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);
}

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

Przykład kodu
{
  "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.

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 ?? "");

Zamówienie przechodzi przez charging, ordering i pending, zanim osiągnie stan końcowy. Przy failed pole failure_reason opisuje prostym językiem, co poszło nie tak. Za numer od operatora opłata jest zwykle pobierana, gdy operator go dostarczy. Pobrana już opłata aktywacyjna, za numer z naszego inwentarza lub za numer operatora rozliczany z góry, nie jest zwracana, więc nieudane zamówienie może zostawić po sobie obciążenie; jeśli tak się stanie, skontaktuj się z pomocą techniczną. Za zamówienie numeru operatora o statusie pending opłata zwykle nie jest pobierana, dopóki operator go nie dostarczy, więc zapewnij dostępne środki: dostarczony numer, za który nadal nie można pobrać opłaty, zostaje zwolniony nie wcześniej niż 72 godziny po złożeniu zamówienia, jego zamówienie kończy się niepowodzeniem, a opłata aktywacyjna pobrana z góry zostaje zwrócona.

Zwolnij numer

Zwolnienie zatrzymuje opłatę cykliczną i numer przestaje dla Ciebie działać. Zwolnić można tylko numer, którego kind ma wartość dedicated, a zwolniony numer nie wraca od razu do sprzedaży.

// Releasing stops the recurring 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");

Pomyślne zwolnienie zwraca 204 bez treści odpowiedzi. Aby zachować numer do końca okresu, za który już zapłaciłeś, anuluj go zamiast tego: Zarządzanie numerami telefonów opisuje oba warianty.

Kiedy zamówienie zostaje odrzucone

Cztery przyczyny odrzucenia obejmują niemal wszystkie nieudane zakupy.

402 z 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 oznacza, że numer został zajęty, gdy go wybierałeś. Wyszukaj ponownie i wybierz inny.

409 z 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

Przejdź do dokumentacji, przewodników i przykładów dotyczących tego tematu.