Przejdź do głównej zawartości

Zamówienia (orders)

Składanie zamówień, ich cykl życia i kontrola dostępu. Łączy wyznaczanie cen w koszyku, rezerwację stanów magazynowych, uruchomienie sterownika płatności, generowanie faktur i zapis do dziennika audytu.

API publiczne​

Trasy administracyjne są chronione przez orders:read (odczyt) i orders:write (zmiany).

Metoda i ścieżkaKtoPrzeznaczenie
POST /api/v1/ordersklientZłożenie zamówienia z aktywnego koszyka
GET /api/v1/ordersklientLista zamówień: własne albo całej organizacji z uprawnieniem orders.view_organization (zob. niżej)
GET /api/v1/orders/:idklientSzczegóły zamówienia
GET /api/v1/orders/:id/invoiceklientStarsze pobieranie faktury: uproszczony PDF pierwszej faktury zamówienia (404 INVOICE_NOT_READY, dopóki nie jest gotowa); PDF renderowany z szablonu udostępnia moduł invoices pod …/invoices/:invoiceId/pdf
GET /api/v1/admin/ordersadministratorLista wszystkich zamówień (we wszystkich organizacjach)
GET /api/v1/admin/orders/:idadministratorSzczegóły zamówienia (bez ograniczenia do klienta)
POST /api/v1/admin/orders/:id/statusadministratorZmiana statusu (audytowana)
POST /api/v1/admin/orders/:id/payment-statusadministratorZmiana statusu płatności (audytowana)

Kto widzi zamówienie współpracownika​

Kupujący widzi zamówienia, które sam złożył. Każde inne zamówienie jego organizacji — na liście, na stronie szczegółów i w każdej akcji, która czyta zamówienie jako źródło (ponowienie zamówienia, utworzenie z niego zapytania ofertowego, zgłoszenie do niego zwrotu lub reklamacji, jego faktury) — wymaga uprawnienia organizacji Wyświetlanie zamówień organizacji (orders.view_organization), które deklaruje ten moduł:

RolaCzy je ma
Administratorzawsze (domyślnie ma każde uprawnienie)
Członeknie, chyba że administrator organizacji nada je tej roli
rola własnagdy rola je nadaje

Bez tego uprawnienia zamówienie współpracownika odpowiada 404, dokładnie tak jak zamówienie innej organizacji, nigdy 403. Z nim zasięgiem jest organizacja; logowanie centrali z włączonym roll-upem obejmuje także jej poddrzewo — roll-up poszerza zasięg, ale nigdy nie nadaje uprawnienia.

Zgłoszenie zwrotu lub reklamacji do zamówienia współpracownika wymaga ponadto uprawnienia modułu returns Zgłaszanie zwrotów i reklamacji (returns.create); sprawa zostaje zgłoszona w imieniu członka, który ją rozpoczyna (zob. stronę returns).

W storefroncie lista zamówień i strona zamówienia pokazują członkowi z tym uprawnieniem zamówienie współpracownika tak samo jak jego własne. Strona zamówienia proponuje Zgłoś zwrot / reklamację (lub Złóż reklamację) tylko członkowi, którego rola ma returns.create.

Ponowne zamówienie i kopia jako zapytanie ofertowe są oceniane także według tego, co tworzą: POST /api/v1/orders/:id/reorder zastępuje aktywny koszyk i wymaga carts.create, a POST /api/v1/orders/:id/clone-to-quote tworzy zapytanie ofertowe i wymaga quote_requests.create. Uprawnienie jest sprawdzane przed odczytaniem zamówienia, więc członek, który go nie ma, otrzymuje 403 ORGANIZATION_PERMISSION_REQUIRED bez względu na to, jakie zamówienie wskazuje identyfikator, a członek, który je ma, podlega następnie opisanemu wyżej zasięgowi zamówień. Gdy moduł quote_requests jest wyłączony, jego kod niczego nie nadaje, więc kopia kupującego zostaje odrzucona tym samym 403. Strona zamówienia proponuje Zamów ponownie → koszyk i Zamów ponownie → zapytanie ofertowe tylko członkowi z odpowiednim kodem.

Który kanał sprzedaży zapisuje zamówienie​

Zamówienie zapisuje jeden kanał sprzedaży. Skąd on pochodzi, zależy od tego, kto składa zamówienie:

MiejsceKanał zamówienia
Sklep — POST /api/v1/orders, zakup jednym kliknięciemKanał rozpoznany dla żądania: X-Sales-Channel, ?salesChannel=, mapa hostów, a w ostatniej kolejności kanał domyślny
Tworzenie zamówienia w panelu — POST /api/v1/admin/ordersKanał wybrany przez operatora dla zamówienia (salesChannelId w treści żądania)
Klucz API — zewnętrzne przyjmowanie zamówieńKanał, z którym powiązany jest klucz

W sklepie opcjonalne pole salesChannelId w treści żądania nie wybiera kanału. Żądanie bez tego pola jest składane w rozpoznanym kanale; żądanie z identyfikatorem rozpoznanego kanału jest przyjmowane; żądanie wskazujące inny kanał — inny istniejący, nieistniejący albo wyłączony — jest odrzucane odpowiedzią 422 VALIDATION_FAILED z details.code = "order_sales_channel_mismatch" (szczegóły zawierają requestedSalesChannelId i resolvedSalesChannelId), zanim cokolwiek zostanie zapisane — koszyk pozostaje bez zmian.

Przy tworzeniu zamówienia w panelu pole salesChannelId w treści żądania jest wymagane i musi wskazywać jeden z aktywnych kanałów sprzedaży organizacji klienta — kanałów, do których organizacja jest przypisana i które są włączone. Każdy inny kanał — przypisany tylko do innych organizacji, wyłączony albo nieistniejący — jest odrzucany odpowiedzią 422 ORDER_SALES_CHANNEL_NOT_ALLOWED, zanim cokolwiek zostanie zapisane, także koszyk klienta i nowy adres. POST /api/v1/admin/orders/preview odpowiada tak samo, więc ekran nigdy nie pokazuje podsumowania zamówienia, którego nie da się utworzyć. Nie ma kanału zastępczego: żądanie bez salesChannelId jest odrzucane odpowiedzią 400 VALIDATION_FAILED, a nie składane w kanale domyślnym. Tę samą zasadę stosuje zapytanie ofertowe tworzone w imieniu klienta. Zamawiane produkty są sprawdzane względem asortymentu tego kanału, a nie kanału rozpoznanego dla samego żądania panelu — produkt, którego wybrany kanał nie sprzedaje, jest odrzucany odpowiedzią 404 PRODUCT_NOT_FOUND, a produkt, który sprzedaje, jest przyjmowany, nawet jeśli kanał domyślny go nie sprzedaje. Produkt spoza asortymentu wybranego kanału jest odrzucany, zanim koszyk klienta zostanie naruszony, więc koszyk pozostaje bez zmian.

Zewnętrzne API zamówień (POST /api/v1/external/orders) stosuje tę samą zasadę do kanału, z którym powiązany jest klucz API: musi on być jednym z aktywnych kanałów sprzedaży powiązanej organizacji w chwili składania zamówienia, a nie tylko w chwili wydania klucza. Klucz, którego organizacja nigdy nie została przypisana do kanału albo została od niego później odłączona, jest odrzucany odpowiedzią 422 ORDER_SALES_CHANNEL_NOT_ALLOWED, zanim cokolwiek zostanie zapisane, także koszyk konta serwisowego. Wyłączony kanał powiązany z kluczem jest odrzucany wcześniej, odpowiedzią 400 INACTIVE_SALES_CHANNEL.

Z kanału zamówienia odczytywane są:

  • przy składaniu zamówienia — minimalna wartość zamówienia (orders.min_order_value), magazyny brane pod uwagę przy rezerwacji i ustawienia realizacji kanału, prefiks i sufiks numeru zamówienia, dodatkowi odbiorcy potwierdzenia oraz identyfikator kanału przekazywany walidatorom adapterów płatności i dostawy;
  • później — dane sprzedawcy i sekwencja numerów jego faktur, język i kanał wiadomości e-mail o zamówieniu, płatności i przesyłce oraz to, czy zamówienie można ponowić (orders.reorder_enabled).

Sklep musi wskazać kanał w samym żądaniu złożenia zamówienia. Referencyjny sklep przekazuje X-Sales-Channel przy składaniu zamówienia, podglądzie sumy zamówienia, zakupie jednym kliknięciem i funkcji „zamów ponownie jako zapytanie ofertowe”. Sklep utworzony we wcześniejszym wydaniu tego nie robił; kroki opisuje strona Aktualizacja instancji.

Co nie jest powiązane z kanałem zamówienia​

  • Koszyk. Koszyk powstaje w kanale domyślnym, niezależnie od kanału, w którym kupuje klient, i trzy rzeczy są ustalane dla kanału koszyka, a nie zamówienia: czy produkt można dodać (asortyment kanału rozpoznanego dla żądania dodającego — wyjątkiem jest opisane wyżej tworzenie zamówienia w panelu), ceny pozycji oraz promocje — przy składaniu zamówienia dokładnie tak jak w koszyku. W instancji z wieloma kanałami zamówienie może więc zostać zapisane w kanale, który nie sprzedaje jednego z jego produktów, w cenach kanału domyślnego, a promocja ograniczona do kanału innego niż domyślny nie obejmuje jeszcze zamówienia złożonego w tym kanale.
  • Kupujący. Zapisanie kanału żądania nie wiąże kupującego z kanałem. X-Sales-Channel i ?salesChannel= wysyła klient, a nic nie ogranicza kanałów, w których klient lub organizacja może składać zamówienia.

Aktualizacja​

Instancja z więcej niż jednym kanałem sprzedaży. Do tej pory zamówienie ze sklepu, które nie przekazywało salesChannelId w treści żądania — czyli każde zamówienie złożone przez referencyjny sklep — było zapisywane w kanale domyślnym, niezależnie od tego, w którym kanale był kupujący. Nowe zamówienia składane w sklepie kanału innego niż domyślny są teraz zapisywane w tym kanale, więc wszystko, co wymieniono powyżej, jest odczytywane dla niego, a na liście zamówień i w raportach pojawiają się pod tym kanałem. Istniejące zamówienia nie są zmieniane.

