Allegro REST API

gdzie?

Polska | polski | PLN
  • Informacje podstawowe
  • Główne procesy
  • Uwierzytelnianie i autoryzacja
  • Wzorzec Command
  • Glosariusz
  • Lista metod
  • Pierwsze kroki
  • Wystawianie oferty z produktem
  • Serwisy zagraniczne Allegro
  • Zarządzanie ofertami
  • Oferty wielowariantowe
  • Pasuje do
  • Zarządzanie zgłoszeniami ofert do kampanii
  • Rabaty i promocje
  • Zamówienia
  • Wysyłam z Allegro
  • One Fulfillment by Allegro
  • Dyskusje
  • Konto i dane użytkownika
  • Centrum wiadomości
  • Sprawdzanie opłat
  • Wystawianie ogłoszeń
  • Publiczne oferty
FAQ
  • Aktualności
  • Changelog
Dokumentacja
Regulamin
Kontakt
  • Moje aplikacje
  • Moje aplikacje (sandbox)
  • Newsletter
  1. Allegro REST API
  2. Wystawianie ogłoszeń
Jak wystawić ogłoszenie
Wystaw ogłoszenie w kilku krokach
Niezbędne dane
Kategorie i parametry
Zdjęcia
Tytuł ogłoszenia
Opis ogłoszenia
Draft ogłoszenia
Dane w ogłoszeniu
Pakiet i opcje dodatkowe
Koszt wystawienia
Publikacja ogłoszenia
Status ogłoszenia
Jak zarządzać ogłoszeniem
Statystyki ogłoszeń
Lista zasobów

Jak wystawić ogłoszenie

jak wystawic ogoszenie

Przygotuj draft

Na początku tworzysz draft ogłoszenia przez POST /sale/offers. Takie ogłoszenie oznaczymy w polu status jako "INACTIVE". Draft ogłoszenia musi być kompletny do opublikowania w serwisie. Draft może być zalążkiem do dalszej pracy nad ogłoszeniem. W każdym momencie będziesz mógł uzupełnić draft o więcej informacji za pomocą PUT /sale/offers/{offerId}.

Dzięki draftom możesz:

  • trzymać dane o ogłoszeniach na naszych serwerach
  • łatwo przygotować podgląd ogłoszenia

Ustaw pakiet i opcje dodatkowe dla ogłoszenia

Do draftu ogłoszenia, który zawiera komplet danych przypisz pakiet i opcje dodatkowe.

Najpierw pobierz przez GET /sale/classifieds-packages?category.id={category-id} dostępne pakiety i opcje dodatkowe dla ogłoszenia, następnie do uzupełnionego draftu ogłoszenia przypisz za pomocą PUT /sale/offer-classifieds-packages/{offer-id} wybrane opcje do ogłoszenia.

Wystaw ogłoszenie

Opublikuj ogłoszenie na Allegro.pl. Aby to zrobić, aktywuj je za pomocą akcji ACTIVATE w PUT /sale/offer-publication-commands/{commandId}. Do momentu publikacji ogłoszenia w serwisie, oferta będzie miała status przejściowy - ACTIVATING. Status ACTIVATING dotyczy również ofert zaplanowanych do wystawienia w przyszłości.

Sprawdź status ogłoszenia

Gdy wystawisz ogłoszenie w serwisie, wówczas jego status zmienimy na ACTIVE. Dokładny termin wystawienia takiego ogłoszenia wyświetlamy w polu scheduledAt w odpowiedzi dla GET /sale/offer-publication-commands/{commandId}/tasks. Tą samą metodą możesz również zakończyć ogłoszenie - wystarczy że wykonasz akcję END.

Wystaw ogłoszenie w kilku krokach

Niezbędne dane

Skorzystaj z metod pomocniczych, dzięki którym pobierzesz ID elementów niezbędnych do wystawienia ogłoszenia:

Dane kontaktowe

Do zarządzania kontaktami w REST API udostępniliśmy poniższe zasoby:

  • POST /sale/offer-contacts - chcę utworzyć kontakt,
  • GET /sale/offer-contacts/{contact.id} - chcę pobrać szczegóły danego kontaktu,
  • GET /sale/offer-contacts - chcę pobrać szczegóły wielu kontaktów,
  • PUT /sale/offer-contacts/{contact.id} - chcę zmienić dane kontaktu.

Pamiętaj!

  • nie możesz mieć więcej niż 50 kontaktów,
  • w jednym kontakcie możesz podać maksymalnie:
    • 1 adres e-mail,
    • 2 numery telefonu.

POST /sale/offer-contacts - tym zasobem utworzysz nowy kontakt. Musisz być zalogowany jako wystawiający ogłoszenie.

Przykładowy request:

  curl -X POST \
  'https://api.allegro.pl/sale/offer-contacts' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -H 'Accept: application/vnd.allegro.public.v1+json’ \
  -H 'Authorization: Bearer {token}' \
  -d '{
  "name": "Auta terenowe",      -- nazwa kontaktu; wymagane, maksymalna liczba znaków - 250
  "emails": [                   -- adresy e-mail; możesz podać 1
    {
      "address": "test@test.pl/"
    }
  ],
  "phones": [                   -- nr telefonów; możesz podać maksymalnie 2
    {
      "number": "555-555-666"
    },
    {
      "number": "555555667"
    }
  ]
 }’

Przykładowy response:

  ‘{
    "id": "0c046252-9559-4ecb-8ea3-879f60e46947",   -- identyfikator kontaktu (contact.id)
    "name": "Auta terenowe",                        -- nazwa kontaktu
    "emails": [
        {
            "address": "test@test.pl/"
        }
    ],
    "phones": [
        {
            "number": "+48 55 555 57 77"
        }
    ]
  }’

GET /sale/offer-contacts/{contact.id} - tym zasobem pobierzesz szczegóły danego kontaktu. W URL podaj UUID danego kontaktu.

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/sale/offer-contacts/0c046252-9559-4ecb-8ea3-879f60e46947' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'

Przykładowy response:

  ‘{
    "id": "0c046252-9559-4ecb-8ea3-879f60e46947",       -- identyfikator kontaktu (contact.id)
    "name": "Auta terenowe",                            -- nazwa kontaktu
    "emails": [
        {
            "address": "test@test.pl/"
        }
    ],
    "phones": [
        {
            "number": "+48 55 555 57 77"
        }
    ]
  }’

GET /sale/offer-contacts - tym zasobem pobierzesz szczegóły wszystkich kontaktów przypisanych do konta danego usera.

Przykładowy request:

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

Przykładowy response:

  ‘{
    "contacts": [
        {
            "id": "0c046252-9559-4ecb-8ea3-879f60e46947",   -- identyfikator kontaktu (contact.id)
            "name": "Auta terenowe",                        -- nazwa kontaktu
            "emails": [
                {
                    "address": "test@test.pl/"
                }
            ],
            "phones": [
                {
                    "number": "+48 788 788 788"
                },
                {
                    "number": "+48 75 575 57 55"
                }
            ]
        },
        {
            "id": "af1ccfd7-2753-4ed3-bdda-c78eb14442ab",
            "name": "Auta osobowe",
            "emails": [
                {
                    "address": "test@test.pl/"
                }
            ],
            "phones": [
                {
                    "number": "+48 55 555 57 77"
                }
            ]
        },
        {
            "id": "27869b31-048e-43a0-bdc0-52b922f278a5",
            "name": "Ciężarówki",
            "emails": [
                {
                    "address": "test@test.pl/"
                }
            ],
            "phones": []
        }
    ]
   }’

PUT /sale/offer-contacts/{contact.id} - tym zasobem możesz zaktualizować informacje w kontakcie. W URL podaj UUID danego kontaktu.

Przykładowy request:

  curl -X PUT
  'https://api.allegro.pl//sale/offer-contacts/12f43efd-2369-480d-9f945178eeb9c663' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}' \
  -d '{
   "name": "Auta terenowe",
   "emails": [
     {
       "address": "test@test.pl/"
     }
   ],
   "phones": [
     {
       "number": "555-555-777"
     }
   ]
 }'

