Sklep wchodzi na Allegro przez API. Blokada leżała w ustawieniach konta i w umowach z dystrybutorami, nie w kodzie

16 września, późne popołudnie. Oferta numer jeden naszego sklepu ze sprzętem do hokeja na trawie wreszcie dostaje status „aktywna”. Piłka treningowa za 45 zł, dostawa kurierem 18 zł, jeden egzemplarz do kupienia na Allegro. Zajęło to dwa dni, kilkadziesiąt zapytań do API i trzy rozmowy, których nikt nie planował: o cennikach dostawy, o tym, kto jest producentem w rozumieniu unijnego prawa, i o tym, co właściwie podpisaliśmy z markami, które sprzedajemy.

Od początku zakładałem, że problem będzie techniczny. Integracja z Allegro to integracja jak każda inna, a te robię od lat. Tymczasem kod zadziałał od razu. Zatrzymało nas wszystko wokół niego: konto założone pod inny model sprzedaży, brak jednego obowiązkowego wpisu, który od sierpnia 2025 Allegro traktuje zero-jedynkowo, i klauzule w umowach dystrybucyjnych, przez które część naszego asortymentu nigdy nie może trafić na marketplace. Jeśli prowadzisz mały sklep i myślisz o Allegro „podłączę i wystawię”, ten tekst oszczędzi Ci tych dwóch dni. A może kilku tygodni, bo my mieliśmy szczęście, że przeczytaliśmy umowy przed pierwszą ofertą, a nie po pierwszym piśmie od producenta.

Spis treści

Dlaczego poprawny kod nie wystawił ani jednej oferty?

Scenariusz wyglądał tak. Sklep ma własny panel, w którym trzymamy produkty, stany i ceny, i który jest dla nas jednym źródłem prawdy o produkcie. Allegro ma API, czyli drzwi służbowe, przez które program może wystawić ofertę bez klikania w panel sprzedawcy. Zadanie: połączyć jedno z drugim. Na pierwszą ofertę wybraliśmy najprostszy produkt z katalogu, piłkę z kodem EAN, który Allegro zna. Skrypt utworzył ofertę roboczą w kilka sekund.

I na tym się skończyło. Oferta istniała, ale nie dało się jej aktywować. Zamiast jednego błędu dostaliśmy kaskadę sześciu: brak lokalizacji, stan magazynowy musi wynosić zero, brakuje stawki VAT, brakuje adresu zwrotu, usługa nieaktywna, cennik niedozwolony. Każdy z osobna brzmiał absurdalnie. Stan zero? Przecież chcę coś sprzedać. Dopiero po przeczytaniu ich razem zobaczyłem wzór: wszystkie wskazywały na jeden model sprzedaży, którego nie wybieraliśmy.

Tu jest pierwsza lekcja i wracam do niej w tym tekście kilka razy. Błędy z API opisują stan konta, nie stan kodu. Programista czyta „stan musi wynosić zero” i szuka błędu w swoim skrypcie. A to jest zdanie o koncie: zostało skonfigurowane tak, że jedyny dostępny sposób dostawy wymaga trzymania towaru w magazynie Allegro. Kod był tylko posłańcem, który przyniósł złą wiadomość.

Co zepsuło konto, zanim ktokolwiek cokolwiek na nim zrobił?

Konto sprzedawcy założyliśmy na spółkę kilka dni wcześniej. Weryfikację firmy i rejestrację aplikacji API prowadziła koleżanka z zespołu, ja dostałem gotowe klucze. Nikt z nas nie zaglądał w ustawienia dostawy, bo po co, skoro i tak wszystko ma iść przez API.

Pierwsze zapytanie, które wysłałem po kaskadzie błędów, dotyczyło cenników dostawy. Konto miało ich sześć. Wszystkie sześć miały dwie flagi: zarządzany przez Allegro i realizacja z magazynu Allegro. Czyli były to cenniki usługi One Fulfillment, w której wysyłasz towar do centrum logistycznego marketplace, a oni pakują i wysyłają za Ciebie. Model dla kogoś, kto sprzedaje tysiące sztuk miesięcznie. Nie dla sklepu, który pierwszą piłkę wystawia na próbę i chce ją nadać kurierem z własnej półki.