Instancja z jednym kanałem sprzedaży. Zamówienie ze sklepu docierało do sprawdzenia minimalnej wartości zamówienia bez żadnego kanału, a ustawienie odczytywane bez kanału zwraca wartość ogólną dla platformy. Teraz dociera z identyfikatorem kanału domyślnego, więc minimalna wartość zamówienia ustawiona dla kanału domyślnego, a nie dla wszystkich kanałów, jest egzekwowana przy składaniu zamówienia, choć wcześniej nie była. Walidatory adapterów płatności i dostawy również otrzymują identyfikator tego kanału, którego wcześniej nie dostawały. Instancja, która ustawiła minimalną wartość ogólnie dla platformy albo wcale, nie zauważy zmiany.

Akceptacja koszyka przy składaniu zamówienia​

Członek, którego rola nie ma uprawnienia Składanie zamówień bez akceptacji (carts.order_without_approval, deklarowanego przez moduł koszyków), może zamówić koszyk dopiero wtedy, gdy zaakceptuje go współpracownik uprawniony do akceptowania koszyków. Zanim cokolwiek zostanie zarezerwowane lub zapisane, składanie zamówienia pyta moduł koszyków, odczytując rolę właściciela koszyka w tej chwili, i odrzuca taki koszyk, który nie jest approved, z kodem 409 ORDER_CART_APPROVAL_REQUIRED; details zawiera cartId, approvalStatus oraz code nazywający stan:

details.codeKoszykKomunikat (po polsku)
cart_approval_not_submittednigdy nieprzekazany do akceptacji„Twoja rola wymaga akceptacji tego koszyka przed zamówieniem. Najpierw wyślij go do akceptacji.”
cart_approval_pendingczeka na osobę akceptującą„Ten koszyk czeka na akceptację osoby zatwierdzającej w Twojej organizacji. Zamówienie złożysz, gdy koszyk zostanie zaakceptowany.”
cart_approval_rejectedodrzucony„Ten koszyk został odrzucony przez osobę zatwierdzającą w Twojej organizacji, więc nie można go zamówić.”

Koszyk pozostaje bez zmian. Reguła nie dotyczy koszyka żadnego członka, którego rola ma uprawnienie Składanie zamówień bez akceptacji (Administrator ma je zawsze), ani zamówień składanych z koszyka roboczego — tworzenia zamówienia w panelu administracyjnym, zakupu jednym kliknięciem i zewnętrznego API zamówień — które nie składają koszyka członka.

Listy dozwolonych metod przy składaniu zamówienia​

Organizację można ograniczyć do wybranych metod dostawy i płatności (zob. moduł organizations, Ograniczenia handlowe organizacji). Złożenie zamówienia i oba podglądy odrzucają metodę spoza niepustej listy odpowiedzią 400 ORDER_DELIVERY_METHOD_UNAVAILABLE (metoda dostawy) albo 400 ORDER_PAYMENT_METHOD_UNAVAILABLE (metoda płatności), a error.details.code podaje powód:

error.details.codeZawiera teżZnaczenie
delivery_method_not_allowed_for_organizationdeliveryMethodIdLista dozwolonych metod dostawy organizacji nie zawiera wybranej metody
payment_method_not_allowed_for_organizationpaymentMethodIdLista dozwolonych metod płatności organizacji nie zawiera wybranej metody
  • Gdzie — POST /api/v1/orders, POST /api/v1/orders/preview-total, POST /api/v1/admin/orders, POST /api/v1/admin/orders/preview, POST /api/v1/external/orders oraz każde inne wywołanie orderPlacementPort.placeOrder. Zakup jednym kliknięciem nie dochodzi do tej odmowy: gdy lista wyklucza metodę domyślną, kupujący nie może z niego skorzystać (one_click_unavailable, powód missing_defaults).
  • Która organizacja — ta, dla której składane jest zamówienie: organizacja zalogowanego kupującego, organizacja powiązana z kluczem API albo organizacja klienta, gdy zamówienie tworzy administrator. Żądanie nie może wskazać innej.
  • Pusta lista nie ogranicza — pusta lista albo jej brak dopuszcza każdą aktywną metodę, a obie listy są niezależne.
  • Nic nie jest zapisywane — nie powstaje zamówienie, rezerwacja stanu ani płatność, a koszyk klienta pozostaje bez zmian. Tworzenie zamówienia przez administratora i przyjęcie zamówienia kluczem API sprawdzają listy, zanim zapiszą pozycje zamówienia.
  • Administratorów też to obowiązuje — tak zostało postanowione: zamówienie utworzone w imieniu klienta podlega listom dozwolonych metod organizacji tego klienta i żadne ustawienie tego nie wyłącza. Formularz tworzenia pokazuje wszystkie metody; dla metody, na którą organizacja nie pozwala, podgląd i utworzenie zamówienia zwracają powyższą odmowę.
  • Gdy obie metody są spoza list, odmowa dotyczy metody dostawy.
  • Gdy list nie da się odczytać, żądanie kończy się odpowiedzią 500 INTERNAL i zamówienie nie powstaje — tak samo odpowiadają obie listy metod.

Metody a kanał sprzedaży zamówienia​

Metodę dostawy lub płatności można także ograniczyć do kanałów sprzedaży (zobacz moduły delivery_methods i payment_methods, Kanały sprzedaży). Składanie zamówienia i oba podglądy odrzucają metodę, która nie jest dostępna w kanale zamówienia, odpowiedzią 400 ORDER_DELIVERY_METHOD_UNAVAILABLE albo 400 ORDER_PAYMENT_METHOD_UNAVAILABLE, jak wyżej:

error.details.codeZawiera teżZnaczenie
delivery_method_not_in_sales_channeldeliveryMethodId, salesChannelIdMetoda dostawy jest ograniczona do kanałów sprzedaży, a kanału zamówienia wśród nich nie ma
payment_method_not_in_sales_channelpaymentMethodId, salesChannelIdMetoda płatności jest ograniczona do kanałów sprzedaży, a kanału zamówienia wśród nich nie ma
  • Gdzie — te same trasy co dla list dozwolonych metod powyżej. Zakup jednym kliknięciem również tutaj nie dociera do odmowy: domyślna metoda, której kanał żądania nie udostępnia, sprawia, że kupujący nie kwalifikuje się do zakupu (one_click_unavailable, powód missing_defaults).
  • Który kanał — ten, który zapisuje zamówienie; zobacz Który kanał sprzedaży zapisuje zamówienie powyżej.
  • Brak przypisania oznacza każdy kanał — metoda nieprzypisana do żadnego kanału sprzedaży jest dostępna we wszystkich.
  • Nic nie jest zapisywane — tak jak przy listach dozwolonych metod, a tworzenie zamówienia w panelu i przyjmowanie zamówień kluczem API sprawdzają to, zanim zapiszą pozycje zamówienia.

Metoda, która nie przechodzi obu sprawdzeń​

Obie odmowy są niezależne, a na każdej trasie listy dozwolonych metod organizacji są sprawdzane przed kanałem zamówienia. Dlatego metoda, która jest jednocześnie poza listą dozwolonych metod organizacji i niedostępna w kanale zamówienia, jest odrzucana z kodem listy (…_not_allowed_for_organization); kod kanału (…_not_in_sales_channel) zwraca metoda, której organizacja może używać — albo która nie ma listy — a kanał jej nie udostępnia.

To, gdzie między tymi dwoma sprawdzeniami wypada „metoda jest aktywna” i walidator adaptera, zależy od trasy:

  • Składanie zamówienia w sklepie i zakup jednym kliknięciem (placeOrder) — listy, potem aktywność metody, potem walidator jej adaptera, potem kanał.
  • Podgląd w sklepie — listy, potem aktywność metody, potem kanał; walidator adaptera nie jest uruchamiany dla podglądu.
  • Tworzenie zamówienia w panelu i przyjmowanie zamówień kluczem API — listy i kanał są sprawdzane najpierw, zanim koszyk klienta zostanie zmieniony; zamówienie przechodzi następnie przez placeOrder, które powtarza je wokół sprawdzenia aktywności i adaptera. Nieaktywna metoda, która jest też niedostępna w kanale, zwraca więc na tych dwóch trasach kod kanału, a w sklepie — „metoda nieaktywna”.
  • Podgląd w panelu — listy, potem kanał; podgląd nie odrzuca nieaktywnej metody.

Statusy i przejścia (konfigurowalne)​

Cykl życia zamówienia konfiguruje się w panelu administracyjnym: statusy i dozwolone przejścia są zapisane w tabelach order_statuses i order_status_transitions, wypełnianych przy instalacji dziewięcioma domyślnymi statusami — new (początkowy, nie da się go usunąć), pending, paid, processing, shipment_ready, shipment_sent, completed (końcowy), on_hold, cancelled (końcowy) — wraz z predefiniowanymi przejściami oraz przejściami dostępnymi z każdego statusu → on_hold / → cancelled (i on_hold → any). Administratorzy zarządzają nimi przez endpointy /api/v1/admin/orders/statuses i /transitions; graf jest przechowywany w pamięci procesu i sprawdzany ponownie przy każdej zmianie.

Zmiana, której nie pozwala stan grafu, ma własny kod i zdanie po angielsku i po polsku, czytane w języku operatora. Do zgłoszenia #627 były to odpowiedzi VALIDATION_FAILED; status się nie zmienił. Kod statusu trafia do details.statusCode, bo details.code jest miejscem na token odmowy.

KodStatusKiedydetails
ORDER_STATUS_CODE_TAKEN409POST …/statuses — inny status ma już ten kodstatusCode
ORDER_STATUS_TERMINAL_HAS_TRANSITIONS409 / 422PATCH …/statuses/:code oznaczający status z przejściami wychodzącymi jako końcowy (code mark_terminal) albo PUT …/transitions dodający przejście ze statusu końcowego (code add_transition)statusCode oraz outgoingCount albo toStatusCode
ORDER_STATUS_NOT_DELETABLE409DELETE …/statuses/:code statusu początkowego (code initial) albo systemowego (code system)statusCode
ORDER_STATUS_IN_USE409DELETE …/statuses/:code, gdy są w nim zamówieniastatusCode, orderCount

