Wystawianie ofert - Allegro Developer Portal

W drugiej połowie 2022 roku planujemy, żeby każda nowo wystawiona oferta była połączona z Katalogiem produktów. Na stronie allegro można też sprawdzić jaki % ofert jest połączony z produktem.

Skorzystaj z dedykowanych zasobów do wystawiania oferty z produktem. Zastosowaliśmy tam szereg ułatwień, dzięki czemu w prostszy sposób możesz wystawić i edytować ofertę. Jeśli jeszcze korzystasz z zasobu /sale/offers po prostu przypisz produkt do swojej oferty.
Aby sprawdzić, które z ofert nie są powiązane z produktem, skorzystaj z GET /sale/offers i parametru product.id.empty=true.

jak wystawic oferte

Przygotuj draft

Na początku tworzysz draft oferty za pomocą POST /sale/offers. Taką ofertę oznaczymy w polu status jako “INACTIVE”. Draft oferty nie musi być kompletną ofertą, gotową do opublikowania w serwisie. Draft może być zalążkiem do dalszej pracy na ofercie. 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 ofertach na naszych serwerach,
łatwo przygotować podgląd oferty.

Powiąż ofertę z produktem

W 2019 roku wprowadziliśmy Katalog produktów Allegro w wybranych kategoriach serwisu. W ramach Katalogu produktów Allegro chcemy zebrać i opisać wszystkie produkty, jakie są dostępne w ofertach wystawianych przez wszystkich sprzedawców. Katalogujemy pojedyncze produkty jako reprezentatywne, które odróżniają się od innych swoimi właściwościami, np. modelem, kodem producenta, numerem GTIN, czy innymi parametrami podstawowymi.

Aktualnie w wybranych kategoriach wymagamy, aby część ofert była powiązana z Katalogiem produktów. Do końca 2021 roku chcemy natomiast skatalogować wszystkie oferty w kategoriach, w których jest to możliwe.

Więcej informacji o tym, jak powiązać ofertę z produktem znajdziesz w zakładce Produktyzacja.

Wystaw ofertę

Aktywuj kompletny draft (status=INACTIVE), dla którego nie zwracamy żadnych błędów w sekcji “validation”. Zrobisz to za pomocą akcji ACTIVATE w PUT /sale/offer-publication-commands/{commandId}. Od momentu publikacji oferty w serwisie, będzie ona miała status przejściowy - ACTIVATING. Status ACTIVATING dotyczy również ofert zaplanowanych do wystawienia w przyszłości.

Walidację przeprowadzamy za każdym razem, gdy wprowadzasz zmiany w ofercie. Jeśli wysyłasz zmiany, które zawierają:

błędne dane, identyfikatory itp. - to w odpowiedzi otrzymasz: status 422,
błędy logiczne, które blokują wystawienie oferty, np. nie podałeś kwoty minimalnej dla licytacji - to w sekcji “validation” otrzymasz opis błędu.

Więcej informacji, jak opublikować ofertę, znajdziesz w zakładce Publikacja oferty.

Sprawdź status oferty

Gdy wystawisz ofertę w serwisie, wówczas jej status zmienimy na ACTIVE. Dokładny termin wystawienia takiej oferty wyświetlamy w polu scheduledAt w odpowiedzi dla GET /sale/offer-publication-commands/{commandId}/tasks. Za pomocą PUT /sale/offer-publication-commands/{commandId} możesz również zakończyć ofertę - wystarczy, że wykonasz akcję END.

Pamiętaj! Wszystkie żądania musisz wykonywać z tokenem OAuth 2.0.

Draft oferty

Draft oferty utworzysz za pomocą POST /sale/offers. Musisz być uwierzytelnionym i zautoryzowanym użytkownikiem. Gdy utworzysz DRAFT oferty, możesz go później opublikować w serwisie. Możesz przesłać częściowe dane (przynajmniej tytuł) - taki DRAFT oferty uzupełnisz później o wszystkie wymagane pola za pomocą 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 twojej ofercie.

Maksymalnie możesz utworzyć 20 000 draftów. Po przekroczeniu limitu nie będziesz mógł utworzyć nowego draftu. Otrzymasz komunikat - “You cannot create new drafts - your account has exceeded the maximum number 20 000 of drafts.” Usuń niepotrzebne za pomocą DELETE /sale/offers/{offerId}.
Draft oferty przechowujemy do 60 dni. Po tym okresie usuniemy taki draft. Jeśli zmienisz coś w nim, wydłużymy jego ważność o 60 dni.

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": "Oferta testowa"                        -- wymagane, tytuł oferty
  }

Kliknij, aby zobaczyć response

{
    "id": "7276377308",
    "name": "Oferta testowa",
    "category": null,
    "parameters": [],
    "description": null,
    "images": null,
    "sellingMode": null,
    "tax": null,
    "stock": null,
    "publication": {
        "republish": null,
        "duration": null,
        "status": "INACTIVE",
        "startingAt": null,                         -- wartość w odpowiedzi
                                                    zawsze przyjmuje null,
        "endingAt": null
    },
    "delivery": null,
    "payments": {
        "invoice": "NO_INVOICE"
    },
    "discounts": null,
    "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": "New offer description is required.",
                "details": "",
                "path": "",
                "userMessage": "New offer description is required."
            },
            {
                "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": "Category may not be empty.",
                "details": "",
                "path": "",
                "userMessage": "Category may not be empty."
            },
            {
                "code": "VALIDATION_ERROR",
                "message": "Describe your offer.",
                "details": "",
                "path": "",
                "userMessage": "Describe your offer."
            }
        ],
        "validatedAt": "2018-04-06T09:29:47.544Z"
    },
    "b2b": {
        "buyableOnlyByBusiness": false
    },
    "createdAt": "2018-04-06T09:29:47Z",
    "updatedAt": "2018-04-06T09:29:47.544Z"
}

Tytuł oferty

Tytuł oferty przekazujesz w polu name, dopuszczamy dla niego maksymalnie 50 znaków. Listę liter, cyfr i znaków specjalnych jakie pozwalamy wprowadzić w tytule oferty 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 & dlatego zajmuje 5 miejsc w tytule.

Kategorie i parametry

Za pomocą poniższych zasobów pobierz identyfikator wybranej kategorii oraz parametry - dane musisz uzupełnić w sekcjach category oraz parameters.

Identyfikator kategorii

Dzięki GET /sale/categories?parent.id={categoryId} pobierzesz listę kategorii, które należą kategorii nadrzędnej, którą przekażesz jako wartość parametru parent.id.

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 ofertę wystawisz tylko w kategorii najniższego rzędu, która jest oznaczona "leaf": true.
Zadbaj o powiązanie oferty z produktem. Opcja ta jest dostępna w wybranych kategoriach, w których grupujemy oferty z tym samym produktem. Tylko w nich otrzymasz dane o produktach. Kategorie te oznaczyliśmy "offersWithProductPublicationEnabled": true.

Przykładowy request

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

Kliknij, aby zobaczyć response

{
 "categories":[
  {
   "id": "348",                                 -- identyfikator kategorii
   "name": "Akcesoria GSM",                     -- nazwa kategorii
   "parent": {                                  -- identyfikator kategorii nadrzędnej
    "id": "4"                                   dla kategorii głównych parent, ma wartość null
   },
   "leaf": false,                               -- czy dana kategoria jest
                                                kategorią najniższego rzędu, dostępne są
                                                dwie wartości true (jest liściem)
                                                i false (nie jest liściem)
   "options": {                                 -- cechy kategorii
    "advertisement": false,                     -- informacja, czy w danej kategorii
                                                lub jej podkategoriach można wystawić ofertę
                                                ogłoszeniową.
    "advertisementPriceOptional": false,        -- czy w danej
                                                kategorii ogłoszeniowej cena oferty jest
                                                opcjonalna. Dostępne są dwie wartości:
                                                true (cenę można pominąć),
                                                false (cena oferty musi być podana).
    "offersWithProductPublicationEnabled": true, -- czy w danej w danej kategorii możesz
                                                wiązać ofertę z produktem. Więcej na ten temat
                                                znajdziesz w poradniku - Jak powiązać ofertę
                                                z produktem.
    "productCreationEnabled": false,            -- czy w danej kategorii możesz
                                                 utworzyć produkt. Więcej na ten temat
                                                znajdziesz w poradniku - Jak powiązać ofertę
                                                z produktem.
    "customParametersEnabled": true             -- czy w danej kategorii możesz dodać własny
                                                parametr
    }
}]
}

Parametry

Za pomocą GET /sale/categories/{categoryId}/parameters pobierz parametry dostępne w danej kategorii. W odpowiedzi zwrócimy parametry, które możesz ustawić dla kategorii wskazanej jako categoryId.

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/sale/categories/{catId}/parameters'
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Accept-Language: pl-PL' \
  -H 'Authorization: Bearer {token}' \

