Ceneo API – co można zautomatyzować w obsłudze porównywarki

Dostęp i autoryzacja – co musi wiedzieć sprzedawca

Nawet jeśli integrację zbuduje programista albo zewnętrzna firma, warto rozumieć podstawy, bo to Ty odpowiadasz za dostęp do konta. Według dokumentacji połączenie z API zabezpieczone jest certyfikatem SSL i może odbywać się wyłącznie po HTTPS. Autoryzacja opiera się na protokole OAuth 2.0 w trybie client_credentials.

1. Klucz API. Pobierasz go w Panelu Ceneo. Klucz nie ma terminu ważności, ale w razie potrzeby można go zmienić w panelu.

2. Token dostępu. Aplikacja wymienia klucz na token, wywołując metodę GetToken w serwisie autoryzacji. Token jest typu „bearer” i według dokumentacji jest ważny 15 minut.

3. Zapytania. Token dołącza się do nagłówka każdego zapytania o zasoby i operacje. Przeterminowany token lub jego brak kończy się błędem 401, a brak uprawnień – błędem 403.

4. Odnowienie. Po wygaśnięciu tokenu aplikacja musi pobrać nowy. Dobrze napisana integracja robi to automatycznie, bez przerw w działaniu.

[#uwaga] Klucz API traktuj jak hasło do konta. Nie wysyłaj go mailem w otwartej treści, nie wklejaj do publicznych repozytoriów i nie zostawiaj w plikach dostępnych z sieci. Jeśli kończysz współpracę z firmą, która miała dostęp do klucza, albo podejrzewasz wyciek – zmień klucz w Panelu Ceneo.

Wykres – pięć kroków, przez które przechodzi aplikacja łącząca się z API Ceneo. [#chart:ce77]

Limity, cache i błędy – ograniczenia, o których trzeba pamiętać

API nie jest nieograniczonym strumieniem danych. Dokumentacja wymienia kilka zasad, które wpływają na projekt integracji i na to, czego możesz się po niej spodziewać.

Zasada 5-minutowego cache ma praktyczną konsekwencję: API nie służy do reagowania w ułamkach sekund. Jeśli ktoś obiecuje Ci integrację „w czasie rzeczywistym”, zapytaj, jak uwzględnia te ograniczenia.

Co automatyzować w obsłudze Ceneo – i czym

Najczęstszy błąd w myśleniu o automatyzacji to założenie, że wszystko musi przejść przez API. Tymczasem większość pracy przy porównywarce dotyczy kilku obszarów, z których każdy ma swoje naturalne narzędzie.

Ceny, stany i dostępność

Te dane trafiają do Ceneo przez plik produktowy. Regulamin przewiduje, że Ceneo pobiera dane ofertowe automatycznie nie rzadziej niż raz na dobę, a instrukcja tworzenia pliku XML opisuje także tryb przyrostowy, w którym możesz przesyłać tylko zmienione oferty. Dlatego podstawą automatyzacji cen i stanów jest dobrze generowany plik, a nie API. Szczegóły opisujemy w artykułach plik XML dla Ceneo krok po kroku i aktualizacja feedu Ceneo.

Zamówienia z Kup na Ceneo

Zamówienia złożone bezpośrednio w porównywarce muszą trafić do Twojego systemu sprzedaży. Najczęściej robi to wtyczka platformy, integracja SaaS albo system wielokanałowy. Na przykład w Base połączenie z modułem „Kup na Ceneo” wymaga według pomocy Base podania klucza Web API z Ceneo – to przykład, w którym API wykorzystuje gotowe narzędzie, a nie Twój własny kod. Więcej w tekście o integracji Base z Ceneo.

Zaufane Opinie

Przekazywanie transakcji do ankiet Zaufanych Opinii odbywa się przez kod transakcji umieszczony na stronie potwierdzenia zamówienia – ręcznie, przez wtyczkę platformy albo przez Google Tag Manager. To również jest automatyzacja, ale realizowana skryptem w sklepie, a nie przez API.

Dane i operacje dostępne w API

Wszystko, czego nie obsługuje plik ani kod opinii, warto sprawdzić w dokumentacji API i w narzędziu w Panelu Ceneo. Zanim zlecisz integrację, przejdź listę metod razem z programistą i zapisz, które z nich odpowiadają na Twoje realne potrzeby: na przykład regularne pobieranie danych do raportu czy automatyzację powtarzalnych czynności, które dziś wykonujesz ręcznie w panelu.

Wykres – sześć obszarów obsługi Ceneo i narzędzia, którymi najczęściej się je automatyzuje. [#chart:ce77b]

Kiedy własna integracja z API ma sens

Integracja z API to projekt programistyczny: trzeba ją zaprojektować, napisać, przetestować i utrzymywać. Z naszego doświadczenia opłaca się wtedy, gdy spełnionych jest kilka warunków jednocześnie.

Jeśli zastanawiasz się, czy Twój ERP powinien rozmawiać z kanałami sprzedaży bezpośrednio, czy przez system pośredni, zajrzyj do tekstu integracja Base z ERP – kiedy jest potrzebna. Podobna logika dotyczy Ceneo: im więcej kanałów, tym bardziej opłaca się jeden centralny system zamiast osobnych integracji.

[#przyklad] Sklep z kilkudziesięcioma tysiącami produktów co tydzień ręcznie eksportował dane z panelu do arkusza, żeby policzyć koszt kanału na kategorię. Zamiast od razu zamawiać integrację, najpierw spisał, jakie dane naprawdę są mu potrzebne i jak często. Okazało się, że raport tygodniowy wystarczy, a część danych i tak pochodzi z GA4. Integracja z API objęła tylko pobieranie danych do raportu – mniejszy zakres, niższy koszt, szybsze wdrożenie. To przykład poglądowy.

Czego nie robić za pomocą API i automatów

Automatyzacja to nie tylko oszczędność czasu, ale też odpowiedzialność. Kilka granic warto znać z góry.

• Nie pobieraj danych z serwisu Ceneo botami. Regulamin współpracy zabrania korzystania z oprogramowania typu boty czy scrapery do pobierania treści z serwisu bez pisemnej zgody Ceneo. Pobieranie stron porównywarki to co innego niż korzystanie z udostępnionego API.

• Nie zmieniaj identyfikatorów ofert automatem. Instrukcja XML wymaga unikalnych ID, których nie używa się ponownie, a samodzielna zmiana ID ofert jest w regulaminie wymieniona wśród przyczyn zawieszenia prezentacji.

• Nie automatyzuj cen bez kontroli. Błędna cena w pliku to nie tylko strata na sprzedaży, ale też koszt kliknięć – saldo konta przedpłat może według regulaminu spaść poniżej zera, np. przy dużej liczbie przejść na ofertę z błędną ceną.

• Nie zostawiaj integracji bez nadzoru. Każda automatyzacja powinna mieć logi błędów i powiadomienia, żeby problem nie wyszedł dopiero na fakturze.

O narzędziach do automatycznej zmiany cen i ich ryzykach piszemy w artykule repricing a Ceneo, a o legalnych sposobach śledzenia rynku – w tekście monitoring cen na Ceneo.

Jak przygotować się do integracji

Jeśli po analizie zdecydujesz, że własna integracja ma sens, przygotuj się tak, by projekt nie rozrósł się ponad potrzebę.

1. Opisz problem, a nie rozwiązanie. Zamiast „chcemy API” napisz: „co tydzień tracimy kilka godzin na ręczne raporty” albo „chcemy mieć dane kosztowe Ceneo w raporcie zarządczym”.

2. Sprawdź, czy problemu nie rozwiązuje plik lub wtyczka. Wiele zgłoszeń dotyczy cen i stanów, które obsługuje automatycznie generowany plik produktowy.

3. Przejrzyj dokumentację razem z programistą. Zweryfikujcie w Panelu Ceneo, które metody są dostępne dla Twojego konta, i przetestujcie je w narzędziu do wywoływania metod.

4. Ustal zasady bezpieczeństwa. Kto ma dostęp do klucza API, gdzie jest przechowywany, kiedy go zmieniacie.

5. Zaplanuj utrzymanie. API się rozwija, więc ktoś musi reagować na zmiany i błędy. Zapisz to w umowie z wykonawcą.

[#tip] Zanim zlecisz cokolwiek programiście, przejdź przez panel sklepu Ceneo i sprawdź, które raporty i ustawienia są już dostępne. Często okazuje się, że brakujący element to nie integracja, tylko dobrze ustawiony raport lub eksport danych.

Typowe problemy z integracjami – na co uważać

Większość kłopotów z automatyzacją Ceneo nie wynika z samego API, tylko z tego, jak integracja została zaprojektowana i jak jest utrzymywana. Poniżej problemy, które widzimy najczęściej przy przejmowaniu obsługi sklepów.

• Integracja, o której nikt nie pamięta. Skrypt napisany kilka lat temu działa na serwerze, ale nikt nie wie, co dokładnie robi i kto ma do niego dostęp. Gdy przestaje działać, sklep dowiaduje się o tym z opóźnieniem.

• Brak obsługi wygasłego tokenu. Jeśli integracja nie odnawia tokenu automatycznie, po 15 minutach zaczyna dostawać błędy 401 i przestaje pobierać dane.

• Zbyt częste zapytania. Odpytywanie tych samych danych co minutę nie daje świeższych wyników, bo obowiązuje 5-minutowy cache, a może prowadzić do przekroczenia limitów wywołań.

• Dwa źródła prawdy. Ceny zmieniane jednocześnie w pliku XML i w innym narzędziu prowadzą do rozbieżności między ofertą w Ceneo a stroną sklepu – a za to instrukcja przewiduje ukrycie oferty.

• Brak testów po zmianach w sklepie. Zmiana platformy, szablonu czy struktury kategorii potrafi zepsuć plik produktowy i integrację jednocześnie. Po każdej większej zmianie sprawdź, czy dane nadal docierają poprawnie – pomoże w tym nasz przegląd błędów w pliku XML Ceneo.

Jak wybrać wykonawcę integracji

Jeśli nie masz własnego zespołu IT, integrację zbuduje dla Ciebie zewnętrzny programista albo firma. Przy wyborze nie patrz wyłącznie na cenę. Zapytaj, czy wykonawca pracował już z API Ceneo lub podobnymi interfejsami marketplace’ów, jak zamierza przechowywać klucz API, jak będzie obsługiwał limity, cache i błędy oraz kto będzie utrzymywał rozwiązanie po wdrożeniu. Poproś o krótką dokumentację: jakie dane są pobierane, jak często i gdzie trafiają.

Dobrą praktyką jest też zapisanie w umowie, że kod i dostęp do serwera należą do sklepu. Dzięki temu po zakończeniu współpracy z wykonawcą nie zostajesz z rozwiązaniem, którego nikt nie potrafi zmienić. Podobne zasady dotyczą innych integracji – o tym, co da się zautomatyzować przez interfejs systemu wielokanałowego, piszemy w artykule Base API – co można zautomatyzować.

API a raportowanie opłacalności

Najczęstszym powodem, dla którego sklepy pytają o API, jest raportowanie: chcą widzieć koszty Ceneo obok sprzedaży z GA4 i danych z innych kanałów. Warto pamiętać, że według regulaminu podstawą rozliczeń są raporty zweryfikowane w panelu, a raporty on-line mają charakter informacyjny. Dane pobierane automatycznie traktuj więc jako bieżący podgląd, a do rozliczeń i oceny miesięcznej sięgaj po dane zweryfikowane.

Jak zbudować taki raport bez programowania, pokazujemy w artykule raport opłacalności Ceneo w Looker Studio lub arkuszu, a jak czytać same statystyki – w tekście statystyki Ceneo. API może ten proces przyspieszyć, ale nie zastąpi dobrze zdefiniowanych wskaźników.

Najczęściej zadawane pytania

Kto może korzystać z API Ceneo?

Według oficjalnego opisu dostęp do API mają tylko klienci posiadający sklep zintegrowany z Ceneo.pl. Klucz API pobierasz w Panelu Ceneo.

Czy przez API mogę aktualizować ceny zamiast przez plik XML?

Podstawowym kanałem przekazywania cen, stanów i dostępności jest plik produktowy, który Ceneo pobiera automatycznie. Dla dużych katalogów instrukcja XML przewiduje tryb przyrostowy. Czy i jakie operacje na ofertach udostępnia API, sprawdź w aktualnej dokumentacji w panelu.

Jak długo jest ważny token dostępu?

Według dokumentacji token typu bearer jest ważny 15 minut. Po tym czasie trzeba pobrać nowy, podając klucz API.

Dlaczego API zwraca te same dane mimo zmian w panelu?

Wyniki zapytań są przechowywane w cache przez 5 minut. W tym czasie identyczne zapytanie zwróci te same dane, nawet jeśli w międzyczasie się zmieniły.

Czy mogę użyć API do śledzenia cen konkurencji?

API służy do automatyzacji obsługi własnej sprzedaży. Pobieranie treści serwisu Ceneo botami lub scraperami bez pisemnej zgody jest zabronione w regulaminie współpracy.

Czy małemu sklepowi API jest potrzebne?

Zwykle nie. Mały sklep najwięcej zyska na dobrze przygotowanym pliku produktowym, wtyczce platformy, Zaufanych Opiniach i poprawnej analityce. API warto rozważyć, gdy rośnie skala lub liczba kanałów.

Podsumowanie

API Ceneo to narzędzie dla sklepów zintegrowanych z porównywarką, oparte na REST, OData i autoryzacji OAuth 2.0 z tokenem ważnym 15 minut. Ma limity wywołań i 5-minutowy cache, więc nie służy do działań w czasie rzeczywistym. Ceny i stany automatyzujesz przede wszystkim plikiem produktowym, zamówienia z Kup na Ceneo – integracją platformy lub systemu wielokanałowego, a opinie – kodem transakcji. Własną integrację z API planuj wtedy, gdy masz konkretny problem do rozwiązania i potwierdziłeś w dokumentacji, że dostępne metody na niego odpowiadają.

Jeśli chcesz uporządkować automatyzację porównywarki – od pliku produktowego po raportowanie – zobacz, jak wdrażamy i obsługujemy sprzedaż na Ceneo.