Przykładowy response:

  ‘{
    "id": "0c046252-9559-4ecb-8ea3-879f60e46947",
    "name": "Auta terenowe",
    "emails": [
        {
            "address": "test@test.pl/"
        }
    ],
    "phones": [
        {
            "number": "+48 55 555 57 77"
        }
    ]
  }’

Lista pakietów i opcji dodatkowych

Jeśli chcesz wystawić ogłoszenie, musisz wybrać z jakiego pakietu chcesz skorzystać i czy dodatkowo chcesz dokupić dodatkowe opcje promowania. Do zarządzania pakietami i opcjami dodatkowymi w REST API udostępniliśmy poniższe zasoby:

  • GET /sale/classifieds-packages?category.id={category-id} - chcę pobrać dostępne pakiety i opcje dodatkowe w danej kategorii,
  • GET /sale/classifieds-packages/{package-id} - chcę pobrać szczegóły danego pakietu / opcji dodatkowej.

Najpierw przez GET /sale/classifieds-packages?category.id={category-id} pobierz identyfikatory dostępnych pakietów i opcji dodatkowych w danej kategorii.

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/sale/classifieds-packages?category.id={category-id}' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json'

Przykładowy response:

  '{
    "packages": [{
            "id": "6174be19-56f9-484b-b72c-43b0b00785e8",   -- identyfikator pakietu
            "type": "BASE"                                  -- typ pakietu
            "name": "Podstawowy",                           -- nazwa pakietu
            "publication": {
                "duration": "PT960H"                        -- czas trwania ogłoszenia
            },
            promotions: [{                                  -- rodzaje wyróżnień dostępnych
                                                            w danym pakiecie
                    "name": "bold"
                    "duration": "PT240H"
                },
                {
                    "name": "emphasized"
                    "duration": "PT120H"
                },
                ...
            ],
            "extensions": [{                                -- dostępne rozszerzenia w ramach
                                                            danego pakietu
                "name": "autocentrumExport",
                "description": "Eksport ogłoszenia do autocentrum"
            }]
        },
        {
            "id": "3174be19-56f9-484b-b72c-43b0b00785e8",
            "type": "EXTRA"                                 -- typ opcji dodatkowej, którą możesz
                                                            dokupić do pakietu
            "name": "Dodatkowe wyróżnienie na 10 dni",
                                                            -- nazwa dostępnej opcji dodatkowej
            promotions: [{                                  -- rodzaje wyróżnień dostępnych
                                                            w danej opcji dodatkowej do pakietu
                    "name": "bold"
                    "duration": "PT240H"
                },
                {
                    "name": "emphasized"
                    "duration": "PT120H"
                },
                ...
            ]
        }
    ]
  }'

Teraz wykorzystaj GET /sale/classifieds-packages/{package-id} i pobierz szczegółowe informacja na temat danego pakietu i dostępnych do niego opcji dodatkowych.

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/sale/classifieds-packages/6174be19-56f9-484b-b72c-43b0b00785e8' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json'

 '{
    "id": "6174be19-56f9-484b-b72c-43b0b00785e8",   -- identyfikator pakietu
    "type": "BASE"                                  -- typ pakietu
    "name": "Podstawowy",                           -- nazwa pakietu
    "publication": {
        "duration": "PT960H"                        -- czas trwania ogłoszenia
    },
    promotions: [{                                  -- rodzaje promowań dostępnych
                                                    w danym pakiecie
            "name": "bold"
            "duration": "PT240H"
        },
        {
            "name": "emphasized"
            "duration": "PT120H"
        },
        ...
    ],
    "extensions": [{                                -- dostępne rozszerzenia w
                                                    danym pakiecie
            "name": "autocentrumExport",
            "description": "Eksport ogłoszenia do autocentrum"
        }
    }]'

Kategorie i parametry

Skorzystaj z poniższych zasobów, dzięki którym pobierzesz identyfikator wybranej kategorii i parametry, jakie powinieneś uzupełnić:

Identyfikator kategorii

Za pomocą GET /sale/categories?parent.id={categoryId} pobierzesz listę kategorii, które należą do podanej kategorii nadrzędnej (lub listę kategorii głównych). Pamiętaj, że ogłoszenie wystawisz tylko w kategorii najniższego rzędu, która jest oznaczona "leaf": true.

Jeśli wywołasz GET /sale/categories bez podania kategorii, wówczas otrzymasz identyfikatory głównych kategorii na Allegro. Takie identyfikatory możesz następnie użyć w wywołaniu zasobu, aby dotrzeć do interesującej kategorii najniższego rzędu (pamiętaj, że ogłoszenie wystawisz tylko w kategorii najniższego rzędu, która jest oznaczona "leaf": true.).

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/sale/categories?parent.id=4032' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}' 

Przykładowy response:

  '{
    "categories": [
        {
            "id": "249626",
            "name": "Seria 2",
            "parent": {
                "id": "4032"
            },
            "leaf": true,                               -- informacja czy jest to kategoria
                                                        najniższego rzędu w której możesz
                                                        wystawić ogłoszenie
            "options": {
                "variantsByColorPatternAllowed": true,  -- informacja, czy parametr można
                                                        wykorzystać w wielowariantowości.
                                                        dostępne są dwie wartości:
                                                        true (tak) i false (nie).
                "advertisement": true,                  -- informacja, czy w danej kategorii
                                                        można wystawić ogłoszenie
                "advertisementPriceOptional": false     -- informacja, czy w danej kategorii
                                                        opcjonalnie można wystawić ogłoszenie
                                                        bez ceny
            }
        },
        {
    …
        },
        {
            "id": "146805",
            "name": "Seria 4",
            "parent": {
                "id": "4032"
            },
            "leaf": true,
            "options": {
                "variantsByColorPatternAllowed": true,
                "advertisement": true,
                "advertisementPriceOptional": false
            }
        }
    ]
 }'

Parametry

Za pomocą GET /sale/categories/{categoryId}/parameters pobierzesz listę parametrów, które są dostępne w kategorii, którą wskazałeś. Każdorazowo zwracamy listę parametrów, które możesz ustawić w kategorii jaką podałeś w wywołaniu.

Parametry pobieraj, sprawdzaj i aktualizuj, w szczególności te słownikowe, bo mogą zmieniać się ich wartości.

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/sale/categories/57968/parameters' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'
Kliknij aby zobaczyć response
toggle visibility
  ‘{
    "parameters": [                         -- lista dostępnych parametrów dla
                                            wskazanej kategorii
        {
            "id": "11323",                  -- identyfikator danego parametru
            "name": "Stan",                 -- nazwa parametru
            "type": "dictionary",           -- typ parametru, obecnie mamy dostępne wartości:
                                            dictionary (słownik wyboru, może być jednokrotnego,
                                            bądź wielokrotnego wyboru, w zależności od wartości
                                            w polu multipleChoices), integer (liczba całkowita),
                                            float (liczby zmiennoprzecinkowe), string (możesz dodać
                                            jedną lub wiele wartości)
            "required": true,               -- informacja, czy dany parametr jest obowiązkowy
            "unit": null,
            "options": {
                "variantsAllowed": true,    -- informacja, czy parametr można
                                            wykorzystać w wielowariantowości.
                "variantsEqual": false      -- informacja, czy parametr jest weryfikujący.
                                            Jeśli otrzymamy wartość true,to wszystkie warianty
                                            oferty muszą mieć tą samą wartości w tym parametrze
            },
            "dictionary": [
                {
                    "id": "11323_1",        -- wartość parametru jaką powinieneś przekazać w
                                            modelu ogłoszenia
                    "value": "Nowy"
                },
                {
                    "id": "11323_2",
                    "value": "Używany"
                },
                {
                    "id": "11323_238062",
                    "value": "Uszkodzony"
                }
            ],
            "restrictions": {
                "multipleChoices": false    -- parametr z możliwym wyborem jednej lub
                                            wielu wartości
            }
        },
        {
            "id": "1",
            "name": "Rok produkcji",
            "type": "integer",
            "required": true,
            "unit": null,
            "options": {
                "variantsAllowed": true,
                "variantsEqual": false
            },
            "restrictions": {
                "min": 1900,
                "max": 2100,
                "range": false              -- parametr zakresowy. Sekcje range
                                            min i max oznaczają minalną i maksymalna
                                            wartość danego parametru.
            }
        },
       …
        {
            "id": "215898",
            "name": "Numer VIN",
            "type": "string",
            "required": false,
            "unit": null,
            "options": {
                "variantsAllowed": false,
                "variantsEqual": false
            },
            "restrictions": {
                "minLength": 12,
                "maxLength": 17,
                "allowedNumberOfValues": 1  -- informacja o tym, ile wartości możesz
                                            podać w danym parametrze
            }
        }
    ]
  }’

