Allegro REST API

gdzie?

Polska | polski | PLN
  • Informacje podstawowe
  • Główne procesy
  • Uwierzytelnianie i autoryzacja
  • Wzorzec Command
  • Glosariusz
  • Lista metod
  • Pierwsze kroki
  • Wystawianie oferty z produktem
  • Serwisy zagraniczne Allegro
  • Zarządzanie ofertami
  • Oferty wielowariantowe
  • Pasuje do
  • Zarządzanie zgłoszeniami ofert do kampanii
  • Rabaty i promocje
  • Zamówienia
  • Wysyłam z Allegro
  • One Fulfillment by Allegro
  • Dyskusje
  • Konto i dane użytkownika
  • Centrum wiadomości
  • Sprawdzanie opłat
  • Wystawianie ogłoszeń
  • Publiczne oferty
FAQ
  • Aktualności
  • Changelog
Dokumentacja
Regulamin
Kontakt
  • Moje aplikacje
  • Moje aplikacje (sandbox)
  • Newsletter
  1. Allegro REST API
  2. Serwisy zagraniczne Allegro
Harmonogram zmian
Jak sprawdzić serwis bazowy użytkownika oraz listę dostępnych serwisów
Jakie warunki musi spełnić oferta, abyśmy mogli ją wyświetlić w serwisach dodatkowych
Jak wyświetlić ofertę w serwisie dodatkowym
Jak grupowo zarządzać ofertami w ramach serwisów dodatkowych
Jak zarządzać zamówieniami
Jak sprawdzić opłaty
Dotychczasowe newsy

Serwisy zagraniczne Allegro

Już w kwietniu 2023 nasi sprzedający będą mogli testować nowe narzędzia na stronie allegro.pl do zarządzania widocznością oferty w czeskim serwisie. Samo uruchomienie czeskiego serwisu zagranicznego planujemy na początek maja 2023. Gotowość aplikacji jest ważna, bo wraz ze startem nowej domeny, oferty, które w tym czasie będą się kwalifikowały na rynek czeski, będą tam wyświetlane - dlatego sugerujemy, aby aplikacja była odpowiednio przygotowana, by móc nimi zarządzać.

W ramach międzynarodowej ekspansji, sprzedający będą mogli wyświetlić swoje oferty także w zagranicznych domenach serwisu Allegro. Dzięki zmianom, które planujemy wprowadzić, sprzedawcy dotrą do szerszego grona potencjalnych klientów niż dotychczas.

W poniższym artykule znajdziesz zbiór informacji o tym, jakie zmiany wprowadzliśmy i planujemy wprowadzić w najbliższej przyszłości w kontekście wystawiania i zarządzania ofertą w serwisach zagranicznych.

Artykuł będziemy na bieżąco aktualizować, konkretne daty mogą ulec drobnym korektom.

Harmonogram zmian

i e timeline

Jak sprawdzić serwis bazowy użytkownika oraz listę dostępnych serwisów

Serwis bazowy to serwis przypisany do kraju, w którym sprzedający się zarejestrował. W tym momencie dla sprzedającego jest to serwis allegro.pl (allegro-pl). Po uruchomieniu serwisu w Czechach (allegro-cz), będzie on drugim dopuszczalnym serwisem bazowym dla sprzedających. Identyfikator serwisu bazowego użytkownika zwracamy w polu "baseMarketplace.id" w odpowiedzi dla GET /me.

Reguły związane z serwisem bazowym:

  • serwis bazowy oferty będziemy nadawać automatycznie na podstawie danych konta sprzedającego,
  • aktywna oferta zawsze będzie widoczna w jej serwisie bazowym,
  • walidacja oferty podczas jej aktywacji domyślnie dotyczy jej serwisu bazowego.

Serwis dodatkowy to pozostałe serwisy Allegro, na których będzie można sprzedawać produkty. W tym momencie, dla sprzedających, dla których serwisem bazowym jest allegro-pl, będzie to serwis allegro-cz. Analogicznie, serwisem dodatkowym dla serwisu bazowego allegro-cz, będzie serwis allegro-pl oraz inne serwisy Allegro, które uruchomimy w przyszłości.

Za pomocą GET /marketplaces (zasób wdrożony na Sandboxie, na początku kwietnia 2023 - na produkcji) sprawdzisz ID serwisów, w których użytkownik może wyświetlić swoje oferty. Znajdziesz tu również inne dane, które dotyczą konkretnego serwisu, np. języki, w jakich oferta może być utworzona, a także wyświetlona kupującemu, dostępne waluty oraz kraje dostawy.