Kliknij, aby zobaczyć response

  {
    "parameters": [                         -- lista dostępnych parametrów dla
                                            wskazanej kategorii
    {
        "id": "11323",                      -- unikalny 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,
                                            dostępne są dwie wartości: true (tak) i false (nie)
        "unit": null,
        "requiredForProduct": true          -- czy musisz przekazać wartość dla tego
                                            parametru , gdy tworzysz nowy produkt
        "options": {
            "variantsAllowed": false,
            "variantsEqual": false
            "ambiguousValueId": "216917_41" -- id wartości niejednoznacznej, np.
                                            "inna", "pozostałe", etc.
            "dependsOnParameterId": null    -- id parametru, od którego zależne są
                                            dostępne wartości tego parametru
            "requiredDependsOnValueIds": [  -- id wartości parametru warunkującego
                                            (głównego), od której zależy, czy parametr jest wymagany
            "202870_1"
            ],
            "displayDependsOnValueIds": [   -- zbiór identyfikatorów wartości
                                            parametru warunkującego, od których zależy, czy dany parametr będzie
            "202870_1",                     widoczny
            "202870_2"
            ],
            "describesProduct": true,       -- czy parametr opisuje produkt
            "customValuesEnabled": false    -- czy w danym parametrze możesz dodać własną wartość
                                            dla parametru z wartością niejednoznaczną
        },
        "dictionary": [
            {
                "id": "11323_1",
                "value": "Nowy",
                "dependsOnValueIds": []
            },
            {
                "id": "11323_2",
                "value": "Używany",
                "dependsOnValueIds": []
            }
        ],
        "restrictions": {
        "multipleChoices": false            -- parametr z możliwym wyborem jednej lub
                                            wielu wartości, dostępne są dwie wartości:
                                            true (tak) i false (nie)
        }
    },
    {
        "id": "211966",
        "name": "Zakres regulacji wysokości koszenia (cm)",
        "type": "float",
        "required": false,
        "unit": null,
        "requiredForProduct": true,
        "restrictions": {
            "min": 0,
            "max": 1000,
            "range": true,                  -- parametr zakresowy, należy podać
                                            minimalną i maksymalną wartość.
            "precision": 2
        }
    },
    {
        "id": "17448",
        "name": "waga (z opakowaniem)",
        "type": "float",
        "required":false,
        "restrictions": {
            "min": 5,
            "max": 10,
            "range": true,                  -- parametr zakresowy. Sekcje range
                                            min i max oznaczają minalną i maksymalna
                                            wartość danego parametru.
            "precision": 3                  -- określa z jaką dokładnością możemy podać
                                            wartość danego parametru. W tym przypadku
                                            możemy podać wartość z dokładnością do
                                            3 miejsc po przecinku
        }
    },
    {
        "id": "216917",
        "name": "Załączone wyposażenie",
        "type": "string",
        "required": false,
        "unit": null,
        "requiredForProduct": false,
        "options": {
            "variantsAllowed": false,
            "variantsEqual": false
            "ambiguousValueId": "216917_41" -- id wartości niejednoznacznej, np.
                                            "inna", "pozostałe", etc.
            "dependsOnParameterId": null,
            "describesProduct": true,
            "customValuesEnabled": false
        },
        "restrictions": {
            "minLength": 1,
            "maxLength": 40,
            "allowedNumberOfValues": 10     -- informacja o tym, ile wartości możesz
                                            podać w danym parametrze
        }
    }
    ]
  }

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

Poniżej znajdziesz przykłady prawidłowo uzupełnionych struktur przykładowych parametrów, w zależności od ich 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
  }

Własne parametry

Opcjonalnie, w wybranych kategoriach, możesz uzupełnić własne parametry. Za pomocą GET /sale/categories/{categoryID} sprawdź w polu customParametersEnabled, czy jest to możliwe.

Własne parametry:

dodasz w polu customParameters w modelu oferty. Parametr będzie widoczny na stronie oferty,
mają podobne ograniczenie, jak na formularzu wystawiania na stronie internetowej - maksymalnie dodasz 4 własne parametry, dla których możesz przekazać po jednej wartości,
nie mogą być duplikatami - jeżeli parametr o takiej nazwie istnieje już w Allegro, to zwrócimy odpowiedni błąd. Możesz jednak dodać własne parametry o takiej samej nazwie dla różnych ofert.

Przykładowa struktura żądania:

 {
   ...
   "parameters": [...],
   "customParameters": [
     {
       "name": "Nazwa twojego własnego parametru",
       "values": [
         "Wartość własnego parametru"
       ]
     }
    ],
   "description": {...},
   ...
  }

Przykładowa struktura odpowiedzi:

  {
   ...
   "parameters": [...],
   "customParameters": [
     {
       "name": "Nazwa twojego własnego parametru",
       "values": [
         "Wartość własnego parametru"
       ]
     }
    ],
   "description": {...},
   ...
  }

Własna wartość parametru

Jeżeli nie znajdziesz odpowiedniej wartości parametru, dla wybranych parametrów z wartością niejednoznaczną możesz zdefiniować własną wartość. Wartości niejednoznaczne parametru to wartości typu: “inne”, “pozostałe”, etc. np. “inna” w parametrze “Marka”. Identyfikator takiej wartości zwracamy w polu ambiguousValueId w sekcji options w odpowiedzi dla GET /sale/categories/{categoryId}/parameters.

Aby dodać własną wartość:

za pomocą GET /sale/categories/{categoryId}/parameters sprawdź:

w polu customValuesEnabled, czy w danym parametrze wybranej kategorii możesz dodać własną wartość;

w polu ambiguousValueId identyfikator wartości niejednoznacznej;

{
"parameters": [
 {
   "id": "129033",
   "name": "Marka",
   "type": “dictionary”,
   "required":true,
   "unit": null,
   "requiredForProduct": true
   "options": {
       "variantsAllowed": false,
       "variantsEqual": false,
       "ambiguousValueId": "129033_13"         -- id wartości niejednoznacznej,
                                               w tym przypadku jest to wartość “inna”
       "dependsOnParameterId": null,
       "describesProduct": true,  
       "customValuesEnabled": true             -- czy w danym prarametrze możesz
                                               dodać własną wartość
   },
   ...
}

gdy tworzysz draft lub edytujesz ofertę, w sekcji parameters przekaż poniższą strukturę:

{
   "id": "129033",                           -- id parametru
   "valuesIds": [
     "129033_13"                             -- id wartości niejednoznacznej
   ],
   "values": [ "Nazwa brakującej marki" ],   -- wartość, którą chcesz przekazać,
                                             uzupełnij to pole.
   "rangeValue": null
}

Produktyzacja

Od początku 2019 roku wprowadzamy elementy produktyzacji w serwisie. Grupujemy oferty z tym samym produktem, dzięki czemu klient szybciej znajdzie ofertę, która spełnia jego oczekiwania.

Aktualnie w wybranych kategoriach wymagamy, aby część ofert była powiązana z Katalogiem produktów. Do końca 2021 roku chcemy natomiast skatalogować wszystkie oferty w kategoriach, w których jest to możliwe.

W naszym poradniku - Jak powiązać ofertę z produktem, znajdziesz szczegółowe informacje o tym, jak:

wyszukać produkt w naszym katalogu;
pobrać dane produktu;
zarządzać produktem w ofercie;
dodać produkt do naszej bazy.

Możesz także zrezygnować z wystawiania ofert za pomocą POST /sale/offers i zamiast tego korzystać z POST /sale/product-offers. Dzięki temu, za pomocą jednego żądania wystawisz:

aktywną ofertę powiązaną z produktem, który istnieje w naszej bazie. W strukturze żądania przekaż numer EAN (lub identyfikator produktu) oraz cenę i liczbę sztuk;
aktywną ofertę powiązaną z produktem, którego nie ma w naszej bazie. W strukturze żądania, w obiekcie “product”, przekaż komplet danych, które opisują sprzedawany produkt.

Jeśli na podstawie przekazanych danych rozpoznamy, że produkt istnieje w naszej bazie, to weźmiemy jego dane i uwzględnimy je w wystawionej ofercie.

Więcej o tym, jak korzystać z POST /sale/product-offers, znajdziesz w naszym poradniku.

Zdjęcia

Przy pomocy POST /sale/images prześlij zdjęcie na nasze serwery po protokole HTTP i HTTPS (tylko z ważnym certyfikatem). W odpowiedzi otrzymasz link do przesłanej grafiki. Ważne! Informacje odnośnie zasad dla zdjęć w galerii i opisie znajdziesz na stronie dla sprzedających. 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
      }'

Pamiętaj, aby podać adres domeny, nie podawaj adresu IP.

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ś
    }

Ważne!

Zdjęcia są cache’owane przez 7 dni - gdy wyślesz kolejne żądanie z tym samym, zewnętrznym adresem URL, zdjęcia możemy pobrać z wewnętrznego cache Allegro, zamiast bezpośrednio z zewnętrznego serwera.
Jeżeli chcesz, aby czas cache’owania był krótszy, serwer powinien wysłać nagłówek Cache-Control z odpowiednią wartością parametru max-age.
Jeżeli nie chcesz, abyśmy cache’owali zdjęcia, serwer powinien wysłać nagłówek Cache-Control z parametrem Private, No-Cache lub No-Store.

Opis oferty

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.
w opisie możesz wykorzystać tylko zdjęcia, 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.

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

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"
}

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>"
}

Możesz użyć pogrubienia   w znacznikach:
-   - akapit
- < ul > < /ul > - lista wypunktowana
- < ol > < /ol > - lista numerowana
Możesz użyć znacznika akapitu 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"
            }]
        }]
    }

Informacje o dostawie

Cennik dostaw

Cennik dostaw utworzysz za pomocą POST /sale/shipping-rates lub przez naszą stronę internetową.

Na początku skorzystaj z GET /sale/delivery-methods, aby pobrać identyfikatory i nazwy metod dostawy, które są dostępne w Allegro. Wykorzystasz je, gdy będziesz tworzyć nowy cennik dostawy.

Przykładowy request:

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

Kliknij, aby zobaczyć response