Zero cenników dla sprzedawcy, który wysyła sam. Nowe konto, które z definicji nie ma jeszcze aktywnej usługi magazynowej, dostaje fabrycznie tylko cenniki tej usługi. Nie wiem, czy to decyzja produktowa, czy przypadek, ale z punktu widzenia małego sprzedawcy to pułapka: oferta tworzy się bez problemu, a dopiero publikacja odsłania, że żaden z dostępnych cenników nie pasuje.

Jak powstał własny cennik i co poszło nie tak za pierwszym razem

Rozwiązanie brzmi prosto: utwórz własny cennik, przypisz go do oferty. W praktyce to było pięć prób. Pierwsza odrzucona, bo zabrakło typu cennika, fizyczny czy elektroniczny. Druga odrzucona, bo generyczna metoda „przesyłka kurierska” nie istnieje dla sprzedawcy wysyłającego samodzielnie. Allegro ma ponad trzysta dozwolonych metod dostawy i każda ma pole, które mówi, czy można jej użyć we własnym cenniku. Trzeba było je pobrać, przefiltrować i wybrać konkretnych kurierów z nazwy.

Trzecia próba poszła, tylko że skrypt dobrał metodę po pierwszym pasującym słowie i wybrał „kurier medyczny”. Semantycznie bzdura, technicznie bez zarzutu, Allegro przyjęło. I tu drobny szczegół, który bolał: API nie pozwala usunąć cennika. Zapytanie o usunięcie zwraca błąd „metoda niedozwolona”. Pusty cennik „Kurier medyczny” wisi do dziś w ustawieniach konta i czeka, aż ktoś skasuje go ręcznie w panelu. Czwarta próba utworzyła właściwy cennik: trzech kurierów plus dostawa własna, 18 zł za pierwszą sztukę, zero za kolejną w tym samym zamówieniu. Piąta przypisała go do oferty.

Jeśli znasz ten blog, to zabrzmi znajomo. Ten sam mechanizm opisywałem przy czterech cennikach w jednej bazie: program wybiera pierwszą pasującą rzecz, a nie tę właściwą, bo właściwej nikt mu nie zdefiniował. Model językowy robi to z tekstem, mój skrypt zrobił to z listą kurierów. Różnica jest tylko w skali szkody.

Kim jest „producent odpowiedzialny” i czemu bez niego nie ma publikacji?

Po naprawie cenników kaskada sześciu błędów skurczyła się do dwóch. Oba dotyczyły jednego skrótu, którego rok wcześniej nie znałem: GPSR.

To unijne rozporządzenie o ogólnym bezpieczeństwie produktów, stosowane od 13 grudnia 2024. Dla sprzedawcy internetowego sprowadza się do dwóch obowiązków. Pierwszy: przy każdym produkcie musisz wskazać podmiot odpowiedzialny w Unii, zwykle producenta, z nazwą, adresem i kontaktem widocznymi dla kupującego. Drugi: musisz podać informacje o bezpieczeństwie produktu albo ostrzeżenia, jeśli produkt ich wymaga. Allegro wdrożyło to jako wymóg publikacji, a od 4 sierpnia 2025 zamknęło furtkę: opcja „brak informacji o bezpieczeństwie” jest dla nowych ofert zakazana. Coś trzeba napisać. Zawsze.

Nasze konto miało pustą listę producentów odpowiedzialnych. Nie dlatego, że ktoś zapomniał, tylko dlatego, że nikt nigdy nie wystawiał na nim żadnej oferty. A oferta piłki wskazywała na producenta, który nie istniał.

Skąd wziąć dane producenta i czego nie wolno zrobić

Pierwszy odruch programisty: wpisać cokolwiek, żeby przeszło, poprawić później. Zablokowałem to u siebie świadomie. Dane producenta pokazują się kupującemu i są deklaracją prawną, więc wpisanie adresu z pamięci albo z pierwszego wyniku wyszukiwarki to proszenie się o kłopoty. Adres producenta piłki wzięliśmy z oficjalnej noty prawnej na jego stronie, sprawdziliśmy aktualną nazwę spółki, bo marka zmieniła formę prawną kilka lat temu, i dopiero wtedy utworzyliśmy wpis.

