InPost Von Halsky: instrukcja obsługi modułu

InPost Von Halsky: instrukcja obsługi modułu

Zadaniem modułu jest wystawianie produktów sklepu jako oferty na platformie Von Halsky, pilnowanie, aby ceny i stany na platformie zgadzały się z katalogiem, i ściąganie zamówień z platformy do sklepu.

Przed rozpoczęciem: jak wygląda cały cykl

Najpierw jednorazowa konfiguracja: podłączenie sklepu do InPostu, ustawienie zadania cron na
serwerze, mapowanie kategorii, ustawienie szablonu oferty oraz mapowanie statusów i form dostawy.
Potem codzienna praca: sprawdzanie gotowości produktów, wystawianie ich, obserwowanie kolejki i
obsługa zamówień.

1. Podłączenie do InPost

W zakładce "Konfiguracja" należy: wpisać organization_id, client_id i client_secret z panelu
merchanta InPost, wybrać środowisko (Domyślnie powinna to być produkcja - staging służy do testów) i zapisuje





Na tej samej stronie, jeszcze przed połączeniem, moduł pokazuje dwie rzeczy, które trzeba wpisać po
stronie InPostu przy tworzeniu aplikacji: listę wymaganych uprawnień (scope) oraz adres URL
przekierowania.



Następnie należy kliknąć "Połącz z InPost", zalogować się i wrócić do sklepu. Panel "Stan
połączenia" pokaże wynik, a wiersze "Poświadczenia" i "Połączenie" muszą świecić na zielono (OK).

2. Zadanie cron

Trzeba skonfigurować cron na serwerze, bez niego moduł nic nie robi w tle: nie wystawia ofert z
kolejki, nie synchronizuje cen i stanów, nie importuje zamówień. Gotowe polecenie jest w zakładce
"Kolejka zadań", przycisk "Jak ustawić zadanie cron kolejki".




Zielone "Zadanie cron kolejki działa" oznacza, że jest kolejka działa poprawnie.

3. Mapowanie kategorii

W zakładce "Mapowanie kategorii" łączy się kategorie PrestaShop z kategoriami Von Halsky.

Dwie rzeczy warto wiedzieć zawczasu. Po pierwsze moduł patrzy na kategorię domyślną produktu, a nie
na wszystkie, do których produkt należy. Produkt może leżeć w zmapowanej kategorii i dalej być
zablokowany, jeśli jego kategoria domyślna jest gdzie indziej. Po drugie zaznaczenie opcji
"rekursywnie" sprawia, że mapowanie zadziała także dla podkategorii. Bez tego mapowana jest dokładnieta jedna kategoria.
Część kategorii Von Halsky wymaga dodatkowych atrybutów (na przykład format książki). Jeśli
wymagany atrybut nie jest zmapowany, produkt zostanie zablokowany na etapie weryfikacji gotowości.

Czerwonym kolorem oznaczamy kategorie nieposiadające mapowania, zielonym te ktore posiadają mapowanie oraz szarym te które dziedziczą mapowanie z kategorii nadrzędnej.


Aby zmapować kategorię musimy kliknąć przycisk "Mapuj" lub gdy chcemy zmienić już zmapowaną kategorię klikamy "Zmień"

Następnie wyszukujemy odpowiednią kategorię zdefiniowaną przez Von Halsky, która najlepiej odpowiada kategorii z sklepu. Z poziomu tego widoku możemy również wybrać szablon oferty z którego korzystać będzie kategoria.

4. Szablon oferty

Zakładka "Szablony". Szablon decyduje, jak zbudowany jest tytuł oferty, skąd brany jest opis, czy do
ceny doliczany jest narzut lub rabat i ile dni wysyłki deklaruje sklep. Wszystko to można nadpisać
dla pojedynczego produktu na liście kandydatów; nadpisanie wygrywa zawsze, niezależnie od tego, co
mówi szablon.



W sklepie musi istnieć dokładnie jeden szablon domyślny. Bez niego żaden produkt nie zostanie
wystawiony. Po skasowaniu szablonu domyślnego moduł sam ustawi domyślnym któryś z pozostałych
aktywnych.