Dla metod PUT lub POST podaj identyfikatory, a nie wartości parametru.

Przykład poprawnej struktury parametrów podczas wystawiania ogłoszenia w zależności od jego typu:

  • dla parametrów słownikowych (wybór jednego lub wielu wartości z wielu)
    {
     "id": "209878",
     "valuesIds": [
     "209878_2",
     "209878_1"
     ],
     "values": [],
     "rangeValue": null
    }
  • dla parametrów zakresowych

    {
     "id": "212570",
     "valuesIds": [],
     "values": [],
     "rangeValue": {
         "from": "80",
         "to": "100"
      }
    }
  • dla parametrów w których samodzielnie uzupełniasz ich wartość

    {
     "id": "216325",
     "valuesIds": [],
     "values": [
         "zielony",
         "żółty",
         "czerwony"
     ],
     "rangeValue": null
    }

Zdjęcia

Przy pomocy POST /sale/images prześlesz zdjęcie na nasze serwery po protokole HTTP i HTTPS (tylko z ważnym certyfikatem). W odpowiedzi otrzymasz link do grafiki, którą dodałeś.

Informacje odnośnie zasad dla zdjęć w galerii i opisie znajdziesz tutaj.

Możesz przesłać zdjęcie na dwa sposoby:

  • w postaci linku
    curl -X POST \
    'https://upload.allegro.pl/sale/images' \
    -H 'Authorization: Bearer {token}' \
    -H 'Accept: application/vnd.allegro.public.v1+json' \
    -H 'Content-Type: application/vnd.allegro.public.v1+json' \
    -d '{
         "url":"https://imgur.com/1aOIvg3E.jpg"       -- wymagane, link do obrazka
        }'
  • w postaci binarnej
  curl -X POST \
    'https://upload.allegro.pl/sale/images'
    -H 'Authorization: Bearer {token}' \
    -H 'Accept: application/vnd.allegro.public.v1+json' \
    -H 'Content-Type: "image/jpeg", "image/png"' \
    -H 'Accept-Language: pl-PL', (albo en-EN) \
    --data-binary "@file_to_upload.png"                -- wymagane, zawartość pliku z
                                                       obrazkiem w postaci binarnej

Przykładowy response:

  • 401 - unauthorized

  • 413 - za duży obrazek

  • 415 - nieodpowiedni typ obrazka

  • 201 - poprawnie dodany obrazek, response body:

    {
        "expiresAt":"2018-04-06T16:38:04.930Z",            -- data, kiedy usuniemy grafikę z
                                                           serwera. Nie usuniemy jej, jeśli
                                                           wykorzystasz grafikę w ofercie.
        "location":"https://1.allegroimg.com/original/110843/cd7d40b84968ab8d79ab8a2e47a1"
                                                           -- link do zdjęcia, które przesłałeś
    }

Tytuł ogłoszenia

Dopuszczamy maksymalnie 50 znaków w tytule ogłoszenia. Listę liter, cyfr i znaków specjalnych jakie pozwalamy wprowadzić w tytule ogłoszenia znajdziecie poniżej.

Litery: 'a','b','c','d','e','f','g','h','i','j','k','l','m','n','o','p','q','r','s','t','u','w','v','x','y','z',
'ä','ö','ü','ø','ò','ß','0','á','č','ě','í','ř','š','ů','ú','ý','ž','œ','æ','à','â','ç','é','è','ê','ë','î',
'ï','ô','û','ù','ü','ÿ','€','×','ą','ć','ę','ł','ń','ó','ś','ź','ż','µ','⌀',

Cyfry: '0','1','2','3','4','5','6','7','8','9',

Znaki specjalne:'!','@','[',']','#','$','%','^','&','*','{','}','(',')','.',',','/','\\','|','?',' ',';','~','²','³',
'`','\'','’','´','\"','”','"','„','“','″','<','>','_','\t',':','-','=','+','0','…','–','°','°'

Niektóre litery jak i znaki specjalne są zamieniane na encje, dlatego zajmują więcej niż jeden znak. Przykładowo znak & jest encjonowany jako &amp;amp; dlatego zajmuje 5 miejsc w tytule.

Opis ogłoszenia

Szczegółowe informacje o zasadach dla ofert znajdziesz na stronie dla sprzedających.

Najważniejsze informacje

  • maksymalna wielkość całego opisu jaki możesz przesłać to 40000 bajtów

  • możesz korzystać tylko z określonych znaczników HTML:

    • h1 - tytuł

    • h2 - podtytuł

    • p - akapit

    • ul - wypunktowanie

    • ol - wylistowanie

    • li - element listy

    • b - pogrubienie.

  • możesz wykorzystać tylko zdjęcia z galerii w ofercie, które przesyłasz w tablicy images.

Sugerujemy, by pierwszy opis przygotować przez formularz wystawiania. Skorzystaj z wszystkich rodzajów sekcji i opcji formatowania i pobierz ofertę za pomocą GET /sale/offers/{offerId}. W ten sposób najłatwiej dowiesz się jak poprawnie przygotować opis.

Jak wygląda struktura opisu
Sekcje (sections)

Opis oferty składa się z przynajmniej jednej sekcji, które umieszczasz w tablicy sections. Opis może mieć max. 100 sekcji.

    {
        "sections": [
            { section1 },
            { section2 },
             ...
            ]
    }
Elementy opisu (item)

Sekcje grupują elementy opisu (item) w widok kolumnowy:

  • jedna kolumna, która zajmuje całą szerokość ekranu
     {
          "items" : [
          { item1 }
          ]
     }
  • dwie kolumny, z których każda zajmuje połowę ekranu
     {
          "items" : [
          { item1 }
          { item2 }
          ]
     }
  • nie możesz utworzyć sekcji z większą liczbą kolumn. struktura
Typy treści w opisie

Tekst

    {
      "type": "TEXT",
      "content": "<p>opis tekstowy</p>"
    }

Możesz tu użyć określonych znaczników HTML:

  • h1 - tytuł
  • h2 - podtytuł
  • p - akapit
  • ul - wypunktowanie
  • ol - wylistowanie
  • li - element listy
  • b - pogrubienie.

Najważniejsze zasady

  1. Treści musisz umieścić w znacznikach HTML. W znacznikach HTML używaj tylko małych liter.

    Poprawnie

    {
      "type": "TEXT",
      "content": "<p>opis tekstowy</p>"
    }

    Niepoprawnie

    {
      "type": "TEXT",
      "content": "opis tekstowy"
    }
  1. Nie możesz dodatkowo formatować tagów h1 i h2.

    Poprawnie

    {
       "type": "TEXT",
       "content": "<h1>Tytuł sekcji</h1>"
    }

    Niepoprawnie

    {
      "type": "TEXT",
      "content": "<h1><b>Tytuł sekcji<b></h1>"
    }
  1. Możesz użyć pogrubienia < b > < /b > w znacznikach:

    • < p > < /p > - akapit
    • < ul > < /ul > - lista wypunktowana
    • < ol > < /ol > - lista numerowana
  2. Możesz użyć znacznika akapitu < p > < /p > w znacznikach:

    • < ul > < /ul > - lista wypunktowana
    • < ol > < /ol > - lista numerowana

