Przejdź do treści

Wyszukiwanie listingów

GET /allee/listings

wzór Amazon SP-APIallegro:api:sale:offers:readlimit: read

Oferty z SKU, filtrowane po SKU, statusie i problemach (np. wszystkie z błędami: issueSeverity=ERROR).

Zgodność: wzorowana na Amazon Selling Partner API — Listings Items — searchListingsItems.
Uprawnienie: zakres allegro:api:sale:offers:read.
Grupa limitu: read.

Parametry zapytania

skus string

SKU rozdzielone przecinkiem (do 100).

status string

Statusy publikacji rozdzielone przecinkiem (INACTIVE, ACTIVATING, ACTIVE, ENDED).

issueSeverity string

ERROR i/lub WARNING — tylko listingi z takimi problemami.

includedData string

Sekcje rozdzielone przecinkiem: summaries, attributes, issues, offers, fulfillmentAvailability.

pageSize integer

1–100.

pageToken string

Token następnej strony (pagination.nextToken).

Odpowiedzi

200 Listingi. · ListingSearchResult
numberOfResults integer zawsze
pagination object zawsze
Pola obiektu
nextToken string · null zawsze

Token następnej strony (parametr pageToken).

items array<ListingItem> zawsze
Pola obiektu
sku string zawsze
summaries array<ListingSummary>
Pola obiektu
marketplaceId string zawsze
Wartości: allee-pl
offerId string zawsze
category CategoryRef zawsze

Kategoria — oba identyfikatory.

Pola obiektu
id string · null zawsze

Identyfikator kategorii Allegro (bywa liczbą, bywa UUID).

alleeId integer zawsze

Identyfikator kategorii allee.

status array<string> zawsze

BUYABLE = da się kupić; DISCOVERABLE = widoczna.

Wartości: BUYABLE, DISCOVERABLE
publicationStatus PublicationStatus zawsze

INACTIVE = szkic, ACTIVATING = czeka na zdjęcia, ACTIVE = widoczna i kupowalna, ENDED = zakończona.

Wartości: INACTIVE, ACTIVATING, ACTIVE, ENDED
itemName string zawsze
conditionType string · null zawsze

Stan (nazwy Amazona).

Wartości: new_new, used_good, refurbished_refurbished, used_acceptable, null
createdDate string · date-time zawsze
lastUpdatedDate string · date-time zawsze
mainImage object · null zawsze
Pola obiektu
link string · uri zawsze
url string · uri zawsze
attributes ListingAttributes

Atrybuty listingu (płaskie, nazwy jak w schemacie kategorii GET /allee/categories/{id}/schema).

Pola obiektu
name string

Tytuł (10–75 znaków).

category object

Kategoria (alleeId ma pierwszeństwo).

Pola obiektu
alleeId integer
id string
parameters object

Parametry: klucz = id parametru Allegro (patrz schemat kategorii).

images array<string · uri>

1–16 adresów.

description string

Opis (tekst, 20–20 000 znaków).

price MoneyInput

Kwota w żądaniu.

Pola obiektu
amount string|number zawsze

Kwota jako tekst „123.45” (zalecane) albo liczba.

currency string

Waluta: tylko PLN (domyślnie PLN).

Wartości: PLN
stock integer

Sztuki (0–99 999).

ean string

GTIN (EAN).

shippingRatesId string · uuid

Twój cennik.

handlingTime string

PT0S, PT24H, P2D…P60D.

returnPolicyId string · null
warrantyId string · null
impliedWarrantyId string · null
responsibleProducerId string · null
responsiblePersonId string · null
safetyInformation SafetyInformation · null
Pola obiektu
type string zawsze
Wartości: TEXT, NO_SAFETY_INFORMATION, ATTACHMENTS
description string

Treść informacji (dla TEXT).

taxRate string · null
Wartości: 0.00, 5.00, 8.00, 23.00, null
invoice string · null
Wartości: VAT, VAT_MARGIN, WITHOUT_VAT, NO_INVOICE, null
location object · null
issues array<ListingIssue>
Pola obiektu
code string zawsze

Kod problemu (ten sam słownik co błędy walidacji oferty).

message string zawsze
severity string zawsze

ERROR blokuje zapis/publikację, WARNING nie blokuje.

Wartości: ERROR, WARNING, INFO
attributeNames array<string> zawsze

Atrybuty, których dotyczy problem.

categories array<string> zawsze

Grupy problemu, np. MISSING_ATTRIBUTE, INVALID_ATTRIBUTE, GPSR.

path string · null

Pole w kształcie Allegro (np. productSet[0].product.parameters).

messageId integer

Numer komunikatu wsadu (tylko w raporcie wsadu).

offers array<object>
Pola obiektu
marketplaceId string zawsze
Wartości: allee-pl
offerType string zawsze
Wartości: B2C
price Money zawsze

