Allegro REST API

gdzie?

Dyskusje i reklamacje

Głównym celem dyskusji i reklamacji jest wsparcie kupującego w rozwiązaniu problemu transakcyjnego, przy jednoczesnym wsparciu sprzedającego w procesowaniu zgłoszeń i informowaniu o terminach na realizację poszczególnych kroków. Umożliwiamy sprzedającym zarządzanie dyskusjami i reklamacjami za pomocą REST API. Dzięki temu sprzedający mogą łatwo:

  • nawiązać kontakt z kupującymi,
  • wygodnie i szybko rozwiązać każdy problem transakcyjny,
  • rozpatrzyć reklamację.

Więcej informacji na temat dyskusji i reklamacji znajdziesz w Pomocy Allegro.

  1. Do końca września 2025 dotychczasowe zasoby na ścieżce /sale/disputes przestaną być kompatybilne z nowym procesem reklamacyjnym i dyskusyjnym - nie obsłużysz nimi reklamacji, w tym:

    • nie pobierzesz szczegółowych informacji dotyczących złożonych reklamacji,
    • nie zmienisz statusu reklamacji, w tym:
      • nie zaakceptujesz roszczenia klienta,
      • nie odrzucisz go,
      • nie zmienisz rozwiązania.

  2. Zasoby na ścieżce /sale/disputes oznaczyliśmy jako deprecated i w przyszłości całkowicie je usuniemy.

Zadbaj o to, aby do końca września 2025 Twoje oprogramowanie korzystało już z odpowiedników tych zasobów na ścieżce /sale/issues.

Lista dyskusji i reklamacji na koncie

Za pomocą GET /sale/issues pobierzesz wszystkie dyskusje i reklamacje na danym koncie, posortowane wg daty otwarcia lub ponownego otwarcia.

Przykładowy request

  curl -X GET \
  'https://api.allegro.pl/sale/issues \
  -H 'Accept: application/vnd.allegro.beta.v1+json' \
  -H 'Authorization: Bearer {token}'

Przykładowy response, który zawiera dyskusję i reklamację:

{
   "issues":[
      {
         "id":"97ce67c8-823e-45d5-a280-c3e74aea1e2a",
         "type":"DISPUTE",    // typ problemu transakcyjnego (możliwe wartości: DISPUTE (dyskusja) lub CLAIM (reklamacja))
         "referenceNumber":null,    // numer referencyjny reklamacji (nie dotyczy dyskusji, dla których zawsze zwracamy null)
         "decisionDueDate":"2025-06-23T18:47:55.826Z",    // termin przyjęcia lub odrzucenia roszczenia reklamacyjnego (nie dotyczy dyskusji, dla których zawsze zwracamy null) 
         "openedDate":"2025-06-22T18:47:54.632Z",    // data otwarcia dyskusji lub reklamacji
         "subject":"NO_REFUND_AFTER_RETURNING_PRODUCT",    // temat problemu transakcyjnego
         "checkoutForm":{    // dane dotyczące zamówienia
            "id":"545ee5e0-ed1b-11ef-a3a9-0dbad95e3ee6",    // identyfikator zamówienia
            "createdAt":"2025-02-17T10:38:30.639Z"    // data utworzenia zamówienia
         },
         "buyer":{    // dane kupującego
            "id":"93975873",    // identyfikator kupującego
            "login":"test-buyer"    // login kupującego
         },
         "currentState":{
            "status":"DISPUTE_ONGOING",    // status dyskusji (pełna lista wartości dostępna w dokumentacji)
            "dueDate":"2025-06-23T18:47:55.826Z"    // data zmiany statusu dyskusji/reklamacji
         },
         "chat":{
            "lastMessage":{    // ostatnia wiadomość
               "status":"NEW",    // status wiadomości (pełna lista wartości dostępna w dokumentacji)
               "createdAt":"2025-06-22T18:47:54.632Z"    // data utworzenia wiadomości
            },
            "messagesCount":1,    // liczba wiadomości
            "initialMessage":{    // pierwsza wiadomość
               "id":"d6d4aa77-e052-445f-a5e6-74485a1a1119",    // identyfikator wiadomości
               "text":"Dzień dobry. Proszę o wyjaśnienie sytuacji.",    // treść wiadomości
               "attachments":null,    // załączniki dla pierwszej wiadomości
               "createdAt":"2025-06-22T18:47:54.632Z",    // data utworzenia
               "author":{
                  "login":"buyer-login",
                  "role":"BUYER"    // rola autora wiadomości; możliwe wartości: BUYER, SELLER, ADMIN, FULFILLMENT
               }
            }
         },
         "expectations":[    // oczekiwania (dostępne tylko dla reklamacji); możliwe wartości: REPAIR (naprawa), EXCHANGE (wymiana towaru), REFUND (zwrot), PARTIAL_REFUND (częściowy zwrot)

         ],
         "description":"Treść opisu",    // opis problemu
         "product":null,    // dane o produkcie (dostępne tylko dla reklamacji)
         "offer":null,    // oferta (dostępne tylko dla reklamacji)
         "reason":null,    // powód reklamacji (dostępne tylko dla reklamacji);         
   "right":null,    // rodzaj reklamacji (dostępne tylko dla reklamacji); możliwe wartości: WARRANTY (gwarancja), COMPLAINT (reklamacja)
         "attachments":[    // załączniki

         ]
      },
      {
         "id":"c5b4cb14-2bdf-4b06-9fa6-9dd53b358d5b",
         "type":"CLAIM",
         "referenceNumber":"c5b4cb14-2bdf-4b06-9fa6-9dd53b358d5b",
         "decisionDueDate":"2025-07-02T23:59:59Z",
         "openedDate":"2025-06-18T12:39:07.273Z",
         "subject":null,
         "checkoutForm":{
            "id":"83ec1e40-3c5d-11f0-9372-1753ff058dcf",
            "createdAt":"2025-05-29T07:21:18.792Z"
         },
         "buyer":{
            "id":"93975873",
            "login":"sandboxbuyer24"
         },
         "currentState":{
            "status":"CLAIM_SUBMITTED",
            "statusDueDate":"2025-07-02T23:59:59Z"
         },
         "chat":{
            "lastMessage":{
               "status":"NEW",
               "createdAt":"2025-06-18T12:39:07.273Z"
            },
            "messagesCount":1,
            "initialMessage":{
               "id":"d062956a-51dd-41d4-a5ed-6d0d17c10137",
               "text":"Płyta jest porysowana, przez co gra nie może się w pełni zainstalować :(",
               "attachment":null,
               "createdAt":"2025-06-18T12:39:07.273Z",
               "author":{
                  "login":"buyer-login",
                  "role":"BUYER"
               }
            }
         },
         "expectations":[
            {
               "name":"EXCHANGE",
               "refund":null
            }
         ],
         "description":null,
         "product":{
            "id":"053bb0ad-8c31-41e9-837f-fcd24965b662",    // identyfikator produktu
         },
         "offer":{    // dane oferty
            "id":"7778622952",    // id oferty
            "quantity":1    // liczba sztuk
         },
         "reason":{    // powód reklamacji
            "description":"treść opisu",    // treść opisu
            "type":"DETECT_FOUND_DURING_USE",    // powód reklamacji (niedostępne dla dyskusji); pełna lista wartości dostępna w dokumentacji          },
         "right":"WARRANTY",    // rodzaj reklamacji (niedostępne dla dyskusji); możliwe wartości: WARRANTY (gwarancja), COMPLAINT (reklamacja)
         "attachments":[

         ]
      }
   ]
}

Aby zawęzić listę wyszukiwania, skorzystaj z parametrów:

  • status - by pobrać status:
    • dyskusji; dostępne wartości: DISPUTE_CLOSED (zamknięta dyskusja), DISPUTE_ONGOING (dyskusja w trakcie), DISPUTE_UNRESOLVED (nierozwiązana dyskusja),
    • reklamacji; dostępne wartości:, CLAIM_SUBMITTED (złożona reklamacja), CLAIM_ACCEPTED (reklamacja zaakceptowana), CLAIM_REJECTED (reklamacja odrzucona),
  • limit - by określić liczbę wiadomości na liście (min. 1, max. 100),
  • offset - by wskazać miejsce, od którego chcesz pobrać kolejną porcję danych (min. 0), np. GET /sale/issues?limit=4&offset=5,
  • checkoutForm.id - by pobrać dyskusję lub reklamację dla danego zamówienia, np. GET /sale/issues?checkoutForm.id="83ec1e40-3c5d-11f0-9372-1753ff058dcf". Numer zamówienia uzyskasz za pomocą GET /order/checkout-forms.

Szczegółowe informacje o dyskusji/reklamacji

Za pomocą GET /sale/issues/{issueId} pobierzesz szczegółowe informacje o danej dyskusji (DISPUTE) lub reklamacji (CLAIM).

Pole “issueId” to identyfikator dyskusji/reklamacji, który pobierzesz za pomocą GET /sale/issues lub znajdziesz w zakładce Reklamacje i Dyskusje z kupującymi.

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/sale/issues/c5b4cb14-2bdf-4b06-9fa6-9dd53b358d5b' \
  -H 'Accept: application/vnd.allegro.beta.v1+json' \
  -H 'Authorization: Bearer {token}'

Przykładowy response:

  {
   "id":"c5b4cb14-2bdf-4b06-9fa6-9dd53b358d5b",    // identyfikator dyskusji/reklamacji
   "type":"CLAIM",    // typ problemu transakcyjnego (możliwe wartości: DISPUTE (dyskusja), CLAIM (reklamacja)
   "referenceNumber":"c5b4cb14-2bdf-4b06-9fa6-9dd53b358d5b",    // identyfikator reklamacji (nie dotyczy dyskusji, dla których zawsze zwracamy null)
   "decisionDueDate":"2025-07-02T23:59:59Z",    // termin przyjęcia lub odrzucenia roszczenia reklamacyjnego (nie dotyczy dyskusji, dla których zawsze zwracamy null) 
   "openedDate":"2025-06-18T12:39:07.273Z",    // data otwarcia dyskusji lub reklamacji
   "subject":null, 
   "checkoutForm":{
      "id":"83ec1e40-3c5d-11f0-9372-1753ff058dcf",
      "createdAt":"2025-05-29T07:21:18.792Z"
   },
   "buyer":{
      "id":"93975873",
      "login":"test-buyer"
   },
   "currentState":{
      "status":"CLAIM_SUBMITTED",
      "statusDueDate":"2025-07-02T23:59:59Z"
   },
   "chat":{
      "lastMessage":{
         "status":"NEW",
         "createdAt":"2025-06-18T12:39:07.273Z"
      },
      "messagesCount":1,
      "initialMessage":{
         "id":"d062956a-51dd-41d4-a5ed-6d0d17c10137",
         "text":"Płyta jest porysowana, przez co gra nie może się w pełni zainstalować :(",
         "attachment":null,
         "createdAt":"2025-06-18T12:39:07.273Z",
         "author":{
            "login":"buyer-login",
            "role":"BUYER"
         }
      }
   },
   "expectations":[
      {
         "name":"EXCHANGE",
         "refund":null
      }
   ],
   "description":null,
   "product":{
      "id":"053bb0ad-8c31-41e9-837f-fcd24965b662",    // identyfikator produktu
         },
   "offer":{
      "offerId":"7778622952",
      "quantity":1
   },
   "reason":{
      "description":"description",
      "type":"DETECT_FOUND_DURING_USE"
   },
   "right":"WARRANTY",
   "attachments":[

   ]
}

Wiadomości z dyskusji i reklamacji

Za pomocą GET /sale/issues/{issueId}/chat pobierzesz wszystkie wiadomości z dyskusji. Wiadomości zwracamy w kolejności od najnowszej do najstarszej.

Aby zawęzić listę wyszukiwania, możesz skorzystać z parametrów:

  • limit - by określić liczbę wiadomości na liście (min. 1, max. 100),
  • offset - by wskazać miejsce, od którego chcesz pobrać kolejną porcję danych (min. 0), np. GET /sale/issues/{issue.Id}/messages?limit=4&offset=5.

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/sale/issues/c5b4cb14-2bdf-4b06-9fa6-9dd53b358d5b/chat' \
  -H 'Accept: application/vnd.allegro.beta.v1+json' \
  -H 'Authorization: Bearer {token}'

Przykładowy response:

{
    "chat": [
        {
            "id": "a9927fcc-f11a-436a-9f8d-177fd37d393c",
            "text": "Testowa wiadomość nr 2",
            "attachments": [],
            "author": {
                "login": "test-seller",
                "role": "SELLER"
            },
            "createdAt": "2025-06-22T20:44:45.121Z"
        },
        {
            "id": "29bed653-ce11-42b6-ad15-6ca867a951c6",
            "text": "Testowa wiadomość",
            "attachments": [],
            "author": {
                "login": "test-seller",
                "role": "SELLER"
            },
            "createdAt": "2025-06-22T20:39:17.057Z"
        },
        {
            "id": "d6d4aa77-e052-445f-a5e6-74485a1a1119",
            "text": "Dzień dobry. Proszę o wyjaśnienie sytuacji.",
            "attachments": [],
            "author": {
                "login": "test-buyer",
                "role": "BUYER"
            },
            "createdAt": "2025-06-22T18:47:54.726Z"
        }
    ]
}

Nowa wiadomość w dyskusji lub reklamacji

Skorzystaj z POST /sale/issues/{issueId}/message, aby dodać wiadomość w dyskusji lub reklamacji.

Wiadomość może mieć pięć typów:

  • dostępny dla dyskusji i reklamacji:
    • REGULAR to standardowa wiadomość zarówno dla dyskusji, jak i dla reklamacji. Może zawierać tekst i załączniki.
  • dostępny tylko dla dyskusji:
    • END_REQUEST to prośba o zakończenie problemu transakcyjnego (dostępny tylko w przypadku dyskusji),
  • dostepne tylko dla reklamacji:
    • RETURN_REQUIRED_SELLER_LABEL - zwrot towaru, dla którego sprzedawca musi załączyć swoją etykietę przewozową,
    • RETURN_REQUIRED_CUSTOM - zwrot towaru, dla którego sprzedawca nie musi załączać etykiety przewozowej,
    • RETURN_NOT_REQUIRED - zwrot towaru nie jest wymagany.

Przykładowy request:

    curl -X POST \
    'https://api.allegro.pl/sale/issues/97ce67c8-823e-45d5-a280-c3e74aea1e2a/message
    -H 'Authorization: Bearer {token}' \
    -H 'Accept: application/vnd.allegro.beta.v1+json' \
    -d  '{
  "text": "Proszę o propozycję rozwiązania problemu",
  "attachments": [
    {
      "id": 77b2f474-0b87-4b68-9297-56676bc84a6c
    }
  ],
  "type": "REGULAR"
}

