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

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:

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:

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;