Przejście wskazujące nieistniejący status nadal daje VALIDATION_FAILED.

OrderTransitionService.apply() to jedyne miejsce, które rozstrzyga o przejściach: odrzuca przejście, dla którego nie skonfigurowano krawędzi, albo przejście ze statusu końcowego, uruchamia zabezpieczenia wstępne z możliwością zablokowania (onOrderTransitionGuard), a następnie emituje zdarzenia według szablonu (niżej). Zdarzenia płatności i wysyłki wywołują automatyczne przejścia przez OrderStatusRegistry (kolumny statusOn* odwołują się do tych kodów statusów); payment_status pozostaje polem pochodnym, drugorzędnym.

Co wynika z przejścia: działania następcze​

Anulowanie zamówienia zwalnia to, co zamówienie trzymało: jego rezerwacje stanów magazynowych oraz — w przypadku zamówienia złożonego w ramach limitu kredytowego — jego rezerwację limitu. Oznaczenie takiego zamówienia jako opłaconego zwalnia rezerwację limitu. Te zwolnienia to działania następcze przejścia.

Działanie następcze jest zapisywane w tej samej transakcji co status, jako wiersz w tabeli order_transition_effects, i wykonywane zaraz potem, w tym samym żądaniu. W zwykłym przypadku stan magazynowy i limit są więc zwolnione, zanim wywołujący dostanie odpowiedź. Zmieniło się to, co dzieje się, gdy zwolnienia nie da się dokończyć:

  • Przejście i tak jest wykonane, a wywołujący dostaje taką odpowiedź. Każda odmowa — nieznany status, brak skonfigurowanej krawędzi, status końcowy, blokada zabezpieczenia wstępnego — zapada, zanim cokolwiek zostanie zapisane. Po zatwierdzeniu statusu nic nie zamieni odpowiedzi w błąd.
  • Zwolnienie jest ponawiane aż do skutku. Zadanie w tle uruchamia się co minutę i próbuje wykonać każde zaległe działanie, na które przyszła pora, wydłużając odstęp między próbami od jednej minuty do jednej godziny. Nie ma stanu „porzucone”; od piątego niepowodzenia każde kolejne jest zapisywane w logu na poziomie warn wraz z identyfikatorem zamówienia, rodzajem zwolnienia i ostatnim błędem.
  • Nawet odpowiedź nie zamieni tego w błąd. Jeśli po zatwierdzeniu nie uda się odczytać zamówienia na potrzeby treści odpowiedzi, POST /api/v1/admin/orders/:id/status, POST /api/v1/admin/orders/:id/payment-status i POST /api/v1/orders/:id/cancel odpowiadają 200 z { data: { id, businessId, status, paymentStatus }, meta: { partial: true } } (orderCommittedWritePartialResponseSchema w @endora-commerce/contracts). Sprawdź meta.partial, zanim potraktujesz data jako całe zamówienie, i odczytaj zamówienie ponownie, jeśli potrzebna jest reszta.
  • Działania następcze są od siebie niezależne. Nieudane zwolnienie limitu nie wstrzymuje zwolnienia stanu magazynowego — i odwrotnie.
  • Zdarzenia zmiany statusu są emitowane zawsze po zatwierdzeniu, bez względu na to, co stało się ze zwolnieniami.

Powtórzenie przejścia do statusu, który zamówienie już ma, niczego nie zmienia — i jest to bezpieczne: to, co wynika ze statusu, jest zapisane obok niego i zostanie wykonane.

Gdy moduł inventory lub credit_limits jest wyłączony​

Działanie następcze, którego moduł-właściciel jest wyłączony, czeka. Dopóki moduł jest wyłączony, nic w jego danych nie jest zapisywane, oczekiwanie nie liczy się jako nieudana próba, a zwolnienie następuje w ciągu jednego przebiegu zadania w tle (minuty) od ponownego włączenia modułu.

  • Przy wyłączonym inventory anulowane zamówienie zachowuje swoje rezerwacje do czasu powrotu modułu.
  • Przy wyłączonym credit_limits zamówienie złożone w ramach limitu nadal można anulować albo oznaczyć jako opłacone; jego rezerwacja zostanie zwolniona po powrocie modułu. Złożenie nowego zamówienia w ramach limitu kredytowego jest przy wyłączonym module nadal odrzucane.

Na stronie zamówienia​

Strona zamówienia w panelu administracyjnym pokazuje komunikat, dopóki zamówienie ma zaległe działania następcze: które zwolnienie, czy czeka na moduł i ile prób się nie powiodło. Odpowiedź administracyjna z zamówieniem zawiera te same informacje w polu pendingEffects — obecnym tylko wtedy, gdy coś jest zaległe, i nigdy w odpowiedziach przeznaczonych dla kupującego.

Naprawa zamówień pozostawionych przez wcześniejszą wersję​

Zanim działania następcze zaczęły być zapisywane, zwolnienie, które się nie powiodło albo zostało odrzucone, mogło zostawić zamówienie anulowane (albo opłacone), a mimo to nadal trzymające stan magazynowy lub limit — i nic nie mogło go już potem zwolnić. Takie zamówienia nie mają wiersza działania następczego. Znajduje je i naprawia polecenie dla operatora. Uruchom je w katalogu głównym instancji:

# Wypisuje, co zostałoby zwolnione. Niczego nie zapisuje.
pnpm run cli orders transition-effects-repair

# Zwalnia.
pnpm run cli orders transition-effects-repair --apply

W klonie repozytorium Endora Commerce to samo polecenie ma postać pnpm --filter backend run cli orders transition-effects-repair, z tymi samymi opcjami. W instancji ta postać nie robi nic: członek backendu nazywa się tam inaczej, więc pnpm wypisuje No projects matched the filters i kończy się kodem 0, nie uruchamiając polecenia.

Przebieg próbny wypisuje każde zamówienie, które nadal trzyma rezerwacje stanów magazynowych lub aktywną rezerwację limitu, choć powinno było je zwolnić — wraz z tym, co trzyma. --apply zapisuje zwolnienia tym samym mechanizmem działań następczych, od razu próbuje je wykonać i tworzy jeden wpis audytu na stronę zamówień; to, czego nie uda się dokończyć, ponawia zadanie w tle. Ponowne uruchomienie niczego już nie znajduje.

Po aktualizacji uruchom raz przebieg próbny i przeczytaj listę, zanim ją zastosujesz: zwolnienie zmienia liczniki zarezerwowanego stanu i dostępny limit. Naprawa nigdy nie uruchamia się sama.

Czego przebieg próbny nie pokaże. Wypisuje to, co według własnych wierszy zamówienia zamówienie trzyma. Jeśli ktoś już ręcznie poprawił licznik stanu dla któregoś z tych zamówień, zamówienie nadal jest na liście — jego rezerwacja nie jest oznaczona jako zwolniona — a zastosowanie naprawy obniży licznik po raz drugi, więc zarezerwowane będzie mniej, niż faktycznie trzymają aktywne zamówienia (licznik nigdy nie spada poniżej zera, co ukrywa błąd, zamiast mu zapobiec). Takie zamówienie pomiń albo napraw tylko wskazane zamówienia; obie opcje przyjmują identyfikator zamówienia wypisany na liście w nawiasie i można je powtarzać:

pnpm run cli orders transition-effects-repair --apply --except=<identyfikator zamówienia>
pnpm run cli orders transition-effects-repair --apply --order=<identyfikator zamówienia>

Jeśli inventory lub credit_limits jest wyłączony, polecenie nie może zapytać tego modułu, co trzymają zamówienia. Informuje o tym, naprawia resztę i należy je uruchomić ponownie po włączeniu modułu.

Encje​

Order, OrderItem, Payment, OrderStatus, OrderStatusTransition, OrderTransitionEffect, OrderComment, OrderListSavedView, OrderItemGroup (grupy pozycji zamówienia — zob. Grupy pozycji), OrderExternalReference (zob. Numery z systemów zewnętrznych) oraz kolumna organizations.order_confirmation_emails (właściciel: organizations, odczyt przez port). OrderItem zapisuje kopię produktu, wariantu, ceny jednostkowej i stawki podatku z chwili złożenia zamówienia, aby historyczne zamówienia nie zmieniały się po zmianach cen i katalogu. Kopiuje też price_source pozycji koszyka — agreed, base, catalogue, buyer albo sale, czyli krok wyceny w cennikach (albo uzgodnienie z oferty), który ustalił cenę — do order_items.price_source; kolumna jest przechowywana na potrzeby raportowania i przyszłej reguły promocji i nie wchodzi do odpowiedzi API zamówień.

Emitowane zdarzenia​

order.created.v1, order.status_changed.v1, order.cancelled.v1. Anulowanie jest ogłaszane jako order.status_changed.v1 z nowym statusem, a po nim jako order.cancelled.v1 — z orderId, organizationId, salesChannelId, statusem, z którego zamówienie anulowano (from), actor, reason i businessId — gdy zapis anulujący zostanie zatwierdzony, niezależnie od ścieżki, która anulowała zamówienie. order.cancelled.v1 pozostaje wewnątrz szyny zdarzeń: webhooki wychodzące dostarczają anulowanie jako order.status_changed.v1. Każde przejście X→Y emituje dodatkowo cztery zdarzenia według szablonu (budowane przez events/order-status-events.ts): order.status.from_<x>_to_<y>.before, order.status.from_<x>.before (synchroniczne, z możliwością zablokowania) oraz order.status.from_<x>_to_<y>.after, order.status.to_<y>.after (po zatwierdzeniu, odizolowane).

order.created.v1 niesie orderId i organizationId. Dla zamówienia, które administrator utworzył z polem origin (zob. Tworzenie w imieniu klienta niżej), niesie także to origin, bez zmian; dla każdego innego zamówienia tego klucza nie ma. Wartość trafia wszędzie tam, dokąd zdarzenie — webhook wychodzący subskrybujący order.created.v1 dostaje ją w treści.

