UWAGA!!! NOWE ZMIANY BEZPIECZEŃSTWA W API
Jeśli korzystasz z API np. do formularzy osadzonych na stronie z wykorzystaniem autoryzacji za pomocą loginu i hasła, oraz masz włączone w systemie logowanie dwuetapowe (2FA) to:
Należy zmienić sposób autoryzacji na bezpieczniejszy z wykorzystaniem tokena, zwany dalej w artykule jako machine to machine. Obecny sposób autoryzacji przestanie być wspierany.
Uzyskanie danych do API
Aby uzyskać dane, które można będzie umieścić w Postmanie i stosować podczas połączenia machine to machine, które jest polecane do automatyzacji procesów, należy przejść do Ustawień systemu.
Spośród zakładek odszukujemy tą o nazwie Klienci API
Twój system powinien mieć na starcie tylko klienta api-client. Aby dodać kolejnego, należy kliknąć przycisk Dodaj.
W wyświetlonym oknie dodawania zostaną wyświetlone cztery pola: nazwa, zakres, unikalny identyfikator systemu oraz ogranicz do uprawnień współpracownika.
Nazwa (Client ID) - miejsce na Twoją unikalną nazwę klienta API, nie może zawierać polskich znaków, spacji oraz znaków specjalnych prócz "_"
Zakres (Scope) - umożliwiamy dodanie zalecanej integracji machine_to_machine;
Unikalny identyfikator systemu (Tenant) - to pole nie jest do edycji, podanie go jest konieczne przy połaczeniu machine_to_machine;
Ogranicz do uprawnień współpracownika — jest to pole, w którym wskazujesz, z jakimi uprawnieniami nawiążesz połączenie.
Jeśli nie chcesz narzucać ograniczeń w tym zakresie, nie zmieniaj wpisu w tym polu. W przeciwnym razie wyszukaj użytkownika, z którego uprawnień chcesz skorzystać.
Po uzupełnieniu pola Nazwa zatwierdzamy dodanie nowego klienta API, klikając Dodaj. Zaraz po tym wyświetli się okno dodatkowe z tokenem, który należy skopiować i dodać od razu do Postmana lub zapisać, ponieważ po zamknięciu tego okna, już nie będzie możliwości ponownego podejrzenia Sekret Key.
W tabeli wyświetlanej w zakładce Klienci API znajdziemy podsumowanie wszystkich dodanych i aktywnych klientów, tenant oraz bezpośredni link do dokumentacji Berg System - API Swagger UI.
Tenant jest polem obowiązkowym w przypadku używania CRM w wersji cloud. Należy wartość tego pola umieścić w nagłówku x-tenant w każdym żądaniu API
Autoryzacja w API na przykładzie programu POSTMAN
Po uruchomieniu Postmana otwieramy nową zakładkę i wybieramy metodę POST, aby wysłać żądanie o token.
W polu POST wpisujemy adres: https://app.bergsystem.pl/api/token lub inny w zależności od systemu. (adres_strony/api/token)
W zakładce Headers dopisujemy nowy nagłówek "X-Tenant" o wartości pola tenant . Jest to pole obowiązkowe w przypadku korzystania z wersji cloud aplikacji dla każdego endpointu
W zakładce Body muszą się znaleźć takie dane jak:
client_id- nazwa z Berg System, wyświetlana w Ustawienia systemu > Klienci APIclient_secret- sekret generowany w Ustawienia systemu > Klienci API podczas tworzenia zakresu machine_to_machinescope- musi być wpisanemachine_to_machinegrant_type- musi być wpisaneclient_credentials
Przykład wykorzystania dla endpointu Customers
Jako sposób autoryzacji powinien być wybrany Bearer Token, pole token po prawej stronie musi zostać uzupełnione zawartością pola access_token, uzyskanego w ramach poprzedniego żądania .
W zakładce Headers powinny być uzupełnione tak, jak na przykładowym obrazku poniżej.
Po wysłaniu żądania dla endpointu: https://app.bergsystem.pl/api/customers, uzyskujemy w odpowiedzi listę wszystkich klientów.
Szczegółowa dokumentacja API znajduje się pod adresem: https://docs.bergsystem.pl/#/berg-crm-api.