core/emag 0.1.6

Pierwsza implementacja integracji eMAG Marketplace dla Orbito. Obsługuje oddzielne instalacje dla kont i rynków RO, BG oraz HU, import zamówień realizowanych przez sprzedawcę (3P) oraz dwie ścieżki etykiet. Zapis efektów, sprawdzanie właściciela dokumentów i jawny wybór dostawców odbywają się przed nadaniem. Integracje Orbito korzystają wyłącznie z hooków.

Zakres

Basic Auth, test dostępu do zamówień i stawek VAT; hasło w polu konfiguracji secret.
Import z paginacją, krótkimi oknami czasu, trwałym kursorem i niezależną tożsamością źródła dla każdego konta. Historia nie uruchamia automatyzacji.
Link do szczegółów zamówienia w panelu sprzedawcy przez sources.order.references, także dla wcześniejszych importów i historii. Referencja sprawdza zapisane konto oraz instancję i działa przy rozłączonym API; nie pobiera danych z marketplace ani nie wymaga ponownego importu.
Opcjonalne potwierdzenie przyjęcia zamówienia dopiero po zapisanym imporcie.
Etykiety eMAG: jawny wybór aktywnego konta kurierskiego i adresu nadania; utworzenie AWB dla jednej paczki z formularza, PDF A4/A5/A6 oraz ponowne pobranie PDF przez rejestr przesyłek. Metoda labels.zpl pobiera dodatkowo ZPL.
Własne etykiety: wybór innych dostawców przewozu przez standardowe hooki; pobranie ich PDF z wybranej instancji rejestru przesyłek (labels.own.get); dodanie PDF do eMAG jako załącznika AWB (type=10) przez HTTPS (labels.own.send, także z panelu modułu).
Logo eMAG z pliku dostarczonego przez użytkownika przy źródle zamówień, przewoźniku i w panelu. Oryginalny JPG oraz bezstratnie przekodowany WebP są w assets/; logo nie jest pobierane z zewnętrznego serwera.
Diagnostyka importu, zmian zamówienia i niepewnych operacji; blokady odnawiane podczas pracy, kontrola zmian konfiguracji, ograniczanie ruchu i trwałe odczekanie po HTTP 429.
Przycisk Sprawdź dane importu odczytuje pięć zamówień od wybranego dnia, również przy wyłączonym imporcie. Podgląd pokazuje nazwy pól, kwoty finansowe i wynik kontroli przeliczeń importu, bez danych klientów, dokumentów i haseł; nie tworzy zamówień ani nie zmienia danych eMAG.

Utworzenie AWB zwraca stan waiting. Samo wygenerowanie etykiety lub dodanie załącznika nie potwierdza fizycznego przekazania paczki przewoźnikowi i nie zmienia automatycznie zamówienia na wysłane. Dla trackingu tylko udokumentowany kod DLV mapuje się na doręczenie; pozostałe kody pozostają nieznane z zachowaniem oryginalnego kodu.

Instalacja i konfiguracja

