Allegro REST API

gdzie?

Dyskusje

Głównym celem dyskusji jest pomoc kupującemu w rozwiązaniu problemu, przy jednoczesnym wsparciu sprzedającego. Umożliwiamy sprzedającym korzystanie z dyskusji za pomocą REST API. Dzięki temu sprzedający mogą łatwo nawiązać kontakt z kupującymi oraz wygodnie i szybko rozwiązać każdy problem transakcyjny.

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

Dyskusje na koncie

Za pomocą GET /sale/disputes, jako zalogowany sprzedawca, pobierzesz wszystkie dyskusje na danym koncie. Dyskusje sortowane są wg daty otwarcia lub ponownego otwarcia.

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/sale/disputes' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'
{
    "disputes": [
        {
            "id": "a38812fa-6fef-4c9c-ac06-a0952b67ba78",       - identyfikator danej dyskusji
            "subject": {
                "name": "przedmiot jest uszkodzony"             - powód rozpoczęcia dyskusji
            },
            "status": "ONGOING",                                - status dyskusji, dostępne wartości:
                                                                “ONGOING” (w toku),
                                                                “CLOSED” (zakończona),
                                                                “UNRESOLVED” (nierozwiązana)
            "messagesStatus": "NEW",                            - status ostatniej wiadomości w dyskusji,
                                                                dostępne wartości:
                                                                “NEW” (nowa dyskusja),
                                                                “BUYER_REPLIED” (nowa wiadomość od kupującego),
                                                                “SELLER_REPLIED” (nowa wiadomość od sprzedającego),
                                                                “ALLEGRO_ADVISOR_REPLIED” (nowa wiadomość od Allegro)
            "buyer": {                                          
                "id": "3952032",                                - identyfikator kupującego
                "login": "Buyer_login1"                         - login kupującego
            },
            "checkoutForm": {
                "id": "31fc03c3-9ebc-11e8-8885-2bfbcd0aa7ab",   - identyfikator zamówienia
                "createdAt": "2018-08-13T05:46:56.000Z"         - data utworzenia zamówienia
            },
            "message": {                                        - pierwsza wiadomość w dyskusji
                "id": "e75d97ba-18a7-4d1b-a7ee-d02ba1a21bba",   - identyfikator wiadomości
                "text": "Niestety towar jest uszkodzony.",      - treść wiadomości
                "attachment": {                                 - załącznik w dyskusji
                    "fileName": "Zrzut_ekranu.png",             - nazwa pliku
                    "url": "https://upload.allegro.pl/sale/     - adres pliku
                    dispute-attachments/731f2401-7b79-4212-be9e-591464526cfe"
                },
                "author": {
                    "login": "Buyer_login1",
                    "role": "BUYER"                             - rola autora wiadomości:
                                                                BUYER, ADMIN
                },
                "createdAt": "2018-09-14T06:34:24.258Z"         - data utworzenia dyskusji
            },
            "messagesCount": 5,                                 - liczba wiadomości w dyskusji
            "openedDate": "2018-09-14T06:24:24.000Z",           - data otwarcia lub ponownego otwarcia dyskusji
            "lastMessageCreationDate": "2018-09-14T06:34:24.258Z",       - data utworzenia ostatniej wiadomości     
            "claim": {               -  roszczenie kupującego do powodu "problem z produktem" 
                "name": "częściowy zwrot pieniędzy",   -  nazwa roszczenia, które wybrał kupujący
                "description": "description": "Proszę o zwrot 25zł"      - opis roszczenia, tylko dla name: "częściowy zwrot pieniędzy"
            }
            },
        {
            "id": "a6f45545-16a6-4ede-b689-aa105b184229",
            "subject": {
                "name": "przedmiot jest uszkodzony"
            },
            "status": "UNRESOLVED",
            "messagesStatus": "BUYER_REPLIED"
            "buyer": {
                "id": "42334554",
                "login": "Buyer_login2"
            },
            "checkoutForm": {
                "id": "3add96b0-734f-11e6-9999-2be182b71611",
                "createdAt": "2016-09-05T09:58:01.000Z"
            },
            "message": {
                "id": "8de2dd79-75c6-4f35-ba5f-5ddf2c4f699a",
                "text": "dostałem nadgryziony produkt",
                "author": {
                    "login": "Buyer_login2",
                    "role": "BUYER"
                },
                "createdAt": "2016-09-20T11:09:20.659Z"
            },
            "messagesCount": 6,
            "openedDate": "2016-09-14T06:24:24.000Z",
            "lastMessageCreationDate": "2016-09-20T11:09:20.659Z",
            "claim": {
                "name": null,
                "description": null
            }
        }
    ]
}

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

  • status - by pobrać dyskusje o wskazanym statusie, dostępne wartości: ONGOING, CLOSED, UNRESOLVED,

  • 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/disputes?limit=4&offset=5,

  • checkoutForm.id - by pobrać dyskusję dla danego zamówienia, np. GET /sale/disputes?checkoutForm.id=31fc03c3-9ebc-11e8-8885-2bfbcd0aa7ab. Numer zamówienia uzyskasz metodą GET /order/checkout-forms.

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/sale/disputes?checkoutForm.id=31fc03c3-9ebc-11e8-8885-2bfbcd0aa7ab' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'
{
    "disputes": [
        {
            "id": "a38812fa-6fef-4c9c-ac06-a0952b67ba78",       - identyfikator danej dyskusji
            "subject": {
                "name": "przedmiot jest uszkodzony"             - powód rozpoczęcia dyskusji
            },
            "status": "ONGOING",                                - status dyskusji, dostępne wartości:
                                                                “ONGOING” (w toku),
                                                                “CLOSED” (zakończona),
                                                                “UNRESOLVED” (nierozwiązana)
            "messagesStatus": "NEW",                            - status ostatniej wiadomości w dyskusji,
                                                                dostępne wartości:“NEW”,“BUYER_REPLIED”, 
                                                                “SELLER_REPLIED”, “ALLEGRO_ADVISOR_REPLIED”
            "buyer": {                                          
                "id": "3952032",                                - identyfikator kupującego
                "login": "Buyer_login1"                         - login kupującego
            },
            "checkoutForm": {
                "id": "31fc03c3-9ebc-11e8-8885-2bfbcd0aa7ab",   - identyfikator zamówienia
                "createdAt": "2018-08-13T05:46:56.000Z"         - data utworzenia zamówienia
            },
            "message": {                                        - pierwsza wiadomość w dyskusji
                "id": "e75d97ba-18a7-4d1b-a7ee-d02ba1a21bba",   - identyfikator wiadomości
                "text": "Niestety towar jest uszkodzony.",      - treść wiadomości
                "attachment": {                                 - załącznik w dyskusji
                    "fileName": "Zrzut_ekranu.png",             - nazwa pliku
                    "url": "https://upload.allegro.pl/sale/     - adres pliku
                    dispute-attachments/731f2401-7b79-4212-be9e-591464526cfe"
                },
                "author": {
                    "login": "Buyer_login1",
                    "role": "BUYER"                             - rola autora wiadomości:
                                                                BUYER, ADMIN
                },
                "createdAt": "2018-09-14T06:34:24.258Z"         - data utworzenia dyskusji
            },
            "messagesCount": 5,                                 - liczba wiadomości w dyskusji
            "openedDate": "2018-09-14T06:24:24.000Z",           - data otwarcia lub ponownego otwarcia dyskusji
            "lastMessageCreationDate":  "2018-09-14T06:34:24.258Z",     - data utworzenia ostatniej wiadomości     
            "claim": {               -  roszczenie od kupującego do powodu "problem z produktem" 
                "name": "częściowy zwrot pieniędzy",       -  nazwa roszczenia, które wybrał kupujący
                "description": "description": "Proszę o zwrot 25zł"     - opis roszczenia, tylko dla name: "częściowy zwrot pieniędzy"
            }
        }
    ]
}

