Moduł Allegro (core/allegro)

Integracja Orbito z Allegro: import zamówień (formularze pozakupowe), obsługa anulowań, synchronizacja statusu realizacji i numerów przesyłek Orbito → Allegro, „Wysyłam z Allegro” jako przewoźnik hubu core/shipping oraz wysyłka dokumentów sprzedaży (PDF) do zamówienia w Allegro.

Moduł jest multi-instancyjny (module.json: "singleton": false) — jedna instancja = jedno konto Allegro = jeden kontener. Firma może połączyć kilka kont Allegro, instalując moduł wielokrotnie; crony i synchronizacja działają zawsze na koncie własnej instancji.

Powstał jako migracja modułu allegro z ordershub — kontekst decyzji i etapów w ../PLAN-allegro-migration.md.

Wysyłam z Allegro od 1.3.0

Na karcie zamówienia wybierz kafelek „Wysyłam z Allegro — <metoda dostawy>” albo „Dodaj paczkę → Nadaj z <konto> — Wysyłam z Allegro”. Formularz pozwala zmienić wymiary i wagę jednej paczki. Metoda dostawy (także ORLEN Paczka) oraz punkt odbioru pochodzą z zamówienia; nie wybieramy innego przewoźnika na podstawie nazwy modułu. Wymagane jest połączone konto i komplet danych nadawcy.

Moduł rejestruje kontrakty shipping.carrier.getQuickShipOptions, quickShip, getShipmentForm, getPackingCapabilities, generateLabels, getTrackingStatus. Każda operacja używa standardowego src/hook-contract.js oraz wskazanego ID instancji. Formularz oddaje contractSubmit, który rejestr przesyłek wiąże z własnym routerem nadania. Nie ma stałego obcego celu UI ani awaryjnego RPC.

Obsługiwane są plany opakowań v1/v2 dla jednej fizycznej paczki (w tym kartony połączone). Kilka osobnych paczek blokuje nadanie z wyjaśnieniem. Wymiary i waga pochodzą z potwierdzonego planu; zmiana zamówienia unieważnia plan.

Zamiar nadania i UUID komendy są zapisywane przed POST w runtime.shipments.<checkoutFormId>. Timeout, HTTP 5xx lub utrata statusu nie powodują kolejnego POST. Zapisany poprawny wynik pozwala odzyskać numer listu po utracie odpowiedzi hooka. Nierozstrzygniętą komendę trzeba zweryfikować w Allegro przed odblokowaniem nadania.

Wymagania

• SDK @orbito/api-lib ≥ 4.4.3 (RPC po TLS, gdy rdzeń poda ORBITO_TLS_CA) i rdzeń obsługujący kontekst uwierzytelnionych hooków oraz

binarne body w Core.fetch.

• Brak zależności dependsOn. Dostawcy zamówień (orders.*) i opcjonalnie dokumentów

(invoicing.invoices.*) są odkrywani przez kontrakty. Brak lub kilka dostawców daje błąd; moduł nie wybiera pierwszej instalacji.

• Katalog produktów uzupełnia właściciel zamówienia przy orders.create.
• Listy statusów konfiguracji pochodzą z orders.status.search; zachowują zapisane ID

i pokazują błąd pobrania. Referencje historii i problemów pochodzą z orders.references.

Opłaty i nick kupującego od 1.3.3

Na karcie konkretnego zamówienia zakładka Opłaty Allegro jest umieszczona obok Widok pakowania i Widok księgowy. Pokazuje prowizje, opłaty za dostawę, pozostałe opłaty, uznania/korekty oraz koszt łączny (obciążenia minus uznania). Waluty są sumowane osobno, w całkowitych groszach. Tabela pokazuje datę i typ operacji, ofertę, kwotę i podatek przekazany przez Allegro. Odśwież opłaty pobiera aktualne dane wyłącznie tego zamówienia. Moduł nie dodaje strony na pasku nawigacji.

