Instrukcja polaczenia z API WMS

Instrukcja polaczenia z API WMS

Ten dokument opisuje polaczenie z Futuriti WMS REST API w modelu:

Authorization Code + PKCE + Refresh Token

Flow nie uzywa client_secret. Uzytkownik loguje sie w przegladarce przez Auth0, aplikacja odbiera authorization_code, wymienia go na tokeny i wywoluje lokalne API WMS.

Wazne: publiczna dokumentacja WMS moze pokazywac starszy wariant grant_type=password z client_secret. W tym scenariuszu celowo go nie uzywamy. Ta instrukcja opisuje docelowy wariant dla aplikacji bez sekretu klienta: Authorization Code + PKCE + Refresh Token.

Dwa adresy API

W integracji wystepuja dwa adresy:

• API lokalne WMS, instalowane u klienta – z niego pobieramy dane biznesowe z lokalnej bazy WMS, np. towary, dokumenty, stany i lokalizacje;
• Auth0/Futuriti – uzywane do logowania i wystawienia tokenow.

Request po liste towarow powinien isc do API lokalnego, np. http://localhost:91/{instanceName}/articles, a nie bezposrednio do zdalnego API Futuriti.

Dane konfiguracyjne

Przed testem przygotuj:

• AUTH0_DOMAIN: login.futuriti.pl;
• AUTH0_CLIENT_ID: identyfikator aplikacji Auth0;
• AUTH0_AUDIENCE: dla produkcji https://futuritiwms.api.production;
• AUTH0_SCOPE: dla produkcji openid profile email wms production offline_access;
• REDIRECT_URI: callback wpisany w Auth0, np. http://localhost:8400/callback;
• adres lokalnego API WMS, np. http://localhost:91;
• nazwe instancji WMS, uzywana w adresie jako pierwszy segment sciezki, np. {instanceName};
• srodowisko instancji:
  • 1 albo Devel – srodowisko deweloperskie/testowe,
  • 2 albo Production – produkcja.

Token moze byc poprawny technicznie, ale API zwroci 401, jezeli konto nie ma dostepu do wskazanej instancji i srodowiska.

Wymagania w Auth0

Nowa aplikacja Auth0 powinna byc skonfigurowana jako flow bez sekretu:

• typ: aplikacja obslugujaca Authorization Code + PKCE;
• Token Endpoint Authentication Method: None;
• wlaczone granty: Authorization Code oraz Refresh Token;
• wlaczony refresh token / offline access;
• w Allowed Callback URLs dodany dokladny REDIRECT_URI, np. http://localhost:8400/callback;
• aplikacja ma dostep do API o audience https://futuritiwms.api.production;
• konto uzytkownika ma przypisany dostep do instancji WMS w odpowiednim srodowisku.

Dla domyslnego skryptu wpisz w Auth0 dokladnie:

http://localhost:8400/callback

Auth0 porownuje callback dokladnie. http://127.0.0.1:8400/callback, https://localhost:8400/callback i http://localhost:8400/callback/ to inne adresy.

Jezeli aplikacja zostala utworzona jako standardowa Regular Web Application w Auth0, moze domyslnie wymagac client_secret na /oauth/token. W tym flow token endpoint musi byc ustawiony jako public client: Token Endpoint Authentication Method / Client Authentication = None. Jezeli Dashboard nie pozwala ustawic tego dla RWA, trzeba skonfigurowac klienta po stronie Auth0 jako publiczny albo ustawic token_endpoint_auth_method=none przez narzedzia administracyjne Auth0.

Przebieg logowania

1. Aplikacja generuje code_verifier i code_challenge dla PKCE.
2. Aplikacja przekierowuje uzytkownika na endpoint Auth0:

https://login.futuriti.pl/authorize

z parametrami:

response_type=code
client_id=<client_id>
redirect_uri=<redirect_uri>
scope=openid profile email wms production offline_access
audience=https://futuritiwms.api.production
code_challenge=<code_challenge>
code_challenge_method=S256

3. Po zalogowaniu Auth0 wraca na redirect_uri z parametrem code.
4. Backend albo skrypt wymienia code na tokeny przez:

POST https://login.futuriti.pl/oauth/token
Content-Type: application/json

Body:

{
  "grant_type": "authorization_code",
  "client_id": "<client_id>",
  "code": "<authorization_code>",
  "code_verifier": "<code_verifier>",
  "redirect_uri": "http://localhost:8400/callback"
}

5. Do API WMS wysylamy access_token.

Naglowki API WMS

Publiczna dokumentacja WMS pokazuje naglowek:

AccessToken: <access_token>
Accept: application/json

Kod API akceptuje tez standardowe:

Authorization: Bearer <access_token>

Skrypt testowy uzywa AccessToken.

Test profilu uzytkownika

Przy instalacji lokalnej request wysylamy do API lokalnego:

GET http://localhost:91/me
AccessToken: <access_token>

Poprawna odpowiedz zwraca profil uzytkownika Auth0. Lokalna instancja API do weryfikacji profilu uzywa zdalnego API Futuriti.

Pobranie listy towarow

Towary w API sa dostepne jako articles.

Minimalny request do lokalnego API dla produkcji:

GET http://localhost:91/{instanceName}/articles?environment=2&PageSize=10&PageIndex=0&ReturnTotalCount=true
AccessToken: <access_token>
Accept: application/json

Jezeli API lokalne jest wystawione pod innym adresem, zastap http://localhost:91 adresem przekazanym przez administratora.

Przykladowe filtry query string:

• Code=ABC123 – wyszukanie po kodzie towaru;
• Ean=5900000000000 – wyszukanie po EAN;
• SearchForText=fragment – wyszukanie po kodzie, nazwie, EAN albo EAN jednostki zbiorczej;
• IsActive=true – tylko aktywne towary;
• PageSize=10 i PageIndex=0 – stronicowanie;
• ReturnTotalCount=true – zwrocenie lacznej liczby rekordow.

Refresh token

Refresh token sluzy do uzyskania nowego access_token, gdy poprzedni wygasa.

Przykladowe zadanie:

POST https://login.futuriti.pl/oauth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "client_id": "<client_id>",
  "refresh_token": "<refresh_token>",
  "scope": "openid profile email wms production offline_access",
  "audience": "https://futuritiwms.api.production"
}

Po refreshu zapisz nowy access_token. Jezeli odpowiedz zawiera nowy refresh_token, nadpisz poprzedni.

Skrypt testowy

W repozytorium jest gotowy skrypt:

.\scripts\Test-WmsApiConnection.ps1

Przyklad z logowaniem przez Authorization Code + PKCE:

.\scripts\Test-WmsApiConnection.ps1 `
  -ApiBaseUrl "http://localhost:91" `
  -InstanceName "moja-instancja" `
  -Environment Production `
  -ClientId "<client_id>" `
  -RedirectUri "http://localhost:8400/callback"

Skrypt:

• wygeneruje PKCE;
• otworzy przegladarke z logowaniem Auth0;
• odbierze callback lokalnie na porcie z RedirectUri;
• wymieni code na token;
• sprawdzi /me;
• pobierze pierwsza strone towarow z lokalnego API.

Test refresh tokena:

.\scripts\Test-WmsApiConnection.ps1 `
  -ApiBaseUrl "http://localhost:91" `
  -InstanceName "moja-instancja" `
  -Environment Production `
  -ClientId "<client_id>" `
  -RedirectUri "http://localhost:8400/callback" `
  -TestRefresh

Przyklad z gotowym tokenem:

.\scripts\Test-WmsApiConnection.ps1 `
  -ApiBaseUrl "http://localhost:91" `
  -InstanceName "moja-instancja" `
  -Environment Production `
  -AccessToken "<access_token>"

Przyklad z filtrem po kodzie:

.\scripts\Test-WmsApiConnection.ps1 `
  -ApiBaseUrl "http://localhost:91" `
  -InstanceName "moja-instancja" `
  -Environment Production `
  -AccessToken "<access_token>" `
  -Code "ABC123"

Najczestsze bledy