{

  "deliveryMethods": [
    {
        "id": "7203cb90-864c-4cda-bf08-dc883f0c78ad",   -- ogólny identyfikator danej metody dostawy
        "name": "Przesyłka kurierska",                  -- ogólna nazwa danej metody dostawy
        "paymentPolicy": "IN_ADVANCE",                  -- rodzaj płatności. Dostępne są dwie
                                                        wartości IN_ADVANCE (opłata z góry)
                                                        i CASH_ON_DELIVERY (opłata przy odbiorze)
        "allegroEndorsed": false,                       -- czy dana dostawa jest sygnowana
                                                        przez Allegro, pole pozwala łatwo rozróżnić
                                                        podobne metody dostawy z różnymi ograniczeniami,
                                                        np. Allegro Paczkomaty 24/7 InPost od Paczkomaty 24/7
        "shippingRatesConstraints": {
            "allowed": true,                            -- czy możesz dodać dany sposób dostawy
                                                        do nowego, bądź już istniejącego cennika dostaw
            "maxQuantityPerPackage": {                  -- maksymalna wartość, jaką możesz podać
                                                        dla pola "liczba w paczce"
                "max": 999999
            },
            "maxPackageWeight": {                       -- warunki dla pola "maksymalna waga paczki"
                "supported": true,                      -- czy możesz zdefiniować maksymalną wagę paczki
                                                        dla danej metody dostawy
                "min": "1.000",
                "max": "30.000",
                "unit": "KILOGRAM"
            },
            "firstItemRate": {                          -- warunki dla pola "cena przesyłki"
                "min": "0.00",
                "max": "100000000.00",
                "currency": "PLN"
            },
            "nextItemRate": {                           -- warunki dla pola "cena kolejnej sztuki"
                "min": "0.00",
                "max": "100000000.00",
                "currency": "PLN"
            },
            "shippingTime": {                           -- warunki dla pola "czas dostawy"
                "default": {
                    "from": "PT24H",
                    "to": "PT48H"
                },
                "customizable": true                    -- informacja, czy możesz zmienić czas dostawy
            }
        }
    }, {
        "id": "aa1d05e0-943b-47cb-a759-9d8c16707129",
        "name": "Allegro Przesyłka polecona",
        "paymentPolicy": "IN_ADVANCE",
        "allegroEndorsed": true,
        "shippingRatesConstraints": {
            "allowed": true,
            "maxQuantityPerPackage": {
                "max": 999999
            },
            "maxPackageWeight": {
                "supported": false
            },
            "firstItemRate": {
                "min": "0.00",
                "max": "5.90",
                "currency": "PLN"
            },
            "nextItemRate": {
                "min": "0.00",
                "max": "0.00",
                "currency": "PLN"
            },
            "shippingTime": {
                "default": {
                    "from": "PT96H",
                    "to": "PT120H"
                },
                "customizable": false
            }
        }
    },
    ...
    {
        "id": "845efe05-0c96-47c3-a8cb-aa4699c158ce",
        "name": "Przesyłka kurierska pobranie",
        "paymentPolicy": "CASH_ON_DELIVERY",
        "allegroEndorsed": false,
        "shippingRatesConstraints": {
            "allowed": true,
            "maxQuantityPerPackage": {
                "max": 999999
            },
            "maxPackageWeight": {
                "supported": true,
                "min": "1.000",
                "max": "30.000",
                "unit": "KILOGRAM"
            },
            "firstItemRate": {
                "min": "0.00",
                "max": "100000000.00",
                "currency": "PLN"
            },
            "nextItemRate": {
                "min": "0.00",
                "max": "100000000.00",
                "currency": "PLN"
            },
            "shippingTime": {
                "default": {
                    "from": "PT24H",
                    "to": "PT48H"
                },
                "customizable": true
            }
        }
    }
    ]

Jeśli masz ofertę, do której nie przypisałeś cennika dostawy, skorzystaj z GET /sale/offers/{offerId}/shipping-rates, dzięki temu pobierzesz informacje o metodach dostawy w danej ofercie.

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/sale/offers/8151913057/shipping-rates' \
  -H 'Accept: application/vnd.allegro.beta.v1+json'

Przykładowy response:

  {
    "rates": [
        {
            "deliveryMethod": {
                "id": "845efe05-0c96-47c3-a8cb-aa4699c158ce"    -- identyfikator danej
                                                                metody dostawy
            },
            "maxQuantityPerPackage": 1,                         -- liczba w paczce
            "maxPackageWeight": {                               -- maksymalna waga paczki
                "value": "19.000",
                "unit": "KILOGRAM"
            },
            "firstItemRate": {                                  -- cena przesyłki
                "amount": "11.00",
                "currency": "PLN"
            },
            "nextItemRate": {                                   -- cena kolejnej sztuki
                "amount": "0.00",
                "currency": "PLN"
            },
            "shippingTime": {                                   -- czas dostawy
                "from": "PT72H",
                "to": "PT120H"
            }
        }
    ]
  }

Teraz za pomocą POST /sale/shipping-rates utworzysz Cennik dostawy. Jego identyfikatora użyjesz, gdy będziesz tworzyć ofertę - w polu shippingRates.id.

Na jednym koncie możesz mieć maksymalnie 250 cenników dostawy.

Kliknij, aby zobaczyć request

curl -X POST \
'https://api.allegro.pl/sale/shipping-rates' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: {token}' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d '{
    "name": "Nowy cennik dostawy",                               -- wymagane, nazwa
                                                                danego cennika dostaw
    "rates": [
        {
            "deliveryMethod": {
                "id": "845efe05-0c96-47c3-a8cb-aa4699c158ce"    -- wymagane, identyfikator
                                                                danej metody dostawy
            },
            "maxQuantityPerPackage": 10,                        -- wymagane, liczba w paczce
            "maxPackageWeight": {                               -- maksymalna waga paczki, może być podana tylko dla
                                                                niektórych metod dostawy
                "value": "19.000",
                "unit": "KILOGRAM"
            },
            "firstItemRate": {                                   -- wymagane, cena przesyłki
                "amount": "12.58",
                "currency": "PLN"
            },
            "nextItemRate": {                                    -- wymagane, cena
                                                                 kolejnej sztuki
                "amount": "12.58",
                "currency": "PLN"
            },
            "shippingTime": {                                    -- czas dostawy, może być podany tylko dla
                                                                 niektórych metod dostawy
                                                                 (np. "845efe05-0c96-47c3-a8cb-aa4699c158ce").
                                                                 Jeśli nie został podany, zostanie użyty
                                                                 domyślny czas wysyłki danej metody dostawy.
                "from": "PT72H",                                 -- podaj wielokrotność 24H,
                "to": "PT120H"                                   -- zgodnie z formatem ISO 8601
            }
        },
        {
            "deliveryMethod": {
                "id": "2488f7b7-5d1c-4d65-b85c-4cbcf253fd93"
            },
            "maxQuantityPerPackage": 1,
            "firstItemRate": {
                "amount": "7.99",
                "currency": "PLN"
            },
            "nextItemRate": {
                "amount": "0.00",
                "currency": "PLN"
            }
        }
    ]
}'

Kliknij, aby zobaczyć response

{
     "id": "73491425-dea3-420b-b2bb-680310d764e4",
     "name": "Nowy cennik dostawy",
    "rates": [
        {
            "deliveryMethod": {
                "id": "845efe05-0c96-47c3-a8cb-aa4699c158ce"
            },
            "maxQuantityPerPackage": 10,
            "maxPackageWeight": {
                "value": "19.000",
                "unit": "KILOGRAM"
            },
            "firstItemRate": {
                "amount": "12.58",
                "currency": "PLN"
            },
            "nextItemRate": {
                "amount": "12.58",
                "currency": "PLN"
            },
            "shippingTime": {
                "from": "PT72H",
                "to": "PT120H"
            }
        },
        {
            "deliveryMethod": {
                "id": "2488f7b7-5d1c-4d65-b85c-4cbcf253fd93"
            },
            "maxQuantityPerPackage": 1,
            "maxPackageWeight": null,
            "firstItemRate": {
                "amount": "7.99",
                "currency": "PLN"
            },
            "nextItemRate": {
                "amount": "0.00",
                "currency": "PLN"
            },
            "shippingTime": null
        }
    ],
    "lastModified": "2018-04-03T13:46:54.722Z"
 }

Szczegóły danego cennika sprawdzisz za pomocą GET /sale/shipping-rates/{shippingRatesId}.

Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/sale/shipping-rates/fde5853c-01ce-4991-a4b3-994c1a4a408e' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'

Kliknij, aby zobaczyć response

{
    "id": "ed1645ab-0895-4010-bd85-bb5d92ab0d83",               -- identyfikator
                                                                danego cennika dostaw
    "name": "Cennik dostawy test API 1",                        -- nazwa danego cennika
                                                                dostaw
    "rates": [
        {
            "deliveryMethod": {
                "id": "9081532b-5ad3-467d-80bc-9252982e9dd8"    -- identyfikator
                                                                danej metody dostawy
            },
            "maxQuantityPerPackage": 1,                         -- liczba w paczce
            "maxPackageWeight": {                               -- maksymalna waga paczki, może być podana tylko dla
                                                                niektórych metod dostawy
                "value": "19.000",
                "unit": "KILOGRAM"
            },
            "firstItemRate": {                                  -- cena przesyłki
                "amount": "10.95",
                "currency": "PLN"
            },
            "nextItemRate": {                                  -- cena kolejnej sztuki
                "amount": "0.00",
                "currency": "PLN"
            },
            "shippingTime": {                                  -- czas dostawy,
                "from": "PT72H",                               wielokrotność 24H,
                "to": "PT120H"                                 zgodnie z formatem ISO 8601
            }
        },
        {
            "deliveryMethod": {
                "id": "574d1c9e-9903-4626-903f-f72441d520d5"
            },
            "maxQuantityPerPackage": 1,
            "maxPackageWeight": null,
            "firstItemRate": {
                "amount": "8.60",
                "currency": "PLN"
            },
            "nextItemRate": {
                "amount": "0.00",
                "currency": "PLN"
            },
            "shippingTime": null
        }
    ],
    "lastModified": "2018-08-08T08:24:56.086Z"                  -- data ostatniej
                                                                modyfikacji danego cennika
}

W tym artykule opisaliśmy szczegółowo, jak zarządzać cennikami dostawy na koncie sprzedawcy i w jego ofertach.

Ustawienia dostawy

Pobierzesz je przy pomocy GET /sale/delivery-settings.

Przykładowy request:

  curl -X GET \ 
  'https://api.allegro.pl/sale/delivery-settings' \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json'

Przykładowy response:

  {
      "freeDelivery": {
            "amount": "4.04",              -- minimalna kwota zamówienia
            "currency": "PLN"              kwalifikująca się do darmowej dostawy
      },
      "abroadFreeDelivery": {
            "amount": "900.12",            -- minimalna kwota zamówienia
            "currency": "PLN"              kwalifikująca do darmowej dostawy za granicę
      },
      "joinPolicy": {
            "strategy": "MAX"              -- sposób obliczania kosztów dostawy
      },
      "customCost": {
            "allowed": true                -- czy klient może wpisać koszt
                                           dostawy ustalony ze sprzedawcą
      },
      "updatedAt": "2019-08-21T10:13:40.036Z"
  }

Ustawienia dostawy możesz edytować za pomocą PUT /sale/delivery-settings.

Warunki oferty

W polu afterSalesServices przekaż informacje o gwarancji oraz warunkach zwrotów i reklamacji. Odpowiednie identyfikatory pobierzesz za pomocą:

GET /after-sales-service-conditions/return-policies - warunki zwrotów;
GET /after-sales-service-conditions/implied-warranties - warunki reklamacji;
GET /after-sales-service-conditions/warranties - informacje o gwarancji;

Przykład prawidłowo uzupełnionej struktury:

  ...
    "afterSalesServices": {
        "impliedWarranty": {                                   -- warunki reklamacji
            "id": "1377b0a6-b397-4e1e-b57c-4234bd84d036"
        },
        "returnPolicy": {                                      -- warunki zwrotów
            "id": "e261d4ed-ced7-4c10-82cd-13aa26192895"
        },
        "warranty": {                                          -- informacje o gwarancji
            "id": "h2dsd4ed-ced7-2c10-82cd-13aa26192895"
        }
    },
  ...

Opcje faktury i ustawienia VAT

Opcje faktury

Aby określić, czy i w jakiej formie sprzedawca udostępnia możliwość wystawienia faktury VAT, skorzystaj z pola payments.invoice i przekaż jedną z dostępnych wartości:

VAT - faktura VAT,
VAT_MARGIN - faktura VAT-marża,
WITHOUT_VAT - faktura bez VAT,
NO_INVOICE - brak faktury.

Przykład prawidłowo uzupełnionej struktury:

  ...
  "payments": {
    "invoice": "NO_INVOICE"
  }
  ...

Ustawienia VAT

W ofercie możesz wskazać konkretną stawkę VAT, niezależnie od ustawionej opcji faktury.

Dostępne ustawienia i identyfikatory stawek VAT w danej kategorii sprawdzisz za pomocą GET /sale/tax-settings?category.id={categoryId}.

W poszczególnych kategoriach dostępne ustawienia VAT mogą się różnić. Dlatego sprawdzaj, jakie stawki VAT są dla danej kategorii dostępne.

Aby ustawić wybraną stawkę:

przekaż odpowiednią kombinację wartości pól tax.rate, tax.subject oraz tax.exemption, na podstawie których znajdziemy identyfikator pasującego ustawienia. W przypadku braku dopasowania zwrócimy błąd walidacji z informacją, które pola powinny zostać uzupełnione lub komunikatem o całkowitym braku dopasowania:
```
...
"tax": {
 "rate": "23.00",
 "subject": "GOODS",
 "exemption": "MONEY_EQUIVALENT"
}
...
```
w polu tax.id przekaż identyfikator ustawienia VAT pozyskany dzięki GET /sale/tax-settings?category.id={categoryId}:
```
...
"tax": {
 "id": “f40ae51c-70a2-4882-98a7-6272404f0ec5”
}
...
```

Promowanie

Do zarządzania promowaniem oferty udostępniliśmy nowe zasoby, o których więcej przeczytasz w naszym poradniku - Jak zarządzać ofertami. Dzięki nim sprzedawca może łatwo zarządzać opcjami promowania ofert - szybciej reagować na zmiany w sprzedaży, a oferty promować tylko wtedy, gdy uzna to za opłacalne.

Informacje o promowaniu są opcjonalne, możesz je uzupełnić także w drafcie oferty.

Przykład prawidłowo uzupełnionej struktury:

  ...
   "promotion": {   
        "emphasized": true,                         -- wyróżnienie
        "bold": false,                              -- pogrubienie (dostępne tylko w 
                                                    ramach emphasizedHighlightBoldPackage)
        "highlight": false,                         -- podświetlenie (dostępne tylko w ramach 
                                                    emphasizedHighlightBoldPackage)
        "departmentPage": false,                    -- oferta promowana na stronie kategorii
        "emphasizedHighlightBoldPackage": false     -- pakiet promowania: wyróżnienie,
                                                    podświetlenie i pogrubienie oferty
    },
...

Opcje dodatkowe

Tagi ofertowe

Jeśli posiadasz wykupiony abonament, możesz do swojej aktywnej oferty także przypisać tagi ofertowe. Najpierw sprawdź, jakie tagi wcześniej utworzyłeś na swoim koncie.

Dnia 1.04.2021 zmniejszyliśmy limit tagów ofertowych, jakie możesz dodać do konta za pomocą: POST /sale/offer-tags. Dotychczasowy limit, który wynosił: 10000, zmieniliśmy na: 100. Nie usunęliśmy jednak nadmiarowych tagów użytkownikom, którzy już wcześniej przekroczyli próg 100 tagów.

Tagi ofertowe pobierzesz za pomocą GET /sale/offer-tags. Otrzymasz maksymalnie 100 tagów, jakie masz przypisane do swojego konta. Możesz również pobrać listę tagów, która jest dostosowana do twoich potrzeb, używając parametrów:

offset - wskaż miejsce, od którego chcesz pobrać kolejną porcję danych (przyjmuje wartości z zakresu, jaki obejmuje typ danych integer). Domyślnie 0.
limit - określ liczbę tagów, jaką mamy zwrócić w odpowiedzi (przyjmuje wartości z zakresu, jaki obejmuje typ danych integer). Domyślnie 100.

np. GET /sale/offer-tags&offset=0&limit=10 zwróci listę 10 tagów licząc od pierwszego.

Przykładowy request:

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

Przykładowy response:

  {
    "tags": [
        {
            "id": "500fedd3-2140-4225-87d4-a22484222776",   -- identyfikator taga,
            "name": "Komiksy",                              -- nazwa taga,
            "hidden": false                                 -- czy tag jest ukryty,
                                                            przyjmuje wartości false
                                                            (tag jest widoczny) oraz
                                                            true (tag jest ukryty),
        },
        {
            "id": "d2d2d475-7049-493d-bb95-f4ea59983ecb",
            "name": "Filmy",
            "hidden": false
        },
        {
            "id": "4b876428-d827-492b-a30e-aee3f5be791a",
            "name": "Muzyka",
            "hidden": false
        }
    ]
  }

Teraz, gdy wiesz już jakich tagów możesz użyć, przypisz wybrane tagi do swojej oferty. Zrobisz to za pomocą POST sale/offers/{offerId}/tags.

Przykładowy request:

  curl -X POST \
  http://api.allegro.pl/sale/offers/{offerId}/tags \
  -H 'Content-Type: application/vnd.allegro.public.v1+json'
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}' \
  -d '{
      "tags": [
        {
            "id": "500fedd3-2140-4225-87d4-a22484222776"   -- wymagany, identyfikator taga,
        }
    ]
  }'