Kwota (kształt Allegro).

Pola obiektu
amount string zawsze

Kwota z dwoma miejscami po przecinku, kropka dziesiętna.

currency string zawsze

Waluta (allee.pl: tylko PLN).

Wartości: PLN
sellingFormat string zawsze
Wartości: BUY_NOW, AUCTION
fulfillmentAvailability array<object>
Pola obiektu
fulfillmentChannelCode string zawsze
Wartości: DEFAULT
quantity integer zawsze
handlingTime string · null zawsze

Błędy

HTTPKodZnaczenie
400VALIDATION_ERRORZła wartość parametru zapytania (400) albo pola treści (422); path wskazuje miejsce.
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ę).
429TOO_MANY_REQUESTSPrzekroczony limit (minutowy, grupy operacji albo IP).
500INTERNAL_ERRORBłąd serwera allee.
Przykład
curl -sS -X GET "${ALLEE_API_URL:-https://api.allee.pl}/allee/listings?skus=FILM-21ef85-1%2CFILM-21ef85-3&includedData=summaries%2Cissues&pageSize=20" \
  -H "Authorization: Bearer $ALLEE_API_KEY" \
  -H "Accept: application/vnd.allegro.public.v1+json" \
  -w '\nHTTP %{http_code}\n'
Odpowiedź (środowisko testowe)
HTTP 200 application/vnd.allegro.public.v1+json
{
  "numberOfResults": 2,
  "pagination": {
    "nextToken": null
  },
  "items": [
    {
      "sku": "FILM-21ef85-1",
      "summaries": [
        {
          "marketplaceId": "allee-pl",
          "offerId": "900000000000021",
          "category": {
            "alleeId": 35,
            "id": "20585"
          },
          "status": [
            "DISCOVERABLE",
            "BUYABLE"
          ],
          "publicationStatus": "ACTIVE",
          "itemName": "Podróż na Księżyc DVD wydanie kolekcjonerskie",
          "conditionType": "new_new",
          "createdDate": "2026-11-10T11:10:03.000Z",
          "lastUpdatedDate": "2026-11-10T11:10:04.000Z",
          "mainImage": {
            "link": "https://cdn.allee.pl/img/sandbox/9a16623650ab051ba0d7-1200.webp"
          },
          "url": "https://allee.pl/oferta/podroz-na-ksiezyc-dvd-wydanie-kolekcjonerskie-900000000000021"
        }
      ],
      "issues": []
    },
    {
      "sku": "FILM-21ef85-3",
      "summaries": [
        {
          "marketplaceId": "allee-pl",
          "offerId": "900000000000024",
          "category": {
            "alleeId": 35,
            "id": "20585"
          },
          "status": [
            "DISCOVERABLE",
            "BUYABLE"
          ],
          "publicationStatus": "ACTIVE",
          "itemName": "Metropolis DVD wersja odrestaurowana",
          "conditionType": "new_new",
          "createdDate": "2026-11-10T11:10:04.000Z",
          "lastUpdatedDate": "2026-11-10T11:10:04.000Z",
          "mainImage": {
            "link": "https://cdn.allee.pl/img/sandbox/9a16623650ab051ba0d7-1200.webp"
          },
          "url": "https://allee.pl/oferta/metropolis-dvd-wersja-odrestaurowana-900000000000024"
        }
      ],
      "issues": []
    }
  ]
}

Listing po SKU

GET /allee/listings/{sku}

wzór Amazon SP-APIallegro:api:sale:offers:readlimit: read

Oferta po SKU w wybranych sekcjach. issues = problemy liczone z tych samych reguł co walidacja i panel Jakość.

Zgodność: wzorowana na Amazon Selling Partner API — Listings Items — getListingsItem.
Uprawnienie: zakres allegro:api:sale:offers:read.
Grupa limitu: read.

Parametry ścieżki

sku string wymagany

SKU (external.id): 1–100 znaków, bez „/” i znaków sterujących. W adresie zakoduj (np. spacja → %20).

Parametry zapytania

includedData string

Sekcje rozdzielone przecinkiem: summaries, attributes, issues, offers, fulfillmentAvailability.

Odpowiedzi

200 Listing. · ListingItem
sku string zawsze
summaries array<ListingSummary>
Pola obiektu
marketplaceId string zawsze
Wartości: allee-pl
offerId string zawsze
category CategoryRef zawsze

Kategoria — oba identyfikatory.

Pola obiektu
id string · null zawsze

Identyfikator kategorii Allegro (bywa liczbą, bywa UUID).

alleeId integer zawsze

Identyfikator kategorii allee.

status array<string> zawsze

BUYABLE = da się kupić; DISCOVERABLE = widoczna.

Wartości: BUYABLE, DISCOVERABLE
publicationStatus PublicationStatus zawsze