Nick kupującego (buyer.login) jest zapisywany w customer.login. Na karcie zamówienia widnieje nad imieniem i nazwiskiem, a na liście zastępuje wyświetlany identyfikator Allegro. Techniczne source.uniqueId i source.sourceId pozostają bez zmian. Starsze zamówienia uzupełniają nick przy odczycie z właściwego konta Allegro; wynik jest buforowany w allegro_orders.buyerLogin.

Kontrakty sources.order.tabs, sources.order.tabAction oraz sources.orders.presentation używają hook-contract.js i jawnie wybranej instancji z zapisanych danych źródła. Dodatkowe zakładki przyjmują wyłącznie natywne widżety, semantyczne akcje i lokalne dane tabeli. Moduł zamówień wiąże przycisk odświeżania ze swoim routerem hooków, bez bezpośrednich wywołań innego modułu z UI.

Źródłem jest GET /billing/billing-entries?order.id=...&marketplaceId=..., z pełną paginacją i stałą górną datą odczytu. Nie używamy kalkulatora szacowanych prowizji ani nie rozdzielamy opłat za konto/ofertę bez identyfikatora zamówienia. Kwoty pokazujemy według Allegro, bez wyliczania kosztu zakupu produktu ani zysku. Kierunek obciążenia/uznania ustalamy ze znaku value.amount; dodatni rabat może mieć w API asset: DEBIT i wtedy pomniejsza koszty. Zachowujemy też oryginalną kwotę i pole asset. Migawki starszego formatu są ponownie pobierane i do tego czasu nie pokazują nieaktualnych sum.

Cron co 5 minut obsługuje do 20 należnych zamówień własnej instancji. Uzupełnia także istniejące mapowania importu. Zamówienia zaimportowane w ostatnich 7 dniach odświeża co godzinę, starsze co dobę, także po anulowaniu — aby pobrać późniejsze korekty. Serwis historycznego zamówienia ustala z formularza; marketplace B2B korzysta ze wspólnego billingu kraju zgodnie z API Allegro. Stare zamówienia bez mapowania trafiają do kolejki po wyświetleniu, po potwierdzeniu source.moduleCode, source.moduleId i source.uniqueId w kontrakcie źródła.

Zestaw opłat zapisujemy atomowo dopiero po pobraniu wszystkich stron. Błąd, nieprawidłowe dane lub limit paginacji zachowują poprzedni zestaw, oznaczają błąd odświeżenia i planują ponowienie za godzinę. Brak pobrania oznaczamy —, a potwierdzony pusty wynik jako „Brak naliczonych opłat”. Problemy mają kod ALLEGRO_BILLING_FAILED i klucz billing:<checkoutFormId>. Brak dostępu (403) zgłasza jeden wspólny problem billing-access i wstrzymuje cron na godzinę; po poprawieniu dostępu można od razu wykonać ręczne odświeżenie.

Wymagane jest uprawnienie użytkownika accounting.view i zakres aplikacji Allegro allegro:api:billing:read. Przy HTTP 403 widok podaje instrukcję włączenia zakresu w aplikacji i ponownego połączenia konta. Dane są przechowywane w allegro_orders własnej instancji, a odczyt zamówień korzysta z odkrywanego dostawcy hooków orders.*, bez zależności od konkretnego modułu zamówień.

Połączenie konta

Konto sprzedawcy łączy się przez OAuth device flow, obsługiwany akcjami bloku konfiguracji „Połączenie z Allegro” (src/register-config.js, src/auth.js):

Pole connection.environment wybiera środowisko: production (domyślne) albo sandbox (testy). Zmiana środowiska rozłącza konto — tokeny i kod device flow są wydane dla konkretnego środowiska, więc trzeba połączyć je ponownie.

Wygaśnięcie sesji: gdy Allegro odrzuci odświeżenie tokenu (4xx, czyli sesja realnie utracona — błędy sieci/5xx/429 są tylko przejściowe), moduł kasuje tokeny, konto wraca do stanu „niepołączone” (crony i handlery synchronizacji milkną) i zgłasza problem ALLEGRO_AUTH_EXPIRED z instrukcją ponownego połączenia.