• callback mismatch – RedirectUri w skrypcie nie jest identyczny z Allowed Callback URLs w Auth0.
• access_denied / Unauthorized przy POST https://login.futuriti.pl/oauth/token – najczesciej aplikacja Auth0 nadal wymaga client_secret, nie ma wlaczonego grantu Authorization Code, nie ma grantu Refresh Token albo nie moze wydac tokenu dla audience https://futuritiwms.api.production.
• invalid_grant – kod wygasl, zostal juz uzyty albo nie pasuje do aktualnego code_verifier.
• access_denied z /authorize – uzytkownik nie ma dostepu albo aplikacja/Auth0 nie pozwala na ten flow.
• brak refresh_token – sprawdz offline_access w scope i ustawienia refresh tokenow aplikacji Auth0.
• 401 Api Key was not provided. – brak naglowka AccessToken albo Authorization.
• 401 Unauthorized client. – token jest niepoprawny, wygasl albo zostal wystawiony dla niewlasciwego audience.
• 401 przy /{instanceName}/articles mimo poprawnego /me – konto nie ma dostepu do tej instancji, wskazano zla nazwe instancji albo zle environment.
• 404, blad polaczenia albo timeout – sprawdz, czy lokalne API dziala i czy uzywasz lokalnego adresu.
• 503 – lokalne API nie moze zweryfikowac dostepu do instancji w usludze zdalnej.

Uwagi bezpieczenstwa

• Nie generuj nowego tokenu przed kazdym requestem.
• Trzymaj tokeny w bezpiecznym storage backendu.
• Refresh token traktuj jak sekret.
• Do integracji produkcyjnej uzywaj konta i uprawnien uzgodnionych z Futuriti.

Instrukcja uruchomienia skryptu testowego WMS API

Skrypt Test-WmsApiConnection.ps1 sluzy do sprawdzenia polaczenia z WMS API. Wykonuje logowanie przez Auth0 w modelu Authorization Code + PKCE, pobiera token, sprawdza endpoint /me, a nastepnie pobiera testowo pierwsza strone towarow z lokalnego API WMS.

Download

Test-WmsApiConnection.zip

Wymagania

Przed uruchomieniem przygotuj:

• client_id aplikacji Auth0 skonfigurowanej bez client_secret;
• nazwe instancji WMS, np. XL_70e68af2_3976_465d_9dbd_f90e1aeb1b33;
• adres lokalnego API WMS, domyslnie http://localhost:91;
• poprawny callback w Auth0: http://localhost:8400/callback;
• konto uzytkownika z dostepem do wskazanej instancji WMS.

Uruchomienie

Otworz PowerShell i wykonaj:

C:\R\M\FuturitiWMS\FuturitiWMSRESTAPI\scripts\Test-WmsApiConnection.ps1 `
  -ApiBaseUrl "http://localhost:91" `
  -InstanceName "XL_70e68af2_3976_465d_9dbd_f90e1aeb1b33" `
  -Environment Production `
  -ClientId "<client_id>" `
  -RedirectUri "http://localhost:8400/callback"

Po uruchomieniu skrypt otworzy przegladarke. Zaloguj sie do Auth0. Po poprawnym logowaniu skrypt automatycznie odbierze callback, wymieni kod na token i pobierze liste towarow.

Test refresh tokena

Jezeli chcesz dodatkowo sprawdzic refresh token, dodaj parametr -TestRefresh:

C:\R\M\FuturitiWMS\FuturitiWMSRESTAPI\scripts\Test-WmsApiConnection.ps1 `
  -ApiBaseUrl "http://localhost:91" `
  -InstanceName "XL_70e68af2_3976_465d_9dbd_f90e1aeb1b33" `
  -Environment Production `
  -ClientId "<client_id>" `
  -RedirectUri "http://localhost:8400/callback" `
  -TestRefresh

Najczestsze problemy

• callback mismatch – w Auth0 brakuje dokladnie takiego callbacka: http://localhost:8400/callback.
• access_denied / Unauthorized przy /oauth/token – aplikacja Auth0 nadal wymaga client_secret albo nie ma wlaczonego flow Authorization Code + PKCE bez sekretu.
• 401 przy pobieraniu towarow – token jest poprawny, ale konto nie ma dostepu do wskazanej instancji lub srodowiska.
• 404 albo timeout – lokalne API WMS nie dziala pod wskazanym adresem albo portem.

Poprawny wynik

Poprawne wykonanie powinno pokazac m.in.:

Token: OK
Profil: OK
Towary: OK. Pobrano ... rekordow na stronie.