Klucze dostępowe do API Admin

Klucze dostępowe do API Admin umożliwiają aplikacjom zewnętrznym bezpieczną komunikację z panelem administracyjnym IdoSell. Dzięki nim możesz pobierać dane, modyfikować zasoby oraz korzystać z funkcji API zgodnie z nadanymi uprawnieniami. System udostępnia dwa sposoby autoryzacji dostępu do API: za pomocą klucza API lub tokena OAuth 2.0. Wybór metody zależy od wymagań aplikacji oraz sposobu integracji.

Prawidłowa konfiguracja klucza dostępowego jest istotna dla bezpieczeństwa danych. Każda aplikacja korzystająca z API powinna posiadać własny klucz oraz odpowiednio skonfigurowane uprawnienia.

• Jak utworzyć klucz dostępu do API,

• Jakie metody autoryzacji są dostępne,

• Jak korzystać z klucza API,

• Jak działa autoryzacja OAuth 2.0,

• Czy posiadasz uprawnienia Szef?

• Czy wiesz, która aplikacja będzie korzystać z API?

• Czy znasz wymagania dotyczące autoryzacji wybranej integracji?

Klucze dostępowe zarządzane są bezpośrednio z poziomu panelu administracyjnego. Po ich utworzeniu możesz wykorzystać je do wykonywania operacji zgodnych z przyznanymi uprawnieniami.

1. Przejdź do: USTAWIENIA > Dostęp.

2. Dodaj nowy klucz.

3. Wybierz sposób autoryzacji.

4. Wprowadź nazwę aplikacji, która będzie korzystać z klucza.

5. Opcjonalnie uzupełnij adres e-mail w razie potrzeby kontaktu.

6. Możesz ograniczyć hosty, z których można się logować.

7. Wypełnij informacje dotyczące lokalizacji.

8. Nadaj wymagane uprawnienia do poszczególnych bramek API. Dla każdej bramki określ zakres dostępu odpowiedni do operacji wykonywanych przez aplikację:

• System - pobieranie i aktualizowanie informacji o konfiguracji panelu IdoSell oraz sklepów.

• CMS - pobieranie, dodawanie i aktualizowanie informacji o zasobach systemu zarządzania treścią, np. wpisach na blogu i aktualnościach.

• CRM - pobieranie, dodawanie i aktualizowanie informacji o klientach.

• PIM - pobieranie, dodawanie i aktualizowanie informacji o towarach.

• OMS - pobieranie, dodawanie i aktualizowanie informacji o zamówieniach, zwrotach, reklamacjach oraz subskrypcjach.

• WMS - pobieranie, dodawanie i aktualizowanie informacji o magazynach oraz dokumentach magazynowych.

Dla każdej bramki wybierz jeden z trzech trybów uprawnień:

• brak dostępu - aplikacja nie ma dostępu do danej bramki,

• tylko odczyt - aplikacja może wyłącznie odczytywać dane,

• odczyt i zapis - aplikacja może odczytywać, dodawać i aktualizować dane.

9. Dodaj klucz.

10. Po dodaniu klucza pojawi się wiersz Klucz API. Za pomocą przycisku „Pokaż aktywne klucze” odkryjesz Klucz API oraz Nagłówek HTTP.

11. W tym miejscu możesz również dezaktywować klucz.

• Język - określa język odpowiedzi zwracanych przez API oraz tłumaczeń komunikatów. Jeśli komunikat źródłowy brzmi „Nie odnaleziono takiego towaru”, a dla klucza ustawisz język angielski, API może zwrócić komunikat „Product not found”.

• Format liczb, kwot i dat - ustawienia lokalizacji wpływają również na sposób prezentowania tych wartości w odpowiedziach API.

• Główny język edycji elementów w panelu - jest używany domyślnie, jeśli w żądaniu nie wskażesz innego języka.

• Strefa czasowa - wpływa na zapis czasu zdarzeń. Panel przelicza go po stronie interfejsu zgodnie ze strefą czasową aktualnie zalogowanego użytkownika. Jeśli aplikacja korzystająca z API ma ustawioną strefę UTC−6, zdarzenie zostanie zapisane z takim przesunięciem, a użytkownik korzystający z polskiej strefy czasowej zobaczy odpowiednio przeliczony czas.

• Hosty - ograniczenie dostępu do wskazanych hostów zwiększa bezpieczeństwo klucza API. Z kluczem połączy się wyłącznie dozwolony host. Żądanie wysłane z innego hosta zostanie odrzucone, a API zwróci błąd 403 Unauthorized Access.

Klucz API jest najprostszą metodą autoryzacji. Po wygenerowaniu należy przekazać go w nagłówku żądania jako wartość pola X-API-KEY. Każda aplikacja powinna korzystać z własnego klucza dostępowego. Ułatwia to zarządzanie uprawnieniami oraz zwiększa bezpieczeństwo integracji.

headers: {
  'X-API-KEY': 'YXBwbGlhY3Rpb24xOmFkbWluMTIzNA=='
}

OAuth 2.0 umożliwia korzystanie z tokenów dostępowych generowanych przez AUTHORIZE API. Rozwiązanie to wymaga dodatkowej autoryzacji przed uzyskaniem tokena Bearer. Aby skonfigurować Token OAuth 2.0:

1. Przejdź do: USTAWIENIA > Dostęp.

2. Dodaj nowy klucz API.

3. W metodzie autoryzacji wybierz OAuth 2.0.

4. Uzupełnij niezbędne informacje zgodnie z instrukcją z sekcji „Dodawanie klucza dostępu do Admin API”.

5. Przed dodaniem klucza zapamiętaj lub zapisz automatycznie wygenerowane hasło.

6. Username zostanie wygenerowane po dodaniu klucza.

7. W konfigurowanej aplikacji wywołaj endpoint authorize/accessToken udostępniony w AUTHORIZE API.

8. Podaj dane uwierzytelniające przypisane do klucza.

9. Odbierz token Bearer.

10. Użyj tokena podczas wywołań API Admin.

headers: {
  authorization: 'Basic YXBwbGlhY3Rpb24xOmFkbWluMTIzNA=='
}

{ 
  "scope": [
    "admin"
  ]
}

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciO"
}

headers: {
  authorization: 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciO'
}

Jedną z zewnętrznych aplikacji, którą można połączyć ze sklepem IdoSell za pomocą API, jest base.com. Na jej przykładzie pokazujemy podstawowy przebieg integracji z wykorzystaniem klucza API. Aby połączyć sklep z base.com, wygeneruj klucz API zgodnie z instrukcją opisaną w tym artykule. Następnie skopiuj wygenerowany klucz i wprowadź go w konfiguracji zewnętrznej aplikacji, zgodnie z wymaganiami dostawcy integracji.

Rezultat

Zewnętrzna aplikacja może wykonywać operacje na danych sklepu zgodnie z zakresem przyznanych uprawnień. Dzięki wykorzystaniu osobnego klucza łatwiej zarządzać bezpieczeństwem oraz identyfikować integracje korzystające z API.

Dalsza konfiguracja przebiega po stronie zewnętrznej aplikacji. Informacja, co zrobić dalej na base.com znajduje się tutaj .