
Partnerzy mogą korzystać z tego samego API Atli eSIM, na którym działają heyatli.com i widżet Atli. Na stronie, w aplikacji albo w bocie możesz zbudować własne ekrany: listę kierunków, wybór pakietu, płatność i instalację. Atli dostarcza katalog pakietów, obsługuje płatności przez swoje konto Stripe i wydaje eSIM.
API nie używa kluczy API na poziomie aplikacji. Uwierzytelnianie opiera się na tokenach poszczególnych użytkowników. Twój serwer loguje każdego użytkownika unikalnym identyfikatorem urządzenia albo przez OAuth, a potem wysyła żądania do API w jego imieniu. Każde konto gościa wymaga własnego identyfikatora urządzenia, który twoja aplikacja musi bezpiecznie przechowywać.
Sandbox, produkcja i plik OpenAPI
| Sandbox | Produkcja | |
|---|---|---|
| API | https://api-staging.heyatli.com | https://api.heyatli.com |
| Plik OpenAPI | https://api-staging.heyatli.com/openapi.yaml | https://api.heyatli.com/openapi.yaml |
| Strona płatności | https://staging.heyatli.com/pay | https://heyatli.com/pay |
Sandbox ma osobne konta i używa testowych płatności, dlatego nikt nie zostaje naprawdę obciążony. Tamtejsze eSIM pochodzą od testowego operatora, więc nie da się ich zainstalować na telefonie, a sprzedaż w Sandbox nigdy nie daje prowizji. Wszystkie przykłady w tym poradniku, które tworzą konta albo zamówienia, używają endpointów Sandbox. W środowisku produkcyjnym zmień bazowy adres URL API na https://api.heyatli.com. Dokumentacja pod partners.heyatli.com/pl/dev/api przełącza się między oboma środowiskami.