Przykładowy response

200 - OK - poprawnie przypisane tagi

Każde kolejne przypisanie tagów do tej oferty nadpisuje poprzednie przypisania. Oznacza to, że jeśli chcesz usunąć przypisania tagów do oferty i nie dopisywać do niej nowych, wywołaj ten zasób i przekaż w body pustą strukturę tags.

    {
         "tags":[]
     }

Załączniki

Do ofert możesz dodawać załączniki w formacie PDF, JPEG i PNG. Wyświetlimy je pod opisem oferty w sekcji Dodatkowe informacje. Załączników może być maksymalnie 9 - po jednym załączniku z listy:

Poradnik (MANUAL)
Regulamin promocji (SPECIAL_OFFER_RULES)
Regulamin konkursu (COMPETITION_RULES)
Fragment książki (BOOK_EXCERPT)
Instrukcję obsługi (USER_MANUAL)
Instrukcję montażu (INSTALLATION_INSTRUCTIONS)
Instrukcję gry (GAME_INSTRUCTIONS)
Etykietę energetyczną (ENERGY_LABEL)
Kartę produktu (PRODUCT_INFORMATION_SHEET)

Jeśli chcesz dodać załącznik do oferty:

Stwórz obiekt załącznika, dzięki czemu otrzymasz identyfikator załącznika oraz adres URL, na który wyślesz załącznik,
Na ten URL prześlij plik, który chcesz dodać do oferty,
Przesłany załącznik podłącz do oferty.