order.created.v1 jest emitowane po zatwierdzeniu transakcji składającej zamówienie, na każdej ścieżce składania: subskrybent może odczytać zamówienie, które zdarzenie wskazuje, a nieudane złożenie zamówienia niczego nie ogłasza.

Operacje w panelu administracyjnym​

  • Tworzenie w imieniu klienta — POST /api/v1/admin/orders buduje koszyk klienta z pozycji wprowadzonych przez administratora i uruchamia placeOrder w imieniu klienta; klient dostaje e-mail z prośbą o opłacenie. Żądanie może nieść opcjonalne origin: { type, id }, mówiące, skąd zamówienie jest tworzone — type to identyfikator nadawcy pisany małymi literami (litery, cyfry, podkreślenia), id to UUID. Moduł sprawdza tylko kształt i przekazuje wartość dalej, nie czytając jej, w zdarzeniu order.created.v1: nie jest zapisywana, nie jest zwracana i niczego w zamówieniu nie zmienia. Moduł, który rozpoznaje type, może na nią zareagować — moduł CRM wiąże takie zamówienie z szansą, z której je utworzono. Przyjmuje je tylko to żądanie; zamówienie składane w sklepie nie może go ustawić. Ekran tworzenia (/orders/new) czyta to samo z adresu, gdy otwiera go inny ekran — originType, originId, do tego organizationId, customerAccountId i salesChannelId do wstępnego wyboru oraz returnTo, czyli ścieżkę w Admin UI, do której wraca się po utworzeniu zamówienia.
  • Lista — GET /api/v1/admin/orders filtruje, sortuje i wyszukuje po stronie serwera, z licznikami dla każdego statusu. Wyszukiwanie (q) dopasowuje numer zamówienia, nazwę Organizacji, klienta oraz numer nadany zamówieniu przez system zewnętrzny (zob. Numery z systemów zewnętrznych); GET …/export zwraca CSV strumieniowo; zapisane widoki przez …/list-views — zob. Zapisane widoki niżej.
  • Operacje masowe — POST …/bulk/status (zamówienia, które się kwalifikują, zmieniają status; pominięte są zgłaszane z powodem — pominięte zamówienie nie zmieniło statusu) oraz …/bulk/print-invoices.
  • Komentarze — …/:id/comments dla administratora i klienta, z flagą widoczności dla klienta i powiadomieniem; zablokowane w zamówieniach o statusie końcowym (409 ORDER_COMMENTS_CLOSED). Platforma zapisuje tu też wewnętrzne notatki systemowe o wartościach pól niestandardowych, których nie przeniesiono do zamówienia — zob. Notatka systemowa niżej.
  • Ponowne zamówienie — …/:id/reorder odtwarza koszyk (zależnie od ustawienia orders.reorder_enabled); kopia jako zapytanie ofertowe — …/:id/clone-to-quote (zamówienie bez pozycji daje 409 ORDER_CLONE_NO_LINES; bez modułu quote_requests kopia kupującego jest odrzucana z 403 ORGANIZATION_PERMISSION_REQUIRED, a kopia operatora z 503 MODULE_DISABLED).

Ekran tworzenia zamówienia​

Kanał sprzedaży wybiera się spośród aktywnych kanałów sprzedaży organizacji klienta. Pole Kanał sprzedaży niczego nie proponuje, dopóki nie wybrano klienta; potem proponuje dokładnie te kanały, które przyjmuje serwer — nigdy innego aktywnego kanału ani wyłączonego kanału, do którego organizacja jest przypisana. Jedyny kanał jest wybierany od razu; przy kilku wybiera operator. salesChannelId w adresie jest wybierany tylko wtedy, gdy należy do tych kanałów, a w przeciwnym razie jest pomijany. Wybranie klienta innej organizacji czyści wybór. Gdy organizacja nie ma aktywnego kanału sprzedaży, ekran to mówi, a przycisk Utwórz zamówienie pozostaje nieaktywny, dopóki nie zostanie ona przypisana do takiego kanału; gdy nie da się wczytać jej kanałów, ekran to mówi i pokazuje przycisk Ponów, a niczego nie można wysłać.

Sekcje Pozycje i podsumowanie zamówienia pojawiają się dopiero po wybraniu klienta i kanału sprzedaży. To dwie dane, których potrzebuje wycena; metoda płatności, metoda dostawy i adresy niczego nie blokują. Dopóki obie nie są ustawione, jedna podpowiedź mówi, czego jeszcze brakuje. Wyczyszczenie któregoś z tych pól znowu ukrywa obie sekcje, ale nie usuwa pozycji — wracają, gdy pole zostanie ponownie ustawione. Ekran otwarty z customerAccountId i salesChannelId w adresie pokazuje sekcję Pozycje, gdy tylko kanały organizacji zostaną wczytane, a wskazany kanał jest wśród nich.

Produkty dodaje się na dwa sposoby.

  • Przeglądaj produkty otwiera wspólną przeglądarkę produktów panelu administracyjnego na zakładce Aktywne: katalog podzielony na strony, z zakładkami statusów i ich licznikami, filtrem typu i wyszukiwaniem po SKU, slugu lub nazwie. Zaznaczenie przetrwa zmianę strony, rozmiaru strony i filtrów, a Dodaj N dodaje każdy zaznaczony produkt jako pozycję o ilości 1 — najwyżej 200 naraz. Produkty nadrzędne typu grouped i bundle oraz produkty robocze i nieaktywne są widoczne z powodem i nie da się ich zaznaczyć. Produkt, który już jest w zamówieniu, można dodać ponownie: staje się osobną pozycją (na przykład w innej grupie).
  • Szybkie dodawanie po nazwie lub SKU, obok, dopisuje jeden produkt według tych samych zasad.

Bez uprawnienia catalog:read obie te opcje są nieaktywne i każda pokazuje podpowiedź.

Każda pozycja pokazuje nazwę i SKU produktu, edytowalną ilość, cenę jednostkową, wartość pozycji i akcję usunięcia. Zmiana ilości, klienta, kanału sprzedaży, metody dostawy albo metody płatności ponownie wycenia pozycje przez POST /api/v1/admin/orders/preview (orders:write). Ilość, która nie jest liczbą całkowitą równą 1 lub większą, oznacza pozycję, wyłącza ją z wyceny i blokuje Utwórz zamówienie.

Pozycja, której nie da się wycenić, pokazuje przyczynę i blokuje Utwórz zamówienie, dopóki jej nie usuniesz albo nie usuniesz przyczyny. Każda niedostępna pozycja ma dokładnie jeden kod — pierwszy pasujący, w tej kolejności — i pokazuje jeden powód:

Kod wycenyPowód przy pozycjiCo zmienić
PRODUCT_NOT_FOUNDBrak cenyProduktu nie ma już w katalogu: usuń pozycję.
PRODUCT_ARCHIVEDProdukt zarchiwizowanyProdukt jest zarchiwizowany: przywróć go w katalogu albo usuń pozycję.
PRODUCT_NOT_VISIBLE_TO_CUSTOMERKlient nie widzi tego produktuWidoczność produktu albo jego lista dozwolonych organizacji wyklucza organizację klienta: zmień je przy produkcie w katalogu, wybierz innego klienta albo usuń pozycję.
PRODUCT_NOT_IN_SALES_CHANNELPoza asortymentem tego kanału sprzedażyWybierz kanał sprzedaży, którego asortyment zawiera produkt, dodaj produkt do asortymentu tego kanału albo usuń pozycję.
QUOTE_ONLYBrak cenyCena produktu dla tego klienta jest dostępna tylko w ofercie: usuń pozycję albo utwórz zapytanie ofertowe.
UNPRICEDBrak cenyŻaden cennik nie wycenia produktu dla tego klienta, kanału i waluty — nie ma nawet ceny bazowej: ustaw cenę bazową, usuń pozycję albo utwórz zapytanie ofertowe.
BELOW_MINIMUM_QUANTITYPoniżej minimum N szt.Łączna ilość produktu w zamówieniu jest poniżej jego minimalnej ilości zamówienia: zwiększ ilość albo usuń pozycję.

BELOW_MINIMUM_QUANTITY niesie minimum i jest oceniany tylko na pozycjach, które przeszły sprawdzenia powyżej, z sumowaniem pozycji każdego produktu. Pozycje są wyceniane z cenników dokładnie tak, jak wyceniłby je koszyk klienta — jednym zbiorczym wywołaniem dla wszystkich pozycji, przy ilości i wariancie każdej z nich — więc utworzone zamówienie ma ceny pokazane w podglądzie. Kod, którego ekran nie zna, też jest pokazywany jako Brak ceny. Pozostałe pozycje zachowują ceny, a podsumowanie liczy tylko wycenione. Wycena sprawdza asortyment dokładnie tego kanału sprzedaży, który wskazuje żądanie; salesChannelId, który nie wskazuje żadnego kanału, jest odrzucany z 404 NOT_FOUND, a ekran pokazuje Nie udało się przeliczyć cen, nie oznaczając żadnej pozycji. Produkt usunięty miękko ma kod PRODUCT_NOT_FOUND, tak jak odpowiada utworzenie zamówienia (404 PRODUCT_NOT_FOUND). Produkt zarchiwizowany ma kod PRODUCT_ARCHIVED niezależnie od tego, kto może go widzieć i jaki kanał wybrano, a utworzenie zamówienia odrzuca go z 409 PRODUCT_ARCHIVED (Produkt jest zarchiwizowany.), wskazując zarchiwizowane produkty w details.productIds i niczego nie zapisując — z tym samym powodem, który podaje zapytanie ofertowe operatora. Utworzone zamówienie zawiera dokładnie pozycje i ilości widoczne na ekranie, w treści żądania POST /api/v1/admin/orders.

Najwyżej 200 pozycji. POST /api/v1/admin/orders i POST /api/v1/admin/orders/preview w pierwszym kroku odrzucają więcej niż 200 pozycji, z kodem 422 VALIDATION_FAILED i details: { code: 'too_many_items', maximum: 200 }, zanim oceniona zostanie którakolwiek pozycja. Tworzenie zamówienia odrzuca też żądanie, w którym łączna ilość produktu jest poniżej jego minimum, z błędem minimum i details.lines[] kluczowanym index pozycji.

