Przejdź do treści

Referencja API

OAuth

Autoryzacja aplikacji: Authorization Code + PKCE (S256), odświeżanie z rotacją, token aplikacji (client_credentials), odwołanie (RFC 7009). Zgodne z Allegro.

Autoryzacja: przekierowanie sprzedawcy

GET /auth/oauth/authorize

zgodna z Allegro

Adres, na który aplikacja kieruje przeglądarkę sprzedawcy (Authorization Code + PKCE, tylko S256). Poprawne żądanie → 302 na stronę zgody allee.pl; sprzedawca loguje się i klika „Zezwól” → 302 na redirect_uri?code=…&state=….

  • redirect_uri porównujemy 1:1 z zarejestrowanym (bajt w bajt).
  • Zły client_id, nieaktywna aplikacja albo obcy redirect_uri → strona błędu 400 bez przekierowania (ochrona przed otwartym przekierowaniem).
  • Błąd po potwierdzeniu redirect_uri → 302 redirect_uri?error=invalid_request|invalid_scope|unsupported_response_type&state=….
  • Zakresy: nazwy Allegro (allegro:api:…) albo allee (allee:api:…); nieznane są pomijane.

Zgodność: zgodna z Allegro REST API (ten sam kształt) — GET https://allegro.pl/auth/oauth/authorize.
Uwierzytelnienie: brak.

Parametry zapytania

response_type string wymagany

Zawsze code.

Wartości: code
client_id string wymagany

client_id aplikacji.

redirect_uri string · uri wymagany

Zarejestrowany adres powrotu.

state string

Wartość ochronna (CSRF) — wraca bez zmian.

code_challenge string wymagany

BASE64URL(SHA256(code_verifier)).

code_challenge_method string wymagany

Tylko S256.

Wartości: S256
scope string

Zakresy rozdzielone spacją.

Odpowiedzi

302 Przekierowanie na stronę zgody (albo na redirect_uri z błędem).

Błędy

HTTPKodZnaczenie
500INTERNAL_ERRORBłąd serwera allee.
Przykład
curl -sS -X GET "${ALLEE_API_URL:-https://api.allee.pl}/auth/oauth/authorize?response_type=code&client_id=36d6ed33acd3fc480a9270abe6421e9c&redirect_uri=https%3A%2F%2Fintegrator.example.com%2Fallee%2Fpowrot&state=st-7f3a9c&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256&scope=allegro%3Aapi%3Aprofile%3Aread%20allegro%3Aapi%3Asale%3Aoffers%3Aread%20allegro%3Aapi%3Asale%3Aoffers%3Awrite" \
  -H "Accept: text/html" \
  -w '\nHTTP %{http_code}\n'
Odpowiedź (środowisko testowe)
HTTP 302 text/html; charset=UTF-8
(0 B: text/html; charset=UTF-8)

Token: kod, odświeżenie, token aplikacji

POST /auth/oauth/token

Allegro + rozszerzenia

Wywołanie serwer–serwer. Uwierzytelnienie klienta: Authorization: Basic base64(client_id:client_secret). Ciało application/x-www-form-urlencoded.

grant_typepolawynik
authorization_codecode, redirect_uri, code_verifierpara tokenów (access 12 h, refresh 90 dni)
refresh_tokenrefresh_token, opcjonalnie scope (zawężenie)nowa para — stary refresh przestaje działać (rotacja; ponowne użycie poza 60-sekundowym oknem łaski odwołuje całą rodzinę tokenów)
client_credentials—token aplikacji bez sprzedawcy: tylko dane publiczne (kategorie, parametry, metody dostawy, przewoźnicy)

Kod autoryzacyjny jest jednorazowy (10 min) — nieudana wymiana też go zużywa. Odświeżaj pojedynczo i zapisuj nową parę atomowo. Błędy w formacie OAuth (error, error_description).

Zgodność: zgodna z Allegro REST API, z rozszerzeniami allee (pola allee.*, alleeId) — POST https://allegro.pl/auth/oauth/token.
Uwierzytelnienie: klient OAuth — Authorization: Basic base64(client_id:client_secret).

Treść żądania application/x-www-form-urlencoded

grant_type string wymagane
Wartości: authorization_code, refresh_token, client_credentials
code string
redirect_uri string
code_verifier string