Stwórz obiekt załącznika

Aby dodać załącznik, najpierw musisz stworzyć na swoim koncie obiekt załącznika. Zrobisz to za pomocą POST /sale/offer-attachments. Gdy utworzysz obiekt, będziesz miał:

identyfikator załącznika,
adres URL, za pomocą którego prześlesz plik na nasz serwer.

Przykładowy request:

  curl -X POST \
  'https://api.allegro.pl/sale/offer-attachments' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'
  -d '{
      "type": "SPECIAL_OFFER_RULES",                      -- wymagany, rodzaj załącznika,
                                                          dostępne wartości MANUAL,
                                                          SPECIAL_OFFER_RULES,
                                                          COMPETITION_RULES,
                                                          BOOK_EXCERPT, USER_MANUAL,
                                                          INSTALLATION_INSTRUCTIONS,
                                                          GAME_INSTRUCTIONS,
                                                          ENERGY_LABEL,
                                                          PRODUCT_INFORMATION_SHEET
      "file": {
        "name": "abcde.pdf"                               -- wymagany, nazwa pliku, który dodasz,
    }
}'

Adres URL, za pomocą którego prześlesz plik na nasz serwer, znajdziesz w nagłówku response. Adres ten jest jednorazowy i unikalny. Jego format może zmieniać się w czasie, dlatego za każdym razem korzystaj z adresu z nagłówka. Nie składaj samodzielnie adresu z dostępnych elementów.

Przykładowy response

201 - created - obiekt załącznika utworzony prawidłowo

Nagłówek response'a:

    Location: http://upload.allegro.pl/sale/offer-attachments/e9d1bf7c-804e-4faf-9e24-b2d3aa3eda05

Body response'a:

  {
    "id": "e9d1bf7c-804e-4faf-9e24-b2d3aa3eda05",              -- identyfikator draftu załącznika,
    "type": "SPECIAL_OFFER_RULES",                             -- rodzaj załącznika,
    "file": {
        "name": "abcde.pdf"                                    -- nazwa pliku, który dodasz,
    }
  }

Prześlij plik

Teraz możesz przesłać załącznik na nasz serwer. Do tego celu użyj adresu, który otrzymałeś w nagłówku odpowiedzi (w polu Location) na poprzednie wywołanie.

Przykładowy request:

  curl -X PUT \
  'http://upload.allegro.pl/sale/offer-attachments/{attachmentId}' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Content-Type: application/pdf' \
  -H 'Authorization: Bearer {token}'
  --data-binary "@abcde.pdf"                               -- wymagany, zawartość pliku z
                                                           załącznikiem w postaci binarnej

Przykładowy response:

  {
    "id": "07ee5e36-afc7-41eb-af49-3df5354ef858",          -- identyfikator draftu załącznika,
    "type": "SPECIAL_OFFER_RULES",                         -- rodzaj załącznika,
    "file":
        "name": "abcde.pdf",                               -- nazwa pliku, który dodasz,
        "url": {adres_pliku}                               -- adres, pod którym jest dostępny
                                                           załącznik.
    }
  }

Podłącz załącznik do oferty

Za pomocą PUT /sale/offers/{offerId} dodaj załącznik do oferty - dodaj jego identyfikator w strukturze attachments.

    "attachments": [
            {
                "id": "07ee5e36-afc7-41eb-af49-3df5354ef858"
            }
        ]

Tabele rozmiarów

Dane dotyczące tabel rozmiarów i szablonów tabel rozmiarów pobierzesz przy pomocy:

GET /sale/size-tables - pobierz wszystkie tabele rozmiarów z konta.
GET /sale/size-tables/{tableId} - pobierz wybraną tabelę rozmiarów z konta.
GET /sale/size-tables-templates - pobierz listę szablonów tabel rozmiarów.

Tabelami rozmiarów możesz zarządzać przy pomocy:

POST /sale/size-tables - utwórz tabelę na podstawie identyfikatora szablonu tabeli rozmiarów.
PUT /sale/size-tables/{tableId} - zaktualizuj wybraną tabelę rozmiarów.

Aby przypisać tabelę rozmiarów do oferty, przekaż jej identyfikator w polu sizeTable.id.

Więcej informacji na temat Tabel rozmiarów w REST API znajdziesz w naszym newsie.

Ważne informacje dla sprzedającego

W ofercie, w obiekcie "messageToSellerSettings" możesz określić, czy kupujący może wprowadzić “Ważną wiadomości dla sprzedającego” w zamówieniu w formularzu dostawy i płatności. Wyświetlimy ją w polu "messageToSeller" po pobraniu zamówienia poprzez:

W obiekcie "messageToSellerSettings", w polu "mode" możesz przekazać jedną z wartości:

OPTIONAL - wyświetlimy kupującemu pole “Ważne informacje dla sprzedającego” w formularzu dostawy i płatności, ale nie będzie musiał go uzupełniać,
HIDDEN - ukryjemy pole “Ważne informacje dla sprzedającego” w formularzu dostawy i płatności - kupujący nie będzie mógł wprowadzić żadnej wiadomości.
```
...
"messageToSellerSettings": {
    "mode": "HIDDEN"
}
...
```

Jeżeli nie przekażesz żadnej wartości w tym obiekcie (lub przekażesz null) - domyślnie, wypełnienie “Ważnych informacji dla sprzedającego” przez Kupującego będzie opcjonalne.

Uzupełnij dane w ofercie

Gdy już w odpowiedzi dla POST /sale/offers otrzymasz identyfikator oferty w polu id, przekaż go w PUT /sale/offers/{offerId}, aby uzupełnić dane w drafcie oferty. Jeśli prześlesz niekompletne dane, to w polu validation wyświetlimy błędy logiczne, przez które nie możemy wyświetlić oferty, np. nie podano kwoty minimalnej dla licytacji.

Jeżeli chcesz zaktualizować trwającą ofertę:

pobierz ją przez GET /sale/offers/{offerId}. Następnie, gdy aktualizujesz ofertę za pomocą PUT /sale/offers/{offerId}, prześlij analogiczną strukturę, 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 oferty;
skorzystaj z PATCH /sale/product-offers/{offerId} i w strukturze przekaż tylko to pole, które chcesz edytować. Więcej informacji o metodzie PATCH znajdziesz w naszym poradniku.

Za pomocą PUT /sale/offers/{offerId} uzupełnij dane w drafcie oferty. Poniżej opisaliśmy pola, które możesz przesłać, jeśli chcesz opublikować ofertę w serwisie.

Aby zapisać czas wysyłki w drafcie musisz jednocześnie przesłać również informacje o identyfikatorze cennika dostawy i formacie sprzedaży.

Kliknij, aby zobaczyć request

