Widget JavaScript

Osadź autocomplete adresów na swojej stronie za pomocą klucza publicznego widgetu (pk_live_...). Klucze widgetu są przeznaczone do użycia w przeglądarce — w przeciwieństwie do tokenów API serwerowych nie mają dostępu do pełnego API.

Jak to działa

1. Utwórz klucz Widget (JS) w panelu klienta Tensoit i dodaj dozwolone domeny.
2. Załaduj skrypt SDK i arkusz stylów na stronie.
3. SDK wymienia klucz publiczny na krótkotrwałą sesję (sess_..., 15 minut) przez POST /widget/v2/session na https://api.tensoit.pl.
4. Żądania autocomplete używają Authorization: Bearer sess_... i są rozliczane jak trafienia API serwerowego.

Endpoint /session nie wlicza się do zużycia API — liczą się tylko endpointy z danymi autocomplete.

Szybki start

<link rel="stylesheet" href="https://tensoit.pl/css/v1/tensoit-autocomplete.css">
<script src="https://tensoit.pl/js/v1/tensoit-autocomplete.js"></script>
<script>
  TensoitAutocomplete.init({
    publicKey: 'pk_live_YOUR_KEY_HERE',
    autoFillPostal: true,
    selectors: {
      city: '#city',
      street: '#street',
      number: '#number',
      postal: '#postal'
    }
  });
</script>

Konfiguracja

Opcja	Wymagane	Domyślnie	Opis
publicKey	Tak	—	Klucz widgetu z panelu klienta (pk_live_...)
selectors	Tak	—	Selektory CSS pól formularza (minimum city)
apiBase	Nie	https://api.tensoit.pl/widget/v2	Domyślne produkcyjne API widgetu; lokalny host skryptu nadal używa /api/widget/v2
theme	Nie	auto	auto, light lub dark
autoFillPostal	Nie	true	Gdy włączone, pobiera kody pocztowe po ustawieniu miasta i numeru budynku (ulica może być pusta); jeśli zwrócony jest dokładnie jeden wynik, uzupełnia pole kodu pocztowego automatycznie
streetPrefix	Nie	brak	Format etykiety ulicy. dot: wiodące ulica / ul. → ul., aleja → al.. empty: ulica / ul. znikają, aleja i tak staje się al.. Nazwa bez tych cech zostaje bez zmian. Pominięcie opcji zostawia nazwę z bazy

Automatyczne uzupełnianie kodu pocztowego

Gdy autoFillPostal ma wartość true (domyślnie), SDK wywołuje endpoint pocztowy po uzupełnieniu numeru budynku — przez wybór podpowiedzi lub gdy pole numeru traci fokus. Jeśli API zwróci dokładnie jeden kod pocztowy, SDK wpisuje go w pole pocztowe bez otwierania listy rozwijanej.

Auto-uzupełnianie działa tylko gdy:

• skonfigurowany jest selektor postal,
• miasto i numer mają wartości (ulica może być pusta — część miejscowości nie ma nazwy ulicy),
• pole kodu pocztowego jest nadal puste.

Aby wymusić ręczne wyszukiwanie kodu pocztowego, wyłącz funkcję:

TensoitAutocomplete.init({
  publicKey: 'pk_live_YOUR_KEY_HERE',
  autoFillPostal: false,
  selectors: {
    city: '#city',
    street: '#street',
    number: '#number',
    postal: '#postal'
  }
});

Nowe klucze widgetu tworzone w panelu klienta zawierają autoFillPostal: true w generowanym snippecie embed, aby domyślne zachowanie było widoczne w kodzie integracji.

Etykieta ulicy

streetPrefix dokleja ?streetPrefix= do istniejącego GET ulicy. Szukanie w bazie się nie zmienia. W odpowiedzi suggestions to pełna nazwa z bazy, a labels to tekst na listę i do pola.

Po wyborze pozycji pole ulicy dostaje etykietę (al. Jana Pawła II albo Jana Pawła II). Zapytania o numer i kod wysyłają oryginał z suggestions (Aleja Jana Pawła II, ulica Jana Pawła II). Ręczna zmiana pola czyści ten oryginał.