Grupy pozycji. Pozycje na ekranie można podzielić na nazwane grupy — Dodaj grupę, zmiana nazwy, usunięcie, przeciąganie, klawiatura i menu Przenieś do grupy przy każdej pozycji, dokładnie tak jak w zakładce Modyfikacja zapytania ofertowego; Dodaj produkt danej grupy dodaje do tej grupy, każde inne dodanie — do sekcji Bez grupy. Każda grupa pokazuje liczbę pozycji oraz wartość netto, VAT i brutto obok bieżącego podsumowania cen; w tym celu wycena zwraca dla każdej wycenionej pozycji taxRate (ułamek, 0.23, z tego samego źródła co suma podatku w podsumowaniu; brak go przy pozycji, której nie da się wycenić), a VAT grupy to suma netto × stawka po jej pozycjach. Przeniesienie pozycji między grupami nie wycenia zamówienia ponownie. Każda grupa musi mieć nazwę, zanim przycisk Utwórz zamówienie stanie się aktywny. Co zamówienie zachowuje, opisuje sekcja Grupy pozycji niżej.

Podziel pozycję. Pozycja o ilości 2 lub większej ma obok Przenieś do grupy przycisk Podziel pozycję. Pyta on o ilość do przeniesienia na nową pozycję (od 1 do ilości pozycji minus 1) i o grupę nowej pozycji — domyślnie tę samą — po czym dodaje pozycję tego samego produktu z tą ilością, zmniejszając pierwotną. Tak jeden produkt trafia do dwóch grup: na przykład 5 sztuk do Hali A i 3 do Hali B. Każda pozycja jest wyceniana według własnej ilości.

Pola niestandardowe. Przy uprawnieniu custom_fields:read ekran pokazuje pola niestandardowe zamówienia, a ich wartości są wysyłane jako customFieldValues. POST /api/v1/admin/orders sprawdza je według reguł administratora, zanim zapisze koszyk roboczy lub jakikolwiek adres, i wymaga każdego pola zamówienia oznaczonego jako required, także gdy żądanie nie wysyła żadnych wartości; odmowa to 422 CUSTOM_FIELD_VALUE_INVALID (wpisy details { path, issue }), pokazywana przy wskazanym polu, a zamówienie nie powstaje. Wartości są zapisywane razem z zamówieniem, ponad wartościami przeniesionymi z zapytania ofertowego, a wpis audytu order.place_on_behalf podaje ich klucze (changedCustomFields), nigdy wartości.

Wartości pól niestandardowych przeniesione do zamówienia​

Zamówienie może otrzymać wartości pól niestandardowych z rekordu, z którego powstało — dla każdego pola z włączoną opcją Przenoś wartość do: Zamówienie (ustawianą na ekranie Pola niestandardowe; reguły — ten sam klucz, zgodny typ i opcje, zasada widoczności — opisuje strona tamtego modułu). Wypełniane jest tylko puste pole zamówienia i tylko raz.

  • Z zapytania ofertowego, przy składaniu zamówienia. Gdy klient składa zamówienie z koszyka wypełnionego zamówieniem zaakceptowanego zapytania ofertowego, a zamówienie zapisuje to zapytanie (decydują te same reguły co dotąd: zapytanie nadal zatwierdzone, niewykorzystane przez inne zamówienie, z organizacji klienta, co najmniej jedna uzgodniona pozycja nadal w koszyku), wartości zapytania — w stanie z tej chwili — są zapisywane razem z samym zamówieniem. Są częścią jego utworzenia, a nie późniejszą edycją. Nic nie jest przenoszone, gdy zamówienie nie zapisuje zapytania ofertowego albo gdy moduł zapytań ofertowych jest wyłączony.
  • Z szansy sprzedażowej. Zamówienie, które administrator tworzy z szansy sprzedażowej (Utwórz zamówienie na jej karcie Powiązania), otrzymuje wartości szansy, gdy moduł CRM powiąże je z tą szansą — w osobnej zmianie przypisanej systemowi; utworzenie zamówienia pozostaje przypisane administratorowi. Zamówienie powiązane z szansą ręcznie nie otrzymuje niczego.
  • Nie w drugą stronę. Kopia jako zapytanie ofertowe nie przenosi żadnej wartości.
  • Nic nie kończy się błędem. Wartość, której nie da się przenieść, jest pomijana, a zamówienie i tak zostaje złożone lub powiązane.

Przy zamówieniu złożonym w imieniu klienta wpis audytu order.place_on_behalf wymienia przeniesione klucze jako carriedCustomFieldKeys. Zamówienie złożone przez samego klienta, jak dotąd, nie tworzy wpisu audytu. Przeniesione wartości są w zamówieniu od początku, więc odczytują je subskrybenci order.created.v1.

Co zawiera dziennik audytu. Dziennik audytu platformy czyta każdy, kto ma audit_log:read, bez względu na to, które organizacje widzi, dlatego wpisy zamówienia zawierają nazwy i strukturę, nigdy jego wartości. Zmiana pól niestandardowych (order.custom_fields.update) i przeniesienie z szansy sprzedażowej (order.custom_fields.carry) wymieniają zmienione klucze jako changedCustomFields, bez ich wartości. Ani order.place_on_behalf, ani order.place_via_api_key nie zapisują sumy zamówienia, waluty, organizacji ani klienta. Wartości przechowuje samo zamówienie.

Notatka systemowa​

Gdy wartość zostanie pominięta, karta Komentarze zamówienia zawiera jedną notatkę autorstwa System dla danego złożenia lub powiązania, oznaczoną jako Wewnętrzny: Nie przeniesiono z zapytania ofertowego …: lub Nie przeniesiono z szansy sprzedażowej …:, a pod spodem po jednej linii na każde pominięte pole — nazwa pola, z którego pochodzi, z chwili pominięcia, i powód (zamówienie nie ma pola o tym kluczu, pole ma inny typ, pole widoczne dla klientów miałoby dostać wartość pola wewnętrznego, wartość nie pasuje do pola). Może ją przeczytać każdy, kto może otworzyć zamówienie; nie pokazuje żadnej wartości.

Notatka nigdy nie jest pokazywana klientowi — ani w sklepie, ani w endpoincie komentarzy klienta — i nie wysyła powiadomień. Nie ma autora: systemNote w odpowiedzi z komentarzami dla administratora (GET /api/v1/admin/orders/:id/comments) zawiera jej strukturę — kind (custom_field_carry_skipped), source (entityType, recordId, reference) i skipped (key, reason, label) — a body zawiera angielskie zdanie dla odbiorcy, który go nie tłumaczy. Każdy inny komentarz zwraca systemNote: null.

Filtry pól niestandardowych​

Pole niestandardowe zamówienia z włączoną opcją Używaj jako filtra listy (ustawianą na ekranie Pola niestandardowe) jest dostępne jako filtr wśród filtrów zaawansowanych listy zamówień, opisany w twoim języku: tekst, który zawiera, zakres liczb lub dat, tak lub nie albo jedna lub więcej opcji. Zamówienie bez wartości tego pola nigdy nie pasuje. Każdy filtr pola niestandardowego jest pokazany jako usuwalna etykieta obok pozostałych aktywnych filtrów, zawęża sumę i każdą stronę, a jego zmiana wraca do pierwszej strony listy. Filtry są w adresie strony, więc przefiltrowaną listę można dodać do zakładek lub udostępnić, a eksport CSV eksportuje te same zamówienia.

Jeśli adres zawiera filtr, który nie jest już dostępny — jego opcję wyłączono albo pole usunięto — lista mówi o tym, podając nazwę pola, i oferuje Usuń ten filtr; eksport CSV nie jest dostępny, dopóki filtr nie zostanie usunięty. Wywołujący API przesyłają filtry jako customFieldFilters w GET /api/v1/admin/orders i GET /api/v1/admin/orders/export, a dostępne pola odczytują z GET /api/v1/admin/orders/custom-field-filters (orders:read). Odwrócony zakres (min większe niż max, from późniejsze niż to) lub operator niepasujący do typu pola daje 400 VALIDATION_FAILED.

Zapisane widoki​

Zapisany widok to nazwany zestaw filtrów listy zamówień, który administrator może ponownie zastosować jednym wyborem.

Korzystanie z zapisanych widoków​