Przykład, jak poprawnie łączyć znaczniki HTML:

    <h1>Lorem ipsum dolor sit amet, consectetur adipiscing elit</h1>
    <p><b>Aliquam vitae nisi ac lectus gravida rhoncus</b>. Vivamus egestas, orci quis
    fermentum sollicitudin, leo urna pellentesque quam, ut mattis risus nisl sed dolor.</p>
    <ul>
        <li><b>Nulla eu justo ut velit pellentesque porta.</b></li>
        <li>Pellentesque eget arcu id ligula consequat fermentum at nec velit. Maecenas vitae nunc
        non ante aliquet facilisis nec id leo.</li>
        <li>Sed vitae metus vel lorem iaculis rhoncus.</li> <li>Nullam nec felis felis.</li>
    </ul>
    <ol>
        <li><p><b>In eget vulputate purus</b></p></li>
        <li><p>Integer a pharetra odio.</p></li>
        <li><p>Vestibulum ut vestibulum diam.</p></li>
        <li><p>Phasellus quis tempor ipsum, at tincidunt nibh.</p></li>
        <li><p>Nulla sollicitudin, libero sit amet fermentum iaculis.</p></li>
    </ol>

Zdjęcia

Możesz użyć tylko takich zdjęć, które wcześniej przesłałeś za pomocą POST /sale/images.

    {
        "type": "IMAGE",
        "url": "https://d.allegroimg.com/original/0313bd/338d11a74b059fea784beee0084d"
    }
