Moduł do integracji Prestashop
Moduł podłącza się do sklepu podanego w konfiguracji i dodaje zamówienia za pomocą
modułu core/orders
Daty zamówień i płatności
Daty PrestaShop bez oznaczenia strefy (date_add, date_upd) są odczytywane
w strefie sklepu ustawionej w „Połączenie ze sklepem → Strefa czasowa sklepu”.
Domyślnie jest to Europe/Warsaw, również dla istniejących konfiguracji bez
tego pola. Dla sklepu w innej strefie ustaw jej nazwę IANA, np. Europe/London.
Przeliczenie uwzględnia czas letni i zimowy, niezależnie od strefy serwera.
Daty zawierające już Z lub offset zachowują wskazany moment.
Poprawka dotyczy nowych importów zamówień i płatności. Nie zmienia dat już zapisanych zamówień ani istniejących płatności. Niepoprawne daty korzystają z czasu importu; powtórzona godzina przy zmianie czasu oznacza jej pierwsze wystąpienie, ponieważ data PrestaShop nie rozróżnia obu wystąpień.
Statusy zamówień
Orbito jest źródłem prawdy dla statusów zamówień. Przy ładowaniu zakładki „Mapowanie statusów” moduł pobiera aktualną listę i nazwy statusów z PrestaShop. Zapisane mapowanie jest używane wyłącznie w kierunku Orbito → PrestaShop:
- nowe zamówienie otrzymuje w Orbito status ustawiony w „Import zamówień”, bez
odczytywania
current_statejako statusu docelowego; - zmiana zmapowanego statusu w Orbito tworzy wpis
order_historiesw PrestaShop; - zmiany statusu wykonane w PrestaShop nigdy nie nadpisują statusu w Orbito;
- status niezmapowany nie jest wysyłany do sklepu;
- jeden status Orbito może wskazywać tylko jeden status PrestaShop.
Formularz ma wiersz dla każdego statusu Orbito i listę statusów PrestaShop do
wyboru. Kilka statusów Orbito może wskazywać ten sam status PrestaShop.
Lista Orbito pochodzi z kontraktu orders.status.search; brak dostawcy,
niejednoznaczny dostawca lub błąd pobierania są widoczne w formularzu.
Przed udostępnieniem formularza moduł uzupełnia nowe pola na podstawie starych
przypisań. Migracja jest addytywna: można ją wznowić po przerwaniu, a kolejne
uruchomienia nie nadpisują zapisanych wyborów ani celowo wyczyszczonych pól.
Stare klucze mapping.state_<PS ID> pozostają bez zmian. Nowe pola
mapping.orbito_<Orbito ID> mają pierwszeństwo tylko dla danego statusu Orbito;
dopóki pole nie zostało zapisane, synchronizacja odczytuje stare przypisanie.
Zapisanie pustego pola wyłącza wysyłkę, bez przywracania starego
przypisania. Odczyt obejmuje również statusy nieobecne już na listach — formularz
pokazuje ich zapisane ID. Konflikt starych przypisań nie wybiera celu automatycznie:
pokazuje wszystkie cele i wymaga wybrania jednego lub wyczyszczenia pola.
Klucz Webservice wymaga co najmniej odczytu order_states i orders oraz prawa
POST do order_histories. Synchronizacja nie używa sendemail=1, więc sama
zmiana z Orbito nie zleca PrestaShop wysłania wiadomości statusowej do klienta.
Oprócz hooka zmiany statusu integracja co minutę sprawdza maksymalnie 50
najdawniej sprawdzanych mapowań z własnej bazy. Odczytuje aktualny status przez
kontrakt orders.search i uzupełnia zgubione zdarzenia. Po przejściu partii
sprawdza kolejne zamówienia; pełny obieg może trwać kilka minut. Kontrola
okresowa obejmuje zamówienia z previousStatusId, czyli po zmianie statusu,
aby nie wysyłać do sklepu początkowego statusu importu.
Potwierdzony status, jego datę i docelowy status PrestaShop zapisuje lokalnie.
Przed POST utrwala osobny znacznik próby. Jeśli odpowiedź zginie albo kontener
zostanie przerwany, przy następnym sprawdzeniu wykonuje wyłącznie GET. Zgodny
stan sklepu potwierdza poprzednią próbę; niezgodny blokuje dalsze zapisy i
generuje ostrzeżenie previous write outcome is uncertain. Taki przypadek
wymaga ręcznej weryfikacji historii i stanu zamówienia przed wznowieniem;
integracja nie ponawia samodzielnie niepewnego POST. Błąd przed utrwaleniem
próby można sprawdzić ponownie. Pominięcia i błędy obsługi zdarzeń są logowane.
Powiązania zamówień przy synchronizacji statusów są odczytywane po unikalnym
kluczu shopConfigId + psOrderId, z weryfikacją zgodności ID Orbito. Obsługiwane
są zarówno tekstowe orbitoOrderId zapisane podczas importu przez $set, jak
i BSON ObjectId. Nie jest potrzebna migracja ani ponowny import zamówień;
zachowane pozostają potwierdzenia i niepewne próby wcześniejszych zapisów.
Każda kombinacja PrestaShop jest zapisywana w core/products jako osobny
produkt. Tożsamość źródłowa ma postać
product:<id produktu>:combination:<id kombinacji>; dla produktu bez kombinacji
identyfikator kombinacji wynosi 0. Przy kolejnym imporcie zgodny rekord ze
starszym, numerycznym sourceId jest bezpiecznie migrowany po SKU. Dane wariantu
obejmują jego referencję, EAN, lokalizację magazynową, zdjęcie i wagę produktu
powiększoną o wpływ wagi kombinacji. Cena bazowa netto katalogu jest pobierana
z ceny produktu PrestaShop powiększonej o wpływ ceny kombinacji; cena pozycji
zamówienia pozostaje niezależną ceną transakcyjną i nie nadpisuje katalogu.
Podczas importu zamówienia moduł zapisuje publiczne wiadomości klienta jako
customer_message. Obsługuje standardowe zasoby PrestaShop: messages po
id_order i id_cart, wątki customer_threads oraz ich customer_messages,
a także standardowe gift_message. Dotyczy to też DeliveryMessage / pola
delivery_message z checkoutu, które PrestaShop zapisuje w standardowym
messages po id_cart. Klucz Webservice musi mieć uprawnienie GET
do tych zasobów. Niedostępny endpoint powoduje ostrzeżenie bez logowania treści
wiadomości i nie blokuje importu zamówienia.
Wiadomości prywatne i wpisy pracowników są pomijane, a kopie tej samej treści z checkoutu i wątku klienta są deduplikowane. Moduł nie odczytuje prywatnych tabel ani niestandardowych pól checkoutów. Zmiana działa dla nowo importowanych zamówień; nie wykonuje automatycznego backfillu istniejących zamówień.