Integracja eSIM API

Użyj eSIM API, aby kupować pakiety danych i dostarczać szczegóły instalacji z poziomu swojej aplikacji. Potrzebujesz obszaru roboczego, klucza API i środków w portfelu organizacji do zakupów produkcyjnych. Postępuj zgodnie z uwierzytelnianiem i używaj regionu API odpowiadającego Twojemu kluczowi.

Nadaj kluczowi uprawnienie esim:read do przeglądania ofert i zasobów oraz esim:write do zakupów i zarządzania usługą. Dane uwierzytelniające instalacji mają osobne uprawnienia: esim_credentials:read do ich pobierania i esim_credentials:write do tworzenia lub wysyłania linków instalacyjnych. Przechowuj klucz API w swojej aplikacji serwerowej.

1. Wybierz ofertę

Wyświetl listę ofert dla miejsca docelowego, a następnie pobierz wybraną ofertę. Sprawdź zone.countries, limit danych i ważność w pricing, warunki prędkości oraz ewentualną dołączoną usługę telefoniczną. Dla istniejącej karty eSIM użyj Wyświetl kompatybilne oferty; dostępność w katalogu ogólnym nie oznacza kompatybilności z doładowaniem.

Pobierz wymagania identyfikacyjne oferty przed zebraniem danych abonenta. Odpowiedź zawiera schemat JSON dla każdego kraju objętego zasięgiem, wymagający imienia, nazwiska i adresu e-mail oraz ewentualnych dodatkowych pól. Włącz walidację formatu adresu e-mail i daty. To Ty zbierasz i walidujesz te dane; eSIM API nie otrzymuje ani nie weryfikuje odpowiedzi, a pomyślna walidacja nie autoryzuje zakupu.

Dla nowej karty eSIM pobierz opcje realizacji zakupu. Wyświetl zwróconą cenę jednorazową lub dostępną ofertę cykliczną przed zaakceptowaniem zakupu. Ceny realizacji zakupu nie zawierają podatku. Odnowienie ma własną cenę i częstotliwość; postępuj zgodnie z pakietami cyklicznymi, gdy klient je wybierze.

W poniższym przykładzie jednorazowym zainstaluj curl i jq. Ustaw BIRD_API_URL na regionalny bazowy URL, BIRD_API_KEY na swój klucz, a ESIM_OFFER_ID na ID wybranej oferty:

curl --fail-with-body --silent --show-error \
  "$BIRD_API_URL/v1/esim/offers/$ESIM_OFFER_ID/checkout" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  > esim-checkout.json

jq '.one_time' esim-checkout.json

Przejrzyj cenę i warunki oferty przed kontynuowaniem. Wycena nie rezerwuje dostępności.

2. Utwórz zakup

Utwórz zamówienie z offer_id. Pomiń esim_id dla nowego profilu; dołącz go przy doładowaniu. Przy zakupie jednorazowym wyślij offer_revision i expected_price z zaakceptowanej wyceny. Te pola odrzucają zmienione warunki z 409 przed naliczeniem opłaty; pobierz i przejrzyj aktualną wycenę przed zaakceptowaniem zmienionej ceny.

Ustaw ESIM_ORDER_KEY na unikalną wartość dla tego zakupu i zapisz ją razem z żądaniem. Ten przykład kupuje nową, nieprzypisaną kartę eSIM i kopiuje opublikowaną cenę bez zmiany kwoty ani waluty:

jq '{offer_id, offer_revision: .one_time.offer_revision, expected_price: .one_time.price}' \
  esim-checkout.json > esim-order.json

curl --fail-with-body --silent --show-error \
  "$BIRD_API_URL/v1/esim/orders" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $ESIM_ORDER_KEY" \
  --data-binary @esim-order.json

Aby przypisać nowy profil po zakończeniu dostarczania, dołącz subscriber_id obszaru roboczego; postępuj zgodnie z konfiguracją abonenta. Doładowanie zachowuje istniejące przypisanie, więc pomiń subscriber_id przy wysyłaniu esim_id. Szczegóły instalacji wyślij osobno po dostarczeniu.