INACTIVE = szkic, ACTIVATING = czeka na zdjęcia, ACTIVE = widoczna i kupowalna, ENDED = zakończona.

Wartości: INACTIVE, ACTIVATING, ACTIVE, ENDED
itemName string zawsze
conditionType string · null zawsze

Stan (nazwy Amazona).

Wartości: new_new, used_good, refurbished_refurbished, used_acceptable, null
createdDate string · date-time zawsze
lastUpdatedDate string · date-time zawsze
mainImage object · null zawsze
Pola obiektu
link string · uri zawsze
url string · uri zawsze
attributes ListingAttributes

Atrybuty listingu (płaskie, nazwy jak w schemacie kategorii GET /allee/categories/{id}/schema).

Pola obiektu
name string

Tytuł (10–75 znaków).

category object

Kategoria (alleeId ma pierwszeństwo).

Pola obiektu
alleeId integer
id string
parameters object

Parametry: klucz = id parametru Allegro (patrz schemat kategorii).

images array<string · uri>

1–16 adresów.

description string

Opis (tekst, 20–20 000 znaków).

price MoneyInput

Kwota w żądaniu.

Pola obiektu
amount string|number zawsze

Kwota jako tekst „123.45” (zalecane) albo liczba.

currency string

Waluta: tylko PLN (domyślnie PLN).

Wartości: PLN
stock integer

Sztuki (0–99 999).

ean string

GTIN (EAN).

shippingRatesId string · uuid

Twój cennik.

handlingTime string

PT0S, PT24H, P2D…P60D.

returnPolicyId string · null
warrantyId string · null
impliedWarrantyId string · null
responsibleProducerId string · null
responsiblePersonId string · null
safetyInformation SafetyInformation · null
Pola obiektu
type string zawsze
Wartości: TEXT, NO_SAFETY_INFORMATION, ATTACHMENTS
description string

Treść informacji (dla TEXT).

taxRate string · null
Wartości: 0.00, 5.00, 8.00, 23.00, null
invoice string · null
Wartości: VAT, VAT_MARGIN, WITHOUT_VAT, NO_INVOICE, null
location object · null
issues array<ListingIssue>
Pola obiektu
code string zawsze

Kod problemu (ten sam słownik co błędy walidacji oferty).

message string zawsze
severity string zawsze

ERROR blokuje zapis/publikację, WARNING nie blokuje.

Wartości: ERROR, WARNING, INFO
attributeNames array<string> zawsze

Atrybuty, których dotyczy problem.

categories array<string> zawsze

Grupy problemu, np. MISSING_ATTRIBUTE, INVALID_ATTRIBUTE, GPSR.

path string · null

Pole w kształcie Allegro (np. productSet[0].product.parameters).

messageId integer

Numer komunikatu wsadu (tylko w raporcie wsadu).

offers array<object>
Pola obiektu
marketplaceId string zawsze
Wartości: allee-pl
offerType string zawsze
Wartości: B2C
price Money zawsze

Kwota (kształt Allegro).

Pola obiektu
amount string zawsze

Kwota z dwoma miejscami po przecinku, kropka dziesiętna.

currency string zawsze

Waluta (allee.pl: tylko PLN).

Wartości: PLN
sellingFormat string zawsze
Wartości: BUY_NOW, AUCTION
fulfillmentAvailability array<object>
Pola obiektu
fulfillmentChannelCode string zawsze
Wartości: DEFAULT
quantity integer zawsze
handlingTime string · null zawsze

Błędy

HTTPKodZnaczenie
400VALIDATION_ERRORZła wartość parametru zapytania (400) albo pola treści (422); path wskazuje miejsce.
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ę).
404NOT_FOUNDNie ma takiego zasobu (albo należy do innego sprzedawcy — dla wątków, zwrotów i spraw odpowiedź jest ta sama).
429TOO_MANY_REQUESTSPrzekroczony limit (minutowy, grupy operacji albo IP).
500INTERNAL_ERRORBłąd serwera allee.
Przykład
curl -sS -X GET "${ALLEE_API_URL:-https://api.allee.pl}/allee/listings/FILM-21ef85-3?includedData=summaries%2Cattributes%2Cissues%2Coffers%2CfulfillmentAvailability" \
  -H "Authorization: Bearer $ALLEE_API_KEY" \
  -H "Accept: application/vnd.allegro.public.v1+json" \
  -w '\nHTTP %{http_code}\n'