W szablonie możemy ustawić takie parametry jak

• Wzorzec nazwy - z jakich parametrów będzie się składać nazwa produktu widoczna w Von Halsky
• Źródło opisu - Pełny, skrócony lub zapisany na stałe tekst
• Narzut cenowy - w procentach lub lub stała wartość.
• To czy mamy synchronizować ceny i stany magazynowe dla produktów z korzystających z tego szablonu
• Czas wysyłki

Ponadto Wzorzec nazwy ma kilka zmiennych których można użyć do budowania nazwy produktu:

5. Przygotowanie produktów

Zakładka "Oferty", karta "Produkty do wystawienia". Po kliknięciu "Weryfikuj gotowość produktów"
moduł sprawdza cały katalog, a potem pokazuje, co blokuje wystawienie. Nad listą pojawiają się
kolorowe etykiety z liczbami, na przykład "47 Brak EAN" albo "46 Opis za krótki". Kliknięcie
etykiety filtruje listę do produktów z tym jednym problemem.




Weryfikacja nie dzieje się sama. Data ostatniego sprawdzenia jest widoczna obok licznika, więc po
zmianach w produktach trzeba kliknąć przycisk jeszcze raz.

Co musi być uzupełnione, żeby produkt dało się wystawić:

Pole	Wymaganie
EAN	8, 12, 13 lub 14 cyfr, z poprawną cyfrą kontrolną
Referencja (SKU)	dowolna, ale nie może być pusta
Nazwa	nie może być pusta
Zdjęcie	co najmniej jedno, dostępne publicznie pod adresem sklepu
Stawka VAT	ustawiona (0% też jest poprawne)
Jednostka	UNIT, PAIR, SET albo OTHER; brana z karty InPost produktu, jeśli karta ją podaje, w innym razie z mapowania pól, a w ostatniej kolejności przyjmowane jest UNIT
Dni wysyłki	ustawione w szablonie lub na produkcie
Opis	minimum 100 znaków samego tekstu, po odrzuceniu znaczników HTML
Cena	po narzucie z szablonu musi być większa od zera
Kategoria	kategoria domyślna produktu musi być zmapowana
Telefon producenta GPSR	format międzynarodowy, czyli +48600100200

Trzy rzeczy są tylko ostrzeżeniem i nie blokują wystawienia: zerowy stan magazynowy (oferta trafi na
listę wyprzedanych), brak EAN, jeśli produkt ma markę i numer producenta, oraz brak wagi lub
wymiarów (InPost przyjmuje ofertę bez nich, sprawdzone na stage 16.09.2026).

Braki można uzupełnić bez wychodzenia z listy: rozwinąć "co uzupełnić" przy produkcie, wpisać
wartość i zapisać. Taka poprawka dotyczy tylko tego produktu i nie rusza katalogu.




Nazwę, opis i dni wysyłki można nadpisać tu, per produkt, i to nadpisanie faktycznie trafia do
oferty (wcześniej wpisany opis znikał w wystawieniu - poprawione). Przy czerwonej etykiecie "Opis za
krótki" dopisanie opisu na tej liście naprawdę usuwa błąd, bez czekania na kolejną weryfikację
całego katalogu.

Zestawy zamknięte (pakiety) są zawsze pomijane. To ograniczenie platformy, nie błąd modułu.

6. Karta produktowa w InPost: najważniejsze ograniczenie

Von Halsky nie zakłada nowych kart produktowych przez API. Jeśli EAN produktu nie istnieje jeszcze w
katalogu InPostu, oferty nie da się wystawić i nic tego nie obejdzie. Moduł sprawdza to wcześniej i
pokazuje taki produkt jako niegotowy.

Gdy karta istnieje, oferta zostanie przypisana do kategorii tej karty, nawet jeśli w sklepie produkt
zmapowano inaczej. To też decyzja platformy.

