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 przy zamówieniu numeru. 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.

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 się ustabilizuje. Przy failed pole failure_reason opisuje, co poszło nie tak, prostym językiem. Pobrana opłata aktywacyjna 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 opłatę cykliczną 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.

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