Uwierzytelnianie w API zewnętrznym

API zewnętrzne przyjmuje dwa rodzaje dostępu. Oba są przypisane do konta w AMPER – API zwraca dane tego konta (klienta) i tylko na nie pozwala.

	Klucz API	Logowanie integratora (token)
Co dostajesz	identyfikator UUID od administratora AMPER	login i hasło konta
Jak przekazać	parametr ?api_key= w adresie	nagłówek Authorization: Bearer <token>
Odczyt danych (GET)	tak	tak
Zamówienia (create-order)	nie	tak
Ważność	do daty ustawionej przy kluczu albo do wyłączenia	token kilka minut, potem odświeżenie

Jeśli integracja tylko czyta katalog (sklep, porównywarka, plik XML), wystarczy klucz API. Jeśli ma składać zamówienia – potrzebny jest login.

Klucz API

Klucz generuje administrator w panelu AMPER (Ustawienia → Klucze API) i przypisuje go do konta klienta. Klucz ma nazwę, datę ważności i może zostać wyłączony.

Klucz przekazujesz w parametrze api_key w adresie każdego zapytania:

GET https://{amper_ws}/external/v1/products/?api_key={api_key}

• Klucz działa tylko dla zapytań GET. Zamówienia z kluczem API są odrzucane (403).
• API zwraca dane klienta, do którego przypisano klucz: jego asortyment, ceny, stany i promocje.
• Wygasły albo wyłączony klucz, a także klucz klienta, którego konto jest nieaktywne, daje odpowiedź 401. Wyłączenie klucza w panelu działa od razu.

Logowanie integratora

Integracja loguje się loginem i hasłem konta w AMPER – zwykle konta klienta w sklepie B2B, dla którego działa. W odpowiedzi dostaje token dostępu (JWT).

POST https://{amper_ws}/external/v1/auth/
Content-Type: application/json

{
  "username": "login_konta",
  "password": "haslo"
}

Odpowiedź 200 OK:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cC...",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5c...",
  "token_type": "Bearer",
  "amper-company-assigned": "amper-xyz"
}

Odpowiedź może zawierać też pola techniczne serwera logowania (np. session_state, scope) – integracja ich nie potrzebuje.

Pole	Opis
access_token	token dostępu – przekazuj go w nagłówku Authorization: Bearer <access_token>
expires_in	ważność tokena w sekundach
refresh_token	token do odświeżenia sesji bez ponownego logowania
refresh_expires_in	ważność refresh_token w sekundach
amper-company-assigned	identyfikator instalacji AMPER, do której należy konto

Token z /external/v1/auth/ działa tylko w API zewnętrznym (adresy /external/v1/…). Pozostałe adresy serwera odrzucają go z kodem 403 i komunikatem This access token was issued for the external API and is accepted only by /external/v1/.

Logowanie integratora nie wymaga captchy, dlatego nieudane próby są ograniczone:

• 5 nieudanych prób na godzinę dla jednego loginu,
• 20 nieudanych prób na godzinę z jednego adresu IP.

Po przekroczeniu limitu odpowiedź to 429 (Too many failed sign-in attempts. Try again later.). Udane logowania się nie liczą. Nie ponawiaj logowania w pętli po błędnym haśle – poproś o poprawne dane.

Odświeżenie tokena

Gdy access_token wygaśnie, odśwież go tokenem refresh_token zamiast logować się ponownie:

POST https://{amper_ws}/external/v1/auth/refresh/
Content-Type: application/json

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5c..."
}

Odpowiedź ma ten sam format co przy logowaniu – nowy access_token i nowy refresh_token. Gdy refresh_token wygasł, odpowiedź to 400 z błędem invalid_grant – wtedy zaloguj się ponownie przez /external/v1/auth/. Ten adres odświeża tylko tokeny wydane przez /external/v1/auth/.

Zalecane postępowanie

• Zaloguj się raz i używaj tokena, dopóki jest ważny. Nie loguj się przed każdym zapytaniem.
• Przed zapytaniem sprawdź, czy token nie wygasł (expires_in), i w razie potrzeby odśwież go.
• Po odpowiedzi 401 odśwież token i ponów zapytanie.
• Gdy odświeżenie się nie uda (400), zaloguj się ponownie.

Gotowa implementacja: Przykłady kodu.

Kody odpowiedzi logowania

Kod	/external/v1/auth/	/external/v1/auth/refresh/
200	token wydany	nowy token wydany
400	brak loginu lub hasła	brak refresh_token albo token wygasł lub jest nieprawidłowy (invalid_grant)
403	błędny login lub hasło, konto wyłączone, konto spoza tej instalacji AMPER albo zablokowany adres IP	–
404	logowanie integratora nie jest włączone na tej instalacji – skontaktuj się z działem IT firmy	jak obok
429	przekroczony limit nieudanych prób	–

Jakie konto i do czego

Odczyt danych (GET) zawsze pokazuje katalog klienta, do którego należy klucz albo login. Do pobrania katalogu konkretnego klienta używaj jego klucza API albo jego loginu.

Przy składaniu zamówień liczy się rodzaj konta:

Konto	Zamówienia dla
konto klienta w sklepie B2B	tego klienta i klientów z nim powiązanych (np. oddziałów)
konto integracji ERP (Translator), konto API, administrator	dowolnego klienta

Zamówienie dla klienta, dla którego konto nie ma uprawnień, jest odrzucane z kodem 403. Szczegóły: Tworzenie zamówienia „create-order”.

Bezpieczeństwo

• Klucz API i login dają dostęp do danych handlowych klienta (ceny, rabaty, promocje), a login – także do składania zamówień. Przechowuj je po stronie serwera – nigdy w kodzie strony www ani aplikacji mobilnej.
• Każda integracja powinna mieć własny klucz albo login. Gdy integracja przestaje działać albo dane wyciekną, administrator wyłącza klucz lub zmienia hasło.
• Łącz się wyłącznie przez HTTPS.

Wcześniejszy sposób logowania

Integracje, które logowały się przez POST /auth/ (logowanie sklepu B2B) i składały zamówienia przez POST /create-order, powinny przejść na POST /external/v1/auth/ i POST /external/v1/create-order. Logowanie sklepu może wymagać captchy, a adres /create-order zostanie wyłączony. Token z /external/v1/auth/ nie działa pod starym adresem /create-order.