43–128 znaków.

refresh_token string
scope string

Zawężenie zakresów przy odświeżaniu.

Odpowiedzi

200 Tokeny. · TokenResponse
access_token string zawsze

Token dostępu (12 h). Nowe aplikacje: allee_at_…

token_type string zawsze
Wartości: bearer
refresh_token string

Refresh token (90 dni, rotacja przy każdym użyciu). Brak przy client_credentials.

expires_in integer zawsze

Ważność access tokenu w sekundach (43200).

scope string zawsze

Przyznane zakresy rozdzielone spacją — zapisz je.

jti string
allee object

Błędy

HTTPKodZnaczenie
500INTERNAL_ERRORBłąd serwera allee.
Wymiana kodu autoryzacyjnego na tokeny (PKCE)
curl -sS -X POST "${ALLEE_API_URL:-https://api.allee.pl}/auth/oauth/token" \
  -u "$ALLEE_CLIENT_ID:$ALLEE_CLIENT_SECRET" \
  -H "Accept: application/json" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code={kod_z_przekierowania}" \
  --data-urlencode "redirect_uri=https://integrator.example.com/allee/powrot" \
  --data-urlencode "code_verifier={code_verifier}" \
  -w '\nHTTP %{http_code}\n'
Odpowiedź (środowisko testowe)
HTTP 200 application/json
{
  "access_token": "{access_token}",
  "token_type": "bearer",
  "refresh_token": "{refresh_token}",
  "expires_in": 43200,
  "scope": "allegro:api:profile:read allegro:api:sale:offers:read allegro:api:sale:offers:write"
}
Przykład: Odświeżenie tokenu (rotacja refresh tokenu)
curl -sS -X POST "${ALLEE_API_URL:-https://api.allee.pl}/auth/oauth/token" \
  -u "$ALLEE_CLIENT_ID:$ALLEE_CLIENT_SECRET" \
  -H "Accept: application/json" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token={refresh_token}" \
  -w '\nHTTP %{http_code}\n'
HTTP 200 application/json
{
  "access_token": "{access_token}",
  "token_type": "bearer",
  "refresh_token": "{refresh_token}",
  "expires_in": 43200,
  "scope": "allegro:api:profile:read allegro:api:sale:offers:read allegro:api:sale:offers:write"
}
Przykład: Token aplikacji (client_credentials) — tylko dane publiczne
curl -sS -X POST "${ALLEE_API_URL:-https://api.allee.pl}/auth/oauth/token" \
  -u "$ALLEE_CLIENT_ID:$ALLEE_CLIENT_SECRET" \
  -H "Accept: application/json" \
  --data-urlencode "grant_type=client_credentials" \
  -w '\nHTTP %{http_code}\n'
HTTP 200 application/json
{
  "access_token": "{access_token}",
  "token_type": "bearer",
  "expires_in": 43200,
  "scope": ""
}

Odwołanie tokenu

POST /auth/oauth/revoke

tylko allee

Odwołanie access albo refresh tokenu (refresh → cała rodzina tokenów pary). Zawsze 200 po poprawnym uwierzytelnieniu klienta — nie zdradzamy, czy token istniał ani czyj był.

Zgodność: tylko allee — RFC 7009 (Allegro: brak).
Uwierzytelnienie: klient OAuth — Authorization: Basic base64(client_id:client_secret).

Treść żądania application/x-www-form-urlencoded

token string wymagane

Token do odwołania.

token_type_hint string
Wartości: access_token, refresh_token

Odpowiedzi

200 Odwołano (albo nic do odwołania). · RevokeResponse
revoked boolean zawsze
Wartości: true

Błędy

HTTPKodZnaczenie
500INTERNAL_ERRORBłąd serwera allee.
Przykład
curl -sS -X POST "${ALLEE_API_URL:-https://api.allee.pl}/auth/oauth/revoke" \
  -u "$ALLEE_CLIENT_ID:$ALLEE_CLIENT_SECRET" \
  -H "Accept: application/json" \
  --data-urlencode "token={refresh_token}" \
  --data-urlencode "token_type_hint=refresh_token" \
  -w '\nHTTP %{http_code}\n'
Odpowiedź (środowisko testowe)
HTTP 200 application/json
{
  "revoked": true
}