Zarówno na liście kandydatów, jak i na liście ofert, przy produkcie jest rozwijany panel "Karta
InPost" z tym, co moduł ostatnio wiedział o karcie: marka, kategoria, jednostka, wymiary, atrybuty i
data pobrania. Czerwona plakietka przy nagłówku oznacza, że kategoria z karty różni się od
zmapowanej w sklepie - wygrywa karta. Panel pokazuje tylko dane z pamięci podręcznej modułu, nie
odpytuje InPostu na bieżąco, więc gdy jest pusty, należy kliknąć "Weryfikuj gotowość produktów".

7. Wystawianie ofert

Pojedynczy produkt wystawia się przyciskiem "Wystaw" w jego wierszu. Idzie od razu, bez kolejki, więc
odpowiedź pojawia się na ekranie.

Większą paczkę zaznacza się polami wyboru i wystawia przyciskiem "Wystaw zaznaczone". Takie
wystawienie trafia do kolejki, a nad listą pojawia się panel postępu z możliwością wstrzymania i
wznowienia paczki. Kolejkę obsługuje zadanie cron (punkt 2); gdy nie działa, oferty czekają w
kolejce i nad listą pojawia się ostrzeżenie.

Po wystawieniu oferta ma status "W trakcie wystawiania". Platforma potrzebuje chwili na weryfikację
i dopiero potem status zmienia się na "Aktywna". Jeśli oferta wisi w tym stanie bardzo długo, trzeba
zajrzeć do zakładki "Log i diagnostyka" albo poprosić o sprawdzenie osobę techniczną, bo platforma
mogła odrzucić ofertę po cichu (na przykład gdy nie potrafi pobrać zdjęć).

8. Ceny i stany

Zmiana ceny lub stanu w katalogu PrestaShop jest wykrywana automatycznie i wysyłana do InPostu przy
najbliższym przebiegu kolejki. Częstotliwość ustawia się w "Ustawieniach synchronizacji": osobno dla
cen i osobno dla stanów.

Cena i stan zapisują się w module dopiero wtedy, gdy platforma potwierdzi zmianę. Dopóki
potwierdzenia nie ma, kolumny "Cena wysłana" i "Stan wysłany" pokazują poprzednią wartość. To
celowe: pokazują, co faktycznie wie InPost, a nie co zostało wysłane.

Można ustawić minimalny stan magazynowy. Gdy stan spadnie poniżej tej wartości, moduł zamknie ofertę
zamiast wysyłać niski stan.

9. Zamykanie i wznawianie ofert

Na karcie "Oferty" każdy wiersz ma trzy akcje. "Zamknij" kończy sprzedaż oferty na platformie i czeka
na potwierdzenie. "Otwórz ponownie" przywraca zamkniętą ofertę. "Odepnij" usuwa tylko powiązanie po
stronie sklepu, a oferta zostaje na platformie, więc tej akcji należy używać świadomie.

10. Zamówienia

Zakładka "Zamówienia". Moduł sam odpytuje platformę co kilka minut (cron) i zaciąga nowe zamówienia.
Import można też uruchomić ręcznie przyciskiem "Importuj teraz".

Zanim przyjdzie pierwsze zamówienie, trzeba uzupełnić w "Ustawieniach modułu" dwie tabele: mapowanie statusów i mapowanie form dostawy.



Forma dostawy musi mieć przypisanego aktywnego przewoźnika, osobno paczkomat (APM) i osobno kurier (COURIER). Zamówienie z formą dostawy bez przewoźnika nie zaimportuje się wcale i zostanie na liście z błędem MISSING_CARRIER_MAPPING. Nie ma już zapasowego przewoźnika "domyślnego", bo zły przewoźnik oznacza zły list przewozowy. Brakujące mapowanie widać od razu na liście zamówień (żółty baner z nazwą formy dostawy) i w "Logach i diagnostyce".



Wiersz ACCEPTED w mapowaniu statusów decyduje, jaki status w sklepie dostaje każde nowo zaimportowane zamówienie. Odsyłania tego statusu do InPostu nie da się włączyć: InPost wie już, że zamówienie jest zaakceptowane.