Przykładowa struktura opisu
{
    [
        {
            "sections": [{
            "items": [{
                "type": "TEXT",
                "content": "<p>tekstowy opis przedmiotu</p>"
            }]
        }, {
            "items": [{
                "type": "IMAGE",
                "url": "https://d.allegroimg.com/original/0313bd/338d11a74b059fea784beee0084d"
            }]
        }, {
            "items": [{
                "type": "TEXT",
                "content": "<p>tekstowy opis przedmiotu</p>"
            }, {
                "type": "IMAGE",
                "url": "https://f.allegroimg.com/original/037738/bc72c2f24784b50774d7d078c7ef"
            }]
        }, {
            "items": [{
                "type": "IMAGE",
                "url": "https://0.allegroimg.com/original/032ac4/9c10035846bb970cf208f6982fc0"
            }, {
                "type": "IMAGE",
                "url": "https://d.allegroimg.com/original/0313bd/338d11a74b059fea784beee0084d"
            }]
        }]
    }

Draft ogłoszenia

Zrobisz to za pomocą POST /sale/offers. Musisz być uwierzytelnionym i zautoryzowanym użytkownikiem. Gdy utworzysz DRAFT ogłoszenia, możesz go później opublikować w serwisie. Możesz przesłać częściowe dane (przynajmniej tytuł i kategorię ogłoszenia) - taki DRAFT ogłoszenia uzupełnisz później o wszystkie wymagane dane przez PUT /sale/offers/{offerId}. Jeśli prześlesz niekompletne dane, to w polu “validation” wyświetlimy:

  • co powinieneś uzupełnić,
  • błędy, jakie pojawiły się w twoim ofercie.

    Przykładowy request:

    curl -X POST \
    'https://api.allegro.pl/sale/offers' \
    -H 'Authorization: Bearer {token}' \
    -H 'Accept: application/vnd.allegro.public.v1+json' \
    -H 'Content-Type: application/vnd.allegro.public.v1+json' \
    -d '{
     "name": "BMW X5 e53",                           -- wymagane, tytuł ogłoszenia
     "category": {
         "id": "257150"                              -- wymagane, kategoria najniższego rzędu,
                                                     w której znajduje się oferta. Aktualne
                                                     numery kategorii pobierzesz za pomocą
                                                     GET /sale/categories?parent.id={categoryId}
    }
    }'
Kliknij aby zobaczyć response
toggle visibility
{

  '{
    "id": "6206178738",
    "name": "BMW X5 e53",
    "category": {
        "id": "57968"
    },
    "parameters": [],
    "ean": null,
    "description": null,
    "compatibilityList": {
        "items": null
    },
    "images": [],
    "sellingMode": null,
    "stock": null,
    "publication": {
        "duration": null,
        "status": "INACTIVE",
        "startingAt": null,
        "endingAt": null
    },
    "delivery": null,
    "payments": {
        "invoice": "NO_INVOICE"
    },
    "afterSalesServices": null,
    "additionalServices": null,
    "sizeTable": null,
    "fundraisingCampaign": null,
    "promotion": null,
    "location": null,
    "external": null,
    "attachments": [],
    "contact": null,
    "validation": {
        "errors": [
            {
                "code": "VALIDATION_ERROR",
                "message": "Location may not be empty.",
                "details": "",
                "path": "",
                "userMessage": "Location may not be empty."
            },
            {
                "code": "VALIDATION_ERROR",
                "message": "Payments may not be empty.",
                "details": "",
                "path": "",
                "userMessage": "Payments may not be empty."
            },
            {
                "code": "VALIDATION_ERROR",
                "message": "Please describe your offer.",
                "details": "",
                "path": "",
                "userMessage": "Please describe your offer."
            },
            {
                "code": "VALIDATION_ERROR",
                "message": "Missing required parameters: Stan, Rok produkcji, Przebieg [km], Pojemność silnika [cm3], Liczba drzwi, Kolor, Uszkodzony.",
                "details": "",
                "path": "",
                "userMessage": "Missing required parameters: Stan, Rok produkcji, Przebieg [km], Pojemność silnika [cm3], Liczba drzwi, Kolor, Uszkodzony."
            },
            {
                "code": "VALIDATION_ERROR",
                "message": "You must select at least one selling mode and provide the required prices.",
                "details": "",
                "path": "",
                "userMessage": "You must select at least one selling mode and provide the required prices."
            },
            {
                "code": "VALIDATION_ERROR",
                "message": "After sales service conditions (return policies, implied warranties) are required by company account.",
                "details": "",
                "path": "",
                "userMessage": "After sales service conditions (return policies, implied warranties) are required by company account."
            }
        ],
        "validatedAt": "2019-02-26T11:33:38.599Z"
    },
    "b2b": {
        "buyableOnlyByBusiness": false
    },
    "createdAt": "2019-02-26T11:33:38Z",
    "updatedAt": "2019-02-26T11:33:38.6Z"
  }'

Dane w ogłoszeniu

Za pomocą PUT /sale/offers/{offerId} uzupełnij dane w drafcie lub w wystawionym ogłoszeniu. Abyś mógł opublikować draft, prześlij kompletny zestaw informacji. Jeśli prześlesz niekompletne dane, to w polu validation wyświetlimy:

  • co powinieneś uzupełnić,
  • błędy, jakie pojawiły się w twoim ogłoszeniu.

Jeżeli chcesz zaktualizować trwające ogłoszenie, pobierz jego dane przez GET /sale/offers/{offerId}. Następnie, gdy aktualizujesz ogłoszenie, prześlij pełną strukturę danych, jaką wcześniej otrzymałeś w odpowiedzi. Nawet jeśli aktualizujesz wartość tylko w jednym polu, to musisz przesłać pełną strukturę pól ogłoszenia.

Poniżej opisaliśmy tylko pola, które musisz uzupełnić, aby wystawić ogłoszenie. Z pozostałych pól skorzystaj jeśli chcesz wystawić ofertę, więcej na ten temat znajdziesz w naszym poradniku.

Kliknij aby zobaczyć request
toggle visibility
curl -X PUT \
  'https://api.allegro.pl/sale/offers/6206178738' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
    "id": "6206178738",                             -- numer identyfikacyjny ogłoszenia
    "name": "BMW X5 e53",                           -- wymagane, tytuł ogłoszenia
    "category": {
        "id": "57968"                               -- wymagane, kategoria najniższego rzędu, w której
                                                    znajduje się oferta. Aktualne numery kategorii
                                                    pobierzesz za pomocą
                                                    GET /sale/categories?parent.id={categoryId}
    },
    "parameters": [                                 -- wymagane, parametry ogłoszenia, aktualne parametry
                                                    dostępne w danej kategorii
                                                    sprawdzisz za pomocą
                                                    GET /sale/categories/{categoryId}/parameters
        {
            "id": "11323",
            "valuesIds": [
                "11323_2"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "1",
            "valuesIds": [],
            "values": [
                "2003"
            ],
            "rangeValue": null
        },
        {
            "id": "4",
            "valuesIds": [],
            "values": [
                "370000"
            ],
            "rangeValue": null
        },
        {
            "id": "5",
            "valuesIds": [],
            "values": [
                "3000"
            ],
            "rangeValue": null
        },
        {
            "id": "14",
            "valuesIds": [],
            "values": [
                "189"
            ],
            "rangeValue": null
        },
        {
            "id": "12",
            "valuesIds": [
                "12_3"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "128789",
            "valuesIds": [],
            "values": [
                "5"
            ],
            "rangeValue": null
        },
        {
            "id": "3",
            "valuesIds": [
                "3_246550"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "178",
            "valuesIds": [
                "178_1"
            ],
            "values": [],
            "rangeValue": null
        }
    ],
    "ean": null,
    "description": {                                -- wymagane, opis ogłoszenia; więcej o tym jak
                                                    skonstruować poprawnie opis ogłoszenia znajdziesz tutaj
        "sections": [
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content":  "<p>opis tekstowy</p>"
                    }
                ]
            }
        ]
    },
    "compatibilityList": null,
    "images": [                                     -- wymagane ścieżki obrazków, zdjęcia
                                                    prześlesz przy pomocy POST /sale/images.
                                                    Pierwsze zdjęcie w tablicy jest jednocześnie
                                                    pierwszym zdjęciem w ogłoszeniu (miniaturką).
        {
            "url": "https://a.allegroimg.allegrosandbox.pl/original/035b44/6932986c4333a35d8010bdd1993b"
        },
        {
            "url": "https://a.allegroimg.allegrosandbox.pl/original/03cea0/b7bff1db4deab57ad277891442aa"
        }
    ],
    "sellingMode": {
        "format": "ADVERTISEMENT",                  -- wymagane, format sprzedaży ADVERTISEMENT (ogłoszenie)
        "price": {
            "amount": "33000",                      -- wymagane, cena dla ogłoszenia
            "currency": "PLN"
        },
        "startingPrice": null,
        "minimalPrice": null
    },
    "stock": null,
    "publication": {
        "duration": null,                           -- zawsze null, nie edytuj tych wartości, zmienią się
                                                    one automatycznie po przypisaniu odpowiedniego pakietu i opcji
                                                    dodatkowych przy pomocy
                                                    PUT /sale/offer-classifieds-packages/{offer-id}.
        "status": "INACTIVE",                       -- status ogłoszenia, dostępne są obecnie dwie
                                                    wartości: ACTIVE (ogłoszenie aktywne w serwisie),
                                                    INACTIVE (ogłoszenie nieaktywne)
        "startingAt": null,                         -- niewymagane, czas startu ogłoszenia,
                                                    dotyczy ofert do publikacji w przyszłości
        "endingAt": null                            -- niewymagane, data zakończenia ogłoszenia
    },
    "delivery": {
        "shippingRates": null,
        "handlingTime": null,
        "additionalInfo": null,
        "shipmentDate": null
    },
    "payments": {
        "invoice": "NO_INVOICE"                     -- wymagane, informacja o fakturze;
                                                    obecnie dostępne są 4 wartości: VAT (faktura VAT);
                                                    VAT_MARGIN (faktura VAT marża);
                                                    WITHOUT_VAT (faktura bez VAT);
                                                    NO_INVOICE (nie wystawiam faktury)
    },
    "afterSalesServices": null,
    "additionalServices": null,
    "sizeTable": null,
    "fundraisingCampaign": null,
    "promotion": null,                              -- zawsze null, nie edytuj tych wartości, zmienią się
                                                    one automatycznie po przypisaniu odpowiedniego
                                                    pakietu i opcji dodatkowych przy pomocy
                                                    PUT /sale/offer-classifieds-packages/{offer-id}.
    "location": {                                   -- wymagane, informacja o lokalizacji
        "countryCode": "PL",                        -- wymagane, kod kraju zgodny ze
                                                    standardem ISO 3166-1 alpha-2
        "province": "WIELKOPOLSKIE",                -- wymagane dla countryCode “PL”, województwo,
                                                    dostępne wartości: DOLNOSLASKIE; KUJAWSKO_POMORSKIE;
                                                    LUBELSKIE; LUBUSKIE; LODZKIE; MALOPOLSKIE; MAZOWIECKIE;
                                                    OPOLSKIE; PODKARPACKIE; PODLASKIE; POMORSKIE; SLASKIE;
                                                    SWIETOKRZYSKIE; WARMINSKO_MAZURSKIE; WIELKOPOLSKIE;
                                                    ZACHODNIOPOMORSKIE. Dla innych krajów
                                                    nie należy podawać tej wartości.
        "city": "Poznań",                           -- wymagane, miejscowość
        "postCode": "60-166"                        -- wymagane dla adresów w Polsce,
                                                    kod pocztowy
    },
    "external": {                                   -- niewymagany, zewnętrzny ID / sygnatura,
                                                    którą nadaje sprzedający, np. aby powiązać ogłoszenie
                                                    z produktem w swoim magazynie. Możesz wprowadzić tutaj
                                                    dowolny ciąg znaków - będzie on dostępny również po
                                                    wznowieniu ogłoszenia.
        "id":"4131asdsad40011"
                },
    "attachments": [],
    "contact": {                                    -- wymagane, identyfikator danych kontaktowych
                                                    pobierzesz go za pomocą metody,
                                                    GET /sale/offer-contacts
        "id": "0c046252-9559-4ecb-8ea3-879f60e46947"
    },
    "validation": {
        "errors": [],                               -- informacje o ewentualnych błędach
        "validatedAt": "2019-02-26T11:33:38.599Z"   -- informacje, kiedy odbyła się
                                                    ostatnia walidacja ogłoszenia
    },
    "b2b": {
        "buyableOnlyByBusiness": false              -- oferta dla biznesu (true - tak, false - nie)
    },
    "createdAt": "2019-02-26T11:33:38Z",            -- data utworzenia ogłoszenia
    "updatedAt": "2019-02-26T11:33:38.6Z"           -- data ostatniej aktualizacji ogłoszenia
}'
Kliknij aby zobaczyć response
toggle visibility
‘{
    "id": "6206178738",
    "name": "BMW X5 e53",
    "category": {
        "id": "57968"
    },
    "parameters": [
        {
            "id": "11323",
            "valuesIds": [
                "11323_2"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "1",
            "valuesIds": [],
            "values": [
                "2003"
            ],
            "rangeValue": null
        },
        {
            "id": "4",
            "valuesIds": [],
            "values": [
                "370000"
            ],
            "rangeValue": null
        },
        {
            "id": "5",
            "valuesIds": [],
            "values": [
                "3000"
            ],
            "rangeValue": null
        },
        {
            "id": "14",
            "valuesIds": [],
            "values": [
                "189"
            ],
            "rangeValue": null
        },
        {
            "id": "12",
            "valuesIds": [
                "12_3"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "128789",
            "valuesIds": [],
            "values": [
                "5"
            ],
            "rangeValue": null
        },
        {
            "id": "3",
            "valuesIds": [
                "3_246550"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "178",
            "valuesIds": [
                "178_1"
            ],
            "values": [],
            "rangeValue": null
        }
    ],
    "ean": null,
    "description": {
        "sections": [
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content":  "<p>opis tekstowy</p>"
                    }
                ]
            }
        ]
    },
    "compatibilityList": {
        "items": null
    },
    "images": [
        {
            "url": "https://a.allegroimg.allegrosandbox.pl/original/035b44/6932986c4333a35d8010bdd1993b"
        },
        {
            "url": "https://a.allegroimg.allegrosandbox.pl/original/03cea0/b7bff1db4deab57ad277891442aa"
        }
    ],
    "sellingMode": {
        "format": "ADVERTISEMENT",
        "price": {
            "amount": "33000",
            "currency": "PLN"
        },
        "startingPrice": null,
        "minimalPrice": null
    },
    "stock": null,
    "publication": {
        "duration": null,
        "status": "INACTIVE",
        "startingAt": null,
        "endingAt": null
    },
    "delivery": {
        "shippingRates": null,
        "handlingTime": null,
        "additionalInfo": null,
        "shipmentDate": null
    },
    "payments": {
        "invoice": "NO_INVOICE"
    },
    "afterSalesServices": null,
    "additionalServices": null,
    "sizeTable": null,
    "fundraisingCampaign": null,
    "promotion": null,
    "location": {
        "countryCode": "PL",
        "province": "WIELKOPOLSKIE",
        "city": "Poznań",
        "postCode": "60-166"
    },
    "external": {
        "id": "4131asdsad40011"
    },
    "attachments": [],
    "contact": {
        "id": "0c046252-9559-4ecb-8ea3-879f60e46947"
    },
    "validation": {
        "errors": [],
        "validatedAt": "2019-02-26T11:57:05.352Z"
    },
    "b2b": {
        "buyableOnlyByBusiness": false
    },
    "createdAt": "2019-02-26T11:33:38Z",
    "updatedAt": "2019-02-26T11:57:05.352Z"
  }’

