Integracja Shopify — autocomplete adresów PRG w checkout

Oficjalna integracja adresy.app dla Shopify. Autocomplete polskich adresów PRG i walidacja w checkout — wdrożenie przez Additional Scripts w panelu Shopify, bez potrzeby App Store ani modyfikacji kodu sklepu.

Jak działa integracja Shopify?

Shopify nie pozwala na standardowe wtyczki w sekcji checkout — integracja adresy.app działa jako skrypt wstrzykiwany przez panel Ustawienia → Checkout → Additional Scripts. Nie wymaga instalacji z App Store.

Instalacja

Pobierz plik JS integracji (przycisk powyżej).
Wgraj plik do sekcji Assets w edytorze motywów lub skorzystaj z wersji CDN.
W panelu Shopify przejdź do Ustawienia → Checkout → Additional Scripts.
Wklej poniższy snippet (zamień TWOJ_KLUCZ_API na klucz z panelu adresy.app):

<script>
window.adresyShopifyConfig = {
  apiKey: 'TWOJ_KLUCZ_API',
  apiBase: 'https://api.adresy.app/api/v1',
  autocomplete: true,
  validate: true,
  mode: 'warn'
};
</script>
<script src="https://cdn.adresy.app/shopify/adresy-checkout.js"></script>

Zapisz i przetestuj checkout na stronie z adresem dostawy.

Parametry konfiguracji

Parametr	Opis	Domyślnie
apiKey	Klucz API z panelu adresy.app	anonymous
apiBase	URL API — zmień tylko w testach lokalnych	https://api.adresy.app/api/v1
autocomplete	Włącz autocomplete adresu	true
validate	Włącz walidację po blur	true
mode	`warn` — ostrzeżenie, `block` — blokada	warn

Wymagania

Shopify Basic, Shopify, Advanced lub Plus
Klucz API adresy.app

Uwaga o kluczu API

Klucz API w konfiguracji JS jest widoczny w source strony — to zamierzone zachowanie. Klucz adresy.app służy wyłącznie do odczytu adresów PRG (brak zapisu, brak dostępu do danych klientów). W panelu adresy.app możesz ograniczyć dozwolone originy dla klucza.

Funkcje

Autocomplete adresów PRG bezpośrednio w checkout Shopify
Instalacja bez App Store — snippet przez Additional Scripts
Konfiguracja przez zmienną JS — bez edycji kodu
Tryb warn lub block
Działa z Shopify Basic, Standard, Advanced i Plus
Wywołanie API z nagłówkiem X-API-Key (CORS aktywny)

Najczęściej zadawane pytania

Czy integracja działa z nowym checkout Shopify (Checkout Extensibility)?

Aktualnie integracja działa z klasycznym checkout przez Additional Scripts. Wsparcie dla Checkout Extensibility (UI Extensions) jest planowane w kolejnej wersji.

Czy klucz API jest bezpieczny w kodzie JS?

Klucz API adresy.app służy tylko do odczytu danych adresowych PRG — nie ma dostępu do danych klientów ani Twojego sklepu. Możesz dodatkowo ograniczyć dozwolone domeny dla klucza w panelu adresy.app.

Czy integracja wymaga własnego serwera?

Nie — plugin wywołuje API adresy.app bezpośrednio z przeglądarki klienta (CORS). Nie wymaga backendu ani proxy.