Saving a new "start order ID" in the import block moves the import cursor to X-1, so the next run imports from order X inclusive. The block also shows the current cursor. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EDD4j8Y2gTf72v7dMgSHz8
122 lines
7.2 KiB
Markdown
122 lines
7.2 KiB
Markdown
# 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ń.
|
|
|
|
## 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ń.
|