Pakiet i opcje dodatkowe

Wcześniej wybrany pakiet i opcje dodatkowe przypisz przy pomocy PUT /sale/offer-classifieds-packages/{offer-id} do danego draftu ogłoszenia wybrany pakiet i opcje dodatkowe. Musisz być zalogowany jako użytkownik, który utworzył dany draft ogłoszenia.

Pakiety możesz zmieniać tylko do momentu opublikowania ogłoszenia. Do aktywnego ogłoszenia możesz dodawać tylko dodatkowe opcje promowania.

Przykładowy request:

 {
  curl -X PUT \
  'https://api.allegro.pl/sale/offer-classifieds-packages/6206178738' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
    "basePackage": {
        "id": "3174be19-56f9-484b-b72c-43b0b00785e8"        -- identyfikator pakietu
    },
    "extraPackages": [{
            "id": "3174be19-56f9-484b-b72c-43b0b00785e8"    -- identyfikator opcji dodatkowych,
                                                            które chcesz dokupić do danego pakietu
        },
        {
            "id": "3174be19-56f9-484b-b72c-43b0b00785e6"
        }
    ]
 }'

Przykładowy response:

 Status 200 OK

Koszt wystawienia

Jeśli masz już skompletowane pełne ogłoszenie z przypisanym pakietem, to możesz przy pomocy POST /pricing/offer-fee-preview sprawdzić koszt wystawienia takiego ogłoszenia. W body podaj całą strukturę jaką otrzymasz po pobraniu danego ogłoszenia przy pomocy GET /sale/offers/{offerId} , a także wybrane pakiety i opcje dodatkowe, które możesz pobrać przez GET /sale/offer-classifieds-packages/{offer-id}.

Kliknij aby zobaczyć request
toggle visibility
curl -X POST \
'https://api.allegro.pl/pricing/fee-preview' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json'  \
-H 'Authorization: Bearer {token}' \
-H 'Accept-Language: PL' \
-d '{
    “offer”: {
    "id": "6206178738",
    "name": "BMW X5 e53",
    "category": {
    "id": "57968"
    },
    "parameters": [
        {
            "id": "11323",
            "valuesIds": [
                "11323_2"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "1",
            "valuesIds": [],
            "values": [
                "2005"
            ],
            "rangeValue": null
        },
        {
            "id": "4",
            "valuesIds": [],
            "values": [
                "150000"
            ],
            "rangeValue": null
        },
        {
            "id": "5",
            "valuesIds": [],
            "values": [
                "3000"
            ],
            "rangeValue": null
        },
        {
            "id": "14",
            "valuesIds": [],
            "values": [
                "231"
            ],
            "rangeValue": null
        },
        {
            "id": "12",
            "valuesIds": [
                "12_3"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "128789",
            "valuesIds": [],
            "values": [
                "5"
            ],
            "rangeValue": null
        },
        {
            "id": "3",
            "valuesIds": [
                "3_4"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "178",
            "valuesIds": [
                "178_1"
            ],
            "values": [],
            "rangeValue": null
        }
    ],
    "ean": null,
    "description": {
        "sections": [
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content":  "<p>opis tekstowy</p>"
                    }
                ]
            }
        ]
    },
    "compatibilityList": null,
    "images": [
        {
            "url": "https://a.allegroimg.allegrosandbox.pl/original/035b44/6932986c4333a35d8010bdd1993b"
        },
        {
            "url": "https://a.allegroimg.allegrosandbox.pl/original/03cea0/b7bff1db4deab57ad277891442aa"
        }
    ],
    "sellingMode": {
        "format": "ADVERTISEMENT",
        "price": {
            "amount": "33000",
            "currency": "PLN"
        },
            "startingPrice": null,
            "minimalPrice": null
            },
        "stock": null,
        "publication":
   {
        "duration": "PT720H",
        "status": "INACTIVE",
        "startingAt": null,
        "endingAt": null,
    },
    "delivery": {
        "shippingRates": null,
        "handlingTime": null,
        "additionalInfo": null,
        "shipmentDate": null
    },
    "payments": {
        "invoice": "NO_INVOICE"
    },
    "afterSalesServices": null,
    "additionalServices": null,
    "sizeTable": null,
    "fundraisingCampaign": null,
    "promotion": {
            "emphasized": false,
            "bold": true,
            "highlight": true,
            "departmentPage": false,
            "emphasizedHighlightBoldPackage": false
    },
    "location": {
        "countryCode": "PL",
        "province": "WIELKOPOLSKIE",
        "city": "Poznań",
        "postCode": "60-166"
    },
    "external": {
        "id":"4131asdsad40011"
                },
    "attachments": [],
    "contact": {
        "id": "0c046252-9559-4ecb-8ea3-879f60e46947"
    },
    "validation": {
        "errors": [],
        "validatedAt": "2019-02-26T11:33:38.599Z"
    },
    "b2b": {
        "buyableOnlyByBusiness": false
    },
    "createdAt": "2019-02-26T11:33:38Z",
    "updatedAt": "2019-02-26T11:33:38.6Z",
    },
    “classifiedsPackages”: {
        “basePackage”: {
            "id": "708a5240-0dc4-4573-8d50-4a32cdcc5823”
        },
        “extraPackages”: [{
            "id": "74bb1eef-28d3-443a-91ed-d39b0646f2c3"
        },
        {
            "id": "45d1d9d2-0696-4326-9dd0-8d02120f8a1c"
        }]}
    }
Kliknij aby zobaczyć response
toggle visibility
'{
    "commissions": [],
    "quotes": [,
        {
            "name": "Opłata za pakiet Power",
            "fee": {
                "amount": "39.00",
                "currency": "PLN"
            }
            "cycleDuration": "PT1200H"
            "classifiedsPackage": {
                "id":"708a5240-0dc4-4573-8d50-4a32cdcc5823"
                    }
        },
        {
            "name": "Opłata za wyróżnienie ogłoszenia",
            "fee": {
                "amount": "39.00",
                "currency": "PLN"
            }
            "cycleDuration": "PT240H"
            "classifiedsPackage": {
                "id":"74bb1eef-28d3-443a-91ed-d39b0646f2c3"
                    }
        },
        {
            "name": "Promowanie na stronie działu - ogłoszenie",
            "fee": {
                "amount": "33.00",
                "currency": "PLN"
            }
            "cycleDuration": "PT120H"
            "classifiedsPackage": {
                "id":"45d1d9d2-0696-4326-9dd0-8d02120f8a1c"
                    }
        },
        }
  ...
    ]
  }'

Publikacja ogłoszenia

Jeśli ogłoszenie jest już kompletne i poprawnie zwalidowane, to za pomocą PUT /sale/offer-publication-commands/{commandId} możesz je opublikować w serwisie. Proces publikacji działa asynchronicznie.

W polu commandId podaj wartość w formacie UUID (universally unique identifier). Jest to globalnie unikatowy identyfikator, który składa się z 32 liczb szesnastkowych (np.: 21ae4ed1-eab7-34ea-b605-cf2e22b5eed3).