Sam wpis też nie poszedł za pierwszym razem. Schemat danych producenta w API Allegro ma kilka pułapek: nazwa musi stać na najwyższym poziomie struktury i jeszcze raz w środku, kod pocztowy nazywa się inaczej, niż podpowiada intuicja, a kontakt musi być obiektem z mailem i telefonem, nie tekstem. Dochodziłem do działającej struktury minimalnymi zapytaniami, po jednym polu na raz. Czterdzieści minut na jedno zapytanie, które w dokumentacji zajmuje pół ekranu.

Informację o bezpieczeństwie napisałem sam: twarda piłka, zalecane ochraniacze, nadzór dorosłego przy dzieciach. Trzy zdania zwykłym językiem. I tu uczciwie: ten tekst wciąż czeka na przegląd przez kogoś, kto zna produkt lepiej niż ja. Automat go opublikował, człowiek powinien go sprawdzić. Zapisaliśmy to jako otwartą sprawę, nie jako załatwioną.

Dla każdej kolejnej marki w sklepie trzeba będzie zrobić to samo: znaleźć producenta, zweryfikować adres, utworzyć wpis, napisać informację o bezpieczeństwie. To jest praca, którą nie da się zautomatyzować bez ryzyka, bo źródłem danych jest nota prawna na obcej stronie, a odbiorcą prawo. Podobny wniosek wyszedł mi przy cyfrowym paszporcie produktu: dane o produkcie przestają być sprawą marketingu i stają się sprawą zgodności z przepisami, a to zmienia, kto za nie odpowiada.

Jak API Allegro uczy pokory, czyli dziennik dwóch dni

Dla tych, którzy wdrażają integrację sami albo zlecają ją komuś, zostawiam listę rzeczy, na których straciłem czas. Żadna nie jest w dokumentacji wytłuszczona.

Zmiana istniejącej oferty idzie wyłącznie przez częściową aktualizację, czyli PATCH. Próba pełnej podmiany przez PUT kończy się błędem „metoda niedozwolona”. Częściowa aktualizacja odrzuca każde pole, którego nie zna, więc nie można wysłać jej tej samej struktury, którą dostało się z API przy odczycie: trzeba wyciąć identyfikator produktu, znacznik „współtworzone przez AI” i cały blok publikacji. Publikacji nie zmienia się w ofercie. Zmienia się ją osobnym poleceniem, które tworzy zadanie w tle, a potem pyta się co kilka sekund, czy zadanie się skończyło. Nasze skończyło się sukcesem po trzecim zapytaniu.

Informacja o bezpieczeństwie ma dwa akceptowane typy: tekst albo załączniki. Pola o innych nazwach, które wyglądają sensownie, API przyjmuje w milczeniu i ignoruje. Walidacja przechodzi, informacji nie ma. To najbardziej zdradliwy rodzaj błędu: nic nie krzyczy. Dowiedziałem się tylko dlatego, że po każdym zapisie odczytywałem ofertę z powrotem i porównywałem z tym, co wysłałem. Ta zasada, sprawdzaj skutek, nie kod wyjścia, wraca u mnie przy każdym wdrożeniu i za każdym razem okazuje się potrzebna.

I jeszcze jedno, czego nie przewidziałem. Publiczna strona oferty, otwierana skryptem, zwraca błąd 403. Antybot. Przez kwadrans byłem przekonany, że publikacja się nie udała, choć API mówiło „aktywna”. W przeglądarce strona działała od początku. Lekcja: stan oferty bierze się z API, nie z próby wejścia na stronę, bo marketplace broni się przed automatami, także tymi, które są jego własnym sprzedawcą.

Szczerze? Dwa dni na jedną piłkę za 45 zł to upokarzający wynik dla kogoś, kto integracje robi zawodowo. Ale te dwa dni kupiły coś konkretnego: plik konfiguracyjny z identyfikatorami cennika, producenta, warunków zwrotu i reklamacji, do którego każda kolejna oferta sięgnie w sekundę. Pierwsza oferta zawsze kosztuje najwięcej. Pytanie tylko, czy płacisz za nią czasem, czy pismem od prawnika.

Co znalazliśmy w umowach z markami i dlaczego czytaliśmy je w ostatniej chwili?

Teraz część, która z kodem nie ma nic wspólnego, a zdecydowała o większej liczbie produktów niż wszystkie błędy API razem.