Zbuduj ZIP poleceniem omm pack -C emag-module -o release-packages/core-emag-0.1.6.zip z głównego workspace i zainstaluj go jako osobny moduł. Manifest nie deklaruje zależności od instalowalnych modułów.
W eMAG przygotuj użytkownika z prawami API i autoryzuj IP wyjściowe serwera Orbito. W Orbito zatwierdź domenę właściwego rynku: marketplace-api.emag.ro, marketplace-api.emag.bg lub marketplace-api.emag.hu. Transport wykorzystuje Core.fetch, więc liczy się IP serwera proxy, a nie komputera użytkownika ani kontenera modułu.
W bloku Połączenie eMAG zapisz rynek, login, hasło i nazwę źródła; uruchom Sprawdź połączenie. Test wykonuje odczyty. Konto i rynek wiążą się z instalacją; dla innego konta utwórz kolejną instalację. Zmiana hasła wymaga ponownego testu.
W Import zamówień wybierz konkretne ID instancji zamówień oraz rejestru przesyłek. Wybierz trzy różne statusy: nowego zamówienia, problemu i historii. Ustaw dzień rozpoczęcia w strefie danego rynku i odstęp importu. Import domyślnie jest wyłączony. Po rozpoczęciu importu instancja zamówień pozostaje związana z kontem.
VAT produktu jest odczytywany wyłącznie z products[].vat zamówienia (np. "0.2100" = 21%, "0.0000" = 0%). Każda pozycja zachowuje własną stawkę; rynek i wcześniejsze ręczne ustawienia VAT produktów nie nadpisują danych eMAG. Domyślnie VAT dostawy (również bezpłatnej) pochodzi ze wspólnej stawki pozycji tego zamówienia. Przy różnych stawkach i płatnej dostawie potrzebna jest weryfikacja albo jawna osobna stawka dostawy. Potwierdź na rzeczywistym zamówieniu, czy shipping_tax jest kwotą netto czy brutto; dla pilotażowego konta RO potwierdzono kwotę brutto.
W Etykiety i przesyłki wybierz własne umowy albo AWB eMAG. Dla AWB wybierz konto kurierskie, adres nadania, nazwę i osobę kontaktową nadawcy, telefon oraz format PDF. Dane odbiorcy i ID punktu odbioru pochodzą z zamówienia. Moduł sprawdza ograniczenia konta kurierskiego, dostawę do punktu i obsługę wysyłki zagranicznej.
Przed włączeniem automatycznego potwierdzania przyjęcia przeprowadź pilotaż: import jednego zamówienia, kontrola ceny, VAT, dostawy i pobrania, utworzenie jednej paczki oraz ponowne pobranie tego samego PDF. Import historyczny i zamówienie zmienione po imporcie nie mogą otrzymać nowego AWB.

Listy dostawców i statusów pobierane są przez hooki. Niedostępna lista zachowuje zapisane ID i pokazuje błąd. Kilka instalacji tego samego dostawcy wymaga jawnego wyboru. Zalecana jest jedna instalacja na dane konto i rynek; limity API mogą być wspólne dla kilku klientów używających tego samego konta.

Własny PDF

eMAG pobiera załącznik z podanego adresu HTTPS. Pliki w prywatnym magazynie Orbito nie mają publicznego URL, dlatego ta wersja nie publikuje ich automatycznie. Podaj dostępny dla eMAG adres pliku PDF na swoim serwerze; podpisany URL musi pozostać ważny podczas pobierania przez eMAG. Moduł nie wykonuje pobrania arbitralnego URL i nie ujawnia tokenów URL w diagnostyce.

Etykietę utworzoną przez dostawcę Orbito można pobrać z wybranego rejestru przesyłek. Dodanie PDF przez URL jest osobną operacją i nie zastępuje wymagań realizacji konkretnego zamówienia eMAG; dopuszczalność własnej umowy sprawdź dla konta, rynku i metody dostawy podczas pilotażu.

Wynik niepewny

Każda operacja importu, potwierdzenia przyjęcia, zmiany lokalnego statusu problemu, AWB i załącznika ma zapis próby przed efektem. Utrata odpowiedzi lub aplikacyjny błąd zapisu nie powodują automatycznego ponowienia. Potwierdzona zmiana statusu problemu nie jest ponawiana przy kolejnych odczytach, dzięki czemu późniejsza ręczna zmiana statusu pozostaje zachowana.

Import uzgadnia wcześniejszy zapis po tożsamości źródła przez orders.searchIds i orders.getById.
Potwierdzenie przyjęcia sprawdza bieżący status eMAG.
AWB z zapisanym identyfikatorem pobierany jest ponownie bez kolejnego nadania. Jeżeli odpowiedź nie zawierała identyfikatora, formularz pozwala podać ID istniejącej rezerwacji. Moduł sprawdza zamówienie, konto kurierskie, wagę, walutę i pobranie. Brak potwierdzenia oznacza konieczność sprawdzenia w panelu eMAG, a nie ponowienie.
Własny PDF uzgadnia istniejący załącznik po URL, nazwie i typie. Niepotwierdzony zapis tego samego załącznika blokuje ponowienie.

Nie kasuj zapisów prób, aby wymusić ponowienie: może to utworzyć drugą przesyłkę. Zmiana adresu URL jest nową, jawną operacją dodania załącznika.

Kontrakty i uprawnienia

Dostawca zamówień musi oferować orders.import.capabilities z protokołem 1 i flagami idempotentImport, historyWithoutAutomations, marketplaceProductData. Moduł konsumuje również orders.create, orders.getById, orders.searchIds, orders.source.register, orders.status.search, orders.updateStatus. Rejestr przesyłek udostępnia shipping.shipments.search, shipping.shipments.getById, shipping.shipments.getLabel.

