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.

Zamówienia z bezpłatnymi produktami i darmową dostawą są importowane z cenami 0 zł. Gdy zerowe sumy zamówienia i produktów oraz rabat netto/brutto równy kosztowi dostawy potwierdzają ten przypadek, rabat ma typ delivery i VAT z carrier_tax_rate. Koszt dostawy otrzymuje tę samą stawkę. Późniejsza edycja ceny produktu, np. na 0,01 zł, nie jest pomniejszana rabatem dostawy.

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ń.

ID startowe importu

Pierwszy import ustawia kursor na najnowszym zamówieniu w sklepie i nie pobiera zamówień historycznych. W bloku „Import zamówień” widać ostatnio przetworzone zamówienie PrestaShop. Zapis nowej wartości „ID startowe zamówienia PrestaShop” przesuwa kursor tak, by następny import zaczął od tego zamówienia włącznie — do przodu lub wstecz, także na działającej instancji. Zapis tej samej wartości ani wyczyszczenie pola nie zmieniają kursora. Zamówienia już obecne w Orbito nie są duplikowane, ale cofnięcie kursora może ponownie zaimportować zamówienia usunięte w Orbito.

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_<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ń.