# Moduł do integracji Prestashop Moduł podłącza się do sklepu podanego w konfiguracji i dodaje zamówienia za pomocą modułu `core/orders` ## VAT rabatów Importer zachowuje kwotę brutto rabatu ze sklepu. Przy jednej stawce VAT produktów (również składowych zestawów) stosuje tę stawkę i wylicza netto z brutto. Niespójne sumy netto/brutto ze źródła nie tworzą nowej stawki VAT. Przykład: 75,35 zł brutto przy VAT 23% daje 61,26 zł netto, nawet gdy sklep przekazał 63,51 zł netto. Pozycje bezpłatne nie wyznaczają VAT rabatu. Przy kilku stawkach VAT albo brakujących danych importer zgłasza `DISCOUNT_TAX_AMBIGUOUS` przed utworzeniem zamówienia. W takim przypadku potrzebne jest potwierdzone rozbicie rabatu według stawek; importer nie wybiera pierwszej stawki ani stawki uśrednionej. ## 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_state` jako statusu docelowego; - zmiana zmapowanego statusu w Orbito tworzy wpis `order_histories` w 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_` pozostają bez zmian. Nowe pola `mapping.orbito_` 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::combination:`; 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ń.