Na pasku narzędzi listy zamówień jest lista wyboru Zapisane widoki, której pierwsza pozycja to — Wybierz widok —, a obok niej dwa przyciski: Zapisz widok i Usuń widok.

  • Co zapamiętuje widok. Wszystkie filtry listy zamówień — status, status płatności, kanał sprzedaży, metodę płatności, metodę dostawy, zakres dat, wyszukiwany tekst, nazwy organizacji i klienta, zakres kwoty oraz filtry pól niestandardowych — a także sortowanie i widoczne kolumny. Filtr pola niestandardowego, który przy wczytaniu widoku nie jest już dostępny, zostaje pominięty z komunikatem, który go nazywa, a reszta widoku się wczytuje. Wybranie widoku zastępuje je wszystkie wartościami z widoku: filtr, którego widok nie zawiera, zostaje wyczyszczony, to, co zmieniono i nie zapisano, przepada, a lista wraca na pierwszą stronę.
  • Zapisywanie. Zapisz widok otwiera jedno okno z polem Nazwa i polem wyboru Udostępnij wszystkim administratorom, którzy mają dostęp do tej listy. Pole wyboru jest na początku odznaczone, więc nowy widok jest prywatny, dopóki go nie zaznaczysz. Nazwa jest wymagana, spacje na początku i na końcu są usuwane, a jej długość to najwyżej 160 znaków. Problemy są pokazywane przy polu i nic nie zostaje wysłane, dopóki ich nie poprawisz; odmowa serwera jest pokazywana w oknie, które pozostaje otwarte z wpisanymi danymi.
  • Prywatny czy udostępniony. Widok prywatny widzisz tylko ty. Widok udostępniony widzi każdy administrator, który ma dostęp do listy zamówień, z dopiskiem (udostępniony) po nazwie. Lista wyboru nie pokazuje, kto zapisał udostępniony widok.
  • Jedna nazwa na administratora. Nie możesz mieć na tej liście dwóch widoków, których nazwy różnią się tylko wielkością liter albo spacjami na początku lub końcu. Okno odpowiada Masz już widok o tej nazwie., zanim cokolwiek wyśle, a serwer także odrzuca taką nazwę. Litery ze znakami diakrytycznymi są innymi literami: Zamówienia i Zamowienia to dwie różne nazwy. Nazwy używane przez innych administratorów i nazwy z listy produktów lub zapytań ofertowych się nie liczą. Widoki, których nazwy powtarzały się już przed wprowadzeniem tej zasady, pozostały bez zmian.
  • Usuwanie. Usuń widok jest aktywny tylko wtedy, gdy wybrany widok jest jednym z tych, które możesz usunąć. Prosi o potwierdzenie i podaje nazwę widoku — Usunąć widok „…”? — a dla widoku udostępnionego dodaje, że zniknie on dla wszystkich administratorów, którzy mają dostęp do tej listy. Nic nie zostaje usunięte, dopóki nie naciśniesz Usuń.
  • Kto może usunąć lub zmienić udostępniony widok. Jego właściciel albo każdy administrator, którego rola nie jest sales_representative — nie tylko rola platform_admin: liczy się także rola niestandardowa. Takie usunięcie lub zmiana nie zostawia śladu audytu: zapisane widoki nie trafiają do dziennika audytu. Weź to pod uwagę, przydzielając role, zanim zespół zacznie polegać na udostępnionych widokach. Opiekun handlowy może usuwać tylko własne widoki, a prywatnego widoku innego administratora nikt nie widzi i nikt nie może go usunąć.
  • Tylko zapis, wczytanie i usunięcie. Panel administracyjny nie zmienia nazwy widoku, nie zmienia tego, czy jest udostępniony, i nie nadpisuje go bieżącymi filtrami; zamiast tego zapisz nowy widok i usuń stary. Liczba widoków nie jest ograniczona.

API zapisanych widoków​

Metoda i ścieżkaOdpowiedź
GET /api/v1/admin/orders/list-views200 — własne widoki wywołującego oraz wszystkie widoki udostępnione, posortowane po nazwie
POST /api/v1/admin/orders/list-views201 — utworzony widok
PATCH /api/v1/admin/orders/list-views/:id200 — zmieniony widok; dowolne z name, shared, filters, sort, visibleColumns. Panel administracyjny go nie wywołuje. Treść, która niczego nie zmienia — pusta albo z wartościami takimi jak zapisane — niczego nie zapisuje ani nie loguje i zwraca bieżący widok
DELETE /api/v1/admin/orders/list-views/:id200 — { data: { deleted: <id> } }
  • Uprawnienie. Wszystkie cztery trasy wymagają orders:read; nie ma osobnego kodu uprawnienia. Żądanie bez aktora-administratora jest odrzucane z 401 UNAUTHORIZED.
  • Treść żądania. name (po przycięciu 1–160 znaków, bez znaków sterujących ani formatujących Unicode), shared (wartość logiczna), filters (obiekt, najwyżej 8192 bajty jako JSON w UTF-8), sort ({ field, dir }, field najwyżej 64 znaki, dir to asc albo desc; wymagane przy tworzeniu) oraz opcjonalne visibleColumns (najwyżej 64 identyfikatory po najwyżej 64 znaki albo null dla kolumn domyślnych). Wszystko poza tymi granicami to 400 VALIDATION_FAILED. Kształty to createOrderSavedViewRequestSchema i updateOrderSavedViewRequestSchema w @endora-commerce/contracts.
  • Dwie flagi zależne od wywołującego. Każdy widok w odpowiedzi ma ownedByCaller i canModify — true, gdy wywołujący jest właścicielem widoku albo widok jest udostępniony, a wywołujący jest administratorem platformy w rozumieniu poniżej. Panel administracyjny włącza Usuń widok na podstawie canModify, a przed zapisem wstępnie, w miarę możliwości, sprawdza powtórzenie nazwy wśród wyświetlonych widoków z ownedByCaller. Rozstrzyga porównanie lower(btrim(name)) po stronie serwera: nazwa przepuszczona przez to wstępne sprawdzenie nadal może zostać odrzucona z 409.
  • Administrator platformy, na potrzeby zapisanych widoków, to administrator, którego kontekst dzierżawy (tenant context) żądania ma mode === 'all' — każda rola poza sales_representative. Listy zamówień, produktów i zapytań ofertowych wyznaczają go tak samo, a w razie wątpliwości odmawiają: administrator, którego zasięgu nie da się ustalić, nie jest administratorem platformy.
  • Odmowy. Nieistniejący widok i prywatny widok innego administratora to 404 NOT_FOUND — nie da się ich odróżnić. Udostępniony widok, którego wywołujący nie jest właścicielem i którego nie może zmienić jako administrator platformy, to 403 FORBIDDEN. Nazwa, której klucza właściciel widoku już używa na tej liście, to 409 ORDER_SAVED_VIEW_NAME_TAKEN, „Masz już zapisany widok o tej nazwie na liście zamówień. Wybierz inną nazwę.”, w języku żądania.
  • Klucz nazwy to nazwa przycięta i zapisana małymi literami, porównywana w PostgreSQL jako lower(btrim(name)) — bez usuwania znaków diakrytycznych. Zasada wiąże właściciela widoku: administrator platformy zmieniający nazwę udostępnionego widoku kolegi dostaje odmowę, gdy kolega już używa tego klucza. Utworzenie widoku i zmiana klucza nazwy biorą blokadę doradczą (advisory lock) w zakresie transakcji, kluczowaną właścicielem, więc dwa równoczesne zapisy pod jedną nazwą zostawiają dokładnie jeden widok. Wiersze w order_list_saved_views, które już dzieliły klucz, pozostawiono bez zmian; zasada dotyczy tylko zapisów, a zapisana nazwa może być dłuższa, niż pozwala reguła zapisu.
  • Brak audytu. Zapisane widoki to osobista konfiguracja interfejsu i nie przechodzą przez Command Bus. Gdy administrator zmienia lub usuwa widok, którego nie jest właścicielem, usługa zapisuje jeden wpis dziennika na poziomie info: { event: 'saved_view.updated' | 'saved_view.deleted', list: 'order_list_saved_views', viewId, ownerAdminUserId, actorAdminUserId }. Ten wpis jest jedynym śladem.
  • Przechowywanie. order_list_saved_views (OrderListSavedView) jest globalna dla platformy, a nie przypisana do organizacji: przechowuje wartości filtrów, nigdy wyniki listy, a każdy odczyt listy po zastosowaniu widoku odbywa się w zakresie osoby, która go wczytała.

Zamówienie złożone z zaakceptowanego zapytania ofertowego​

Zamówienie złożone z koszyka wypełnionego zaakceptowanym zapytaniem ofertowym zapisuje to zapytanie w polu sourceQuoteRequestId (orders.source_quote_request_id). Moduł zapytań ofertowych kończy zapytanie, gdy zobaczy takie zamówienie, a inne moduły odczytują to pole, aby ustalić, którym zamówieniem stało się zapytanie.

Koszyk niesie jedynie deklarację, a przy składaniu zamówienia jest ona sprawdzana z zapytaniem ofertowym w jego bieżącym stanie. Zamówienie zapisuje zapytanie, gdy spełnione są wszystkie cztery warunki:

  • zapytanie należy do tej samej organizacji co zamówienie;
  • zapytanie jest nadal w statusie Approved — nie zostało anulowane, nie wygasło i nie jest już zakończone;
  • żadne inne zamówienie nie zapisało już tego zapytania — gdy dwie osoby z jednej organizacji zamieniły to samo zapytanie w koszyk, zapytanie przypada pierwszemu złożonemu zamówieniu, a drugie jest zwykłym zamówieniem;
  • w koszyku wciąż jest co najmniej jedna jego pozycja — ten sam produkt i wariant w uzgodnionej cenie jednostkowej.

W przeciwnym razie zamówienie i tak zostaje złożone, lecz niczego nie zapisuje; odmowa trafia do logu i nie jest pokazywana kupującemu. Żadne żądanie nie przyjmuje tego pola: ani storefront, ani ekran tworzenia zamówienia w panelu administracyjnym, ani zewnętrzne API zamówień nie mogą wskazać zapytania ofertowego.

Uzgodnione ceny to osobne pytanie i ono może zablokować zamówienie. Zanim cokolwiek zostanie zarezerwowane lub zapisane, składanie zamówienia sprawdza każdą pozycję koszyka wciąż wycenioną według uzgodnienia z oferty (wciąż w uzgodnionej ilości) względem tej oferty w jej obecnym stanie i odmawia z kodem 410 QUOTE_VALIDITY_ENDED, gdy termin ważności oferty upłynął (details.code lapsed), gdy oferta już nie obowiązuje — otwarta ponownie, anulowana, wygasła lub usunięta (withdrawn) — albo gdy moduł zapytań ofertowych jest wyłączony i nic nie może potwierdzić cen (unavailable). Koszyk pozostaje bez zmian. Oferta zakończona już przez inne zamówienie nadal wiąże swoje ceny do terminu ważności. Strona modułu zapytań ofertowych, w części Termin ważności, opisuje tę regułę od strony kupującego.

Gdy moduł zapytań ofertowych jest wyłączony, koszyk bez cen z oferty jest składany dokładnie tak jak dotąd i nie zapisuje żadnego zapytania.

Grupy pozycji​

Zamówienie może pokazywać pozycje w nazwanych grupach — Hala A, Hala B — z pozycjami bez grupy pod nagłówkiem Pozostałe pozycje. Grupy służą wyłącznie prezentacji: nie zmieniają żadnej ceny, ilości ani sumy. Zamówienie otrzymuje je na jeden z dwóch sposobów i nigdy ich później nie zmienia: żaden ekran ani API nie edytuje grupowania złożonego zamówienia.