Przykładowy response:

{
    "id": "a9927fcc-f11a-436a-9f8d-177fd37d393c",
    "text": "Proszę o propozycję rozwiązania problemu",
    "attachments": [],
    "author": {
        "login": "test-seller",
        "role": "SELLER"
    },
    "createdAt": "2025-06-24T09:59:05.551219403Z"
}

Zmień status reklamacji

Skorzystaj z POST /sale/issues/{issueId}/status, aby zmienić status reklamacji.

Reklamację możesz zaakceptować, przekazując jedną z poniższych wartości:

  • ACCEPTED_REPAIR - akceptuję naprawę towaru,
  • ACCEPTED_REFUND - akceptuję zwrot płatności,
  • ACCEPTED_EXCHANGE - akceptuję wymianę towaru,
  • ACCEPTED_PARTIAL_REFUND - akceptuję częściowy zwrot płatności,

lub odrzucić, ponieważ:

  • REJECTED_ADDITIONAL_REQUIREMENTS_NOT_COMPLETED - dodatkowe wymagania nie zostały spełnione,
  • REJECTED_PRODUCT_NOT_RETURNED - klient nie zwrócił towaru,
  • REJECTED_PRODUCT_DAMAGED_BY_USER - klient uszkodził towar,
  • REJECTED_PRODUCT_CONFORMS_TO_CONTRACT - produkt zgodny z umową,
  • REJECTED_MINOR_DEFECT - z powodu drobnej wady,
  • REJECTED_OTHER - z innego powodu.