Nasz sklep sprzedaje sprzęt kilku marek, każdą na podstawie osobnej umowy albo warunków dystrybucji. Umowy podpisywaliśmy z myślą o własnym sklepie internetowym i o sprzedaży stacjonarnej. Allegro w tych rozmowach nie było. Pięć dni przed pierwszą ofertą usiedliśmy nad dokumentami jeszcze raz, z jednym pytaniem: czy wolno nam wystawić to na marketplace?

Odpowiedź nie była jedna. W umowach znalazły się cztery różne rodzaje ograniczeń:

  • zakaz sprzedaży na marketplace w ogóle. Marka pozwala sprzedawać przez własną stronę sklepu, ale nie przez platformy zewnętrzne. W Unii taki zakaz jest co do zasady wykonalny, orzecznictwo to potwierdziło, więc nie ma sensu z nim dyskutować;
  • zgoda ustna, brak zgody na piśmie. Przedstawiciel marki powiedział na spotkaniu, że nie ma problemu, ale w dokumentach stoi co innego. Dla nas to znaczy „nie”, dopóki nie przyjdzie mail;
  • ograniczenie terytorialne. Sprzedaż online dozwolona tylko w krajach wymienionych w umowie. Kilka sąsiednich rynków jest poza listą, a naruszenie terytorium oznacza rozwiązanie umowy w trybie natychmiastowym;
  • zakaz budowania strefy marki. Zwykłe oferty są w porządku, ale nie wolno tworzyć osobnej witryny, profilu ani sklepu pod nazwą producenta.

Pozostałe marki nie zabraniały nic. Z całego asortymentu wyszło więc: część wolno wystawić wszędzie, część tylko w Polsce, część wcale, a jedna marka czeka na potwierdzenie mailem.

Dlaczego ograniczenie terytorialne stało się nagle problemem

Jeszcze latem ten punkt mógłbym zignorować, bo oferta na allegro.pl trafia do polskich kupujących i tyle. Od 18 sierpnia już nie. Allegro zaczęło samo rozszerzać promowane oferty na swoje rynki w Czechach, Słowacji i na Węgrzech. Sprzedawca nic nie robi, oferta pojawia się za granicą. Dla marketplace to wzrost zasięgu. Dla sprzedawcy, który ma w umowie listę krajów bez tych trzech, to automatyczne złamanie umowy bez jednego kliknięcia z jego strony.

Dlatego pierwszą ofertę opublikowaliśmy wyłącznie na rynku polskim, zdejmując z niej rynki dodatkowe i ofertę dla firm. Nie z ostrożności technicznej, tylko dlatego, że umowa na producenta tej konkretnej piłki wymienia kraje, a trzech z nich nie ma na liście. Gdyby nikt nie przeczytał umowy, oferta poszłaby z domyślnymi ustawieniami, czyli na wszystkie rynki, i wyglądałaby świetnie. Do pierwszego maila od dystrybutora.

To jest coś, co powtarzam klientom przy każdym wdrożeniu z AI: narzędzie ma ustawienia domyślne dobrane pod cel dostawcy narzędzia, nie pod Twoją umowę. Model językowy domyślnie odpowiada na każde pytanie. Marketplace domyślnie sprzedaje wszędzie, gdzie może. Jeśli Twoje zobowiązania są węższe niż domyślne ustawienia narzędzia, to Ty musisz je zawęzić, bo narzędzie samo tego nie zrobi.

Jak flaga przy marce zastąpiła pamięć człowieka?

Wynik lektury umów można było zapisać w notatce i poprosić zespół, żeby pamiętał. Wiem, jak kończą się takie notatki, bo przegrałem już kilka razy z własną pamięcią przy przypomnieniach. Zamiast tego dopisaliśmy do kartoteki marek w panelu trzy pola: wolno na Allegro, wolno na Empik, wolno na Amazon. Tak lub nie, z miejscem na powód.

Zasada działania jest celowo nudna. Domyślna wartość dla każdej marki to „nie”. Włączamy pojedynczo, po przeczytaniu umowy, z wpisanym powodem i datą. Marka z zakazem marketplace ma „nie” na stałe. Marka czekająca na mail ma „nie” do dnia, w którym mail przyjdzie. Marki z ograniczeniem terytorialnym mają „tak”, ale integracja wystawia je tylko na rynek polski, bo przy fladze stoi też terytorium. Skrypt wystawiający oferty czyta tę flagę przed każdym zapytaniem do API i przy „nie” nie wysyła nic. Nie pyta, nie ostrzega, nie wystawia.