Z zaakceptowanego zapytania ofertowego. Gdy przy składaniu zamówienia zostaje zapisane zapytanie ofertowe, z którego pochodzi koszyk (zob. poprzednią sekcję), zamówienie kopiuje grupy oferty w tej samej transakcji. Każda pozycja zamówienia jest dopasowywana do pozycji oferty: najpierw wszystkie pozycje z tym samym produktem, wariantem, uzgodnioną ilością i uzgodnioną ceną jednostkową, potem według produktu, wariantu i ceny, potem według produktu, wariantu i ilości, a na końcu wyłącznie według produktu i wariantu, przy czym każda pozycja oferty jest użyta raz. Dzięki temu produkt rozdzielony w ofercie na dwie grupy — 5 sztuk w jednej, 3 w drugiej, po tej samej cenie — zachowuje każdą pozycję w jej grupie. Dopasowana pozycja przejmuje grupę i miejsce pozycji oferty; pozycja, która do niczego nie pasuje — dodana do koszyka po zamianie albo zmieniona tak, że już nie pasuje — trafia do sekcji Pozostałe pozycje, za dopasowanymi. Grupa oferty, do której nie trafiła żadna pozycja, nie jest kopiowana. Gdy przy składaniu zamówienia zapytanie nie zostaje zapisane albo moduł zapytań ofertowych jest wyłączony, zamówienie jest składane bez grup, a poza tym dokładnie tak jak wcześniej. Późniejsza zmiana oferty nie rusza grup zamówienia.

Z ekranu tworzenia zamówienia. Operator układa pozycje w grupy przed utworzeniem zamówienia (zob. Ekran tworzenia zamówienia); zamówienie powstaje z nimi w tej samej transakcji, a odrzucone utworzenie nie zapisuje żadnej grupy. Grupy bez pozycji nie są tworzone. Jeden produkt może być w kilku pozycjach — w dwóch różnych grupach albo dwa razy w jednej: każda pozycja żądania staje się osobną pozycją zamówienia, we własnej grupie, wycenioną według własnej ilości (minimalna ilość zamówienia produktu jest nadal oceniana na sumie jego pozycji). POST /api/v1/admin/orders przyjmuje opcjonalną listę groups ({ key, name }, w kolejności wyświetlania, najwyżej 50, nazwy od 1 do 120 znaków) i dla każdej pozycji opcjonalny groupKey. Grupowanie jest utrwalane we wpisie audytu order.place_on_behalf (liczba pozycji każdej grupy, w kolejności; bez nazwy, która jest wartością i nie trafia do dziennika audytu); własne złożenie zamówienia przez kupującego, jak dotąd, nie trafia do audytu.

Gdzie są pokazywane. Ekran zamówienia w panelu administracyjnym i strona zamówienia kupującego pokazują każdą grupę jako sekcję z nagłówkiem, pozycjami i podsumowaniem — liczba pozycji, netto, VAT i brutto, sumujące wiersze nad nim — a następnie Pozostałe pozycje. Zamówienie bez grup i każde zamówienie złożone, zanim powstały grupy, wygląda dokładnie tak jak wcześniej. Każda odpowiedź z zamówieniem — dla administratora, klienta i zewnętrznego API zamówień — zawiera itemGroups ({ id, name, position }) oraz dla każdej pozycji groupId i position, z pozycjami w kolejności wyświetlania; integracja, która je pomija, działa dalej.

Co nie przenosi grup. Faktury, zwroty, ponowne zamówienie (wypełnia koszyk), zamów ponownie jako zapytanie ofertowe, koszyk i checkout, e-maile, webhooki i przyjmowanie zamówień przez zewnętrzne API. Nie ma PDF zamówienia.

Minimalne ilości zamówienia przy składaniu zamówienia​

Składanie zamówienia stosuje minimalne ilości zamówienia z katalogu do każdej pozycji koszyka — minimum produktu w sztukach i minimum każdej jednostki opakowania w jednostkach, liczone ze wszystkich pozycji produktu (oba definiuje strona modułu Catalog). To ostatnie słowo na każdej ścieżce, która kończy się zamówieniem: checkout, zakup jednym kliknięciem, ponowne zamówienie, koszyk wypełniony z zapytania ofertowego, tworzenie zamówienia w panelu administracyjnym i zewnętrzne API zamówień.

  • Przed jakimkolwiek skutkiem ubocznym. Sprawdzenie działa w transakcji składania zamówienia zaraz po odczytaniu koszyka — przed sprawdzeniem wartości zamówienia i limitu kredytowego, numerem zamówienia oraz jakąkolwiek rezerwacją stanu lub kredytu. Odmowa niczego nie zapisuje.
  • Co odpowiada. Pozycja, której rekord produktu zniknął → 404 PRODUCT_NOT_FOUND z details.cartItemIds. Pozycja poniżej minimum → 422 PRODUCT_BELOW_MINIMUM_QUANTITY albo 422 PACKAGING_UNIT_BELOW_MINIMUM_QUANTITY z details.lines[], po jednym wpisie na każdą odrzuconą pozycję (cartItemId, productId, productName, kind, minimum, packagingUnitName). Zdanie i nazwy produktów są w języku, w którym udzielana jest odpowiedź: zapisanym języku administratora, w przeciwnym razie w języku z nagłówka Accept-Language żądania (z uwzględnieniem wag q), a w ostateczności w domyślnym języku kanału.
  • Podgląd checkoutu mówi to samo wcześniej. POST /api/v1/orders/preview-total zwraca belowMinimumLines[] — pozycje, które składanie zamówienia by odrzuciło, z tymi samymi zwolnieniami; pozycja, której produkt zniknął, ma kind: 'product_unavailable' i nie ma nazwy ani minimum. Storefront je wymienia i wyłącza Place order. Podgląd nie zakłada blokady, więc przy wyścigu rozstrzyga składanie zamówienia.
  • Koszyk wypełniony z zaakceptowanego zapytania ofertowego. Moduł Carts zwalnia każdą pozycję wypełnioną z zapytania, dopóki jej ilość równa się ilości z zapytania. Składanie zamówienia i podgląd honorują to zwolnienie tylko wtedy, gdy zapytanie ofertowe jest w tej chwili nadal ważne: istnieje, należy do organizacji kupującego, ma nadal status Approved — nie jest anulowane ani wygasłe, a jego ważność się nie skończyła — żadne zamówienie go jeszcze nie zapisuje, a koszyk wciąż zawiera co najmniej jedną jego pozycję w uzgodnionej cenie. W przeciwnym razie każda pozycja jest oceniana jak każda inna. Sprawdzenie i jego blokada działają na początku składania zamówienia, więc o zwolnieniu decyduje się, zanim cokolwiek zostanie zapisane. Gdy moduł Quote Requests jest wyłączony, nic nie może potwierdzić zapytania i żadna pozycja nie jest zwolniona. Sprawdzenie podglądu jest też udostępnione jako orderQuoteSourcePort, o które pyta moduł Carts przy przekazaniu koszyka do akceptacji, więc przekazanie ocenia pozycję wypełnioną z zapytania tak jak podgląd; składanie zamówienia potwierdza zapytanie ponownie.
  • Zewnętrzne API zamówień (POST /api/v1/external/orders) i tworzenie zamówienia w panelu budują z żądania koszyk roboczy (Koszyki robocze modułu koszyków) i oceniają łączną ilość każdego produktu ze wszystkich pozycji żądania; żądanie poniżej minimum jest odrzucane w całości, z details.lines[] kluczowanym index. Żądanie jest oceniane samodzielnie — koszyk klienta nie liczy się do niczego — i odrzucane, zanim cokolwiek zostanie zapisane. Koszyk klienta nigdy nie jest naruszany, niezależnie od tego, czy zamówienie zostanie złożone, czy odrzucone. To samo dotyczy pozycji bez ceny albo sprzedawanej wyłącznie na zapytanie: jest wyceniana, zanim koszyk roboczy powstanie. Żadne z nich nie przenosi jednostki opakowania, więc działa tam tylko minimum w sztukach. Oba odrzucają więcej niż 200 pozycji z kodem 422 VALIDATION_FAILED, details.code = 'too_many_items' — w zewnętrznym API jest to sprawdzane jako pierwsze, zanim wymagany będzie nagłówek Idempotency-Key, i nie zostawia żadnego rekordu idempotencji.

Podleganie zwrotowi w chwili zakupu​

Każda pozycja zamówienia zapisuje, czy jej produkt podlegał zwrotowi w chwili złożenia zamówienia (order_items.returnable_at_purchase), na każdej ścieżce składania zamówienia. Późniejsze zmiany flagi Podlega zwrotowi produktu jej nie zmieniają. Pozycja, której rekordu produktu albo flagi nie dało się odczytać przy składaniu zamówienia, jest zapisywana jako niepodlegająca zwrotowi, nigdy pusta. Pozycje zamówień złożonych przed powstaniem tej kolumny mają null, co moduł Returns traktuje jako podleganie zwrotowi. Wartość trafia do modułu Returns przez OrderReturnContextPort (returnableAtPurchase na każdej pozycji); Returns nie odczytuje żadnej tabeli modułu Orders. Składanie zamówienia zapisuje ją niezależnie od tego, czy moduł Returns jest włączony.

Migracja 20261016T082022_orders_order_item_returnable_at_purchase.ts dodaje tę kolumnę (dopuszcza null).

Kiedy zamówienie zostało zrealizowane​

Zamówienie zapisuje chwilę, w której po raz pierwszy weszło w status completed (orders.completed_at). OrderTransitionService zapisuje ją w tej samej transakcji co zmianę statusu, a zamówienie utworzone od razu w statusie completed dostaje ją przy zapisie. Nigdy nie jest nadpisywana: późniejsza edycja zrealizowanego zamówienia jej nie przesuwa.

Od tej chwili liczy moduł Returns. OrderReturnContextPort podaje ją jako completingStatusEnteredAt, i od niej biegną okno bezpłatnego zwrotu oraz termin konsumenta na odstąpienie od umowy. Zamówienie, które nigdy nie zostało zrealizowane, podaje null: jego termin jeszcze się nie rozpoczął. Nic tutaj nie odczytuje modułu Shipments, więc jego wyłączenie niczego w tym nie zmienia.

