Jak utworzyć token API
Chcesz wciągać dane z Salecare do własnego arkusza, hurtowni danych albo narzędzia BI, na przykład Power BI? Do tego służą tokeny API. Token uwierzytelnia Twoje narzędzie i pozwala mu pobierać dane przez API, bez logowania i bez podawania komukolwiek hasła. Wystawiasz go raz i podpinasz w integracji.
Krok 1. Otwórz stronę Tokeny API
W menu bocznym kliknij Ustawienia, a potem w grupie Integracje wiersz Tokeny API. Otwiera on stronę Tokeny API w Ustawieniach, z tokenami firmy. Stronę otworzy osoba z uprawnieniem Integracje (konta, tokeny API). Widzi na niej tokeny całej firmy i każdy z nich może unieważnić. Dostęp do API obejmuje plan Pro i wyższe. Na niższym planie przycisk Utwórz token jest wyłączony, a po najechaniu na ikonę kłódki obok zobaczysz wymagany plan.
Krok 2. Wydaj nowy token
Kliknij Utwórz token obok tytułu strony. Pokaże się formularz Nowy token. W polu Nazwa wpisz nazwę, po której poznasz, do czego służy token, na przykład nazwę narzędzia, które go użyje. W polu Zakresy zaznacz to, co token może zrobić.
Do wyboru są cztery zakresy odczytu, czyli marża i agregaty, zamówienia, oferty oraz prowizje i zwroty prowizji. Zaznacz tylko zakresy, których narzędzie potrzebuje. Zapytanie o adres spoza zakresów tokenu dostaje kod 403, a wąski token wyrządzi mniej szkody, jeśli wycieknie. Pole Wygasa (opcjonalnie) jest wstępnie ustawione na rok od dziś. Token przestaje działać o 00:00 w wybranym dniu, a nie na jego końcu. Możesz wybrać inny dzień albo kliknąć Wyczyść datę obok pola, jeśli token ma działać aż do unieważnienia. Drugie kliknięcie Utwórz token zapisuje token.
Token działa z uprawnieniami osoby, która go utworzyła. Na liście zakresów widzisz tylko te obszary, do których daje dostęp Twoja rola. Jeśli ktoś później zawęzi Twoje uprawnienia, token od razu przestaje zwracać dane z tych obszarów. Gdy konto zostanie usunięte z firmy, wydane przez nie tokeny są unieważniane automatycznie.
Krok 3. Skopiuj token od razu
Sekret nowego tokenu strona pokazuje tylko raz, do jej opuszczenia. Skopiuj go teraz przyciskiem Skopiuj i zapisz w bezpiecznym miejscu, na przykład w menedżerze haseł, bo nie zostanie wyświetlony ponownie. Lista na stronie pokazuje najpierw aktywne tokeny, od najbliższego końca ważności, potem wygasłe i unieważnione. Przy tokenie zobaczysz później jego nazwę, zakresy, status i datę wygaśnięcia, a pełnego tokenu już nie. Token traktuj jak hasło i nie wklejaj go do wiadomości ani do wspólnych dokumentów.
Krok 4. Podepnij token w narzędziu
Na dole strony jest zwinięta sekcja Jak pobierać dane przez API. Po rozwinięciu pokazuje gotowe zapytanie z nagłówkami i adres każdego zapytania razem z zakresem, którego wymaga, oraz opisem danych, które zwraca. Pokazuje też parametry from, to i per_page, znaczenie kodów w odpowiedziach oraz limity zapytań i kody odmowy. Token wpisujesz w nagłówku Authorization po słowie Bearer, bo Salecare nie przyjmuje go w adresie zapytania. W Power BI token trafia więc do nagłówka zapytania i zostaje zapisany w pliku raportu. Utwórz osobny token dla każdego narzędzia i każdej osoby, a gdy plik trafi do kogoś spoza firmy, unieważnij token.
Stan zamówienia, status oferty na Allegro i dopasowanie oferty do produktu przychodzą jako stałe kody tekstowe, na przykład awaiting_payment przy zamówieniu, które czeka na płatność, albo ended przy ofercie zakończonej. Lista ofert obejmuje także oferty zakończone. Każde zamówienie i każda oferta podaje konto Allegro, z którego pochodzi, a oferta także swój numer na Allegro i SKU, więc dane z kilku kont połączysz z danymi Allegro. Kwoty przychodzą w groszach jako liczby całkowite, a odpowiedź ma format JSON:API, więc kolejną stronę narzędzie pobiera z adresu w polu links.next.
Liczby z adresu marży czytaj tak, jak opisuje je ta sekcja. Pole margin_cents to marża zamówień po koszcie zakupu, wysyłki, prowizji, innych opłatach Allegro, zwrotach, promowaniu i reklamie, a nie zysk. Koszty operacyjne i opłaty konta przychodzą w osobnych polach i nie są od niej odjęte, a kosztów stałych API nie zwraca. Zysk w Rachunku zysków i strat będzie więc niższy. Prowizja, inne opłaty Allegro i wpływ zwrotów przychodzą jako liczby ujemne, a koszt zakupu, wysyłki, promowania i reklamy, koszty operacyjne i opłaty konta jako dodatnie. Dlatego nie licz marży od nowa, odejmując wszystkie te pola od przychodu, tylko weź pole margin_cents. Kwoty są brutto. Gdy Twoja firma jest czynnym podatnikiem VAT, Salecare pokazuje na ekranach kwoty netto, więc do raportu weź pola net_revenue_cents, net_purchase_cost_cents i net_margin_cents. Pole meta.money_basis podaje, które kwoty widzisz w Salecare, netto (net) czy brutto (gross).
Krok 5. Wymień albo unieważnij token
Każdy wydany token widzisz na liście na stronie ze statusem „Aktywny”, „Wygasły” albo „Unieważniony”. Gdy kończysz współpracę z narzędziem albo podejrzewasz, że token wyciekł, kliknij przy nim Unieważnij i potwierdź przyciskiem Unieważnij token. Token zostaje odrzucony natychmiast, a wszystkie integracje, które go używały, tracą dostęp. Wygasły token też możesz unieważnić, a lista pokaże go wtedy ze statusem „Unieważniony”.
Przed datą wygaśnięcia utwórz nowy token i podmień go w integracji, bo od 00:00 tego dnia każde zapytanie ze starym tokenem dostaje kod 401. Salecare nie przypomina o zbliżającym się wygaśnięciu, więc zapisz tę datę w swoim kalendarzu. Tokeny przestają też działać po przejściu na plan bez dostępu do API albo przy blokadzie konta za brak płatności i działają znowu, gdy dostęp wróci. Zapytanie z nagłówkami z tej sekcji dostaje w tym czasie kod 402.
Co dalej
Tokeny API są dostępne w planie Pro i wyższych. Swój plan sprawdzisz na stronie Plan i płatności według poradnika „Jak zarządzać planem i fakturami”. Zanim podepniesz BI, upewnij się, że marża w danych jest policzona z Twoimi kosztami. Pomoże w tym poradnik „Jak skonfigurować koszty i marżę, żeby widzieć realny zysk z Allegro”, który opisuje też, jak z marży powstaje zysk.