Przykładowy response:

  {
 "marketplaces": [                    - lista dostępnych serwisów
  {
   "id": "allegro-pl",                - ID dostępnego serwisu
   "languages": {
      “offerCreation” : [             - języki, w jakich oferta może być utworzona
      {
           "code": "pl-PL"                           
         },
         {
            "code": "en-US"                
         }
     ],
    "offerDisplay": [                 - języki, w jakich oferta może być wyświetlona kupującemu
 {
    "code”: “uk-UA"
 },
 {
    "code": "en-US"
 },
 {
    "code": "cs-CZ"
 }
     ]
   }

   "currencies": {                      - dostępne waluty
     "base": {
       "code": "PLN"                    - waluta bazowa dla danego serwisu
     },
     "additional": [                    - pozostałe waluty dostępne tylko dla kupującego
       {
         "code": "EUR"
       },
       {
         "code": "USD"
       }
     ]
   },
   "shippingCountries": [               - dostępne kraje dostawy dla danego serwisu 
     {
       "code": "PL"
     },
     {
       "code": "CZ"
     },
     {
       "code": "DE"
     }
   ]
 },
 {
   "id": "allegro-cz",
   "languages": {
      “offerCreation” : [                  
      {
           "code": "cs-CZ"                           
         },
         {
            "code": "en-US"                
         }
     ],
    “offerDisplay”: [                  
 {
    "code": "pl-PL"
 },
 {
    “code”: "en-US"
 },
 {
    “code”: "cs-CZ"
 }
     ]
   }
   "currencies": {                   
     "base": {      
       "code": "CZK"               
     },
     "additional": [
       {
         "code": "EUR"
       },
       {
         "code": "USD"
       },
       {
         "code": "PLN"
       }
     ]
   },
   "shippingCountries": [   
     {
       "code": "CZ"
     },
     {
       "code": "PL"
     },
     {
       "code": "SK"
     }
   ]
  }
 ]
}

Jakie warunki musi spełnić oferta, abyśmy mogli ją wyświetlić w serwisach dodatkowych

Serwis dodatkowy allegro-cz sprzedający wybierze tylko dla ofert, które:

  • są wystawione przez zweryfikowane konto firmowe,
  • są oferowane tylko jako Kup Teraz,
  • nie są ofertą charytatywną,
  • nie są ofertą B2B.

Oferty muszą przejść dodatkowy proces kwalifikacji, zanim wyświetlimy je w serwisie dodatkowym. Uruchomimy go:

  • podczas aktywacji oferty,
  • podczas edycji oferty,
  • dla aktywnej już oferty, dla której dodasz chęć widoczności oferty w serwisie dodatkowym.

Sprawdzimy, czy oferta (warunki mogą ulec zmianie):

  • ma co najmniej jedną metodę dostawy prawidłową dla serwisu allegro-cz,
  • ma cenę w walucie CZK,
  • ma tłumaczenie na język czeski (ofertę przetłumaczymy automatycznie, jeśli będzie spełniać pozostałe warunki do wyświetlenia w serwisie dodatkowym),
  • znajduje się w kategorii asortymentowej, dla której istnieje odpowiednia kategoria w serwisie allegro-cz.

Jak wyświetlić ofertę w serwisie dodatkowym

Ważne! Ze względu na uwarunkowania techniczne zmiany opisane w poniższej sekcji wdrożymy na Sandboxie w ramach nagłówków:

  • “Accept: application/vnd.allegro.beta.v1+json”,
  • “Content-Type: application/vnd.allegro.beta.v1+json”.

Aby oferta mogła przejść proces kwalifikacji i być tym samym wyświetlona w serwisie dodatkowym, musisz zadeklarować chęć widoczności oferty w danym serwisie. W związku z tym dodaliśmy na Sandboxie (a na początku kwietnia 2023 dodamy na produkcji) w zasobach:

  • /sale/product-offers,
  • /sale/product-offers/{offerId},
  • /sale/offers.
  • /sale/offers/{offerId}

nowe pola:

  • publication.marketplaces.base - serwis bazowy oferty. Wartość w polu nadajemy automatycznie w momencie stworzenia oferty i jest tylko do odczytu, nigdy się nie zmieni;
  • publication.marketplaces.additional - serwis dodatkowy oferty, gdzie sprzedający będzie mógł określić, czy jego oferta ma być widoczna w serwisie dodatkowym. Pole to nie jest obowiązkowe. Brak tego pola zinterpretujemy jako pustą tablicę (oferta będzie widoczna tylko w jej serwisie bazowym).