Zamówienie nieopłacone nie zostanie zaimportowane, moduł poczeka na płatność. Zamówienie w statusie
CREATED czeka na decyzję sprzedawcy: akceptację albo odrzucenie przyciskiem w sczegółach
zamówienia. Po akceptacji zamówienie od razu trafia do sklepu. Można też włączyć automatyczną
akceptację.

Produkt z zamówienia moduł szuka najpierw po identyfikatorze oferty (jeśli ofertę wystawił ten
sklep), potem po EAN, na końcu po SKU. Gdy nie znajdzie produktu albo znajdzie dwa pasujące,
zamówienie zatrzyma się z błędem. W szczegółach zamówienia, w sekcji "Ręczne dopasowanie produktów", należy wtedy wpisać albo wybrać właściwy produkt i kliknąć "Zastosuj i zaimportuj ponownie".

Po każdym nowym zamówieniu sklep wysyła e-mail do sprzedawcy na adres ustawiony w PrestaShop jako e-mail sklepu. Jeśli wysyłka się nie uda (np. źle ustawiony serwer SMTP), w logu pojawi się
ostrzeżenie "Nie udało się wysłać e-maila o nowym zamówieniu do sprzedawcy".

Na stronie zamówienia w PrestaShop (Zamówienia -> Zamówienia -> szczegóły) moduł dodaje blok "Zamówienie InPost Von Halsky" z numerem zamówienia Von Halsky, statusem i kodem paczkomatu. Tego kodu nie ma w adresie wysyłki, więc kod do nadania paczki należy brać go z tego bloku.






Gdy InPost anuluje, odrzuci lub cofnie zamówienie, moduł przestawi je w sklepie na status z mapowania
i zwróci towar na stan. Po ręcznym przesunięciu zamówienia do statusu oznaczonego "wysyłaj do InPost"
moduł odeśle odrzucenie na platformę. Moduł nie wysyła do InPostu numeru przesyłki ani informacji o
wysyłce, bo API tego nie udostępnia.

11. Gdy coś świeci na czerwono

Pierwszy krok to "Konfiguracja". Jeśli "Połączenie" jest czerwone, żadna inna funkcja nie zadziała,
a opis przy każdej z czterech pozycji pokazuje, co odpowiedział InPost.

Drugi krok to "Kolejka zadań". Stojący cron oznacza, że nic nie dzieje się w tle, nawet jeśli w
module wszystko wygląda poprawnie.

Na końcu "Log i diagnostyka". Kafelki na górze pokazują stan poświadczeń, tokenu, synchronizacji
ofert i importu zamówień, liczbę błędów API z ostatniej doby oraz liczbę zadań zakończonych błędem.

Objaw	Znaczenie	Rozwiązanie
"Nieprawidłowy token" przy cronie	harmonogram woła moduł ze złym adresem	skopiować adres z zakładki "Kolejka zadań"
Oferta "Błąd / odrzucona"	platforma odrzuciła ofertę	otworzyć "Pokaż całość" przy błędzie, poprawić dane produktu i wystawić ponownie
Oferta długo "W trakcie wystawiania"	platforma jeszcze nie potwierdziła albo odrzuciła po cichu	sprawdzić log, w razie potrzeby zgłosić do wsparcia
Zamówienie z błędem dopasowania	EAN z zamówienia nie pasuje do katalogu	dopasować produkt ręcznie w szczegółach zamówienia
"Kategoria niezmapowana"	kategoria domyślna produktu nie ma odpowiednika	uzupełnić mapowanie kategorii

12. Log i zgłoszenia do InPostu

Zakładka "Log i diagnostyka" zapisuje każde wywołanie API razem z odpowiedzią. Można filtrować po
poziomie, kanale i dacie, a całość wyeksportować do pliku CSV, który dołącza się do zgłoszenia w
InPoście.

W tym eksporcie znajdują się pełne treści żądań i odpowiedzi, a przy zamówieniach także dane
kupujących: imię, nazwisko, telefon i adres. Należy go udostępniać tylko tam, gdzie faktycznie jest
potrzebny i nie naruszy to prywatności.

Log czyści się sam po liczbie dni ustawionej w konfiguracji, domyślnie po trzydziestu.