Zapisz zwrócone ID zamówienia. Sprawdź status nawet po HTTP 201, które może zawierać zamówienie zakończone lub nieudane. HTTP 202 oznacza kontynuację przetwarzania. Pobierz zamówienie, aż uzyska status completed lub failed. Zakończone zamówienie identyfikuje esim_id i package_id; instalacja na urządzeniu pozostaje osobnym krokiem.

3. Dostarcz dane instalacyjne

Po zakupie odczytaj dane uwierzytelniające instalacji, utwórz hostowany link instalacyjny lub wyślij link e-mailem lub SMS. Nie umieszczaj szczegółów aktywacji ani linków instalacyjnych w analityce i publicznych logach.

W przypadku wysłanego linku zapisz identyfikator dostarczenia i sprawdź historię dostarczenia. Odpowiedź 202 potwierdza przyjęcie do wysłania; delivered potwierdza dostarczenie wiadomości, a instalacja na urządzeniu wymaga osobnej weryfikacji. Postępuj zgodnie z przewodnikiem instalacji, który opisuje obsługiwane metody, wygasanie linku i odzyskiwanie.

4. Odzyskaj przerwany zakup

Jeśli odpowiedź na żądanie utworzenia została utracona lub zwróciła 503, powtórz zapisane żądanie z oryginalnym Idempotency-Key; zobacz żądania idempotentne. Jeśli masz identyfikator zamówienia, najpierw odczytaj to zamówienie. Utworzenie kolejnego zakupu, gdy wynik jest niepewny, może spowodować dodatkowe obciążenie.

W przypadku zamówienia w charging sprawdź funding i saldo portfela. funding.required_amount to łączne wymagane saldo, łącznie z podatkiem; porównaj je z dostępnymi środkami przed doładowaniem. Zamówienia jednorazowe automatycznie ponawiają próbę pobrania środków. Jeśli początkowy zakup cykliczny został odrzucony z powodu niewystarczających środków, doładuj portfel i jawnie powtórz to samo żądanie utworzenia z oryginalnym kluczem.

Sprawdź bieżący status zamówienia nawet po funding.lapses_at: ten znacznik czasu nie gwarantuje anulowania. Zamówienie może zostać zrealizowane, jeśli otrzyma środki, zanim kolejna próba pobrania zakończy się niepowodzeniem.

Aby zatrzymać niechciany nieopłacony zakup, anuluj zamówienie. Pomyślne anulowanie nieopłaconego zamówienia zwraca status: failed i failure_code: canceled. Opłacone zamówienie jednorazowe zwraca 409 i jest kontynuowane. W przypadku początkowego zakupu cyklicznego odzyskanie płatności podczas anulowania może pozostawić opłacony zakup w trakcie realizacji, podczas gdy przyszłe odnowienia zostaną wstrzymane. Sprawdź zwrócone zamówienie i subskrypcję przed zgłoszeniem anulowania lub zwrotu środków.

W przypadku nieudanego zakupu sprawdź failure_code i failure_reason. Każde obciążenie jest automatycznie zwracane; refund_transaction_id identyfikuje wystawiony zwrot. Zachowaj identyfikator zamówienia na potrzeby wsparcia, jeśli płatność, dostarczenie lub zwrot pozostaje nierozwiązany.

5. Wyświetl salda i stan usługi

Pobierz eSIM, aby sprawdzić status, stan instalacji, pakiety i available_actions. Wyświetlaj limit pakietu, zużycie i czas obserwacji, korzystając z przewodnika zużycia. Nieznane zużycie musi pozostać nieznane w Twojej aplikacji.

Ponownie sprawdź dostępność akcji, gdy klient podejmie działanie; operacja ponownie weryfikuje uprawnienia i stan. Użyj przewodnika operacji, aby zbadać niedokończone zakupy, problemy z instalacją lub awarie łączności.

Następne kroki

• Wybierz pakiet podróżny.
• Przygotuj instalację na urządzeniu.
• Zarządzaj pakietami cyklicznymi.