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
Wdrożone zmiany
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 zarządzać opcjami promowania w serwisach dodatkowych
Jak sprawdzić opłaty
Jak sprawdzić płatności
Dotychczasowe newsy

Serwisy zagraniczne Allegro

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

W poniższym artykule znajdziesz zbiór informacji o tym, jakie zmiany wprowadzliśmy w kontekście wystawiania i zarządzania ofertą w serwisach zagranicznych.

Wdrożone zmiany

harmonogram 9 05 2023 pl

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 nadajemy 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 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

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 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 może 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).

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
              }
       ]
     }
 },
 …
}

Udostępniliśmy także nową sekcję additionalMarketplaces.{marketplaceId}, w której:

  • zwracamy informację o statusie widoczności oferty w danym serwisie dodatkowym w polu publication.state. Pole jest tylko do odczytu i przyjmuje 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.

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ść wskazuje na to, że oferta jest wyświetlana 
                                   w serwisie dodatkowym
         },
         "sellingMode": {        
             "price": {            - cena oferty w serwisie dodatkowym
                 "amount": "629", 
                 "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

  • PUT /sale/offer-modification-commands/{commandId} - sprzedający mogą grupowo zmienić chęć widoczności oferty w zagranicznych domenach serwisu Allegro;
    Przykładowy request:
    curl  -X  PUT  \
    'https://api.allegro.pl/sale/offer-modification-commands/{commandId}' \
    -H  'Accept: application/vnd.allegro.public.v1+json' \
    -H 'Content-Type: application/vnd.allegro.public.v1+json' \
    -H 'Authorization: Bearer {token}' \
    -d '{
      "modification": {
          "publication": {
              "marketplaces": {
                  "additional": {
                      "add": [   - dodaj możliwość widoczności oferty w serwisach dodatkowych
                          {
                              "id": "allegro-cz"  - ID serwisu dodatkowego, 
                                                   który możesz pobrać za pomocą GET /marketplaces
                          }
                      ],
                      "remove": []   - usuń możliwość widoczności oferty w serwisach dodatkowych
                  }
              }
          }
      },
      "offerCriteria": [
          {
              "type": "CONTAINS_OFFERS",
              "offers": [
                  {
                      "id": "1529278070"
                  }
              ]
          }
      ]
    }'
  • PUT /sale/offer-price-change-commands/{commandId} - sprzedający mogą grupowo zmienić cenę w serwisach dodatkowych.
    Przykładowy request:
    curl  -X  PUT  \
    'https://api.allegro.pl/sale/offer-price-change-commands/{commandId}' \
    -H  'Accept: application/vnd.allegro.public.v1+json' \
    -H 'Content-Type: application/vnd.allegro.public.v1+json' \
    -H 'Authorization: Bearer {token}' \
    -d '{
    "modification": {
      "type": "FIXED_PRICE",
      "marketplaceId": "allegro-cz",  - ID serwisu allegro na którym chcesz zmienić cenę
      "price": {
        "amount": 70,
        "currency": "CZK"
      }
    },
    "offerCriteria": [
      {
        "type": "CONTAINS_OFFERS",
        "offers": [
          {
            "id": "13529278070"
          }
        ]
      }
    ]
    }'

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 zarządzać opcjami promowania w serwisach dodatkowych

Na ten moment opcje promowania dostępne są tylko dla serwisu “allegro-pl”. Próba promowania ofert na innym rynku zakończy się błędem o statusie 422, informującym o tym, że dana opcja nie jest dostępna na wybranym rynku.

Po uruchomieniu serwisu w Czechach ustawisz opcje promowania w serwisie “allegro-pl” dla ofert utworzonych w serwisie bazowym “allegro-cz”.

Jak zarządzać promowaniem pojedynczej oferty

Za pomocą GET /sale/offers/{offerId}/promo-options edytujesz opcje promowania pojedynczej oferty. W sekcji:

  • “modifications” - ustawisz promowanie dla oferty w serwisie bazowym - obecnie tylko w “allegro-pl”,
  • “additionalMarketplaces” - przekażesz informacje o opcjach promowania dla serwisu dodatkowego, gdzie obecnie jedyna możliwa wartość to “allegro-pl”; to pole przeznaczone będzie dla użytkowników, których serwis bazowy jest inny niż “allegro-pl” np. “allegro-cz”.

Przykładowy request

 curl -X POST \
    'https://api.allegro.pl/sale/offers/9531382307/promo-options-modification \
    -H 'Authorization: Bearer {token}' \
    -H 'Accept: application/vnd.allegro.public.v1+json' \
    -H 'Content-Type:  application/vnd.allegro.public.v1+json' 

{
 "modifications": [],                     - tu zmienisz opcje promowania 
                                          w serwisie bazowym
 "additionalMarketplaces": [              - tu zmienisz opcje promowania 
                                          w serwisie dodatkowym
   {
     "marketplaceId": "allegro-pl",
     "modifications": [
       {
         "modificationType": "CHANGE",
         "packageType": "BASE",
         "packageId": "emphasized10d"
       }
     ]
   }
 ]
}