curl -X PUT \
'https://api.allegro.pl/sale/offers/{offerId}'
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d '{
    "id": "7276261934",                             -- numer identyfikacyjny oferty
    "name": "Oferta testowa",                       -- wymagane, tytuł pobranej oferty
    "product": {
     "id": "634238b1-4385-4de7-9c00-dfa49fce16ab"   -- identyfikator produktu
    "category": {
        "id": "257150"                              -- wymagane, kategoria najniższego rzędu, w której
                                                    znajduje się oferta. Aktualne numery kategorii
                                                    pobierzesz za GET  /sale/categories?parent.id={catId}
    },
    "parameters": [                                 -- wymagane, parametry oferty, aktualne parametry
                                                    dostępne w danej kategorii
                                                    sprawdzisz za pomocą
                                                    GET /sale/categories/{categoryId}/parameters
        {
            "id": "11323",
            "valuesIds": [
                "11323_1"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "128188",
            "valuesIds": [
                "128188_1"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "127448",
            "valuesIds": [
                "127448_1"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "4386",
            "valuesIds": [
                "4386_1"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "219",
            "valuesIds": [
                "219_2",
                "219_256",
                "219_4"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "225693",                         -- parametr GTIN
            "valuesIds": [],                        (info: http://developer.allegro.pl/news/#gtin)
            "values": [
                "6901443187416"
            ],
            "rangeValue": null
        }
    ],
    "description": {                                -- wymagane, opis oferty
        "sections": [
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content": "<p>Tekstowy opis przedmiotu</p>"
                    },
                    {
                        "type": "IMAGE",
                        "url": "https://e.allegroimg.com/original/01fd60/4ea8d18e4275b0878b7f0562067e"
                    }
                ]
            },
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content": ""<p>Tekstowy opis przedmiotu</p>""
                    }
                ]
            }
        ]
    },
    "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 ofercie (miniaturką).
        {
            "url": "https://e.allegroimg.com/original/01fd60/4ea8d18e4275b0878b7f0562067e"
        },
        {
            "url": "https://e.allegroimg.com/original/018474/c62b54a74120a7983b09d0fa4a4e"
        },
        {
            "url": "https://8.allegroimg.com/original/013a51/4dd0904a4169ad8b0d25a8984b48"
        },
        {
            "url": "https://2.allegroimg.com/original/01b48e/6e777def4a71ba68952358bd2072"
        }
    ],
    "compatibilityList": {                          -- niewymagane, sekcja Pasuje do
        "id": "d04e8a0c-40a1-4c53-8902-ffee7261845e-922db1ed6fa1c9731d50ce251007ab400247b0ebb62f1006493f5b6c418bb0fa-2",
        "type": "PRODUCT_BASED"
    },
    "tecdocSpecification": {                        -- niewymagane, specyfikacja techniczna TecDoc
                                                    dla części motoryzacyjnych
        "id": "e3725f4b-1b4b-4e39-ad7f-331a2c858a7f"
    },
    "sellingMode": {                                -- wymagane, format sprzedaży, obecnie
                                                    dostępne są trzy wartości: BUY_NOW (Kup Teraz);
                                                    AUCTION (licytacja); ADVERTISEMENT (ogłoszenie)
        "format": "BUY_NOW",
        "price": {
            "amount": "1499",                       -- wymagane, cena dla oferty w formacie
                                                    BUY_NOW (Kup Teraz), ADVERTISEMENT (ogłoszenie)
            "currency": "PLN" 
        },
        "netPrice": null,                           -- cena netto, obliczana automatycznie na
                                                    podstawie stawki podatku VAT
        "startingPrice": null,                      -- cena początkowa licytacji, dostępna w
                                                    formacie sprzedaży AUCTION (licytacja)
        "minimalPrice": null                        -- cena minimalna, dostępna w
                                                    formacie sprzedaży AUCTION (licytacja)
    },
    "tax": {                                        -- ustawienia podatku VAT
        "id": "f40ae51c-70a2-4882-98a7-6272404f0ec5"                       
    },
    "stock": {
        "available": 4,                             -- wymagane, liczba aktualnie dostępnych
                                                    przedmiotów, WAŻNE! Nie uzupełniaj dla oferty
                                                    typu ADVERTISEMENT (ogłoszenie), natomiast
                                                    dla ogłoszenia typu AUCTION (licytacja) podaj wartość 1
        "unit": "UNIT"                              -- wymagane, obecnie dostępne są trzy
                                                    wartości: UNIT (sztuki); SET (komplety);
                                                    PAIR (pary). WAŻNE! Nie uzupełniaj tego
                                                    pola dla oferty typu ADVERTISEMENT (ogłoszenie)
    },
    "publication": {
        "republish": true,                          -- niewymagane, automatyczne wznowienie oferty.
                                                    Pamiętaj, że możesz automatycznie wznowić
                                                    ofertę i licytację:
                                                    -- ofertę wznowimy ze stałą początkową
                                                    liczbą przedmiotów niezależnie od tego,
                                                    ile przedmiotów sprzedasz.
                                                    -- licytację wznowimy tylko,
                                                    gdy nie zakończyła się sprzedażą.
        "duration": null,                           -- wymagane, czas trwania oferty, dostępne
                                                    wartości: null (do wyczerpania zapasów),
                                                    P3D (3 dni); P5D (5 dni); P7D (7 dni);
                                                    P10D (10 dni); P20D (20 dni); P30D (30 dni), czas
                                                    możesz podać też w godzinach - np.: P72H (3 dni).
                                                    Dla oferty typu AUCTION (licytacja) nie możesz
                                                    podać wartości null i dostępne są wartości:
                                                    P1D (1 dzień); P3D (3 dni); P5D (5 dni); P7D (7 dni);
                                                    P10D (10 dni); Natomiast dla ofert typu
                                                    ADVERTISMENT (ogłoszenia) dostępne są wartości:
                                                    null (na czas nieokreślony - opłaty naliczane co 10 dni);
                                                    P10D (10 dni); P20D (20 dni); P30D (30 dni)
        "status": "INACTIVE",                       -- status oferty, dostępne są obecnie trzy
                                                    wartości: ACTIVE (oferta aktywna w serwisie),
                                                    INACTIVE (oferta nieaktywna), ENDED (zakończona oferta)
        "startingAt": null,                         -- niewymagane, czas startu oferty, dotyczy
                                                    ofert do publikacji w przyszłości
        "endingAt": null,                           -- niewymagane, data zakończenia oferty
        "endedBy": null                             -- niewymagane, powód zakończenia oferty.
                                                    Dostępne wartości: USER (przez użytkownika),
                                                    ADMIN (przez pracownika allegro),
                                                    EXPIRATION (zgodnie z planowaną datą lub oferta się
                                                    wyprzedała), ERROR (w wyniku wewnętrznego błędu)
    },
    "delivery": {
        "shippingRates": {
            "id": "4b9ad5b9-7ee9-409b-86f5-578672c13df8"    -- wymagane, numer identyfikacyjny
                                                            cennika dostawy, pobierzesz go
                                                            za pomocą
                                                            GET /sale/shipping-rates.
                                                            Dla formatu sprzedaży typu  ADVERTISEMENT
                                                            (ogłoszenie) zostaw to
                                                            pole puste - prześlij "delivery": null
        },
        "handlingTime": "PT168H",                           -- czas wysyłki, obecnie dostępne są
                                                            wartości: PT0S (natychmiast), PT24H (24 godziny),
                                                            P2D (2 dni), P3D (3 dni), P4D (4 dni), P5D (5 dni),
                                                            P7D (7 dni), P10D (10 dni), P14D (14 dni),
                                                            P21D (21 dni), P30D (30 dni), P60D (60 dni).
                                                            Można również podać te wartości
                                                            w godzinach, np. PT72H (3 dni).
                                                            Niewymagane dla formatu sprzedaży
                                                            typu ADVERTISEMENT (ogłoszenie).
        "additionalInfo": "Dodatkowe informacje o dostawie" -- niewymagane, dodatkowe
                                                            informacje o dostawie, możesz tutaj wpisać
                                                            informację w formie tekstowej, którą wyświetlimy
                                                            w ofercie w sekcji “Dostawa i płatność”.
        "shipmentDate":"2018-04-01T08:00:00Z"               -- wysyłka od - np.dla przedsprzedaży.
                                                            Uzupełnij datę w formacie zgodnym z ISO 8601.
    },
    "payments": {
        "invoice": "VAT"                                    -- 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)
    },
    "discounts": {                                          -- niewymagane, informacje o zniżkach,
       "wholesalePriceList": {                              identyfikator cennika hurtowego pobierzesz
           "id": "5637592a-0a24-4771-b527-d89b2767d821"     za pomocą GET /sale/loyalty/promotions
       }                                                    i filtra “promotionType=WHOLESALE_PRICE_LIST”
    },
    "afterSalesServices": {                                 -- warunki dla oferty, wymagane dla
                                                            kont firma. Dla formatu sprzedażu
                                                            ADVERTISEMENT (ogłoszenie) ta
                                                            opcja jest niedostępna, prześlij
                                                            "afterSalesServices": null.
        "impliedWarranty": {
            "id": "b0590fac-9858-4d01-8487-1c6a09c55a68"    -- wymagane dla kont firma,
                                                            informacje o reklamacji; identyfikator
                                                            pobierzesz za pomocą
                                                            GET /after-sales-service-conditions/implied-warranties
        },
        "returnPolicy": {
            "id": "c27c2ddd-f587-44db-b3c8-1f181964ea4d"    -- wymagane dla kont firma, polityka
                                                            zwrotów; identyfikator pobierzesz za pomocą
                                                            GET /after-sales-service-conditions/return-policies
        },
        "warranty": {
            "id": "f8694df6-f020-4a27-ac0a-f4f959969e14"    -- niewymagane, informacje o
                                                            gwarancjach, identyfikator pobierzesz za pomocą
                                                            GET /after-sales-service-conditions/warranties
        }
    },
    "additionalServices": null,                             -- usługi dodatkowe; identyfikatory swoich
                                                            grup usług dodatkowych pobierzesz za pomocą metody
                                                            GET /sale/offer-additional-services/groups.
                                                            Opcja niedostępna dla formatu sprzedaży
                                                            typu ADVERTISEMENT (ogłoszenie), prześlij
                                                            "additionalServices": null.
    "sizeTable": null,                                      -- identyfikator tabeli rozmiarów,
                                                            pobierzesz go przy pomocy
                                                            GET /sale/size-tables
    "fundraisingCampaign": null,                            -- niewymagane, identyfikator organizacji   
                                                            charytatywnej, pobierzesz go przy pomocy
                                                            GET /charity/fundraising-campaigns     
    "promotion": {                                          -- niewymagane, opcje promowania,
                                                            przy każdej z opcji należy wybrać
                                                            jedną z wartości: false (opcja nieaktywna);
                                                            true (opcja aktywna)
        "emphasized": true,                                 -- wyróżnienie
        "bold": false,                                      -- pogrubienie
        "highlight": false,                                 -- podświetlenie
        "departmentPage": false,                            -- oferta promowana na stronie kategorii
        "emphasizedHighlightBoldPackage": false             -- pakiet promowania: wyróżnienie,
                                                            podświetlenie i pogrubienie oferty
    },
    "location": {                                           -- wymagane, dla ofert z wysyłką, to miejsce,
                                                            z którego paczka zostanie wysłana.
                                                            Dla ofert z odbiorem osobistym, jest to miejsce odbioru,
                                                            dodatkowo zalecamy użycie punktów odbioru
                                                            Przed uzupełniem tego pola przypisz wcześniej cennik
                                                            dostawy oraz określ format sprzedaży.
        "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,
        "id":"4131asdsad40011"                              który nadaje sprzedający, np. aby powiązać ofertę
                },                                          z produktem w swoim magazynie. Możesz wprowadzić
                                                            tutaj dowolny ciąg znaków - będzie on dostępny
                                                            również po wznowieniu oferty.
    "attachments": [
            {
        "id": "07ee5e36-afc7-41eb-af49-3df5354ef858"        -- niewymagany, identyfikator załącznika
            }
        ]
    "contact": null,                                        -- niewymagane, identyfikator
                                                            danych kontaktowych identyfikator danych kontaktowych
                                                            dla oferty w formacie ADVERTISEMENT (ogłoszenie),
                                                            pobierzesz go za pomocą
                                                            GET /sale/offer-contacts
    "validation": {
        "errors": [],                                       -- informacje o ewentualnych błędach,
                                                            poinformujemy cię o tym jeśli na przykład podasz
                                                            niepoprawny numer ID cennika.
        "validatedAt": "2018-04-06T08:29:37.461Z"           -- informacje, kiedy odbyła się
                                                            ostatnia walidacja oferty
    },
    "b2b": {
        "buyableOnlyByBusiness": false                      -- oferta dla biznesu (true - tak, false - nie)
    },
    "createdAt": "2018-04-06T08:26:32Z",                    -- wymagane, data utworzenia oferty
    "updatedAt": "2018-04-06T08:29:38.664Z"                 -- wymagane, data ostatniej aktualizacji oferty
}'