Ktoś zapyta, czemu nie zostawić decyzji człowiekowi przy każdej ofercie. Bo przy stu produktach człowiek zacznie klikać „tak” z rozpędu, a przy tysiącu przestanie czytać. Flaga przy marce ustawiana jest raz, po lekturze umowy, przez osobę, która ją czytała. Potem egzekwuje ją kod. To ten sam schemat, który opisywałem przy zasadzie „dla klientów nic bez wyceny”: reguła zapisana w notatce jest do interpretacji, reguła zapisana w kodzie po prostu działa.

Jest w tym też koszt, który chcę nazwać. Flaga odcina od marketplace marki, na których moglibyśmy zarobić, i odcina je dopóty, dopóki ktoś nie podniesie telefonu do dystrybutora i nie wynegocjuje zgody na piśmie. Automatyzacja nie załatwia relacji z producentem. Pokazuje tylko wyraźnie, gdzie ta relacja jest niedokończona.

Co się stało po publikacji i czego to nauczyło?

Pierwsza oferta wisiała pięć tygodni, zanim ktoś ją kupił. Jedno zamówienie, jedna piłka, w trzecim tygodniu października. I tu kolejna lekcja, tym razem nie o API, tylko o nas.

Powiadomienie o zamówieniu przyszło do panelu Allegro, do którego nikt z zespołu na co dzień nie zaglądał. Zamówienia ze sklepu własnego wpadają do naszego panelu i stamtąd idą do wysyłki, Allegro było poza tym obiegiem. Paczka wyszła po terminie wyznaczonym przez marketplace. Jedno opóźnienie przy jednym zamówieniu wystarczyło, żeby wskaźnik jakości sprzedaży nowego konta spadł poniżej poziomu neutralnego. Marketplace nie wie, że to pierwsze zamówienie w historii konta. Widzi jedno zamówienie i jedno spóźnienie, czyli sto procent spóźnień.

Naprawa zajęła jeden dzień: skrypt co pięć minut pobiera przez API opłacone zamówienia z Allegro, zakłada je w naszym panelu jak każde inne, zdejmuje stan z magazynu i wysyła mail do osoby, która pakuje. Osobna metryka pilnuje, czy jest coś do wysłania po terminie, i alarmuje. Kiedy paczka jest nadana, numer przesyłki wraca do Allegro przez API i zamówienie zmienia status na wysłane.

Dlaczego tego nie było od początku? Bo wystawienie oferty i obsługa zamówień to dwie różne integracje, a my zrobiliśmy jedną i uznaliśmy temat za zamknięty. Pierwsza piłka pokazała, że marketplace to nie dodatkowy kanał wystawiania. To dodatkowy kanał zobowiązań: terminy wysyłki, których pilnuje ktoś inny, i oceny, które się nie resetują. Kto wystawia przez API, musi też przez API odbierać, inaczej jego oferty żyją w miejscu, w które nikt nie patrzy.

Lista do sprawdzenia przed pierwszą ofertą

Gdybym miał dziś podłączać do Allegro sklep klienta, kolejność byłaby odwrotna niż ta, w której sam to zrobiłem. Najpierw papier, potem konto, dopiero na końcu kod.

  1. Przeczytaj umowy z każdą marką pod kątem marketplace. Szukaj czterech rzeczy: zakazu platform zewnętrznych, listy krajów, wymogu zgody pisemnej, zakazu strefy marki. Zapisz wynik per marka, z datą i cytatem.
  2. Zdecyduj, co robisz z rozszerzaniem ofert na rynki zagraniczne. Jeśli choć jedna umowa wymienia kraje, oferty tej marki publikuj wyłącznie na rynek polski i sprawdź w ustawieniach konta, czy marketplace nie rozszerza ich sam.
  3. Zajrzyj w cenniki dostawy konta, zanim napiszesz pierwszą linię kodu. Jeśli wszystkie są cennikami realizacji z magazynu marketplace, utwórz własny. Wybieraj metody dostawy z nazwy, nie po pierwszym pasującym słowie.
  4. Dla każdej marki przygotuj dane producenta odpowiedzialnego. Nazwa prawna, adres, mail, telefon, wszystko z oficjalnej noty prawnej producenta, zweryfikowane. Do tego informacja o bezpieczeństwie napisana po ludzku, przeczytana przez kogoś, kto zna produkt.
  5. Zapisz pozwolenia marek jako pola w swoim systemie, nie w notatce. Domyślnie „nie”. Integracja ma czytać to pole przed każdym wystawieniem.
  6. Po każdym zapisie przez API odczytaj ofertę z powrotem i porównaj. Część pól jest ignorowana bez komunikatu. Stan oferty bierz z API, nie ze strony publicznej.
  7. Podłącz zamówienia tego samego dnia, w którym wystawiasz pierwszą ofertę. Nie za tydzień. Pierwsze spóźnienie przy pierwszym zamówieniu zostaje w ocenie konta na długo.
  8. Zachowaj identyfikatory wszystkiego, co utworzyłeś na koncie. Cennik, producent, warunki zwrotu i reklamacji. Druga oferta ma trwać sekundę, nie dwa dni.