Gdy skorzystasz z GET /sale/offers/{offerId}/promo-options, w odpowiedzi uzyskasz informacje o opcjach promowania oferty dla serwisu:

  • bazowego - w polu “marketplaceId”,
  • dodatkowego - w sekcji “additionalMarketplaces”, w polu “marketplaceId”.

Przykładowy response

{
 "offerId": "9531382307",
 "marketplaceId": "allegro-cz",   - serwis bazowy oferty
 "basePackage":  null,
 "extraPackages": [],
 "pendingChanges": null,
 "additionalMarketplaces": [      - serwis dodatkowy oferty
   {
     "marketplaceId": "allegro-pl",
     "basePackage": {
       "id": "emphasized10d",
       "validFrom": "2020-01-01T00:00:00Z",
       "validTo": "2020-01-01T00:00:00Z",
       "nextCycleDate": "2020-01-01T00:00:00Z"
     },
     "extraPackages": [],
     "pendingChanges": null
   }
 ]
}

Jak grupowo zarządzać promowaniem ofert

Za pomocą PUT /sale/offers/promo-options-commands/{commandId} edytujesz opcje promowania wielu ofert. W sekcji:

  • “modification”- dla wybranych ofert ustawisz opcje promowania w serwisie bazowym - obecnie tylko w “allegro-pl”,
  • “additionalMarketplaces” - dla wybranych ofert przekażesz informacje o opcjach promowania na Allegro.pl dla serwisu dodatkowego, gdzie jedyna możliwa wartość to “allegro-pl”; to pole przeznaczone będzie dla użytkowników, których serwis bazowy jest inny niż “allegro-pl” np. “allegro-cz”.

Przykładowy request

curl -X PUT \
    'https://api.allegro.pl/sale/offers/promo-options-commands/{commandId} \
    -H 'Authorization: Bearer {token}' \
    -H 'Accept: application/vnd.allegro.public.v1+json' \
    -H 'Content-Type:  application/vnd.allegro.public.v1+json' 

{
 "offerCriteria": [
   {
     "offers": [
       {
         "id": "9531382307"
       },
       {
         "id": "9531382308"
       }
     ],
     "type": "CONTAINS_OFFERS"
   }
 ],
 "modification": {},         - ta sekcja dotyczy serwisu bazowego
 "additionalMarketplaces": [ - ta sekcja dotyczy serwisu dodatkowego
   {
     "marketplaceId": "allegro-pl",
     "modification": {
       "basePackage": {
         "id": "emphasized10d"
       },
       "extraPackages": [],
       "modificationTime": "NOW"
     }
   }
 ]
}

Jak sprawdzić aktualne opcje promowania przypisanych do ofert w serwisach dodatkowych

Za pomocą GET /sale/offers/promo-options pobierzesz aktualne opcje promowania na Allegro.pl przypisane do ofert sprzedającego.

Przykładowy response

{
 "promoOptions": [
   {
     "offerId": "9531382307",
     "marketplaceId": "allegro-cz",
     "basePackage": null,
     "extraPackages": [],
     "pendingChanges": null,
     "additionalMarketplaces": [
       {
         "marketplaceId": "allegro-pl",
         "basePackage": {
           "id": "promoPackage",
           "validFrom": "2020-01-01T00:00:00Z",
           "validTo": "2020-01-01T00:00:00Z",
           "nextCycleDate": "2020-01-01T00:00:00Z"
         },
         "extraPackages": [],
         "pendingChanges": null
       }
     ]
   }
 ],
 "count": 1,
 "totalCount": 1
}

Jak sprawdzić opłaty

W zasobie /billing/billing-entries dodaliśmy nowy parametr "marketplaceId”, za pomocą którego sprawdzisz historię operacji billingowych dla wybranego przez Ciebie serwisu.

Jeżeli nie użyjesz parametru "marketplaceId", to domyślnie zwrócimy serwis bazowy, np. allegro-pl. Natomiast po uruchomieniu serwisu w Czechach pobierzesz również wszystkie operacje billingowe dla serwisu bazowego allegro-cz.

Identyfikator serwisu bazowego użytkownika sprawdzisz w polu "baseMarketplace.id", korzystając z GET /me.

Jak sprawdzić płatności

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

09.05.2023 - Serwisy zagraniczne Allegro - dodaliśmy parametr “marketplaceId” w zasobach do kwalifikacji ofert i sprzedawcy w programie Allegro Smart!

08.05.2023 - Serwisy zagraniczne Allegro - zmiany na zasobach do zarządzania opcjami promowania

28.04.2023 - Serwisy zagraniczne - dodaliśmy nowe pole w POST /pricing/offer-fee-preview

12.04.2023 - Serwisy zagraniczne Allegro - wdrożyliśmy zmiany w ofercie na produkcji

28.03.2023 - Serwisy zagraniczne allegro - zmiany w metodach i ustawieniach dostaw

28.03.2023 - Serwisy zagraniczne Allegro - dodaliśmy nowy parametr “marketplaceId” w historii operacji billingowych

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?