Odpowiedź (środowisko testowe)
HTTP 200 application/vnd.allegro.public.v1+json
{
  "sku": "FILM-21ef85-3",
  "summaries": [
    {
      "marketplaceId": "allee-pl",
      "offerId": "900000000000024",
      "category": {
        "alleeId": 35,
        "id": "20585"
      },
      "status": [
        "DISCOVERABLE",
        "BUYABLE"
      ],
      "publicationStatus": "ACTIVE",
      "itemName": "Metropolis DVD wersja odrestaurowana",
      "conditionType": "new_new",
      "createdDate": "2026-11-10T11:10:04.000Z",
      "lastUpdatedDate": "2026-11-10T11:10:04.000Z",
      "mainImage": {
        "link": "https://cdn.allee.pl/img/sandbox/9a16623650ab051ba0d7-1200.webp"
      },
      "url": "https://allee.pl/oferta/metropolis-dvd-wersja-odrestaurowana-900000000000024"
    }
  ],
  "attributes": {
    "name": "Metropolis DVD wersja odrestaurowana",
    "category": {
      "alleeId": 35,
      "id": "20585"
    },
    "parameters": {
      "246845": {
        "valuesIds": [
          "246845_622165"
        ]
      },
      "250077": {
        "valuesIds": [
          "250077_1797493"
        ]
      },
      "225693": {
        "values": [
          "5901234123464"
        ]
      },
      "237218": {
        "values": [
          "Metropolis"
        ]
      },
      "11323": {
        "valuesIds": [
          "11323_1"
        ]
      }
    },
    "images": [
      "https://cdn.allee.pl/img/a/webe/1930/10001318-0-1200.webp"
    ],
    "description": "Film na płycie DVD, nowy w folii. Wersja z polskimi napisami.",
    "price": {
      "amount": "59.90",
      "currency": "PLN"
    },
    "stock": 4,
    "shippingRatesId": "797d2e65-cb23-4a16-98e9-d6f2a399839a",
    "responsibleProducerId": "472bad66-e704-4344-a2d6-9bd85b1f9a5e",
    "safetyInformation": {
      "type": "TEXT",
      "description": "Produkt bezpieczny w normalnym użytkowaniu."
    }
  },
  "issues": [],
  "offers": [
    {
      "marketplaceId": "allee-pl",
      "offerType": "B2C",
      "price": {
        "amount": "59.90",
        "currency": "PLN"
      },
      "sellingFormat": "BUY_NOW"
    }
  ],
  "fulfillmentAvailability": [
    {
      "fulfillmentChannelCode": "DEFAULT",
      "quantity": 4,
      "handlingTime": null
    }
  ]
}

Utworzenie albo zastąpienie oferty po SKU

PUT /allee/listings/{sku}

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

Idempotentne po SKU: brak oferty → tworzy (201), jest → zastępuje (200, change: UPDATED albo UNCHANGED). Atrybuty płaskie, nazwy jak w schemacie kategorii.

Błędy nie przerywają w połowie: odpowiedź 422 ma status: INVALID, pełną listę issues[] (kod, ważność, atrybuty) i te same błędy w kształcie Allegro (errors[]). Z ?mode=VALIDATION_PREVIEW nic nie zapisujemy — sprawdzasz dokument przed wysłaniem.

Zgodność: wzorowana na Amazon Selling Partner API — Listings Items — putListingsItem.
Uprawnienie: zakres allegro:api:sale:offers:write.
Grupa limitu: write.

Parametry ścieżki

sku string wymagany

SKU (external.id): 1–100 znaków, bez „/” i znaków sterujących. W adresie zakoduj (np. spacja → %20).

Parametry zapytania

mode string

VALIDATION_PREVIEW = pełna walidacja bez zapisu (odpowiedź 200, status VALID/INVALID).

Wartości: VALIDATION_PREVIEW

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

requirements string

LISTING (domyślnie) = pełna oferta; LISTING_OFFER_ONLY = tylko cena, stan, dostawa… istniejącego SKU.

Wartości: LISTING, LISTING_OFFER_ONLY
status string

ACTIVE = publikuj (wymaga GPSR), INACTIVE = szkic.

Wartości: ACTIVE, INACTIVE
attributes ListingAttributes wymagane

Atrybuty listingu (płaskie, nazwy jak w schemacie kategorii GET /allee/categories/{id}/schema).

Pola obiektu
name string

Tytuł (10–75 znaków).

category object

Kategoria (alleeId ma pierwszeństwo).

Pola obiektu
alleeId integer
id string
parameters object

Parametry: klucz = id parametru Allegro (patrz schemat kategorii).

images array<string · uri>

1–16 adresów.

description string

Opis (tekst, 20–20 000 znaków).

price MoneyInput

Kwota w żądaniu.

Pola obiektu
amount string|number wymagane

Kwota jako tekst „123.45” (zalecane) albo liczba.

currency string

Waluta: tylko PLN (domyślnie PLN).

Wartości: PLN
stock integer

Sztuki (0–99 999).

ean string

GTIN (EAN).

shippingRatesId string · uuid

Twój cennik.

handlingTime string

PT0S, PT24H, P2D…P60D.

