Słowniczek

  • Aplikacja - to rozwiązanie techniczne napisane w oparciu o Allegro REST API. Jest udostępniane Klientom Końcowym pod postacią Instancji Aplikacji.

  • Instancja Aplikacji - to kopia Aplikacji, zainstalowana i używana przez określonego Klienta Końcowego, który na jej potrzeby generuje i posługuje się własnymi Danymi Dostępowymi.

  • Autor Aplikacji - to twórca kodu Aplikacji, który udostępnia ją Klientom Końcowym pod postacią Instancji Aplikacji.

  • Klient Końcowy - to osoba, która instaluje i jest użytkownikiem Instancji Aplikacji.

  • Szablon Aplikacji - to zbiór danych niezbędnych do działania DCR. Jest generowany przez Allegro na prośbę Autora Aplikacji i widoczny na liście Zarządzania aplikacjami Allegro.

  • Software statement ID - to identyfikator Aplikacji, który jest generowany w ramach Szablonu Aplikacji.

  • Dane Dostępowe - to wartości Client ID i Client Secret, wymagane do komunikacji z Allegro REST API. Są generowane przez Klienta Końcowego i przypisane do Instancji Aplikacji.

  • Jednorazowy Kod - to kod generowany przez Klienta Końcowego w procesie instalacji Instancji Aplikacji. Pozwala on wygenerować i przypisać Dane Dostępowe do konta Klienta Końcowego.

Dla kogo DCR?

Dynamic Client Registration (DCR) to proces rejestracji dla aplikacji sieciowych, które z uwagi na przyjęty model biznesowy funkcjonują na wielu serwerach i różnych domenach (np. niektóre platformy sklepowe). Implementacja DCR dla tego typu aplikacji zapewni spełnienie zalecenia Allegro: każda aplikacja powinna przedstawiać się pojedynczym identyfikatorem (w tym przypadku będzie to Software statement ID). Dodatkowo DCR pozwoli uprościć proces instalacji *Instancji Aplikacji* przez Klienta Końcowego. Klient nie będzie zmuszany do własnoręcznego generowania Danych Dostępowych. Jedyne co będzie musiał zrobić to przepisanie Jednorazowego Kodu w odpowiednie miejsce w procesie instalacji aplikacji, a dynamicznym wygenerowaniem niezbędnych danych zajmie się już Instancja Aplikacji.

DCR w Allegro - jak to przebiega?

Wymagania początkowe

Aby wygenerować nowe Client ID i Client Secret w procesie DCR spełnione muszą być następujące warunki:

  1. Klient Końcowy posiada konto na Allegro

  2. Autor Aplikacji  posiada wygenerowany przez Allegro Szablon Aplikacji (można to sprawdzić na liście Zarządzania aplikacjami Allegro).

Software statement ID w Developer Apps

Uzyskiwanie Jednorazowego Kodu przez Klienta Końcowego

Aby wygenerować nowe Dane Dostępowe konieczne jest podanie Jednorazowego Kodu przez Klienta Końcowego. Pozwoli to powiązać te Dane Dostępowe z konkretną Instancją Aplikacji.

Klient Końcowy, chcąc uzyskać kod, musi wejść na stronę https://allegro.pl/uzytkownik/bezpieczenstwo/wygeneruj-kod.

Generowanie kodu przez Klienta Końcowego

Tam, po zapoznaniu się i akceptacji regulaminów API, Klient Końcowy ma możliwość własnoręcznego wygenerowania kodu. Kod jest ważny 2 minuty od momentu wygenerowania i tyle też czasu ma Klient końcowy na wprowadzenie kodu w przeznaczone do tego miejsce w procesie instalacji Instancji Aplikacji. Jeżeli termin ważności kodu minie, należy wygenerować nowy kod, ponawiając cały proces.

Wygenerowany kod

Generowanie nowych Danych Dostępowych

Autor Aplikacji razem z Instancją Aplikacji dystrybuuje Software statement ID  (które może znaleźć na liście Zarządzania aplikacjami Allegro).