Na tym etapie sprzedawcy będą mogli zadeklarować chęć widoczności oferty w innym serwisie, zwrócimy również tę informację w polu publication.marketplaces.additional, jednak oferta będzie widoczna wyłącznie na allegro.pl.allegrosandbox.pl - nie uruchomimy procesu kwalifikacji, dlatego nie będzie znany jego status.

Przykładowa struktura:

{ 
…
 "publication": {
     "marketplaces": {
        "base": {
            "id": "allegro-pl"           - ID serwisu bazowego, wartość nadamy 
                                         automatycznie na podstawie danych z konta 
                                         sprzedającego
          },
       "additional": [
              {
              "id": "allegro-cz"          - ID serwisu dodatkowego, w którym oferta ma być 
                                          widoczna - pobierzesz go za pomocą GET 
                                          /marketplaces
              }
       ]
     }
 },
 …
}

3.03.2023 udostępniliśmy na środowisku testowym Sandbox, a na początku kwietnia 2023 na produkcji, także nową sekcję additionalMarketplaces.{marketplaceId}, w której:

  • zwrócimy informację o statusie widoczności oferty w danym serwisie dodatkowym w polu publication.state. Pole będzie tylko do odczytu i przyjmie jedną z poniższych wartości:

    • "APPROVED" - oferta jest widoczna w danym serwisie dodatkowym, jeżeli jest aktywna,
    • "REFUSED" - oferta lub sprzedający nie spełniają warunków wymaganych do wyświetlenia oferty w danym serwisie dodatkowym,
    • "IN_PROGRESS" - trwa proces kwalifikacji oferty do widoczności w danym serwisie dodatkowym,
    • "NOT_REQUESTED" - sprzedający nie zaznaczył intencji widoczności w danym serwisie dodatkowym (w polu publication.marketplaces.additional),
    • “PENDING” - sprzedający zaznaczył intencję widoczności w danym serwisie dodatkowym, jednak proces kwalifikacji oferty nie rozpoczął się np. ze względu na status oferty (tylko oferty aktywne podlegają procesowi kwalifikacji widoczności).

Informację o zmianie statusu widoczności w serwisie dodatkowym otrzymasz w ramach dziennika ofertowego, w odpowiedzi GET /sale/offer-events - będzie świadczyć o tym zdarzenie "OFFER_VISIBILITY_CHANGED". Dodatkowo, dla statusu “REFUSED” zwrócimy konkretny powód odrzucenia.

  • sprzedający zadeklaruje cenę oferty dla wybranego serwisu dodatkowego w polu sellingMode.price. Cenę w tym polu sprzedający musi podać w walucie prawidłowej dla danego serwisu, co jest określone w konfiguracji dostępnej w zasobie GET /marketplaces.

Na tym etapie sprzedawcy będą mogli podać cenę oferty w serwisie dodatkowym i sprawdzić, czy oferta się zakwalifikowała, aby mogła być wyświetlana w dodatkowym serwisie. Oferta będzie jednak nadal widoczna jedynie w serwisie allegro.pl.allegrosandbox.pl.

Przykładowa struktura:

{
   …
 "additionalMarketplaces": {
     "allegro-cz": {        - serwis dodatkowy allegro-cz (czeska domena serwisu)
         "publication": {
             "state": "APPROVED" - status widoczności w serwisie dodatkowym, w tym 
                                   przypadku wartośc wskazuje na to, że oferta jest wyświetlana 
                                   w serwisie dodatkowym
         },
         "sellingMode": {        
             "price": {            - cena oferty w serwisie dodatkowym
                 "amount": "629.65", 
                 "currency": "CZK" 
             }
         }
     },
             "allegro-xy": {        - przykładowy serwis dodatkowy, który na ten moment nie 
                                   istnieje,  a jest podany dla zobrazowania sytuacji
         "publication": {
             "state": "NOT_REQUESTED"
         }
     }
 }
…
}

Jak grupowo zarządzać ofertami w ramach serwisów dodatkowych

Na początku kwietnia 2023 planujemy wprowadzić zmiany w:

  • PUT /sale/offer-modification-commands/{commandId} - sprzedający będą mogli grupowo zmienić chęć widoczności oferty w zagranicznych domenach serwisu Allegro;
  • PUT /sale/offer-price-change-commands/{commandId} - sprzedający będa mogli grupowo zmienić cenę w serwisach dodatkowych.