Klucze aplikacji Allegro

Klucze aplikacji (clientId/clientSecret, osobne dla produkcji i sandboxa) to sekrety modułu — nie ma ich w kodzie paczki. module.json → secrets deklaruje cztery zmienne:

• Produkcja — wartości ustawia autor modułu w repozytorium modułów (`omm secrets set

<NAZWA>` w katalogu modułu albo karta „Sekrety aplikacji” w modules.orbito.pl), a rdzeń wstrzykuje je do kontenera każdej instancji jako zmienne środowiskowe. Sprzedawca niczego nie konfiguruje.

• Lokalnie — omm dev czyta je z .env w katalogu modułu (wzór: .env.example; .env

jest w .gitignore, a omm nie dołącza plików .env* do paczki).

src/app-keys.js (getAppKeys(environment)) czyta parę dla środowiska z konfiguracji. Brak którejś wartości kończy operację błędem ALLEGRO_APP_KEYS_MISSING („skontaktuj się z administratorem platformy”) i zgłasza problem ALLEGRO_APP_KEYS_MISSING (klucz app-keys) — moduł nie pada, ale nie łączy się z Allegro. Stan sprawdzany jest przy starcie modułu (checkAppKeys w index.js — kasuje też problem pozostawiony przez poprzedni kontener), a później zgłoszenie i jego skasowanie idą tylko przy zmianie stanu (np. przełączeniu na środowisko bez kluczy), nie przy każdym żądaniu.

Konfiguracja

Bloki rejestruje src/register-config.js (Config.registerConfigBlocks), wszystkie w zasięgu global.

Import zamówień

Cron 25 * * * * * (co minutę), pod lockiem allegro-orders-import (TTL 300 s, odnawiany w trakcie przebiegu — src/job-runtime.js). Import wyłączony w konfiguracji albo konto niepołączone (stan normalny przed pierwszym połączeniem) — cron nic wtedy nie robi.

Kursor zdarzeń (runtime.lastEventId): przy połączeniu konta i jako zabezpieczenie w cronie (brak kursora) ustawiany na najnowszym zdarzeniu konta — import startuje bez backfillu (decyzja D6). Konto bez żadnych zdarzeń dostaje kursor „od początku strumienia”, żeby pierwsze prawdziwe zdarzenie nie zostało wzięte za punkt startu i pominięte.

Obsługiwane typy zdarzeń: READY_FOR_PROCESSING (import) oraz BUYER_CANCELLED i AUTO_CANCELLED (anulowanie, decyzja D4). Zdarzenia czytane są stronami po 100 (maks. 10 stron na przebieg), kursor przesuwa się po każdym obsłużonym zdarzeniu.

Deduplikacja: pierwsza linia to lokalny model allegro_orders (indeks unikalny na checkoutFormId); druga — core/orders → search({ source: { moduleCode, uniqueId } }), na wypadek gdy create się powiodło, a zapis lokalnego mapowania nie.

Kolejka ponowień nieudanego importu: odstępy 1 min, 5 min, 15 min, 1 h, 6 h (6 prób łącznie), do 20 należnych ponowień na przebieg crona, przed odczytem nowych zdarzeń. Po wyczerpaniu prób wpis zostaje failed bez kolejnego terminu — problem prosi o dodanie zamówienia ręcznie. Anulowanie formularza czekającego w kolejce wstrzymuje import (bez wpisu w historii, bo zamówienie nigdy nie powstało w Orbito).

Mapowanie checkout-form → zamówienie (src/order-mapper.js, czyste funkcje, testowalne bez SDK):