Szczegółowe informacje o dyskusji

Za pomocą GET /sale/disputes/{disputeId}, jako zalogowany sprzedawca, pobierzesz szczegółowe informacje o danej dyskusji.

Pole “disputeId” to identyfikator dyskusji, którą znajdziesz w zakładce Dyskusje z kupującymi, lub pobierzesz metodą GET /sale/disputes.

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/sale/disputes/a38812fa-6fef-4c9c-ac06-a0952b67ba78' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'
{
    "id": "a38812fa-6fef-4c9c-ac06-a0952b67ba78",       - identyfikator danej dyskusji
    "subject": {
        "name": "przedmiot jest uszkodzony"             - powód rozpoczęcia dyskusji   
    },
    "status": "ONGOING",                                - status dyskusji, dostępne wartości:
                                                        “ONGOING” (w toku), “CLOSED” (zakończona),
                                                        “UNRESOLVED” (nierozwiązana)
    "messagesStatus": "NEW",                            - status ostatniej wiadomości w dyskusji,
                                                        dostępne wartości:
                                                        “NEW” (nowa dyskusja),
                                                        “BUYER_REPLIED” (nowa wiadomość od kupującego),
                                                        “SELLER_REPLIED” (nowa wiadomość od sprzedającego),
                                                        “ALLEGRO_ADVISOR_REPLIED” (nowa wiadomość od Allegro)
    "buyer": {                                          
        "id": "3952032",                                - identyfikator kupującego
        "login": "Buyer_login1"                         - login kupującego
    },
    "checkoutForm": {
        "id": "31fc03c3-9ebc-11e8-8885-2bfbcd0aa7ab",   - identyfikator zamówienia
        "createdAt": "2018-08-13T05:46:56.000Z"         - data utworzenia zamówienia
    },
    "message": {                                        - pierwsza wiadomość w dyskusji
        "id": "e75d97ba-18a7-4d1b-a7ee-d02ba1a21bba",   - identyfikator wiadomości
        "text": "Niestety towar jest uszkodzony.",      - treść wiadomości
        "attachment": {                                 - załącznik w dyskusji
            "fileName": "Zrzut_ekranu.png",             - nazwa pliku
            "url": "https://upload.allegro.pl/sale/     - adres pliku
            dispute-attachments/731f2401-7b79-4212-be9e-591464526cfe"
    },
    "author": {
        "login": "Buyer_login1",
        "role": "BUYER"                                 - rola autora wiadomości:
                                                        BUYER, ADMIN
    },
    "createdAt": "2018-09-14T06:34:24.258Z"             - data utworzenia dyskusji
    },
    "messagesCount": 5,                                 - liczba wiadomości w dyskusji
    "openedDate": "2018-09-14T06:24:24.000Z",           - data otwarcia lub ponownego otwarcia dyskusji
    "lastMessageCreationDate": "2018-09-14T06:34:24.258Z",      - data utworzenia ostatniej wiadomości     
    "claim": {               -  roszczenie od kupującego do powodu "problem z produktem" 
          "name": "częściowy zwrot pieniędzy",       -  nazwa roszczenia, które wybrał kupujący
          "description": "description": "Proszę o zwrot 25zł"   - opis roszczenia, tylko dla name: "częściowy zwrot pieniędzy"
          }
            },
}

