Przejdź do treści

Referencja API

Zdjęcia

Zdjęcia z adresu (Allegro) albo wgrane wprost do magazynu (podpisany adres PUT).

Zdjęcie z adresu

POST /sale/images

zgodna z Allegroallegro:api:sale:offers:writelimit: write

Ciało JSON {"url": "https://…"} — adres sprawdzamy od razu (SSRF: tylko publiczne https/http, porty 80/443), plik pobiera allee w tle.
Zwrócone location wpisz do images oferty. Plik binarny w treści → 415: użyj POST /allee/uploads (wgranie wprost do magazynu).

Zgodność: zgodna z Allegro REST API (ten sam kształt) — POST /sale/images.
Uprawnienie: zakres allegro:api:sale:offers:write.
Grupa limitu: write.

Nagłówki

Idempotency-Key string

Ochrona przed podwójnym wykonaniem (jak Stripe/Amazon): powtórzony POST z tym samym kluczem i tą samą treścią w ciągu 24 h zwraca zapisaną odpowiedź z nagłówkiem Idempotent-Replayed: true i niczego nie wykonuje drugi raz. Inna treść → 422 IDEMPOTENCY_KEY_REUSED; żądanie jeszcze trwa → 409 IDEMPOTENCY_KEY_IN_USE. 1–100 znaków ASCII (np. UUID).

Treść żądania application/vnd.allegro.public.v1+json

url string · uri wymagane

Publiczny adres zdjęcia.

Odpowiedzi

201 Przyjęto. · ImageUploaded
location string · uri zawsze

Adres zdjęcia do użycia w ofercie (images).

expiresAt string · date-time zawsze

Do kiedy adres trzeba użyć w ofercie.

Błędy

HTTPKodZnaczenie
401invalid_tokenBrak, zły, wygasły albo odwołany token lub klucz (format OAuth, nagłówek WWW-Authenticate).
403ACCOUNT_INACTIVEKonto sprzedawcy jest nieaktywne.
403AccessDeniedBrak zakresu albo zasób innego sprzedawcy.
403KEY_QUARANTINEDKwarantanna: działa tylko odczyt (wykryto nietypowe użycie).
403KEY_SUSPENDEDKlucz albo dostęp aplikacji wstrzymany (przez sprzedawcę albo ochronę).
413PAYLOAD_TOO_LARGETreść żądania za duża (JSON 5 MB, faktura PDF 3 MB).
415UNSUPPORTED_MEDIA_TYPEZły Content-Type treści.
422IMAGE_DOWNLOAD_FAILEDAdres zdjęcia niedozwolony albo nie da się go pobrać (path = które zdjęcie).
422JsonMappingExceptionTreść nie jest poprawnym JSON albo ma zły kształt (np. images jako obiekty).
422UnknownJSONPropertyPole nieznane w tym miejscu (path wskazuje które).
429TOO_MANY_REQUESTSPrzekroczony limit (minutowy, grupy operacji albo IP).
500INTERNAL_ERRORBłąd serwera allee.
Przykład
curl -sS -X POST "${ALLEE_API_URL:-https://api.allee.pl}/sale/images" \
  -H "Authorization: Bearer $ALLEE_API_KEY" \
  -H "Accept: application/vnd.allegro.public.v1+json" \
  -H "Content-Type: application/vnd.allegro.public.v1+json" \
  --data-binary @- \
  -w '\nHTTP %{http_code}\n' <<'JSON'
{
  "url": "https://cdn.allee.pl/img/a/webe/1930/10001318-0-1200.webp"
}
JSON
Odpowiedź (środowisko testowe)
HTTP 201 application/vnd.allegro.public.v1+json
{
  "location": "https://cdn.allee.pl/img/a/webe/1930/10001318-0-1200.webp",
  "expiresAt": "2026-11-17T11:10:04.000Z"
}

Miejsce wgrania zdjęcia (wprost do magazynu)

POST /allee/uploads

wzór Amazon SP-APIallegro:api:sale:offers:writelimit: bulk

Zwraca podpisany adres PUT (ważny 5 min). Wyślij tam plik wprost (serwer allee go nie dotyka) z nagłówkami z headers, potem użyj location w images oferty.

Typy: JPEG, PNG, WEBP; do 15 MB; najwyżej 600 miejsc na godzinę na sprzedawcę. W sandboxie → 403 SANDBOX_UNSUPPORTED (podawaj adresy URL).

Zgodność: wzorowana na Amazon Selling Partner API — Uploads — createUploadDestinationForResource.
Uprawnienie: zakres allegro:api:sale:offers:write.
Grupa limitu: bulk.