• płatności — wpłata dla każdej opłaconej płatności poza pobraniem (`transactionId:

'allegro:<paymentId>'); etykieta i kod metody płatności z PAYMENT_TYPES` (online, za pobraniem, przelew tradycyjny, podzielona płatność, odroczony termin),

• VAT dostawy — koszt dostawy w Allegro jest brutto; netto liczone stawką ze import.shippingTaxRate,
• zestawy — pozycja z productSet dostaje pack[] (składniki z nazwą, SKU, EAN, zdjęciem);

własne weight/EAN pozycji-zestawu jest wtedy ignorowane,

• EAN/SKU — EAN z parametru oferty „EAN (GTIN)” (tylko dla pojedynczego produktu), SKU z

lineItem.offer.external.id; składniki zestawu z parametru „Kod producenta”,

• punkt odbioru — delivery.pickupPoint formularza → order.delivery.pickupPoint (adres,

nazwa, opis),

• faktura — dane firmy (NIP z PL_NIP albo taxId) albo osoby fizycznej z invoice.address.

Ceny Allegro są brutto — rabaty są już w nich uwzględnione, zamówienie nie dostaje osobnych pozycji rabatu. Oferty (zdjęcie, VAT, EAN) i produkty katalogowe zestawów dociągane są równolegle (4 żądania naraz), błąd pojedynczego pobrania nie blokuje importu — pozycja powstaje z samych danych formularza.

Kontrola zgodności kwot: po imporcie findTotalMismatch (src/order-total.js) porównuje brutto zamówienia Orbito z summary.totalToPay formularza (tolerancja 1 grosz na zaokrąglenia). Rozbieżność — zwykle dopłaty albo płatne usługi dodatkowe spoza mapowania — zgłasza problem ALLEGRO_ORDER_TOTAL_MISMATCH, żeby sprzedawca sprawdził zamówienie przed wystawieniem faktury.

Hooki

Konsumowane

Wszystkie trzy handlery połykają błędy (owinięte w src/sync-hook.js) — wyjątek kazałby outboxowi rdzenia ponawiać zdarzenie w nieskończoność. Błędy operacji zgłaszają się same jako problemy (patrz niżej). Konto niepołączone to stan normalny — zdarzenie jest wtedy cicho pomijane.

Emitowany: core.shipping.getCarrier

„Wysyłam z Allegro” jako przewoźnik hubu core/shipping (kontrakt 2.x, jak core.inpost):

{
    name: `${accountName} — Wysyłam z Allegro`,
    moduleCode: Core.getModuleInfo().code,
    instanceId: Core.getInstanceId(),
    logoFile: 'logo.png',
    packingPlans: true,
    packingPlanVersions: [1, 2],
    packingCapabilitiesMethod: 'getPackingCapabilities',
    shipmentFormMethod: 'getShipmentForm',
    quickShipOptionsMethod: 'getQuickShipOptions',
    getTrackingStatusMethod: 'getTrackingStatus',
    generateLabelsMethod: 'generateLabels'
}

Zwraca null, gdy instancja nie może nadawać (konto niepołączone albo dane nadawcy niekompletne) — przewoźnik nie pojawia się wtedy na liście hubu. Od 1.3.0 dostępny jest również prosty formularz jednej paczki przez getShipmentForm.

Metody

Metody ładuje Utils.loadMethods z katalogu methods/ (nazwa pliku = nazwa metody).

Wywołania moduł→moduł mają ctx.caller ustawiony przez rdzeń; getQuickShipOptions, quickShip i getTrackingStatus woła uwierzytelniony konsument kontraktu — wywołanie bez ctx.caller kończy się błędem INTERNAL_CALL_REQUIRED.

Automatyzacje

Ta sama funkcja (uploadInvoicesToAllegro) obsługuje akcję i automatyczną wysyłkę po event:core.invoicing.invoice.issued (sync.invoices); wysyłki tego samego zamówienia idą kolejno (kolejka w procesie per orderId), więc nie powstaje podwójny wpis faktury w Allegro.

Problemy i historia

Zgłoszenia w rejestrze problemów firmy (Problems, SDK ≥ 3.9.0), src/problems.js:

entityName problemu to nazwa konta (problem autoryzacji; problem kluczy aplikacji go nie ma) albo ID formularza Allegro, gdy zamówienie z niego pochodzi — ten sam identyfikator, który karta zamówienia pokazuje jako „ID Allegro”. Problemy zamówień linkują do karty zamówienia w core/orders, o ile ono istnieje; problem autoryzacji nie ma linku (formularz konfiguracji instancji to strona rdzenia, do której moduł linkować nie może).

Wpisy historii firmy (History, SDK ≥ 3.10.0, src/history.js), relacja do zamówienia:

Crony i locki

Crony startują idempotentnie top-level w index.js i ponownie w Core.onEnabled (bo onEnabled przychodzi raz na wersję instancji, a nie przy każdym starcie kontenera); Core.onDisabled je zatrzymuje i czeka na trwający przebieg.

Wysyłka dokumentów po event:core.invoicing.invoice.issued nie jest cronem — biegnie w tle przez runtime.track (src/background.js), bo rdzeń czeka na zwrot z handlera hooka, a pobranie PDF-u i żądania do Allegro trwają zbyt długo, by blokować rejestrację dokumentu w core/invoicing.

Testy

source ~/.nvm/nvm.sh && nvm use 22 && npm test

npm test uruchamia node --test --test-concurrency=1 test/*.test.js — testy node:test wymagają Node ≥ 22. SDK @orbito/api-lib jest mockowany, więc testy nie dotykają rdzenia ani sieci.

Różnice względem starego modułu (ordershub allegro)

• jedna instancja = jedno konto = jeden kontener — stary moduł obsługiwał wszystkie

instancje firmy pętlą w jednym procesie,

• odświeżanie tokenu: zamiast crona co 2 h — odświeżanie na żądanie przed wygaśnięciem

(auth.js) plus cron zapasowy co godzinę,

• event:order:statusChanged → event:order:status_changed; event:shipment:created →

event:core.shipping.shipment.created (nowe nazwy i payloady zdarzeń Orbito v2),

• „Wysyłam z Allegro” zgodne z kontraktem hubu core/shipping 2.x — tożsamością przewoźnika

jest instanceId, nie moduleId,

• usunięto stary pełny formularz nadania (createShipmentForOrder,

getShipmentDataForOrder, generateLabel, getDeliveryMethods) i nieużywany checkStatus — pełny formularz to osobny etap poza tą migracją (D8),

• usunięto hook core.orders.getImporterInfo (brak konsumenta w v2) — profil źródła

zamówień (nazwa, ikona, etykieta ID) rejestruje teraz core/orders → source.register,

• dodano obsługę anulowań (BUYER_CANCELLED, AUTO_CANCELLED) — stary moduł je ignorował,
• bez migracji danych z ordershub — konto łączy się od nowa, import startuje od

najnowszego zdarzenia (bez backfillu).

Poza zakresem tej iteracji

• Formularz wielu paczek i usług dodatkowych — obecnie formularz jednej paczki.
• Zarządzanie ofertami (stany magazynowe, ceny).
• Wiadomości i dyskusje z kupującymi, zwroty (customer-returns).
• Rynki zagraniczne Allegro (allegro.cz/.sk/.hu) poza tym, co zwraca API zamówień.

Wdrożenie

Kolejność ma znaczenie z powodu binarnego body w Core.fetch (wysyłka PDF faktur, patrz „Wymagania”):

1. Rdzeń (git pull && pm2 restart core-v2) — obsługa Buffer w fetch.js.
2. Publikacja @orbito/api-lib 3.11.0.
3. Moduł (zależność ^3.11.0), publikacja: omm publish --release, aktualizacja instancji

przez panel.

Od 1.2.0 (zmiana wymagająca działania operatora): klucze aplikacji nie są już w paczce. Przed aktualizacją instancji trzeba ustawić cztery sekrety w repozytorium modułów (omm secrets set ALLEGRO_CLIENT_ID itd., patrz „Klucze aplikacji Allegro”), a rdzeń musi obsługiwać wstrzykiwanie sekretów modułu do kontenera. Bez nich instancja zgłasza problem ALLEGRO_APP_KEYS_MISSING i nie łączy się z Allegro (import, synchronizacja i „Wysyłam z Allegro” stoją), aż sekrety pojawią się, a kontener zostanie odtworzony.