Wiadomości z dyskusji

Za pomocą GET/sale/disputes/{disputeId}/messages, jako zalogowany sprzedawca, 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/disputes/{dispute.Id}/messages?limit=4&offset=5.

{
    "messages": [
        {
            "id": "657fc2c1-addf-416a-8129-e2b55740248b",   - identyfikator wiadomości
            "text": "Vestibulum eu interdum ex, p...",      - treść wiadomości
            "author": {
                "login": "Seller_login1",                   - login autora wiadomości
                "role": "SELLER"                            - rola autora wiadomości:
                                                            BUYER, ADMIN, SELLER
            },
            "createdAt": "2018-09-14T06:36:55.332Z"         - data utworzenia
        },
        {
            "id": "8586fa58-ff19-4713-8b3e-9c0c3ff73e1b",
            "text": "Lorem ipsum ...",
            "author": {
                "login": "Buyer_login1",
                "role": "BUYER"
            },
            "createdAt": "2018-09-14T06:36:40.100Z"
        },
        {
            "id": "3f730fe3-f2d4-4548-a722-b81c27acd282",
            "text": "Proszę o szczegóły...",
            "author": {
                "login": "Seller_login1",
                "role": "SELLER"
            },
            "createdAt": "2018-09-14T06:36:14.270Z"
        },
        {
            "id": "10d392e2-6ea7-4347-9baf-5fe54a9580e8",
            "text": "Czy mogę prosić o wymianę?",
            "author": {
                "login": "Buyer_login1",
                "role": "BUYER"
            },
            "createdAt": "2018-09-14T06:34:44.439Z"
        },
        {
            "id": "e75d97ba-18a7-4d1b-a7ee-d02ba1a21bba",
            "text": "Niestety towar jest uszkodzony.",
            "attachment": {                                 - załącznik w dyskusji
                "fileName": "Zrzut_ekranu.png",             - nazwa pliku
                "url": "https://upload.allegro.pl/sale/     - adres pliku
                dispute-attachments/731f2401-7b79-4212-be9e-591464526cfe"
            },
            "author": {
                "login": "Buyer_login1",
                "role": "BUYER"
            },
            "createdAt": "2018-09-14T06:34:24.258Z"
        }
    ]
}