Inna wartość niż dot albo empty jest ignorowana w JS. Na API zwraca 400.

TensoitAutocomplete.init({
  publicKey: 'pk_live_YOUR_KEY_HERE',
  streetPrefix: 'dot',
  selectors: {
    city: '#city',
    street: '#street',
    number: '#number',
    postal: '#postal'
  }
});

To samo pole działa w REST, bez zmiany ścieżki:

GET /v2/street/Warszawa/Jana?streetPrefix=dot
POST /v2/street   { "city": "Warszawa", "street": "Jana", "streetPrefix": "empty" }

Kolejny opcjonalny parametr dodajemy tak samo: query string na GET i to samo pole w JSON POST.

Selektory

Obsługiwany jest dowolny poprawny selektor CSS:

selectors: {
  city: '#city',
  street: '[name="street"]',
  number: '.house-number',
  postal: 'input[data-field="postal"]'
}

Jeśli selektor nie pasuje do żadnego elementu, SDK loguje czytelny błąd w konsoli przeglądarki.

Lista dozwolonych domen

Każdy klucz widgetu ma jeden lub więcej wzorców domen:

Wzorzec	Pasuje do
shop.example.com	dokładnie ten host
*.example.com	jeden poziom subdomeny, np. www.example.com, app.example.com

Przeglądarka musi wysłać nagłówek Origin (automatycznie dla fetch ze strony). Żądania z niewymienionych domen otrzymują 403 Forbidden.

Wersjonowanie SDK

Integracje produkcyjne powinny przypiąć wersję major:

https://tensoit.pl/js/v1/tensoit-autocomplete.js
https://tensoit.pl/css/v1/tensoit-autocomplete.css

Gdy pojawi się nowa wersja major (v2), istniejące URL-e v1 nadal działają. Zaktualizuj wersję w HTML, gdy będziesz gotowy na migrację.

Cykl życia sesji

• Sesje wygasają po 15 minutach (konfigurowalne po stronie serwera).
• SDK odświeża sesję automatycznie około 1 minuty przed wygaśnięciem.
• Jeśli sesja wygaśnie w trakcie żądania, kolejne wywołanie autocomplete uruchomi nową sesję.

Bezpieczeństwo

• Nigdy nie umieszczaj tokenów API serwerowych (id|secret) w kodzie frontendu.
• Klucze widgetu to publiczne identyfikatory ograniczone do dozwolonych domen i endpointów autocomplete.
• W produkcji zawsze używaj HTTPS.

Endpointy API (widget)

Metoda	Ścieżka	Auth
POST	/widget/v2/session	X-Public-Key: pk_live_... + Origin
GET	/widget/v2/city/{city}	Bearer sess_...
GET	/widget/v2/street/{city}/{street}	Bearer sess_...
GET	/widget/v2/number/{city}/{street}/{number?}	Bearer sess_...
POST	/widget/v2/number/	Bearer sess_...
GET	/widget/v2/postal/{city}/{street}/{number?}	Bearer sess_...
POST	/widget/v2/postal/	Bearer sess_...

Kształt odpowiedzi odpowiada standardowemu formatowi autocomplete v2 (tablica suggestions). Przy streetPrefix dochodzi tablica labels o tej samej długości.

Przykład

Zobacz tensoit-autocomplete.example.js — gotowy snippet do skopiowania.

Lokalny smoke test

1. Utwórz klucz widgetu w panelu klienta i dodaj domenę testową (np. 127.0.0.1 lub host stagingowy).
2. W aplikacji API (lokalnie: http://127.0.0.1:8000/widget-demo.html?pk=pk_live_...) otwórz stronę demo z kluczem publicznym.
3. Wpisz prefix miasta (np. Skier) i potwierdź, że pojawiają się podpowiedzi; w zakładce Network sprawdź POST /widget/v2/session, potem GET /widget/v2/city/....

Embed produkcyjny używa tych samych URL-i SDK co w Szybkim starcie; tylko publicKey i selektory zmieniają się w zależności od strony.