Ta informacja jest “zaszyta” w kodzie Aplikacji i pozwala na skonstruowanie żądania o nowe Dane dostępowe:

    POST https://api.allegro.pl/register
    Content-Type: application/json

    {
    	"code":"NMCAHLRPK",
    	"client_name":"Instalacja aplikacji X dla moj.sklep.com",
    	"redirect_uris":["https://nazwa.mojego.sklepu.com/AllegroCallbackUrl.php"],
    	"software_statement_id":"3b8cacc7-eeec-42f9-9f7f-f35090c3d616"
    }
gdzie:

  • code - Jednorazowy Kod uzyskany przez Klienta Końcowego wg instrukcji w sekcji Uzyskiwanie kodu, o który Instancja Aplikacji powinna poprosić w trakcie instalacji.

  • client_name - nazwa Instancji Aplikacji. Musi być unikatowa, może zawierać od 3 do 50 znaków i nie będzie można jej zmienić. Wypełniana przez Klienta Końcowego lub automatycznie uzupełniana przez Instancję Aplikacji w trakcie instalacji. Jest to nazwa, którą będą widzieli użytkownicy, udzielając zgody na dostęp Instancji Aplikacji do swojego konta Allegro.

  • redirect_uris - adresy przekierowań dedykowane Instancji Aplikacji. Wypełniane przez Klienta Końcowego lub automatycznie uzupełniane przez Instancję Aplikacji w trakcie instalacji. Aby ułatwić instalację sugerujemy pozostawienie Klientowi Końcowemu podanie tylko domeny, na którą będą realizowane przekierowania, a doklejanie ścieżki automatycznie przez proces instalacji.

  • software_statement_id - Software statement ID zaszyty w kodzie przez Autora Aplikacji i wiążący tę Instancję Aplikacji z Aplikacją.

Odpowiedź na to żądanie ma następującą postać:

    201 Created
    Content-Type: application/json

    {
        "client_id": "17a747e9b9f74f428ad0203a245e7373",
        "client_secret": "edSDERFsx43dSDJKFDKFJDKLSFJ4dsdsjdkIRIKJFDSSdsdsSDDEWRRRWRd223dsd",
        "client_id_issued_at": 1576225617,
        "client_secret_expires_at": 0,
        "redirect_uris": [
            "https://nazwa.mojego.sklepu.com/AllegroCallbackUrl.php"
        ],
        "grant_types": [
            "authorization_code",
            "implicit",
            "refresh_token",
            "client_credentials"
        ],
        "client_name": "Instalacja aplikacji X dla moj.sklep.com",
        "software_statement_id": "3b8cacc7-eeec-42f9-9f7f-f35090c3d616"
    }
gdzie:

  • client_idclient_secret to Dane Dostępowe wymagane do autoryzacji użytkownika, które Instancja Aplikacji powinna zachować i wykorzystywać podczas komunikacji z Allegro REST API.

  • client_name to podana w żądaniu nazwa Instancji Aplikacji.

  • software_statement_id to podane w żądaniu Software statement ID.

  • pozostałe pola odpowiedzi są zgodne z dokumentacją Dynamic Client Registration i tam zostały opisane.

information

Instancja Aplikacji powinna zachować wygenerowane Dane Dostępowe i używać ich w komunikacji z Allegro REST API. Client Secret nie będzie widoczny dla Klienta Końcowego na liście Zarządzania aplikacjami Allegro.

W przypadku błędu zostanie zwrócony kod HTTP oraz ciało odpowiedzi zgodne ze specyfikacją struktury błędu w Allegro REST API. Przykładowe błędy, które mogą wystąpić podczas generowania Danych Dostępowych:

  1. podano nieprawidłowy lub wygasły Jednorazowy Kod (kod HTTP 403) - Niepoprawny kod dostępu. Wygeneruj nowy kod i spróbuj ponownie.

  2. nazwa aplikacji nie jest unikalna (kod HTTP 422) - Nazwa aplikacji jest już wykorzystywana - podaj inną. Uwaga, po wystąpieniu błędu należy ponownie wygenerować Jednorazowy Kod.