Dwa dni pracy przy pierwszej ofercie to nie była cena integracji. To była cena nieprzeczytanych ustawień i umów, którą zapłaciliśmy wcześnie i tanio. Sklep, który podłącza marketplace „bo kod już jest”, zapłaci ją później, w walucie, której nie da się odzyskać: w ocenach konta i w relacjach z producentami.

Słownik pojęć

  • API - drzwi służbowe programu, przez które inny program może z nim rozmawiać bez klikania w interfejs. Przez API Allegro skrypt tworzy oferty, zmienia ceny i pobiera zamówienia, tak jak zrobiłby to człowiek w panelu, tylko bez człowieka.
  • Marketplace - platforma sprzedażowa, na której wielu sprzedawców wystawia oferty pod wspólnym szyldem, na przykład Allegro, Empik czy Amazon. Sprzedajesz na jej zasadach, w jej terminach i pod jej oceną.
  • GPSR - unijne rozporządzenie o ogólnym bezpieczeństwie produktów, stosowane od 13 grudnia 2024. Wymaga, żeby przy każdym produkcie był wskazany podmiot odpowiedzialny w Unii z danymi kontaktowymi oraz żeby kupujący dostał informacje o bezpieczeństwie produktu.
  • Producent odpowiedzialny - podmiot, który w rozumieniu GPSR odpowiada za bezpieczeństwo produktu na rynku unijnym. Na Allegro trzeba go utworzyć na koncie i przypisać do oferty, inaczej oferta nie przejdzie publikacji.
  • One Fulfillment - usługa Allegro, w której sprzedawca wysyła towar do magazynu marketplace, a pakowaniem i wysyłką zajmuje się platforma. Nowe konto dostaje cenniki tylko tej usługi, nawet jeśli nigdy jej nie włączyło.
  • Cennik dostawy - zestaw metod dostawy i ich cen przypisywany do oferty. Metoda dostawy musi być dozwolona dla sprzedawcy wysyłającego samodzielnie, a utworzonego cennika nie da się usunąć przez API.
  • Flaga eksportu per marka - pole w naszej kartotece marek, które mówi, czy produkty danej marki wolno wystawiać na konkretnym marketplace. Domyślnie „nie”, włączane po lekturze umowy. Integracja czyta je przed każdym wystawieniem.

Zanim podłączysz sklep do Allegro, pokaż mi umowy

Jeśli prowadzisz mały sklep i planujesz marketplace, napisz do mnie na [email protected], zanim ktokolwiek napisze pierwszą linię integracji. Najwięcej powiem Ci nie o API, bo z API da się dojść do ładu w dwa dni, tylko o tym, które z Twoich produktów na marketplace trafić nie mogą i jak ustawić system, żeby sam tego pilnował.

Więcej o tym, jak wygląda współpraca ze mną, od pierwszej rozmowy po wdrożenie.

✓ Sprawdzone na
własnej firmie
cybulski.ai JC
You've successfully subscribed to cybulski.ai
Great! Next, complete checkout for full access to cybulski.ai
Welcome back! You've successfully signed in.
Unable to sign you in. Please try again.
Success! Your account is fully activated, you now have access to all content.
Error! Stripe checkout failed.
Success! Your billing info is updated.
Error! Billing info update failed.