Nowa wiadomość w dyskusji

Skorzystaj z POST /sale/disputes/{disputeId}/messages, aby dodać wiadomość w dyskusji.

Wiadomość może mieć dwa typy:

  • REGULAR to standardowa wiadomość. Może zawierać tekst, załącznik lub oba.

  • END_REQUEST to odpowiednik opcji POPROŚ O ZAKOŃCZENIE DYSKUSJI.

Przykładowy request:

  curl -X POST \
  'https://api.allegro.pl/sale/disputes/a38812fa-6fef-4c9c-ac06-a0952b67ba78/messages' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
"text": "Lorem ipsum dolor sit amet,                - wymagane (jeśli nie przesyłasz załącznika)
consectetur adipiscing elit.\n\n\n  
Pellentesque tincidunt, lacus nec interdum pellentesque.",
"attachment":{
    "id": "77b2f474-0b87-4b68-9297-56676bc84a6c"    - wymagane (jeśli nie przesyłasz pola text);
                                                    id załącznika, który uzyskasz metodą
                                                    POST /sale/dispute-attachments/
},
"type": "REGULAR"                                   - wymagane, typ wiadomości:
                                                    REGULAR i END_REQUEST
}'
{
    "id": "962e051e-2509-4ccf-910d-5e5179b975b9",
    "text": "Lorem ipsum dolor sit amet,
    consectetur adipiscing elit.\n\n\n  
    Pellentesque tincidunt, lacus nec interdum pellentesque.",
    "author": {
        "login": "Seller_login1",
        "role": "SELLER"
    },
    "createdAt": "2018-09-17T05:20:56.692Z"
}

Załączniki

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

Pobranie załącznika

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

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/sale/dispute-attachments/66377da8-eee2-4094-8dcf-3540e51c307f' \
  -H 'Authorization: Bearer {token}'
{
...
 "message": {
        "id": "657fc2c1-addf-416a-8129-e2b55740248b",
        "text": "Vestibulum eu interdum ex, p…",
        "attachment": {
            "fileName": "test.jpg",
            "url": "https://upload.allegro.pl/sale/dispute-attachments/95d066c1-ac44-4c7e-8a7f-0c074b848c6e"
        }
...
}

Deklaracja załącznika

Za pomocą POST /sale/dispute-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/dispute-attachments' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/vnd.allegro.public.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://upload.allegro.pl/sale/dispute-attachments/{attachmentId}, aby przesłać załącznik na nasze serwery. W wywołaniu podaj id załącznika {attachmentId}. Otrzymasz go za pomocą POST /sale/dispute-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://upload.allegro.pl/sale/dispute-attachments/66377da8-eee2-4094-8dcf-3540e51c307f \
  -H 'Accept: application/vnd.allegro.public.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 tu.

Lista zasobów podstawowych opisanych w poradniku:

Czy ten artykuł był dla Ciebie przydatny?

Allegro
zamknij

Dostosuj ustawienia wyświetlania

ustawienia dotyczą tylko tej przeglądarki