Nagłówki

Idempotency-Key string

Ochrona przed podwójnym wykonaniem (jak Stripe/Amazon): powtórzony POST z tym samym kluczem i tą samą treścią w ciągu 24 h zwraca zapisaną odpowiedź z nagłówkiem Idempotent-Replayed: true i niczego nie wykonuje drugi raz. Inna treść → 422 IDEMPOTENCY_KEY_REUSED; żądanie jeszcze trwa → 409 IDEMPOTENCY_KEY_IN_USE. 1–100 znaków ASCII (np. UUID).

Treść żądania application/vnd.allegro.public.v1+json

contentType string wymagane
Wartości: image/jpeg, image/png, image/webp
contentLength integer

Rozmiar pliku w bajtach (1–15 MB).

resource string
Wartości: OFFER_IMAGE

Odpowiedzi

201 Miejsce wgrania. · UploadDestination
uploadId string · uuid zawsze
method string zawsze
Wartości: PUT
url string · uri zawsze

Podpisany adres PUT do magazynu plików (ważny 5 min).

headers object zawsze

Nagłówki, które MUSISZ wysłać z PUT (Content-Type).

location string · uri zawsze

Adres zdjęcia po wgraniu — wpisz go do images oferty.

expiresAt string · date-time zawsze
maxBytes integer zawsze

Największy dozwolony rozmiar pliku.

Błędy

HTTPKodZnaczenie
401invalid_tokenBrak, zły, wygasły albo odwołany token lub klucz (format OAuth, nagłówek WWW-Authenticate).
403ACCOUNT_INACTIVEKonto sprzedawcy jest nieaktywne.
403AccessDeniedBrak zakresu albo zasób innego sprzedawcy.
403KEY_QUARANTINEDKwarantanna: działa tylko odczyt (wykryto nietypowe użycie).
403KEY_SUSPENDEDKlucz albo dostęp aplikacji wstrzymany (przez sprzedawcę albo ochronę).
403SANDBOX_UNSUPPORTEDOperacja niedostępna w sandboxie (pliki trafiałyby do magazynu produkcyjnego).
413PAYLOAD_TOO_LARGETreść żądania za duża (JSON 5 MB, faktura PDF 3 MB).
415UNSUPPORTED_MEDIA_TYPEZły Content-Type treści.
422JsonMappingExceptionTreść nie jest poprawnym JSON albo ma zły kształt (np. images jako obiekty).
422UnknownJSONPropertyPole nieznane w tym miejscu (path wskazuje które).
422VALIDATION_ERRORZła wartość parametru zapytania (400) albo pola treści (422); path wskazuje miejsce.
429TOO_MANY_REQUESTSPrzekroczony limit (minutowy, grupy operacji albo IP).
500INTERNAL_ERRORBłąd serwera allee.
503NOT_DEPLOYEDFunkcja jeszcze nie uruchomiona (np. sandbox, wsady).
503STORAGE_UNAVAILABLEMagazyn plików chwilowo niedostępny.
Miejsce wgrania zdjęcia wprost do magazynu (klucz produkcyjny — w sandboxie 403 SANDBOX_UNSUPPORTED)
curl -sS -X POST "${ALLEE_API_URL:-https://api.allee.pl}/allee/uploads" \
  -H "Authorization: Bearer $ALLEE_API_KEY" \
  -H "Accept: application/vnd.allegro.public.v1+json" \
  -H "Content-Type: application/vnd.allegro.public.v1+json" \
  --data-binary @- \
  -w '\nHTTP %{http_code}\n' <<'JSON'
{
  "contentType": "image/jpeg",
  "contentLength": 245760
}
JSON
Odpowiedź (środowisko testowe)
HTTP 201 application/vnd.allegro.public.v1+json
{
  "uploadId": "ffd13428-40ab-428a-bada-af4de043ce90",
  "method": "PUT",
  "url": "https://0e31a0c8a001f9f8df521110ca4f3f6e.r2.cloudflarestorage.com/allee/api/980000001/ffd13428-40ab-428a-bada-af4de043ce90.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=0136e1e8b4bd3d8e11870c33177d2879%2F20261110%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20261110T111004Z&X-Amz-Expires=300&X-Amz-SignedHeaders=content-type%3Bhost&X-Amz-Signature=…",
  "headers": {
    "Content-Type": "image/jpeg"
  },
  "location": "https://cdn.allee.pl/api/980000001/ffd13428-40ab-428a-bada-af4de043ce90.jpg",
  "expiresAt": "2026-11-10T11:15:04.000Z",
  "maxBytes": 245760
}