Moduł publikuje shipping.source.getCarrierSelection i kontrakty shipping.carrier: getPackingCapabilities, getQuickShipOptions, getShipmentForm, createShipment, generateLabels, getTrackingStatus. Definicję przewoźnika dostarcza wkładem core.shipping.getCarrier. Formularz wiąże się z metodą konsumenta przez contractSubmit.

Panel i zarządzanie wymagają emag.manage. Hooki przewoźnika wymagają uwierzytelnionego kontekstu oraz shipments.view lub shipments.edit. labels.own.get wymaga także orders.view; labels.own.send wymaga emag.manage, orders.view, shipments.edit. Kontekst i uprawnienia nie są przyjmowane z payloadu.

Ograniczenia pierwszej wersji i weryfikacja

Wyłącznie zamówienia 3P; brak FBE, RMA, eksportu ofert, synchronizacji stanów/cen, faktur i automatycznych zmian statusu wysyłki.
Jedna paczka w formularzu; nadanie z planu pakowania nie jest dostępne. Nie jest wybierane domyślne konto kurierskie.
Niekompletne lub nieopłacone zamówienia czekają. Brak lub niepoprawny VAT, odwrotne obciążenie, rabaty, vouchery, kaucje i częściowe anulowania wymagają weryfikacji i nie są automatycznie importowane z szacowanymi kwotami.
Kod pocztowy dostawy jest opcjonalny w eMAG. Brak pozostaje pusty i ma ostrzeżenie w danych importu; nie jest kopiowany z adresu faktury ani zgadywany. Dostawca etykiety może wymagać jego uzupełnienia.
Anulowanie, zwrot lub zmiana pozycji/adresu po imporcie kieruje zamówienie do statusu problemu i blokuje AWB. Moduł nie nadpisuje lokalnych korekt cen lub odbiorcy.
Użyto oficjalnej specyfikacji OpenAPI 4.5.2, endpointów /api-3 i starszego PDF 4.4.4 jako uzupełnienia. Odpowiedzi zapisu AWB i ZPL nie mają pełnego schematu wynikowego. Obsługiwane są jednoznaczne results:[{reservation_id:...}] lub results:[{emag_id:...}] dla AWB i results:["base64..."] dla ZPL; inna postać kończy się kontrolowanym błędem. Nie zgadujemy identyfikatora rezerwacji z liczby bez nazwy pola.
Weryfikacja lokalna używa atrap API i rzeczywistych helperów hooków. Na koncie pilotażowym potwierdzono odczyt API eMAG.ro, pole products[].vat oraz zgodność kwot API z panelem: 2 × 35.7000 netto przy VAT 0.2100 daje 2 × 43.20 brutto; dostawa 19.99 i suma 106.39 RON. API nie podaje osobnej stawki VAT dostawy w tej odpowiedzi; reguła wspólnej stawki jest polityką importu, nie dodatkowym polem API. Na tym koncie potwierdzono import rzeczywistych zamówień do Orbito od 2026-10-01 i mapowanie zakończonych zamówień na istniejący status „Dostarczone”. Tryb importu historycznego pomija automatyzacje niezależnie od nazwy wybranego statusu. Włączono import co 5 minut, własne umowy i VAT dostawy ze wspólnej stawki pozycji (również dla kosztu 0); automatyczne potwierdzanie przyjęcia pozostaje wyłączone. Nadania i przesłania własnego PDF nie sprawdzano na produkcji.

Testy: npm ci, npm test, npm run check w katalogu modułu oraz node --test --test-concurrency=1 --test-force-exit module-contracts/*.test.js z głównego workspace. Testy sprawdzają alternatywnych dostawców, kilka instalacji, brak dostawcy, stratę odpowiedzi, brak ponownego efektu, rozdzielenie kont, finanse, wybór przewoźnika, własne etykiety, uprawnienia i start bez konfiguracji.

Źródła: aktualna dokumentacja API eMAG, oficjalny PDF 4.4.4, analiza wymagań i zagrożeń. Analiza opisuje projekt przed implementacją; aktualny zakres wersji 0.1.6 przedstawia ten README.