Przy pomocy tej metody możesz również:

  • zakończyć wybrane ogłoszenia - wystarczy, że w polu action podasz wartość END.
  • zaplanować wystawienie ogłoszenia w przyszłości - wystarczy, że w polu scheduleFor ustawisz datę planowanej publikacji ogłoszenia
  • wznowić zakończone oferty - w statusie ENDED. Przekaż dla takich ogłoszeń wartość 'ACTIVATE' w polu action. Udostępnimy je ponownie w serwisie.

Przed wznowieniem ogłoszenia niezbędne jest ponowne przypisanie pakietu i opcji dodatkowych. Za wybrany pakiet i opcje dodatkowe w danym ogłoszeniu naliczymy ponownie opłaty.

Przykładowy request:

   curl -X PUT \
  'https://api.allegro.pl/sale/offer-publication-commands/3380d97f-0d32-4747-8a17-1da38f9499de' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
    "publication": {
        "action": "ACTIVATE",                 -- wymagane, dostępne są dwie wartości:
                                              ACTIVATE (aktywowanie danych ogłoszeń) i
                                              END (zakończenie danych ogłoszeń)
    "scheduledFor":"2018-03-28T12:00:00.000Z" -- niewymagane, wysyłasz jeśli chcesz
                                              zaplanować wystawienie ogłoszenia w
                                              przyszłości
    },
    "offerCriteria": [
        {
            "offers":[                        -- wymagane, tablica obiektów z
                                              numerami identyfikacyjnymi ogłoszeń
                {
                    "id": "7276377308"
                }
            ],
            "type": "CONTAINS_OFFERS"         -- wymagane, obecnie dostępna jest
                                              jedna wartość: CONTAINS_OFFERS
                                              (ogłoszenia, w których zmienimy status)
     }
    ]
  }'

W odpowiedz otrzymasz puste zestawienie. Nie jesteśmy w stanie od razu zweryfikować ile ofert po przetworzeniu opublikuje się prawidłowo, a przy ilu wykryjemy braki. Aby sprawdzić status zadania skorzystaj z dedykowanych metod, które opisaliśmy w kolejnym kroku.

Przykładowy response:

   ‘{
    "id": "3380d97f-0d32-4747-8a17-1da38f9499de",
    "taskCount": {
        "total": 0,
        "success": 0,
        "failed": 0
    }’

Status ogłoszenia

Status zadania, jakie zleciłeś w poprzednim kroku sprawdzisz za pomocą:

  • GET /sale/offer-publication-commands/{commandId}
  • GET /sale/offer-publication-commands/{commandId}/tasks

Zestawienie zadań

GET /sale/offer-publication-commands/{commandId} pozwoli ci pobrać informacje o statusie zadania publikacji ogłoszeń. W odpowiedzi otrzymasz zestawienie, ile ogłoszeń wystawiło się poprawnie, a z iloma wystąpił jakiś problem.

Przykładowy request:

   curl -X GET \
  'https://api.allegro.pl/sale/offer-publication-commands/{commandId}' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json'

Przykładowy response:

  '{
    "id": "3380d97f-0d32-4747-8a17-1da38f9499de",
    "taskCount": {
        "total": 1,
        "success": 1,
        "failed": 0
    }
   }'

Informacje o publikacji

GET /sale/offer-publication-commands/{commandId}/tasks pozwoli ci pobrać informacje o statusie publikacji ogłoszenia w serwisie. W odpowiedzi otrzymasz:

  • identyfikatory ogłoszenia, które chciałeś opublikować w serwisie,
  • status modyfikacji ogłoszenia - czy zakończyła się sukcesem,
  • datę zlecenia modyfikacji ogłoszenia,
  • datę wykonania danego zadania - wystawienia lub zakończenia ogłoszenia,
  • przy statusie FAIL w polu "message" informacje dlaczego nie udało się opublikować ogłoszenia w serwisie.

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/sale/offer-publication-commands/{commandId}/tasks’ \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json'

Przykładowy resposne:

  ‘{
            "offer": {
                "id": "7168735300"
            },
            "message": "",                      -- opis dlaczego nie udało się  opublikować
                                                ogłoszenia w serwisie
            "status": "SUCCESS",                -- status publikacji ogłoszenia w serwisie,
                                                dostępne są trzy wartości: SUCCESS (publikacja
                                                zakończyła się pomyślnie); FAIL
                                                (wystąpiły błędy przy publikacji i oferta nie
                                                jest aktywna w serwisie); NEW (trwa publikacja
                                                ogłoszenia w serwisie, akcja nie została jeszcze
                                                zakończona)
            "scheduledAt": "2018-03-01T11:02:50.005+01:00",
            "finishedAt": "2018-03-01T11:02:51.691+01:00",
            "field": "publication"
   }’

Jak zarządzać ogłoszeniem

Dodatkowe opcje promowania

Do zarządzania dodatkowymi opcjami promowania w trwających ogłoszeniach przygotowaliśmy zasoby w Allegro REST API:

  • GET /sale/offer-classifieds-packages/{offerId} - pobierz informacje na temat przypisanego pakietu i opcji dodatkowych do danego ogłoszenia,
  • PUT /sale/offer-classifieds-packages/{offerId} - dodaj do danego ogłoszenia opcje dodatkowe.

Pakiety możesz zmieniać tylko do momentu opublikowania ogłoszenia. Natomiast do aktywnego ogłoszenia dodasz tylko dodatkowe opcje promowania.

Przypisane pakiety

GET /sale/offer-classifieds-packages/{offerId} - pobierz informacje na temat przypisanych pakietów i opcji dodatkowych do ogłoszenia. Musisz być zalogowany jako użytkownik, który wystawił dane ogłoszenie.

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/sale/offer-classifieds-packages/{offerId}' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json'

Przykładowy response:

  ‘{
    "basePackage": {
        "id": "3174be19-56f9-484b-b72c-43b0b00785e8"      -- identyfikator pakietu
    },
    "extraPackages": [{
            "id": "3174be19-56f9-484b-b72c-43b0b00785e8", -- identyfikator opcji dodatkowych, 
                                                             które chcesz dodać do danego pakietu
            "republish": true                             -- opcja automatycznego wznowienia 
                                                             (true - włączona, false - wyłączona)
        },
        {
            "id": "3174be19-56f9-484b-b72c-43b0b00785e6",
            "republish": false
        }
    ]
  }’
Edycja opcji promowania

PUT /sale/offer-classifieds-packages/{offerId} - dodaj dodatkowe opcje promowania do ogłoszenia. Oprócz opcji dodatkowych, które chcesz dodać przekaż strukturę jaką pobrałeś za pomocą GET /sale/offer-classifieds-packages/{offerId}. Musisz być zalogowany jako użytkownik, który wystawił dane ogłoszenie.

Przykładowy request:

  curl -X PUT \
  'https://api.allegro.pl/sale/offer-classifieds-packages/{offerId}' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json'
  -d '{
    "basePackage": {
        "id": "3174be19-56f9-484b-b72c-43b0b00785e8"
    },
    "extraPackages": [{
            "id": "3174be19-56f9-484b-b72c-43b0b00785e8",
            "republish": true
        },
        {
            "id": "3174be19-56f9-484b-b72c-43b0b00785e7",
            "republish": true
        },
        {
            "id": "3174be19-56f9-484b-b72c-43b0b00785e6",
            "republish": false
        }
    ]
  }'

Przykładowy response:

  Status 201 No Content

Edycja ogłoszenia

Jeśli chcesz zmienić dane w swoim ogłoszeniu, to wystarczy, że pobierzesz je przy pomocy GET /sale/offers/{offerId}. I całą strukturę jaką otrzymasz w odpowiedzi przekażesz w metodzie PUT /sale/offers/{offerId}. Pamiętaj, aby przed wysłaniem requesta odpowiednio zmienić dane w polach, które chcesz wyedytować. Musisz być uwierzytelniony i zautoryzowany jako użytkownik, który wystawił tę ogłoszenia.

Nawet jeśli chcesz zmienić jedno pole, to musisz przekazać całą strukturę ogłoszenia jaką pobrałeś przy pomocy GET /sale/offers/{offerId}.

Wystaw podobne