Realizuj zamówienie, gdy towar został doręczony. Platforma nie zna daty doręczenia: sukces przesyłki oznacza, że przewoźnik przyjął paczkę. Termin konsumenta na odstąpienie od umowy liczy się od dnia, w którym otrzymał towar, a zrealizowanie zamówienia jest sposobem, w jaki sklep stwierdza, że ten dzień nadszedł. Zrealizowanie go przy wysyłce rozpoczyna termin za wcześnie; z tego powodu moduł Returns zachowuje okres karencji po terminie (zob. stronę Returns).

Zanim powstała ta kolumna, tę chwilę odczytywano z updated_at zamówienia, które każda późniejsza edycja przesuwała do przodu. Migracja 20261108T000543_orders_completed_at.ts dodaje kolumnę (dopuszcza null) i wypełnia ją wartością updated_at w każdym zamówieniu, które już jest w statusie completed. To dokładnie ta chwila, według której te zamówienia były oceniane wcześniej, więc aktualizacja nie zmienia żadnego istniejącego zamówienia; dla zamówienia edytowanego po realizacji jest to ostatnia edycja zamiast realizacji — przybliżenie, którego nic zapisanego nie pozwala poprawić.

Ustawienia​

orders.min_order_value (liczba; dotyczy checkoutu i tworzenia zamówień w panelu; to kwota, więc ma najwyżej dwa miejsca po przecinku — więcej jest odrzucane z 400 AMOUNT_PRECISION_EXCEEDED; zamówienie poniżej tej wartości jest odrzucane z 422 ORDER_BELOW_MINIMUM_VALUE, a jego details zawierają minimum, subtotal i currency, kwoty jako stringi z dwoma miejscami po przecinku), orders.reorder_enabled (wartość logiczna), orders.confirmation_recipients (lista stringów) — wszystkie globalnie albo dla kanału sprzedaży. Do tego order_confirmation_emails dla każdej organizacji. E-mail z potwierdzeniem trafia do klienta, a w kopii do listy organizacji i listy z ustawień (bez gwarancji doręczenia, nigdy nie blokuje składania zamówienia).

E-mail z potwierdzeniem zamówienia​

Po udanym checkoucie OrderService.placeOrder wysyła e-mail z potwierdzeniem (po zatwierdzeniu transakcji, bez gwarancji doręczenia — błąd poczty nigdy nie wycofuje złożonego zamówienia). Wiadomość budowana przez email-templates/order-confirmation.ts zawiera zamówione produkty z kwotami, metodę dostawy i jej koszt, metodę płatności z ewentualną dopłatą (np. +5.00 PLN przy pobraniu), zastosowane rabaty, podsumowanie wartości zamówienia oraz adresy dostawy i do faktury. Wiersz płatności jest generowany przez rejestr szablonów e-mail płatności (payments/services/payment-email-renderer.ts) — klucz renderers.email adaptera zastępuje domyślny szablon platformy.

Dane firmy do rozliczenia​

Migawka danych rozliczeniowych zamówienia zawiera nazwę firmy i NIP tylko wtedy, gdy jest firma, której można wystawić fakturę. Dla Organizacji firmowej placeOrder przyjmuje domyślnie jej nazwę prawną (lub nazwę) i NIP, a kupujący może nadpisać każde z nich przy finalizacji tego jednego zamówienia. Organizacja osobista (B2C) nie jest firmą, więc nie dostarcza wartości domyślnych: jej NIP to wewnętrzny symbol zastępczy, a jej nazwa to imię i nazwisko osoby. Jej zamówienie jest rozliczane na osobę — bez nazwy firmy i bez NIP — chyba że kupujący zaznaczy przy finalizacji Chcę fakturę na firmę i wpisze nazwę firmy oraz NIP, które są wtedy sprawdzane tak jak przy rejestracji firmy. Faktura, jej PDF, e-mail z potwierdzeniem i ekran zamówienia pokazują wiersz z NIP tylko wtedy, gdy zamówienie go zawiera. Zamówienie zachowuje migawkę, z którą zostało złożone. Panel Organizacja na ekranie zamówienia w panelu administracyjnym również nie pokazuje NIP Organizacji osobistej, tylko etykietę Klient indywidualny: odpowiedź administracyjna zamówienia zawiera dla niej organization.taxId: null i organization.isPersonal: true.

Numery z systemów zewnętrznych​

Moduł, który przekazuje zamówienia do innego systemu — ERP, systemu magazynowego, integracji fulfilmentu — zapisuje na zamówieniu, co ten system odpowiedział: jego własny numer zamówienia, stan przekazania oraz własne słowa tego systemu, gdy zamówienie odrzucił. Operator widzi to na stronie zamówienia, tam gdzie odbiera telefon od kupującego, a nie na ekranach samej integracji.

Zamówienie ma jeden wpis na system. Wpis zawiera:

PoleZnaczenie
SystemStały klucz piszącego, zwykle identyfikator jego modułu — małe litery, cyfry, _, - lub ., zaczyna się literą, najwyżej 64 znaki.
NumerNumer zamówienia w drugim systemie, gdy już go nadał (najwyżej 255 znaków).
Stanpending (przekazane, bez odpowiedzi), synced (przyjęte) albo error (odrzucone).
KomunikatWłasne słowa drugiego systemu, zwykle przy error — zwykły tekst, najwyżej 1000 znaków.
ZaktualizowanoKiedy wpis ostatnio się zmienił.

Na stronie zamówienia sekcja Systemy zewnętrzne pokazuje każdy wpis ze stanem w postaci plakietki, a gdy żaden system jeszcze nic nie przekazał — mówi o tym. Komunikat jest wyświetlany jako tekst, nigdy jako znaczniki. Widzi go każdy, kto może otworzyć zamówienie: odczyt wynika z orders:read, a przedstawiciel handlowy widzi wpisy zamówień, które sam widzi. Kupujący nigdy ich nie widzą.

Na liście zamówień wyszukiwanie znajduje zamówienie po numerze z systemu zewnętrznego tak, jak po numerze zamówienia: po fragmencie, bez rozróżniania wielkości liter, niezależnie od tego, który system go zapisał. Komunikat nie jest przeszukiwany.

Dla autora modułu punktem styku jest port orderExternalReferencePort (OrderExternalReferencePort w @endora-commerce/contracts; nazwa w kontenerze jest też eksportowana jako ORDER_EXTERNAL_REFERENCE_PORT). Rozwiązuj go przy każdym użyciu przez lazyPort; nie ma on trasy HTTP w panelu administracyjnym.

  • set(orderId, system, { state, reference?, message? }) tworzy lub aktualizuje wpis systemu. Pominięty reference zachowuje zapisany numer, a null go czyści; pominięty message oznacza brak komunikatu, więc zgłoszenie synced po error nie zostawia starego odrzucenia.
  • get(orderId, system) i listForOrder(orderId) odczytują wpisy, a findOrderIds(system, reference) znajduje zamówienia o dokładnie tym numerze — zwykle jedno.

Każda zmiana to jedna komenda, order.external_reference.set, zapisywana w dzienniku audytu z wywołującym aktorem, więc wywołuj ją w kontekście dzierżawcy — worker w enterSystemScope. Zapis, który niczego nie zmienia, niczego nie rejestruje i nie przesuwa pola Zaktualizowano, bo pętla synchronizacji wysyła dane ponownie. Zamówienie, którego wywołujący nie widzi, jest odrzucane z 404 ORDER_NOT_FOUND, a błędny klucz systemu, stan, numer lub komunikat z 400 VALIDATION_FAILED, zanim cokolwiek zostanie zapisane.

Wpis przeżywa swojego autora: odinstalowanie modułu, który go zapisał, zostawia wpis na zamówieniu jako historię. Migracja 20261110T143322_orders_order_external_references.ts tworzy pustą tabelę (order_external_references, unikalną dla pary zamówienie i system).

Punkty rozszerzenia​

  • Adaptery płatności — zobacz moduł payment_methods. placeOrder rozpoczyna płatność przez PaymentAdapterRegistry; nowe metody rejestrują adapter zamiast zmieniać usługę zamówień.
  • Zakres dostępu — order-access-service.ts to jedyne miejsce egzekwujące zakres zamówień kupującego (własne albo całej organizacji z orders.view_organization, o które pyta organizationPermissionPort); przechodzą przez nie lista, szczegóły, ponowienie zamówienia, utworzenie zapytania ofertowego i OrderReadPort.findByIdForCustomer. Moduły invoices i returns korzystają z niego przez ten port.
  • Panele na ekranie zamówienia — strefa panelu administracyjnego order.detail.after jest osadzona raz, na końcu ekranu zamówienia, pod jego zakładkami, i przekazuje wkładowi { orderId }. Moduł dodaje panel, deklarując zoneComponent('order.detail.after', …) we własnych wkładach do panelu administracyjnego; ten moduł nie wymienia żadnego z nich. Gdy nikt nic nie wnosi — nie ma takiego modułu, moduł jest wyłączony albo osoba nie ma uprawnienia wymaganego przez panel — strefa nie renderuje niczego, a ekran jest dokładnie taki jak bez niej.

Wyszukiwanie globalne​

Wyszukiwanie globalne w panelu administracyjnym (paleta poleceń, ⌘K / Ctrl+K) znajduje zamówienia. Ten moduł udostępnia poniższe pola; to, które z nich są używane, wybiera się na ekranie konfiguracji wyszukiwania globalnego.

PolePrzeszukiwane domyślnie
Numer zamówieniatak
Nazwa organizacjitak
Imię i nazwisko lub e-mail klientatak
Nazwa firmy do fakturynie
NIP do fakturynie

Wynik pokazuje numer zamówienia, organizację, datę złożenia, wartość i status, a jego wybranie otwiera zamówienie. Dokładnie pasujący numer zamówienia jest pokazywany jako pierwszy. Zamówienia pojawiają się dla roli z uprawnieniem orders:read, a przedstawiciel handlowy widzi tylko zamówienia przypisanych mu organizacji — te same, które pokazuje mu lista zamówień.