Jak zarządzać zamówieniami

Jak rozpoznać, w jakim serwisie zostało złożone zamówienie

W zamówieniach dodaliśmy obiekt "marketplace", gdzie w polu "id" zwracamy identyfikator domeny serwisu, w którym kupujący dokonał zakupu.

Nowy obiekt zwracamy w:

  • GET /order/checkout-forms,
  • GET /order/checkout-forms/{id},
  • GET /order/events.

Aktualnie w polu "marketplace.id" zwracamy jednie wartość "allegro-pl", natomiast po uruchomieniu nowych domen będą to także inne wartości, np. “allegro-cz”.

W GET /order/checkout-forms dodaliśmy także nowy parametr wyszukiwania "marketplace.id", dzięki któremu możesz filtrować zamówienia dla wskazanego serwisu.

Informację o preferencjach językowych kupującego zwracamy już teraz w polu “buyer.preferences.language”.

Jak rozpoznać, z jakiego serwisu pochodzi zwrot od klienta

W ramach zasobów do obsługi zwrotów klienckich dodaliśmy pole “marketplaceId” w odpowiedzi:

  • GET /order/customer-returns,
  • GET /order/customer-returns/{customerReturnId},
  • POST /order/customer-returns/{customerReturnId}/rejection,

w którym zwrócimy informację, jakiego serwisu dotyczy dotyczy dany zwrot.

Jak sprawdzić opłaty

W zasobie /payments/payment-operations, dzięki któremu pobierzesz historię operacji na saldzie zalogowanego sprzedającego, dodaliśmy:

  • pole marketplaceId - identyfikator serwisu, na którym została przeprowadzona operacja płatnościowa. Aktualnie zwrócimy w nim:
    • null, jeśli operacja odbywa się w ramach konta Allegro, a nie konkretnego serwisu np. dla wypłaty środków z konta. Null zwrócimy także dla części operacji sprzed 10 lutego 2023;
    • “allegro-pl” np. dla wpłaty środków od kupującego. Po uruchomieniu nowych domen będą to także inne wartości, np. “allegro-cz”;
  • nowe parametry, dzięki którym wyfiltrujesz wyniki:
    • marketplaceId - identyfikator serwisu, na którym została przeprowadzona operacja płatnościowa. Aktualnie dostępną wartością jest “allegro-pl” - jeśli ją ustawisz, zwrócimy tylko te operacje, dla których w polu “marketplaceId” widnieje “allegro-pl”, nie uwzględnimy zatem wypłaty środków. Wraz z uruchomieniem nowych serwisów, w których sprzedawca będzie mógł wyświetlić swoją ofertę, a kupujący zakupić przedmiot, pojawią się dodatkowe wartości, np. “allegro-cz”;
    • currency - waluta, w której została przeprowadzona operacja. Aktualnie dostępną wartością jest “PLN”. W momencie kiedy uruchomimy nowe serwisy, w których płatność może nastąpić w innej walucie, dodamy nowe wartości do wyboru w tym parametrze;

Dotychczasowe newsy

3.03.2023 - Serwisy zagraniczne Allegro - wdrożenie zmian w ofercie na Sandbox (etap II)

1.03.2023 - Serwisy zagraniczne Allegro - dodaliśmy obiekt "baseMarketplace" w /me

28.02.2023 - Serwisy zagraniczne Allegro - dodaliśmy parametr “language” w zasobie, dzięki któremu pobierzesz sugerowaną sekcję “Pasuje do”

27.02.2023 - Gotowość integracji na uruchomienie zagranicznych serwisów

15.02.2023 - Serwisy zagraniczne Allegro - dodaliśmy nowy obiekt "marketplace" w zamówieniach

14.02.2023 - Serwisy zagraniczne Allegro - dodaliśmy parametr i pole “marketplaceId” w zasobach do obsługi zwrotów klienckich

6.02.2023 - Serwisy zagraniczne Allegro - wdrożenie zmian w ofercie na Sandbox

26.01.2023 - Serwisy zagraniczne Allegro - dodaliśmy nowe parametry i pole w GET /payments/payment-operations

29.12.2022 - GET /sale/offer-events - nowy typ zdarzenia,

22.12.2022 - Umożliwiamy wyszukiwanie i pobieranie danych produktów w różnych językach,

8.12.2022 - Zmiany w wystawianiu ofert - dodamy możliwość wyświetlania ofert w zagranicznych domenach serwisu Allegro


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

Czy ten artykuł był dla Ciebie przydatny?