Jeśli już wystawiłeś ogloszenie i chcesz na jego podstawie wystawić podobne, to wystarczy, że pobierzesz je przy pomocy GET /sale/offers/{offerId}. Przez GET /sale/offers/{offerId} pobierzesz wszystkie pola wskazanego ogłoszenia. Musisz być uwierzytelniony i zautoryzowany jako użytkownik, który wystawił tę ogłoszenia. Całą pobraną strukturę z wyłączeniem:

  • id - numeru identyfikacyjnego ogłoszenia,
  • validatedAt - informacji, kiedy odbyła się ostatnia walidacja ogłoszenia,
  • createdAt - daty utworzenia ogłoszenia,
  • updatedAt - daty ostatniej aktualizacji ogłoszenia,

prześlij metodą POST /sale/offers. Dzięki temu stworzysz nowy draft ogłoszenia na podstawie danych z ogłoszenia, którą wcześniej pobrałeś. Gdy uzupełniasz draft, możesz wprowadzić zmiany w strukturze, którą pobrałeś zasobem GET /sale/offers/{offerId}.

Statystyki ogłoszeń

Sprzedający mogą sprawdzić statystyki ogłoszeń takie jak:

  • liczba odsłon numeru telefonu,
  • wiadomości wysłane przez Kupujących za pośrednictwem opcji “Zadaj pytanie”.

Dzięki temu mogą łatwiej przeanalizować ogłoszenia pod kątem zainteresowania ze strony potencjalnych kontrahentów.

Statystyki wszystkich ogłoszeń sprzedawcy

Za pomocą GET /sale/classified-seller-stats sprawdzisz ogólne statystyki wszystkich ogłoszeń sprzedawcy.

Przykładowy request:

 curl -X GET \
  'https://api.allegro.pl/sale/classified-seller-stats’ \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'

Przykładowy response:

{
   "eventStatsTotal": [                         - łączne statystyki ogłoszeń 
                                                sprzedawcy
       {
           "eventType": "SHOWED_PHONE_NUMBER",  - typ zdarzenia; zwracane wartości: 
                                                SHOWED_PHONE_NUMBER 
                                                (odsłonięta opcja “Pokaż numer 
                                                telefonu”), ASKED_QUESTION 
                                                (Klient skorzystał z opcji “Zadaj 
                                                pytanie”)
           "count": 1                           - liczba zdarzeń
       },
       {
           "eventType": "ASKED_QUESTION",
           "count": 12
       }
   ],
   "eventsPerDay": [                            - łączne statystyki ogłoszeń 
                                                sprzedawcy na dany dzień
       {
           "date": "2022-08-24",                - data zdarzenia
           "eventStats": [                      - statystyki zdarzenia
               {
                   "eventType": "ASKED_QUESTION",
                   "count": 12
               }
           ]
       },
       {
           "date": "2022-08-25",
           "eventStats": [
               {
                   "eventType": "SHOWED_PHONE_NUMBER",
                   "count": 1
               }
           ]
       }
   ]
}

Aby zawęzić listę wyszukiwania, skorzystaj z parametrów, dzięki którym wyfiltrujesz statystyki ogłoszeń:

  • date.gte - od najwcześniejszej daty (w formacie ISO 8601),
  • date.lte - od najpóźniejszej daty (w formacie ISO 8601), np. GET /sale/classified-seller-stats?date.gte=2022-08-10T11:06:50.935Z&date.lte=2022-08-20T11:06:50.935Z.

Statystyki wybranych ogłoszeń

Za pomocą GET /sale/classified-offers-stats sprawdzisz statystyki wybranych ogłoszeń. W żądaniu możesz przekazać maksymalnie do 50 numerów ofert w parametrze offer.id.

Przykładowy request:

 curl -X GET \
  'https://api.allegro.pl/sale/classified-offers-stats?offer.id=7693291322, 7693291524’ \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'

Przykładowy response:

{
   "offerStats": [                                 - statystyki ogłoszeń
       {
           "offer": {                              - oferta
               "id": "7693291322"                  - numer oferty
           },
           "eventStatsTotal": [                    - łączne statystyki ogłoszeń dla 
danego zdarzenia
               {
                   "eventType": "ASKED_QUESTION",    - typ zdarzenia; zwracane 
                                                    wartości: SHOWED_PHONE_NUMBER 
                                                    (odsłonięta opcja “Pokaż numer 
                                                    telefonu”), "ASKED_QUESTION" 
                                                    (Klient skorzystał z opcji “Zadaj 
                                                    pytanie”)

                   "count": 9                      - liczba zdarzeń
               }
           ],
           "eventsPerDay": [                       - statystyki ogłoszeń na dany dzień
               {
                   "date": "2022-08-24",           - data zdarzenia
                   "eventStats": [                 - statystyki zdarzenia
                       {
                           "eventType": "ASKED_QUESTION",
                           "count": 9
                       }
                   ]
               }
           ]
       },
       {
           "offer": {
               "id": "7693291524"
           },
           "eventStatsTotal": [
               {
                   "eventType": "SHOWED_PHONE_NUMBER",
                   "count": 1
               },
               {
                   "eventType": "ASKED_QUESTION",
                   "count": 3
               }
           ],
           "eventsPerDay": [
               {
                   "date": "2022-08-24",
                   "eventStats": [
                       {
                           "eventType": "ASKED_QUESTION",
                           "count": 3
                       }
                   ]
               },
               {
                   "date": "2022-08-25",
                   "eventStats": [
                       {
                           "eventType": "SHOWED_PHONE_NUMBER",
                           "count": 1
                       }
                   ]
               }
           ]
       }
   ]
}

Aby zawęzić listę wyszukiwania, możesz skorzystać z parametrów, dzięki którym wyfiltrujesz statystyki ogłoszeń:

  • date.gte - od najwcześniejszej daty (w formacie ISO 8601),
  • date.lte - od najpóźniejszej daty (w formacie ISO 8601), np. GET /sale/classified-offers-stats?offer.id=7693291322, 7693291524&date.gte=2022-08-10T11:06:50.935Z&date.lte=2022-08-20T11:06:50.935Z.

Lista zasobów

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

Lista zasobów podstawowych opisanych w poradniku:

  • POST /sale/offers - utwórz draft ogłoszenia
  • GET /sale/offers/{offerId} - pobierz ogłoszenie
  • PUT /sale/offers/{offerId} - edytuj draft / ogłoszenie
  • GET /sale/classifieds-packages - pobierz dostępne pakiety i opcje dla ogłoszenia
  • PUT /sale/offer-classifieds-packages/{offerId} - przypisz pakiet i opcje do ogłoszenia
  • PUT /sale/offer-publication-commands/{commandId} - zmień grupowo status publikacji ogłoszenia
  • POST /sale/offer-contacts - utwórz kontakt
  • GET /sale/categories - pobierz listę kategorii
  • GET /sale/categories/{categoryId}/parameters - pobierz listę parametrów dla kategorii
  • POST /sale/images - dodaj zdjęcia

Lista zasobów wspierających opisanych w poradniku:

  • GET /sale/offer-publication-commands/{commandId} - pobierz raport o statusie zadania publikacji ogłoszenia
  • GET /sale/offer-publication-commands/{commandId}/tasks - pobierz szczegółowy raport o statusie zadania publikacji ogłoszenia
  • GET /sale/offer-contacts/{id} - pobierz szczegóły kontaktu
  • GET /sale/offer-contacts - pobierz listę kontaktów
  • PUT /sale/offer-contacts/{id} - edytuj dane kontaktu
  • GET /sale/classifieds-packages/{packageId} - pobierz szczegóły pakietu / opcji
  • POST /pricing/offer-fee-preview - sprawdź koszt wystawienia ogłoszenia
  • GET /sale/offer-classifieds-packages/{offerId} - pobierz informacje o pakiecie i opcjach dodatkowych przypisanych do oferty
  • GET /sale/classified-seller-stats - sprawdź ogólne statystyki wszystkich ogłoszeń sprzedawcy
  • GET /sale/classified-offers-stats - sprawdź statystyki wybranych ogłoszeń

Zgłoś błąd lub zasugeruj zmianę

Czy ten artykuł był dla Ciebie przydatny?