returnPolicyId string · null
warrantyId string · null
impliedWarrantyId string · null
responsibleProducerId string · null
responsiblePersonId string · null
safetyInformation SafetyInformation · null
Pola obiektu
type string wymagane
Wartości: TEXT, NO_SAFETY_INFORMATION, ATTACHMENTS
description string

Treść informacji (dla TEXT).

taxRate string · null
Wartości: 0.00, 5.00, 8.00, 23.00, null
invoice string · null
Wartości: VAT, VAT_MARGIN, WITHOUT_VAT, NO_INVOICE, null
location object · null
productType string

Przyjmowane bez skutku (zgodność z klientami Amazon).

marketplaceIds array<string>

Bez skutku.

issueLocale string

Bez skutku.

Odpowiedzi

200 Zastąpiono / bez zmian / podgląd. · ListingSubmissionResponse
sku string zawsze
status string zawsze

ACCEPTED = zapisano; VALID = podgląd poprawny (nic nie zapisano); INVALID = błędy (nic nie zapisano).

Wartości: ACCEPTED, INVALID, VALID
submissionId string zawsze

Identyfikator zgłoszenia (= X-Request-Id).

offerId string · null zawsze
change string · null zawsze

Co się stało z ofertą.

Wartości: CREATED, UPDATED, UNCHANGED, DELETED, ENDED, null
publicationStatus PublicationStatus · null zawsze
issues array<ListingIssue> zawsze
Pola obiektu
code string zawsze

Kod problemu (ten sam słownik co błędy walidacji oferty).

message string zawsze
severity string zawsze

ERROR blokuje zapis/publikację, WARNING nie blokuje.

Wartości: ERROR, WARNING, INFO
attributeNames array<string> zawsze

Atrybuty, których dotyczy problem.

categories array<string> zawsze

Grupy problemu, np. MISSING_ATTRIBUTE, INVALID_ATTRIBUTE, GPSR.

path string · null

Pole w kształcie Allegro (np. productSet[0].product.parameters).

messageId integer

Numer komunikatu wsadu (tylko w raporcie wsadu).

errors array<Error>

Przy INVALID: te same problemy w kształcie Allegro.

Pola obiektu
code string zawsze

Kod maszynowy błędu — na nim opieraj obsługę (lista: przewodnik „Błędy”).

message string zawsze

Opis dla programisty (po polsku).

details any zawsze

Dane dodatkowe albo null — np. id istniejącej oferty przy OfferDuplicate, {"current": "SENT"} przy błędzie statusu, {"retryAfterMs": 1200} przy limicie.

path string · null zawsze

Pole żądania, którego dotyczy błąd, np. productSet[0].product.parameters.

userMessage string zawsze

Komunikat, który można pokazać sprzedawcy.

201 Utworzono. · ListingSubmissionResponse
sku string zawsze
status string zawsze

ACCEPTED = zapisano; VALID = podgląd poprawny (nic nie zapisano); INVALID = błędy (nic nie zapisano).

Wartości: ACCEPTED, INVALID, VALID
submissionId string zawsze

Identyfikator zgłoszenia (= X-Request-Id).

offerId string · null zawsze
change string · null zawsze

Co się stało z ofertą.

Wartości: CREATED, UPDATED, UNCHANGED, DELETED, ENDED, null
publicationStatus PublicationStatus · null zawsze
issues array<ListingIssue> zawsze
Pola obiektu
code string zawsze

Kod problemu (ten sam słownik co błędy walidacji oferty).

message string zawsze
severity string zawsze

ERROR blokuje zapis/publikację, WARNING nie blokuje.

Wartości: ERROR, WARNING, INFO
attributeNames array<string> zawsze

Atrybuty, których dotyczy problem.

categories array<string> zawsze

Grupy problemu, np. MISSING_ATTRIBUTE, INVALID_ATTRIBUTE, GPSR.

path string · null

Pole w kształcie Allegro (np. productSet[0].product.parameters).

messageId integer

Numer komunikatu wsadu (tylko w raporcie wsadu).

errors array<Error>

Przy INVALID: te same problemy w kształcie Allegro.

Pola obiektu
code string zawsze

Kod maszynowy błędu — na nim opieraj obsługę (lista: przewodnik „Błędy”).

message string zawsze

Opis dla programisty (po polsku).

details any zawsze

Dane dodatkowe albo null — np. id istniejącej oferty przy OfferDuplicate, {"current": "SENT"} przy błędzie statusu, {"retryAfterMs": 1200} przy limicie.

path string · null zawsze

Pole żądania, którego dotyczy błąd, np. productSet[0].product.parameters.

userMessage string zawsze

Komunikat, który można pokazać sprzedawcy.

Błędy

HTTPKodZnaczenie
400VALIDATION_ERRORZła wartość parametru zapytania (400) albo pola treści (422); path wskazuje miejsce.
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.
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.
Utworzenie oferty po SKU
curl -sS -X PUT "${ALLEE_API_URL:-https://api.allee.pl}/allee/listings/FILM-21ef85-3" \
  -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'
{
  "requirements": "LISTING",
  "status": "ACTIVE",
  "attributes": {
    "name": "Metropolis DVD wersja odrestaurowana",
    "category": {
      "alleeId": 35
    },
    "parameters": {
      "225693": {
        "values": [
          "5901234123464"
        ]
      },
      "237218": {
        "values": [
          "Metropolis"
        ]
      },
      "246845": {
        "valuesIds": [
          "246845_622165"
        ]
      },
      "250077": {
        "valuesIds": [
          "250077_1797493"
        ]
      },
      "11323": {
        "valuesIds": [
          "11323_1"
        ]
      }
    },
    "price": {
      "amount": "59.90",
      "currency": "PLN"
    },
    "stock": 4,
    "images": [
      "https://cdn.allee.pl/img/a/webe/1930/10001318-0-1200.webp"
    ],
    "description": "Film na płycie DVD, nowy w folii. Wersja z polskimi napisami.",
    "shippingRatesId": "797d2e65-cb23-4a16-98e9-d6f2a399839a",
    "responsibleProducerId": "472bad66-e704-4344-a2d6-9bd85b1f9a5e",
    "safetyInformation": {
      "type": "TEXT",
      "description": "Produkt bezpieczny w normalnym użytkowaniu."
    }
  }
}
JSON
Odpowiedź (środowisko testowe)
HTTP 201 application/vnd.allegro.public.v1+json
{
  "sku": "FILM-21ef85-3",
  "status": "ACCEPTED",
  "submissionId": "703bc87433a98c12",
  "offerId": "900000000000024",
  "change": "CREATED",
  "publicationStatus": "ACTIVE",
  "issues": []
}
Przykład: Podgląd walidacji bez zapisu (mode=VALIDATION_PREVIEW)
curl -sS -X PUT "${ALLEE_API_URL:-https://api.allee.pl}/allee/listings/FILM-21ef85-3?mode=VALIDATION_PREVIEW" \
  -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'
{
  "requirements": "LISTING",
  "status": "ACTIVE",
  "attributes": {
    "name": "Metropolis DVD wersja odrestaurowana",
    "category": {
      "alleeId": 35
    },
    "parameters": {
      "225693": {
        "values": [
          "5901234123464"
        ]
      },
      "237218": {
        "values": [
          "Metropolis"
        ]
      },
      "246845": {
        "valuesIds": [
          "246845_622165"
        ]
      },
      "250077": {
        "valuesIds": [
          "250077_1797493"
        ]
      },
      "11323": {
        "valuesIds": [
          "11323_1"
        ]
      }
    },
    "price": {
      "amount": "59.90",
      "currency": "PLN"
    },
    "stock": 4,
    "images": [
      "https://cdn.allee.pl/img/a/webe/1930/10001318-0-1200.webp"
    ],
    "description": "Film na płycie DVD, nowy w folii. Wersja z polskimi napisami.",
    "shippingRatesId": "797d2e65-cb23-4a16-98e9-d6f2a399839a",
    "responsibleProducerId": "472bad66-e704-4344-a2d6-9bd85b1f9a5e",
    "safetyInformation": {
      "type": "TEXT",
      "description": "Produkt bezpieczny w normalnym użytkowaniu."
    }
  }
}
JSON
HTTP 200 application/vnd.allegro.public.v1+json
{
  "sku": "FILM-21ef85-3",
  "status": "VALID",
  "submissionId": "813685289be61f68",
  "offerId": null,
  "change": null,
  "publicationStatus": null,
  "issues": []
}
Przykład: Szkic po SKU (do usunięcia)
curl -sS -X PUT "${ALLEE_API_URL:-https://api.allee.pl}/allee/listings/FILM-21ef85-4" \
  -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'
{
  "requirements": "LISTING",
  "status": "INACTIVE",
  "attributes": {
    "name": "Nosferatu DVD wydanie specjalne",
    "category": {
      "alleeId": 35
    },
    "parameters": {
      "225693": {
        "values": [
          "5901234123464"
        ]
      },
      "237218": {
        "values": [
          "Metropolis"
        ]
      },
      "246845": {
        "valuesIds": [
          "246845_622165"
        ]
      },
      "250077": {
        "valuesIds": [
          "250077_1797493"
        ]
      },
      "11323": {
        "valuesIds": [
          "11323_1"
        ]
      }
    },
    "price": {
      "amount": "39.90",
      "currency": "PLN"
    },
    "stock": 2,
    "images": [
      "https://cdn.allee.pl/img/a/webe/1930/10001318-0-1200.webp"
    ],
    "description": "Film na płycie DVD, nowy w folii. Wersja z polskimi napisami.",
    "shippingRatesId": "797d2e65-cb23-4a16-98e9-d6f2a399839a",
    "responsibleProducerId": "472bad66-e704-4344-a2d6-9bd85b1f9a5e",
    "safetyInformation": {
      "type": "TEXT",
      "description": "Produkt bezpieczny w normalnym użytkowaniu."
    }
  }
}
JSON
HTTP 201 application/vnd.allegro.public.v1+json
{
  "sku": "FILM-21ef85-4",
  "status": "ACCEPTED",
  "submissionId": "f54c1ef8b70b117b",
  "offerId": "900000000000025",
  "change": "CREATED",
  "publicationStatus": "INACTIVE",
  "issues": []
}

Częściowa zmiana oferty po SKU (JSON Patch)

PATCH /allee/listings/{sku}

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

Zmiany replace / add / delete na /attributes/{nazwa} (np. /attributes/price, /attributes/stock). Zmiana tylko ceny i stanu idzie szybką ścieżką.

Zły dokument JSON Patch → 400. Nieistniejące SKU → 404. ?mode=VALIDATION_PREVIEW — podgląd bez zapisu.

Zgodność: wzorowana na Amazon Selling Partner API — Listings Items — patchListingsItem.
Uprawnienie: zakres allegro:api:sale:offers:write.
Grupa limitu: write.

Parametry ścieżki

sku string wymagany

SKU (external.id): 1–100 znaków, bez „/” i znaków sterujących. W adresie zakoduj (np. spacja → %20).

Parametry zapytania

mode string

VALIDATION_PREVIEW = pełna walidacja bez zapisu (odpowiedź 200, status VALID/INVALID).

Wartości: VALIDATION_PREVIEW

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

patches array<object> wymagane

Zmiany JSON Patch (RFC 6902, podzbiór).

Pola obiektu
op string wymagane
Wartości: replace, add, delete
path string wymagane

Ścieżka /attributes/{nazwa}, np. /attributes/price, /attributes/stock.

value any

Nowa wartość (dla replace i add).

status string
Wartości: ACTIVE, INACTIVE
productType string
marketplaceIds array<string>
issueLocale string

Odpowiedzi

200 Zmieniono (albo podgląd). · ListingSubmissionResponse
sku string zawsze
status string zawsze

ACCEPTED = zapisano; VALID = podgląd poprawny (nic nie zapisano); INVALID = błędy (nic nie zapisano).

Wartości: ACCEPTED, INVALID, VALID
submissionId string zawsze

Identyfikator zgłoszenia (= X-Request-Id).

offerId string · null zawsze
change string · null zawsze

Co się stało z ofertą.

Wartości: CREATED, UPDATED, UNCHANGED, DELETED, ENDED, null
publicationStatus PublicationStatus · null zawsze
issues array<ListingIssue> zawsze
Pola obiektu
code string zawsze

Kod problemu (ten sam słownik co błędy walidacji oferty).

message string zawsze
severity string zawsze

ERROR blokuje zapis/publikację, WARNING nie blokuje.

Wartości: ERROR, WARNING, INFO
attributeNames array<string> zawsze

Atrybuty, których dotyczy problem.

categories array<string> zawsze

Grupy problemu, np. MISSING_ATTRIBUTE, INVALID_ATTRIBUTE, GPSR.

path string · null

Pole w kształcie Allegro (np. productSet[0].product.parameters).

messageId integer

Numer komunikatu wsadu (tylko w raporcie wsadu).

errors array<Error>

Przy INVALID: te same problemy w kształcie Allegro.

Pola obiektu
code string zawsze

Kod maszynowy błędu — na nim opieraj obsługę (lista: przewodnik „Błędy”).

message string zawsze

Opis dla programisty (po polsku).

details any zawsze

Dane dodatkowe albo null — np. id istniejącej oferty przy OfferDuplicate, {"current": "SENT"} przy błędzie statusu, {"retryAfterMs": 1200} przy limicie.

path string · null zawsze

Pole żądania, którego dotyczy błąd, np. productSet[0].product.parameters.

userMessage string zawsze

Komunikat, który można pokazać sprzedawcy.

Błędy

HTTPKodZnaczenie
400VALIDATION_ERRORZła wartość parametru zapytania (400) albo pola treści (422); path wskazuje miejsce.
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ę).
404NOT_FOUNDNie ma takiego zasobu (albo należy do innego sprzedawcy — dla wątków, zwrotów i spraw odpowiedź jest ta sama).
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).
429TOO_MANY_REQUESTSPrzekroczony limit (minutowy, grupy operacji albo IP).
500INTERNAL_ERRORBłąd serwera allee.
Przykład
curl -sS -X PATCH "${ALLEE_API_URL:-https://api.allee.pl}/allee/listings/FILM-21ef85-3" \
  -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'
{
  "patches": [
    {
      "op": "replace",
      "path": "/attributes/price",
      "value": {
        "amount": "54.90",
        "currency": "PLN"
      }
    },
    {
      "op": "replace",
      "path": "/attributes/stock",
      "value": 6
    }
  ]
}
JSON
Odpowiedź (środowisko testowe)
HTTP 200 application/vnd.allegro.public.v1+json
{
  "sku": "FILM-21ef85-3",
  "status": "ACCEPTED",
  "submissionId": "3840cf94b7276dc2",
  "offerId": "900000000000024",
  "change": "UPDATED",
  "publicationStatus": "ACTIVE",
  "issues": []
}

Usunięcie albo zakończenie oferty po SKU

DELETE /allee/listings/{sku}

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

Szkic nigdy nieopublikowany → usunięty (change: DELETED). Oferta opublikowana → zakończona (change: ENDED; historia sprzedaży zostaje). ?mode=VALIDATION_PREVIEW — nic nie zmienia.

Zgodność: wzorowana na Amazon Selling Partner API — Listings Items — deleteListingsItem.
Uprawnienie: zakres allegro:api:sale:offers:write.
Grupa limitu: write.

Parametry ścieżki

sku string wymagany

SKU (external.id): 1–100 znaków, bez „/” i znaków sterujących. W adresie zakoduj (np. spacja → %20).

Parametry zapytania

mode string

VALIDATION_PREVIEW = pełna walidacja bez zapisu (odpowiedź 200, status VALID/INVALID).

Wartości: VALIDATION_PREVIEW

Odpowiedzi

200 Usunięto / zakończono. · ListingSubmissionResponse
sku string zawsze
status string zawsze

ACCEPTED = zapisano; VALID = podgląd poprawny (nic nie zapisano); INVALID = błędy (nic nie zapisano).

Wartości: ACCEPTED, INVALID, VALID
submissionId string zawsze

Identyfikator zgłoszenia (= X-Request-Id).

offerId string · null zawsze
change string · null zawsze

Co się stało z ofertą.

Wartości: CREATED, UPDATED, UNCHANGED, DELETED, ENDED, null
publicationStatus PublicationStatus · null zawsze
issues array<ListingIssue> zawsze
Pola obiektu
code string zawsze

Kod problemu (ten sam słownik co błędy walidacji oferty).

message string zawsze
severity string zawsze

ERROR blokuje zapis/publikację, WARNING nie blokuje.

Wartości: ERROR, WARNING, INFO
attributeNames array<string> zawsze

Atrybuty, których dotyczy problem.

categories array<string> zawsze

Grupy problemu, np. MISSING_ATTRIBUTE, INVALID_ATTRIBUTE, GPSR.

path string · null

Pole w kształcie Allegro (np. productSet[0].product.parameters).

messageId integer

Numer komunikatu wsadu (tylko w raporcie wsadu).

errors array<Error>

Przy INVALID: te same problemy w kształcie Allegro.

Pola obiektu
code string zawsze

Kod maszynowy błędu — na nim opieraj obsługę (lista: przewodnik „Błędy”).

message string zawsze

Opis dla programisty (po polsku).

details any zawsze

Dane dodatkowe albo null — np. id istniejącej oferty przy OfferDuplicate, {"current": "SENT"} przy błędzie statusu, {"retryAfterMs": 1200} przy limicie.

path string · null zawsze

Pole żądania, którego dotyczy błąd, np. productSet[0].product.parameters.

userMessage string zawsze

Komunikat, który można pokazać sprzedawcy.

Błędy

HTTPKodZnaczenie
400VALIDATION_ERRORZła wartość parametru zapytania (400) albo pola treści (422); path wskazuje miejsce.
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ę).
404NOT_FOUNDNie ma takiego zasobu (albo należy do innego sprzedawcy — dla wątków, zwrotów i spraw odpowiedź jest ta sama).
429TOO_MANY_REQUESTSPrzekroczony limit (minutowy, grupy operacji albo IP).
500INTERNAL_ERRORBłąd serwera allee.
Przykład
curl -sS -X DELETE "${ALLEE_API_URL:-https://api.allee.pl}/allee/listings/FILM-21ef85-4" \
  -H "Authorization: Bearer $ALLEE_API_KEY" \
  -H "Accept: application/vnd.allegro.public.v1+json" \
  -w '\nHTTP %{http_code}\n'
Odpowiedź (środowisko testowe)
HTTP 200 application/vnd.allegro.public.v1+json
{
  "sku": "FILM-21ef85-4",
  "status": "ACCEPTED",
  "submissionId": "e06fa881ccf8a1a7",
  "offerId": "900000000000025",
  "change": "DELETED",
  "publicationStatus": null,
  "issues": []
}