Błędy API mają jednolity format: code, angielski message i trace_id, który podajesz pomocy technicznej Atli przy rozwiązywaniu problemów. Na podstawie code decyduj, jak twoja aplikacja obsłuży błąd i jaki komunikat wyświetli. Pole message możesz zachować w logach.
Logowanie, wyceny, realizacja voucherów i synchronizacja eSIM mają limity zapytań, a odrzucone żądanie dostaje 429 z Retry-After w sekundach.
Zamiast pisać pojedyncze żądania HTTP, możesz wygenerować typowanego klienta API ze specyfikacji OpenAPI:
docker run --rm -v "$PWD:/out" \
openapitools/openapi-generator-cli generate \
-i https://api.heyatli.com/openapi.yaml \
-g typescript-fetch -o /out/atli-sdkZamień typescript-fetch na python, java, csharp, php albo swift6. Go wymaga go --additional-properties=enumClassPrefix=true.
Krok 1: utwórz użytkownika
Możesz utworzyć dla każdego użytkownika konto gościa Atli bez konieczności rejestracji. Wygeneruj unikalny UUID dla każdego z nich, na przykład przez crypto.randomUUID(), i bezpiecznie zapisz go w rekordzie jego konta.
Traktuj identyfikator urządzenia jak poufne dane logowania, bo każdy, kto ma do niego dostęp, może uwierzytelnić się jako ten użytkownik.
Zaloguj się nim ze swojego serwera. Identyfikator nieznany jeszcze Atli tworzy konto gościa, a znany po prostu loguje na istniejące konto:
curl https://api-staging.heyatli.com/login \
-H 'Content-Type: application/json' \
-d '{ "device_id": "YOUR_DEVICE_ID" }'{
"token": "eyJhbGci…",
"refresh_token": "…",
"expires_in": 900,
"session_id": "…",
"user": { "id": "…", "email": null }
}Wysyłaj token jako Authorization: Bearer YOUR_TOKEN w każdym wywołaniu, które wymaga użytkownika. Token jest ważny 15 minut. Odnów go tuż przed upływem tego czasu przez POST /refresh z refresh_token. Odpowiedź na odświeżenie nazywa nowy token access_token, a nie token. Upewnij się, że twoja integracja odczytuje właściwe pole, aby uniknąć błędów uwierzytelniania po wygaśnięciu pierwszego tokena. Za każdym razem zapisuj token odświeżania, bo każde odświeżenie zwraca nowy i unieważnia stary. Jeśli zgubisz oba, zaloguj się ponownie identyfikatorem urządzenia.
Gość może kupować i używać eSIM. Niektóre udostępniane eSIM i vouchery wymagają prawdziwego konta, a API odmawia ich gościowi z kodem takim jak gift_sign_in_required. Żeby dodać gościowi adres e-mail, wyślij jego token i device_id do POST /auth/email/otp, a potem potwierdź przez POST /auth/email/verify. Logowanie przez WhatsApp lub Telegram może w ten sam sposób zamienić gościa w prawdziwe konto. W obu przypadkach istniejące eSIM i dane konta gościa zostają zachowane. Jeśli pominiesz device_id albo użyjesz adresu e-mail, który ma już konto Atli, osoba trafi na inne konto.
Krok 2: przypisz użytkownika do kodu partnera
Przypisz każdego nowego użytkownika do swojego kodu przed jego pierwszą wyceną:
curl https://api-staging.heyatli.com/user/referral/redeem \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "code": "YOUR_PARTNER_CODE" }'Pole result wskazuje wynik: ok oznacza, że użytkownik został pomyślnie przypisany, already, że ma już polecającego, notnew, że dokonał już wcześniej zakupu, own, że to twój własny kod polecający, a notfound, że nie znaleziono takiego kodu. Przypisać można tylko osobę bez polecającego i bez wcześniejszych zakupów, i to tylko raz. Wykonaj to wywołanie zaraz po utworzeniu użytkownika.
Przypisanie jest stałe. Jeśli twój kod daje zniżkę, pierwsza eSIM użytkownika ją dostanie i nie musisz ponownie wysyłać kodu. Ile przynosi przypisanie, opisuje poradnik o programie partnerskim.
Krok 3: pokaż pakiety i pobierz wycenę
GET /explore/plans zwraca pełny katalog z dostępnymi kierunkami, pakietami, cenami i limitami danych. Nie wymaga tokena, więc twój serwer może pobrać pakiety, zanim ktokolwiek założy konto. Wywołuj go z serwera, bo na zapytania przeglądarki z innych stron API odpowiada odmową 403. Przekaż currency i filtruj przez destination (JP, europe) albo category (local, regional, global):
curl 'https://api-staging.heyatli.com/explore/plans?currency=EUR&destination=JP'id pakietu to product_id, który kupujesz. Wyceń go z store: true, żeby dostać quote_id:
curl https://api-staging.heyatli.com/plan/quote \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "product_id": "THE_PACKAGE_ID",
"currency": "EUR",
"store": true }'{
"subtotal_cents": 1500,
"total_discount_cents": 150,
"net_total_cents": 1350,
"currency": "EUR",
"quote_id": "…",
"expires_at": "…"
}Jako cenę końcową wyświetlaj net_total_cents. Zapisane wyceny wygasają po 30 minutach, więc generuj wycenę, gdy użytkownik przechodzi do płatności. Każdy użytkownik ma naraz jedną zapisaną wycenę, a nowa zastępuje poprzednią.
target_esim_id doładowuje eSIM, którą użytkownik już ma. Bez niego pakiet trafia na domyślną eSIM użytkownika. Jeśli nie ma on jeszcze żadnej eSIM albo sieć domyślnej eSIM nie sprzedaje tego pakietu, pakiet trafia na nową eSIM. U kogoś zalogowanego własnym kontem Atli pole new_esim w wycenie mówi, który przypadek zachodzi. Wyceny dla gości go pomijają. U gościa porównaj eSIM z ukończonego zamówienia z tymi, które zwraca GET /esims, zanim pokażesz kroki instalacji.
auto_apply_best_voucher stosuje najcenniejszy voucher użytkownika spośród tych, które może wykorzystać, a points_to_redeem pozwala użytkownikom wymienić punkty, które aplikacje Atli pokazują jako kredyty Atli. Zamówienie przyjmuje jeden rodzaj zniżki. Zniżka z polecenia z twojego linku ma pierwszeństwo i wygrywa z każdym voucherem, który wycena wybrałaby sama. Voucher podany w voucher_code ją zastępuje, a podanie jednocześnie vouchera i referral_code kończy się błędem cannot_combine_voucher_and_referral. Punkty liczą się tylko wtedy, gdy nie ma ani zniżki z polecenia, ani vouchera.
Krok 4: utwórz zamówienie i przyjmij płatność
Kupuj według zapisanej wyceny, podając jej quote_id. Zamówienie bierze pakiet, zniżki i cenę z wyceny. Jeśli od tego czasu suma zmieniła się o więcej niż 1%, zakup kończy się błędem price_changed i trzeba wycenić ponownie.
Każdej wyceny można użyć do jednego zamówienia. Gdy żądanie zakupu zostanie wysłane ponownie przez pomyłkę albo po przekroczeniu czasu oczekiwania, API zwraca istniejące zamówienie zamiast tworzyć duplikat. Żądanie musi też zawierać idempotency_key, który zapobiega podwójnym zamówieniom, gdy kupujesz bezpośrednio po product_id zamiast według zapisanej wyceny.
curl https://api-staging.heyatli.com/plan/purchase \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "quote_id": "THE_QUOTE_ID",
"idempotency_key": "A_NEW_UUID" }'{
"order_id": "…",
"client_secret": "pi_…_secret_…",
"sealed_secret": "eyJhbGciOiJFQ0RILUVTIi…",
"key_id": "…",
"seal_signature": "…",
"options": "{\"message\":\"Plan for Japan\",\"lang\":\"en\"}",
"options_signature": "…",
"total_amount_cents": 1350,
"status": "pending_payment"
}client_secret należy do PaymentIntent Stripe na koncie Atli. Zamontuj z nim Payment Element Stripe. Twój serwer odczytuje klucz publikowalny z GET /stripe/config i przekazuje go stronie razem z client_secret. Nie wpisuj klucza na sztywno, bo w Sandbox jest inny niż na produkcji, i nie pobieraj go ze strony, bo API odrzuca zapytania przeglądarki z innych stron:
const stripe = Stripe(publishable_key);
const elements = stripe.elements({ clientSecret: order.client_secret });
elements.create('payment').mount('#pay');
const { error } = await stripe.confirmPayment({
elements,
confirmParams: { return_url: window.location.href },
redirect: 'if_required',
});Przekazuj client_secret tylko do sesji płacącego użytkownika i nie zapisuj go w logach. Gdy Stripe potwierdzi płatność, poproś Atli o wydanie eSIM:
curl https://api-staging.heyatli.com/plan/fulfill-payment \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "order_id": "THE_ORDER_ID" }'Jeśli to wywołanie się nie powiedzie, nie obciążaj karty ponownie. Atli samodzielnie kończy opłacone zamówienie.
Płatność jest pobierana na konto Stripe Atli, więc na wyciągu z karty twojego klienta widnieje nazwa Atli, a zwroty i spory o płatności trafiają do Atli. Żeby oferować Apple Pay i Google Pay we własnym formularzu, napisz na [email protected], gdy twoja integracja będzie miała za sobą prawdziwą sprzedaż. Zapisane karty działają przez ten sam zakup: dodaj payment_method_id, żeby obciążyć jedną z nich, albo save_card: true, żeby zachować nową kartę na następny raz.
Płatność na stronie płatności Atli
Boty na WhatsAppie i Telegramie, aplikacje głosowe oraz asystenci AI nie mogą wyświetlić formularza płatności Stripe. W takich integracjach możesz kierować użytkowników na hostowaną stronę płatności Atli. Zbuduj link z trzech zaszyfrowanych wartości, które zwrócił zakup. Jeśli zakup zwraca też options i options_signature, przekaż je dalej, a strona pokaże nad formularzem karty wiersz w rodzaju „Plan for Japan” w języku wskazanym w twoim zapytaniu:
const link = new URL('https://staging.heyatli.com/pay');
link.search = new URLSearchParams({
type: 'payment_intent',
sealed_secret: order.sealed_secret,
key_id: order.key_id,
seal_signature: order.seal_signature,
...(order.options && {
options: Buffer.from(order.options).toString('base64url'),
options_signature: order.options_signature,
}),
}).toString();Strona płatności wyświetla łączną kwotę zamówienia i obsługuje płatności kartą, Apple Pay i Google Pay. Potem wywołaj POST /plan/fulfill-payment z order_id i powtarzaj to wywołanie, aż zamówienie będzie opłacone. Tylko ono potwierdza płatność, bo strona pokazuje płatność, która wciąż się przetwarza, jako udaną.
Przy generowaniu linków do płatności przestrzegaj tych wymagań:
- Przekazuj
sealed_secret,key_id,seal_signatureioptions_signaturedokładnie w takiej postaci, w jakiej zwróciło je API, a kodowaniem zajmie sięURLSearchParams. Wyjątkiem jestoptions: zakoduj je w base64url bez wcześniejszych zmian w JSON-ie. Nigdy nie umieszczaj jawnegoclient_secretw linku. - Wartości z Sandbox otwierają się tylko na
staging.heyatli.com/pay, a produkcyjne tylko naheyatli.com/pay. - Link opłaca czyjeś zamówienie. Wysyłaj go tylko właścicielowi konta i nie zapisuj w logach.
- Nie przechowuj linków na później. Nowy zakup anuluje wcześniejsze oczekujące zamówienie i jego link.
brand=noneukrywa logo Atli.langithemeustawiają język i wygląd strony. Parametry przekierowania przyjmują tylko adresyhttpsna heyatli.com lub jej subdomenach, więc poproś osobę, żeby po zapłacie wróciła do twojego czatu.- Przycisk Anuluj na stronie zostawia zamówienie otwarte. Żeby je anulować, wywołaj
POST /orders/{id}/cancel.
Ta sama strona zapisuje kartę bez płatności: utwórz konfigurację przez POST /user/payment-methods/setup-intent, zbuduj link z type ustawionym na setup_intent, a potem zapisz kartę przez POST /user/payment-methods/confirm. partners.heyatli.com/pl/dev/payment-widget potrafi otworzyć testową płatność na nowym koncie gościa w Sandbox.
Krok 5: pokaż eSIM i jej linki instalacyjne
Zaraz po płatności eSIM może nie być jeszcze gotowa do instalacji. Sprawdzaj status zamówienia, aż obiekt esim będzie zawierać dane instalacyjne. Dopóki zamówienie jest przetwarzane, wyświetlaj odpowiedni komunikat o stanie:
curl 'https://api-staging.heyatli.com/fulfillment/status-updates?order_id=THE_ORDER_ID' \
-H 'Authorization: Bearer YOUR_TOKEN'{
"order_id": "…",
"status": "completed",
"esim": {
"id": "…",
"iccid": "…",
"lpa_address": "…",
"activation_code": "…",
"qr_string": "…"
}
}Status paid potwierdza płatność, a completed oznacza, że eSIM i powiązany z nią pakiet zostały przygotowane. Wyświetl qr_string jako kod QR do instalacji z drugiego urządzenia. Użytkownikom, którzy instalują eSIM bezpośrednio na telefonie, podaj linki instalacyjne dla iPhone’a lub Androida, które otwierają systemową konfigurację eSIM:
const lpa = `LPA:1$${esim.lpa_address}$${esim.activation_code}`;
const carddata = encodeURIComponent(lpa);
const iphone = `https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=${carddata}`;
const android = `https://esimsetup.android.com/esim_qrcode_provisioning?carddata=${carddata}`;Możesz też dać użytkownikowi jeden link, który robi to wszystko: https://heyatli.com/my/esim z parametrem lpa ustawionym na qr_string w base64url i iccid ustawionym na ICCID eSIM. Strona pokazuje kod QR, oba linki do instalacji jednym dotknięciem i dane do ręcznego wpisania, a z ICCID pokazuje też pakiety i pozostałe dane. Nie wymaga przy tym konta Atli. Język dodajesz do ścieżki, jak w /ja/my/esim, a dla eSIM z Sandbox używasz staging.heyatli.com. Każdy, kto ma link, może zainstalować eSIM, więc wysyłaj go tylko osobie, która będzie jej używać.
Nasze poradniki dla iPhone’a i Androida opisują, co użytkownik zobaczy dalej.
GET /esims zwraca listę eSIM użytkownika z danymi instalacyjnymi, pakietami i zużyciem danych według ostatniej synchronizacji. POST /esims/{id}/sync pyta sieć o aktualne liczby. Każde żądanie synchronizacji trafia do operatora sieci i podlega limitom zapytań. Pobieraj aktualne dane o zużyciu wtedy, gdy są potrzebne, a nie automatycznie w stałych odstępach czasu.
Jak pozwolić ludziom logować się kontem Atli
Dla aplikacji, w której ludzie korzystają z własnego konta Atli zamiast konta gościa, Atli udostępnia OAuth 2.1: przepływ kodu autoryzacji z PKCE (S256), rotowane tokeny odświeżania i unieważnianie. Użytkownicy uwierzytelniają się i udzielają dostępu na heyatli.com, więc twoja aplikacja nigdy nie obsługuje ich haseł do Atli.
Zarejestruj klienta pod partners.heyatli.com/pl/dev/oauth/clients. Jedno konto może mieć 10 klientów: public dla aplikacji na telefon oraz confidential dla serwera, który potrafi przechować sekret. Strona internetowa nie może sama wykonać wywołania po token, bo API odrzuca zapytania przeglądarki z innych stron, chyba że klient został oznaczony przez Atli jako zaufany. Aplikacji webowej daj więc serwer i klienta poufnego. Tokeny do API dostaje tylko klient, którego jesteś właścicielem, a żeby go mieć, twoje konto potrzebuje adresu e-mail.
Odczytuj endpointy OAuth z metadanych serwera autoryzacji, zamiast wpisywać je na sztywno w kod:
curl https://api.heyatli.com/.well-known/oauth-authorization-serverTokeny dostępu są ważne 15 minut. Każde odświeżenie zwraca nowy token odświeżania, który musi zastąpić poprzedni w bezpiecznym magazynie danych twojej aplikacji. Osoby logujące się przez twojego klienta mogą być przypisywane do ciebie automatycznie, gdy Atli włączy to dla twojego konta. Do tego czasu przypisuj je samodzielnie przez POST /user/referral/redeem z ich tokenem dostępu, jak w kroku 2.
Udostępnianie, vouchery i grupy
Żeby kupić eSIM do udostępnienia, wyceń ją z is_gift: true i ustaw max_claims na wartość od 1 do 20. Gdy zamówienie zostanie zrealizowane, pobierz claim_url z GET /gifts/sent. POST /rewards/voucher/redeem dodaje voucher do konta użytkownika. Członek Atli Group może wyceniać z group_id i kupować kartą grupy. partners.heyatli.com/pl/dev/api rozpisuje każdą z tych ścieżek krok po kroku i pokazuje kod.
FAQ
Czy API Atli ma klucz API?
Czy potrzebuję własnego konta Stripe?
GET /stripe/config, a dane karty trafiają prosto do Stripe i nigdy nie dotykają twoich serwerów ani API.Czy klienci mogą płacić przez Apple Pay albo Google Pay?
Jak dodać dane do eSIM, którą użytkownik już ma?
target_esim_id ustawionym na tę eSIM i kup go jak zwykle. Pakiet trafia na eSIM, którą użytkownik już ma, więc nie trzeba niczego instalować. Jeśli sieć tej eSIM nie sprzedaje tego pakietu, API odrzuca go z incompatible_esim.Co jeśli płatność przejdzie, a moje wywołanie realizacji zamówienia się nie powiedzie?
GET /fulfillment/status-updates, aż pojawi się eSIM.Gdzie testować bez prawdziwych pieniędzy?
api-staging.heyatli.com. Płać testową kartą Stripe 4242 4242 4242 4242 z dowolną przyszłą datą i dowolnym kodem bezpieczeństwa. Sandbox ma własne konta.