Przykładowy request:

    curl -X POST \
    'https://api.allegro.pl/sale/issues/c5b4cb14-2bdf-4b06-9fa6-9dd53b358d5b/status
    -H 'Authorization: Bearer {token}' \
    -H 'Accept: application/vnd.allegro.beta.v1+json' \
    -d  '{
  "status": "ACCEPTED_REPAIR",    // status reklamacji
  "message": "Akceptuję naprawę przedmiotu",    // treść wiadomości
  "partialRefund": {
    "amount": "123.45",    // kwota zwrotu
    "currency": "PLN"
  }
}

Załączniki

W naszym API udostępniamy trzy zasoby odpowiedzialne za zarządzanie załącznikami w dyskusjach i reklamacjach:

Pobranie załącznika

Za pomocą GET /sale/issues/attachments/{attachmentId} pobierzesz załącznik z dyskusji/reklamacji. Wartość: "attachmentsId" znajdziesz w polu "attachments.url", gdy skorzystasz z jednego z wymienionych zasobów:

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/sale/issues/attachments/c5b4cb14-2bdf-4b06-9fa6-9dd53b358d5b' \
  -H 'Authorization: Bearer {token}'

Przykładowy response:

Deklaracja załącznika

Za pomocą POST /sale/issues/attachments prześlesz deklarację załącznika, czyli zdefiniujesz jego rozmiar (w bajtach) i nazwę. W odpowiedzi otrzymasz:

Przykładowy request:

  curl -X POST \
  'https://api.allegro.pl/sale/issues/attachments' \
  -H 'Accept: application/vnd.allegro.beta.v1+json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/vnd.allegro.beta.v1+json' \
  -d '{
    "size": 2549,    // wymagane, rozmiar pliku
    "fileName": "Zrzut_ekranu.png"    // wymagane, nazwa pliku
}'

Przykładowy response:

{
    "id": "77b2f474-0b87-4b68-9297-56676bc84a6c"
}

Dodanie załącznika

Skorzystaj z PUT https://api.allegro.pl/sale/issues/attachments/{attachmentId}, aby przesłać załącznik na nasze serwery. W wywołaniu podaj id załącznika {attachmentId}. Otrzymasz go za pomocą POST /sale/issues/attachments. Jako content-type podaj rodzaj pliku jaki chcesz dodać:

  • image/png,
  • image/gif,
  • image/bmp,
  • image/tiff,
  • image/jpeg,
  • application/pdf.

Załącznik musisz przesłać w postaci binarnej. Maksymalna waga załącznika nie może przekroczyć 2097152 bajtów.

Przykładowy request:

  curl -X PUT \
  https://api.allegro.pl/sale/issues/attachments/66377da8-eee2-4094-8dcf-3540e51c307f \
  -H 'Accept: application/vnd.allegro.beta.v1+json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: image/png'

Lista zasobów

Pełną dokumentację zasobów w postaci pliku swagger.yaml znajdziesz tutaj.

Lista zasobów podstawowych opisanych w poradniku:

Czy ten artykuł był dla Ciebie przydatny?

Allegro

Dostosuj ustawienia wyświetlania

ustawienia dotyczą tylko tej przeglądarki