Kliknij, aby zobaczyć response

{
    "id": "7276377308",
    "name": "Oferta testowa",
    "category": {
        "id": "257150"
    },
    "parameters": [
        {
            "id": "11323",
            "valuesIds": [
                "11323_1"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "128188",
            "valuesIds": [
                "128188_1"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "127448",
            "valuesIds": [
                "127448_1"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "4386",
            "valuesIds": [
                "4386_1"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "219",
            "valuesIds": [
                "219_2",
                "219_256",
                "219_4"
            ],
            "values": [],
            "rangeValue": null
        },
        {
            "id": "225693",
            "valuesIds": [],
            "values": [
                "6901443187416"
            ],
            "rangeValue": null
        }
    ],
    "description": {
        "sections": [
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content": "<p>Tekstowy opis przedmiotu</p>"
                    },
                    {
                        "type": "IMAGE",
                        "url": "https://e.allegroimg.com/original/01fd60/4ea8d18e4275b0878b7f0562067e"
                    }
                ]
            },
            {
                "items": [
                    {
                        "type": "TEXT",
                        "content": "<p>Tekstowy opis przedmiotu</p>"
                    }
                ]
            }
        ]
    },
    "images": [
        {
            "url": "https://e.allegroimg.com/original/01fd60/4ea8d18e4275b0878b7f0562067e"
        },
        {
            "url": "https://e.allegroimg.com/original/018474/c62b54a74120a7983b09d0fa4a4e"
        },
        {
            "url": "https://8.allegroimg.com/original/013a51/4dd0904a4169ad8b0d25a8984b48"
        },
        {
            "url": "https://2.allegroimg.com/original/01b48e/6e777def4a71ba68952358bd2072"
        }
    ],
    "compatibilityList": {
        "id": "d04e8a0c-40a1-4c53-8902-ffee7261845e-922db1ed6fa1c9731d50ce251007ab400247b0ebb62f1006493f5b6c418bb0fa-2",
        "type": "PRODUCT_BASED",
        "items": [
            {
                "text": "ALFA ROMEO 147 (937_) 1.6 16V T.SPARK (937.AXA1A, 937.AXB1A, 937.BXB1A) (AR 32104) 1598ccm 120KM/88kW 2001/01-2010/03, szczegóły: Strona zabudowy: z lewej, z prawej, Oś tylna, System hamulcowy: LUCAS, dla numeru artykułu: 343599, 343598"
            },
        ...
            {
                "text": "SKODA RAPID Spaceback (NH1) 1.2 TSI (CBZB) 1197ccm 105KM/77kW 2012/07-, szczegóły: Strona zabudowy: z prawej, Oś tylna, z lewej, System hamulcowy: LUCAS, dla numeru artykułu: 342966, 342967, dla numeru PR: 1KT"
            }
        ]
    },
    "tecdocSpecification": {
        "id": "e3725f4b-1b4b-4e39-ad7f-331a2c858a7f",
        "items": [
            {
                "name": "Wysokość [mm]",
                "values": [
                    "51"
                ]
            },
            {
                "name": "Materiał",
                "values": [
                    "stal"
                ]
            },
            {
                "name": "średnica [mm]",
                "values": [
                    "38"
                ]
            },
            {
                "name": "Wersja TecDoc",
                "values": [
                    "TecDoc 0619"
                ]
            }
        ]
    },
    "sellingMode": {
        "format": "BUY_NOW",
        "price": {
            "amount": "1499",
            "currency": "PLN"
        },
        "netPrice": {
            "amount": "1218.70",
            "currency": "PLN"
        },
        "startingPrice": null,
        "minimalPrice": null
    },
    "tax": {
        "id": "f40ae51c-70a2-4882-98a7-6272404f0ec5",
        "rate": “23.00”,
        "subject": “GOODS”,
        "exemption": “MONEY_EQUIVALENT”
    },               
    "stock": {
        "available": 4,
        "unit": "UNIT"
    },
    "publication": {
        "republish": true,
        "duration": null,
        "status": "INACTIVE",
        "startingAt": null,
        "endingAt": null
    },
    "delivery": {
        "shippingRates": {
            "id": "4b9ad5b9-7ee9-409b-86f5-578672c13df8"
        },
        "handlingTime": "PT168H",
        "additionalInfo": ""
        "shipmentDate":"2018-04-01T08:00:00Z"
    },
    "payments": {
        "invoice": "VAT"
    },
    "discounts": {
       "wholesalePriceList": {
           "id": "5637592a-0a24-4771-b527-d89b2767d821"
       }
    },
    "afterSalesServices": {
        "impliedWarranty": {
            "id": "b0590fac-9858-4d01-8487-1c6a09c55a68"
        },
        "returnPolicy": {
            "id": "c27c2ddd-f587-44db-b3c8-1f181964ea4d"
        },
        "warranty": {
            "id": "f8694df6-f020-4a27-ac0a-f4f959969e14"
        }
    },
    "additionalServices": null,
    "sizeTable": null,
    "fundraisingCampaign": null,
    "promotion": {
        "emphasized": true,
        "bold": false,
        "highlight": false,
        "departmentPage": false,
        "emphasizedHighlightBoldPackage": false
    },
    "location": {
        "countryCode": "PL",
        "province": "WIELKOPOLSKIE",
        "city": "Poznań",
        "postCode": "60-166"
    },
    "external": {                               -- niewymagany, zewnętrzny ID / sygnatura,
        "id":"4131asdsad40011"                  który nadaje sprzedający, np. aby powiązać ofertę
                },                              z produktem w swoim magazynie. Możesz wprowadzić
                                                tutaj dowolny ciąg znaków - będzie on dostępny
                                                również po wznowieniu oferty.
    "attachments": [],
    "contact": null,
    "validation": {
        "errors": [],
        "validatedAt": "2018-04-06T09:34:40.142Z"
    },
    "b2b": {
        "buyableOnlyByBusiness": false
    },
    "createdAt": "2018-04-06T09:29:47Z",
    "updatedAt": "2018-04-06T09:34:40.142Z"
}

Publikacja oferty

Jeśli oferta jest już kompletna i poprawnie zwalidowana, to za pomocą PUT /sale/offer-publication-commands/{commandId} opublikuj ją w serwisie. Zasób działa asynchronicznie - aby otrzymać kompletny raport wykonania zadania, skorzystaj z GET /sale/offer-publication-commands/{commandId}/tasks. 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). Wygeneruj wartość we własnym zakresie.

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

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

Przykładowy request:

  curl -X PUT \
  'https://api.allegro.pl/sale/offer-publication-commands/{commandId}'
  -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 ofert) i
                                            END (zakończenie danych ofert)
        "scheduledFor":"2018-03-28T12:00:00.000Z"   -- niewymagane, wysyłasz jeśli chcesz
                                            zaplanować wystawienie oferty w przyszłości
    },
      "offerCriteria": [
        {
            "offers":[                      -- wymagane, tablica obiektów z
                                            numerami identyfikacyjnymi ofert -
                                            maksymalnie 1000 ofert
                {
                    "id": "7276377308"
                }
            ],
            "type": "CONTAINS_OFFERS"       -- wymagane, obecnie dostępna jest
                                            jedna wartość:
                                            CONTAINS_OFFERS (oferty, w których zmienimy status)
        }
    ]
  }'

Przykładowy response:

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

Zestawienie zadań

Za pomocą GET /sale/offer-publication-commands/{commandId} pobierz informacje o statusie zadania publikacji ofert w serwisie. W odpowiedzi otrzymasz zestawienie, ile ofert 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 request:

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

Informacje o publikacji

Za pomocą GET /sale/offer-publication-commands/{commandId}/tasks pobierz informacje o statusie publikacji ofert w serwisie. W odpowiedzi otrzymasz:

identyfikatory ofert, które chciałeś opublikować w serwisie,
status modyfikacji oferty - czy zakończyła się sukcesem,
datę zlecenia modyfikacji oferty,
datę wykonania danego zadania - wystawienia lub zakończenia oferty.

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 response:

  [
    {
            "offer": {
                "id": "7168735300"
            },
            "message": "",                          -- opis dlaczego nie udało się  opublikować
                                                    oferty w serwisie
            "status": "SUCCESS",                    -- status publikacji oferty w serwisie,
                                                    dostępne są trzy wartości: SUCCESS (publikacja
                                                    zakończona pomyśle, oferta powinna
                                                    być aktywna w ciągu 60 min.); FAIL
                                                    (wystąpiły błędy przy publikacji i oferta nie
                                                    jest aktywna w serwisie); NEW (trwa publikacja
                                                    oferty 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 wystawić podobną ofertę

Jeśli już wystawiłeś ofertę i chcesz na jej podstawie wystawić podobną, to wystarczy, że pobierzesz ją przez GET /sale/offers/{offerId}. Za pomocą GET /sale/offers/{offerId} pobierzesz wszystkie pola wskazanej oferty. Musisz być uwierzytelniony i zautoryzowany jako sprzedawca, który wystawił tę ofertę. Całą pobraną strukturę z wyłączeniem:

numeru identyfikacyjnego oferty,
informacji, kiedy odbyła się ostatnia walidacja oferty,
daty utworzenia oferty,
daty ostatniej aktualizacji oferty,
sekcję "publication".

prześlij za pomocą POST /sale/offers. Dzięki temu stworzysz nowy draft oferty na podstawie danych z oferty, 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}.

Sandbox

Aby w pełni korzystać z opisanych zasobów na środowisku testowym (Allegro Sandbox):

Zarejestruj konto firmowe, uzupełnij dane adresowe i aktywuj konto,
Zweryfikuj konto firmowe.

Jeżeli masz problem z aktywacją konta, zgłoś to w naszym wątku do aktywacji kont na GitHub.

Podstawowe informacje o środowisku testowym znajdziesz w naszym poradniku.

Pytania i odpowiedzi

1. Jak wystawić licytację z opcją Kup Teraz?

Jeśli chcesz wystawić taką ofertę wystarczy, że prześlesz w polu "format" wartość AUCTION i uzupełnisz pola:

startingPrice - cena początkowa
minimalPrice - cena minimalna. To pole nie jest wymagane.

2. Dlaczego wprowadziliśmy funkcję draftów?

Dzięki draftom możesz przygotować zalążek oferty, na którym możesz pracować w innym terminie - np. gdy chcesz wypracować ostateczny kształt opisu. Możesz również od razu przygotować kompletny draft i opublikować ofertę w serwisie.

3. Dlaczego wprowadziliśmy osobny zasób dla zdjęć?

W ramach oferty możesz udostępnić zdjęcia w bardzo dużej rozdzielczości. Wiąże się to z olbrzymią wagą takiego pliku. To, że wprowadziliśmy osobny zasób dedykowany zdjęciom pozwoli zmniejszyć rozmiar requestu. Wpłynie to na krótszy czas wystawienia oferty.

4. Dlaczego wprowadziliśmy osobny zasób dla cenników dostaw?

Dzięki temu, że ceny wysyłki są niezależne od oferty i dzięki osobnemu zasobowi do cenników dostawy, będziesz mógł szybciej przeprowadzić hurtową edycję cen dostawy. Wystarczy, że wprowadzisz zmianę w cenniku dostawy, a koszt przesyłki zmieni się we wszystkich ofertach, do których przypiąłeś dany cennik. Takie rozwiązanie pozwoli dynamicznie reagować na zmiany cen u przewoźników.

5. Jak zaplanować wystawienie oferty w przyszłości?

Termin do wystawienia ofert w przyszłości możesz ustawić za pomocą komendy PUT na zasobie /sale/offer-publication-commands/{commandId}. Wystarczy, że w polu scheduledFor podasz planowany czas wystawienia oferty w przyszłości.

6. Otrzymałem komunikat - “You cannot create new drafts - your account has exceeded the maximum number {maxInactiveOffers} of drafts.” Co powinienem zrobić?

Otrzymałeś taki komunikat, ponieważ przekroczyłeś dostępny limit szkiców ofert (draftów), dotyczy to ofert ze statusem “INACTIVE” - obecny limit to 20 000. Aby rozwiązać ten problem:

sprawdź aktualną liczbę draftów za pomocą GET /sale/offers?publication.status=INACTIVE,
usuń niepotrzebne za pomocą DELETE /sale/offers/{offerId}}.

7. Próbuję utworzyć draft oferty, jednak w odpowiedzi otrzymuję status 401 Unauthorized wraz z komunikatem "Empty user_name claim". Co on oznacza?

Posługujesz się tokenem uzyskanym w wyniku autoryzacji client_credentials, który nie posiada kontekstu użytkownika. Aby utworzyć draft oferty, musisz posiadać token wygenerowany przez code lub device flow.

8. Gdy tworzę ofertę za pomocą POST /sale/offers otrzymuję błąd 422. Co on oznacza?

Upewnij się, że struktura twojego żądania jest prawidłowa i poprawnie przekazujesz wszystkie wartości. Przykładowy request znajdziesz w naszym poradniku.

9. Gdy próbuję aktywować oferty za pomocą PUT /sale/offer-publication-commands/{commandId}, w odpowiedzi otrzymuję same zera. Czy to prawidłowe zachowanie?

Tak, dzieje się tak ponieważ ten zasób działa asynchronicznie. Aby sprawdzić szczegółowy status realizacji zadania, użyj GET /sale/offer-publication-commands/{commandId}/tasks.

10. W swoim żądaniu przesyłam uzupełnione pole location, jednak w odpowiedzi otrzymuję w nim wartość null. Co wykonuję nieprawidłowo?

Upewnij się, że oprócz prawidłowo uzupełnionego pola location, przesyłasz także wartości dla delivery.shippingRates i sellingMode.

10. W odpowiedzi na żądanie otrzymuję błąd 422 wraz z komunikatem “Description images are not valid.”. Co on oznacza?

Upewnij się, że linki do obrazków, które przesyłasz w sekcji description, prawidłowo przekazujesz także w sekcji images.

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 oferty
GET /sale/offers/{offerId} - pobierz ofertę
PUT /sale/offers/{offerId} - edytuj draft / ofertę
GET /sale/delivery-methods - pobierz metody dostawy
POST /sale/shipping-rates - utwórz cennik dostawy
POST /after-sales-service-conditions/return-policies - dodaj warunki zwrotów
POST /after-sales-service-conditions/implied-warranties - dodaj warunki reklamacji
GET /sale/categories - pobierz listę kategorii
GET /sale/categories/{categoryId}/parameters - pobierz listę parametrów dla kategorii
POST /sale/images - dodaj zdjęcia
PUT /sale/offer-publication-commands/{commandId} - zmień grupowo status publikacji oferty

Lista zasobów wspierających opisanych w poradniku:

GET /sale/delivery-settings - pobierz ustawienia dostawy
PUT /sale/delivery-settings - edytuj ustawienia dostawy
GET /sale/shipping-rates - pobierz cenniki dostawy
GET /sale/shipping-rates/{shippingRatesId} - pobierz szczegółowe dane cennika dostawy
GET /after-sales-service-conditions/return-policies - pobierz warunki zwrotów
GET /after-sales-service-conditions/return-policies/{returnPolicyId} - pobierz szczegółowe dane warunków zwrotów
PUT /after-sales-service-conditions/return-policies/{returnPolicyId} - edytuj warunki zwrotów
GET /after-sales-service-conditions/implied-warranties - pobierz warunki reklamacji
GET /after-sales-service-conditions/implied-warranties/{impliedWarrantyId} - pobierz szczegółowe dane warunków reklamacji
PUT /after-sales-service-conditions/implied-warranties/{impliedWarrantyId} - edytuj warunki reklamacji
POST /after-sales-service-conditions/attachments - dodaj obiekt załącznika dla informacji o gwarancjach
PUT /after-sales-service-conditions/attachments/{attachmentId} - prześlij załącznik dla informacji o gwarancjach
POST /after-sales-service-conditions/warranties - dodaj informacje o gwarancjach
GET /after-sales-service-conditions/warranties - pobierz informacje o gwarancjach
GET /after-sales-service-conditions/warranties/{warrantyId} - pobierz szczegółowe dane informacji o gwarancjach
PUT /after-sales-service-conditions/warranties/{warrantyId} - edytuj informacje o gwarancjach
GET /sale/offer-additional-services/groups - pobierz identyfikatory usług dodatkowych
GET /sale/size-tables - pobierz tabele rozmiarów
GET /sale/size-tables/{tableId} - pobierz szczegółowe dane tabeli
GET /sale/offer-contacts - pobierz dane kontaktowe
GET /sale/offer-tags - pobierz tagi
POST /sale/offers/{offerId}/tags - dodaj tagi do oferty
POST /sale/offer-attachments - dodaj obiekt załącznika do oferty
PUT /sale/offer-attachments/{attachmentId} - prześlij załącznik do oferty
GET /sale/offer-publication-commands/{commandId} - pobierz raport o statusie zadania publikacji ofert
GET /sale/offer-publication-commands/{commandId}/tasks - pobierz szczegółowy raport o statusie zadania publikacji ofert

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

Czy ten artykuł był dla Ciebie przydatny?

Startujemy z nową odsłoną Allegro Developer Portal!

Jak wystawić ofertę w Allegro REST API

Draft oferty

Tytuł oferty

Kategorie i parametry

Identyfikator kategorii

Parametry

Własne parametry

Własna wartość parametru

Produktyzacja

Zdjęcia

Opis oferty

Jak wygląda struktura opisu

Sekcje (sections)

Elementy opisu (item)

Typy treści w opisie

Przykładowa struktura opisu

Informacje o dostawie

Cennik dostaw

Ustawienia dostawy

Warunki oferty

Opcje faktury i ustawienia VAT

Opcje faktury

Ustawienia VAT

Promowanie

Opcje dodatkowe

Tagi ofertowe

Załączniki

Stwórz obiekt załącznika

Prześlij plik

Podłącz załącznik do oferty

Tabele rozmiarów

Ważne informacje dla sprzedającego

Uzupełnij dane w ofercie

Publikacja oferty

Zestawienie zadań

Informacje o publikacji

Jak wystawić podobną ofertę

Sandbox

Pytania i odpowiedzi

Lista zasobów

Lista zasobów podstawowych opisanych w poradniku:

Lista zasobów wspierających opisanych w poradniku: