Amazon dla Orbito — 1.4.0

Tryb testowy: instrukcja Sandbox. Sandbox korzysta z osobnej aplikacji testowej, której dane (Client ID, Client Secret, Sandbox Refresh Token) są sekretami platformy AMAZON_SANDBOX_*; testuje statyczne przykłady Amazon, bez tworzenia dokumentów operacyjnych.

Moduł core/amazon importuje zamówienia Amazon FBM do Orbito, potwierdza wysyłkę numerem trackingowym z modułów kurierskich oraz przekazuje PDF faktury z centralnego rejestru core/invoicing (w tym wFirma).

W produkcji sprzedawca klika Zaloguj w Amazon, loguje się w Seller Central i udziela zgody. Nie kopiuje tokenów ani kluczy aplikacji. Aplikację Orbito rejestruje w Amazon administrator platformy, a jej klucze (LWA) są sekretami platformy — firma ich nie wpisuje. Powrót z Seller Central odbiera rdzeń Orbito (bilet OAuth, SDK 4.2.0): w aplikacji Amazon rejestruje się adres https://v2.orbito.pl/api/oauth/callback (produkcja Orbito). Moduł nie wymaga własnej strony powrotu ani konfiguracji serwera WWW.

Wdrożenie produkcyjne

1. Przygotuj aplikację Amazon.
2. Zainstaluj ZIP modułu w Orbito. Wymagane: aktualne core/orders, core/shipping, core/invoicing, działający moduł wFirma, rdzeń z biletami OAuth (SDK 4.2.0) i binarnym Core.fetch oraz front z akcją OVE redirect. Manifest sam nie instaluje zależności.
3. Klucze aplikacji ustawia autor modułu w repozytorium modułów: omm secrets set AMAZON_APP_ID (oraz AMAZON_CLIENT_ID, AMAZON_CLIENT_SECRET, AMAZON_APP_BETA). Rdzeń wstrzykuje je do ENV kontenera przy starcie. AMAZON_APP_BETA=yes dla aplikacji Draft (version=beta), no po publikacji; brak wartości oznacza no. Brak któregoś z trzech kluczy: moduł nie pada, przy starcie zgłasza problem AMAZON_APP_KEYS_MISSING w rejestrze problemów firmy (zamykany przy starcie z kompletem kluczy), a logowanie zwraca ten sam kod. Sandbox ma osobne sekrety AMAZON_SANDBOX_CLIENT_ID, AMAZON_SANDBOX_CLIENT_SECRET, AMAZON_SANDBOX_REFRESH_TOKEN (patrz instrukcja Sandbox); ich brak w instancji Sandbox to problem AMAZON_SANDBOX_KEYS_MISSING. Każde środowisko wymaga tylko własnego kompletu.
4. Nadaj uprawnienie amazon.manage. Otwórz stronę Amazon w ustawieniach, kliknij logowanie i połącz konto. „Sprawdź dostępne rynki” pokaże rynki konta.
5. Wybierz różne statusy: nowe, anulowane/wstrzymane i fizycznie wysłane. Ustaw mapowanie przewoźników. Domyślne rynki: DE A1PA6795UKMFR9, PL A1C3SOZRARQ6R3. Synchronizacja jest początkowo wyłączona.
6. Wykonaj test uruchomieniowy, a następnie włącz synchronizację.

Zakres

• Orders API 2026-01-01: przyrostowe wyszukiwanie z paginacją i zapisywanym oknem importu. Błędy pojedynczych zamówień są zapamiętywane i ponawiane.
• Jedno konto i region na instancję. Rynki wybierane identyfikatorami; DE i PL domyślnie. Regiony EU, NA, FE mają osobne endpointy i zgodę OAuth. Dodanie kolejnego regionu wymaga kolejnej instancji.
• Import danych odbiorcy, produktów/SKU, cen, VAT, dostawy i danych do faktury, o ile uprawnienia Amazon je udostępniają. Kwoty są sprawdzane. Brak wiarygodnego VAT lub niespójność nie tworzy błędnego zamówienia.
• Brak domyślnego założenia „zapłacone”: wpływy i rozliczenia Amazon nie są w zakresie tego wydania.
• Potwierdzenie wysyłki confirmShipment: przewoźnik, usługa, tracking, faktyczna data oraz pozycje. Automatycznie dopiero po ustawionym statusie wysyłki. PDF etykiety nie jest wysyłany do Amazon.
• Automatyczny upload faktury VAT z wFirma przez UPLOAD_VAT_INVOICE w regionie EU. Przyjęcie potwierdza dopiero raport przetwarzania. Samo HTTP 200 ani feedId nie oznacza akceptacji dokumentu.
• Trwała kolejka, odnawiane blokady, powtórzenia z opóźnieniem, oddzielenie kont, karta na zamówieniu i diagnostyka na stronie Amazon.

Świadome ograniczenia pierwszej wersji

Automatyczna wysyłka obejmuje jedno nadanie z jedną paczką na całe zamówienie. Wiele nadań wymaga jawnego podziału pozycji przez shipments.queue; nadanie wielopaczkowe bez osobnych numerów trackingowych nie jest automatycznie rozdzielane. Pierwszy import już częściowo wysłanego zamówienia jest blokowany do ręcznej weryfikacji.

Upload faktur nie jest dostępny globalnie: użyty interfejs Amazon działa w programie VAT/EU. VCS z własnymi dokumentami wymaga ręcznego podania metadanych wysyłki i kwot z Amazon przez invoices.queue. Brak tych danych w wFirma blokuje automatyczny upload w trybie VCS. Gdy fakturę wystawia Amazon (w tym Invoice by Amazon), moduł jej nie wysyła.

Pozycje z niejednoznacznymi rabatami/podatkiem, opłatami za pakowanie prezentowe, COD lub różnicą groszową niemożliwą do zapisania jako cena jednostkowa zatrzymują import z komunikatem. Jawne stawki zastępcze VAT można skonfigurować tylko dla jednolitego, zweryfikowanego asortymentu danego rynku. Moduł nie wyznacza stawek na podstawie kraju dostawy.

Po imporcie aktualizowany jest stan Amazon i anulowanie/wstrzymanie; zmiany produktów i adresu już utworzonego zamówienia wymagają obsługi operatora. Nie ma FBA, Ship+, korekt, zwrotów, zakupów etykiet Amazon, ofert, magazynu ani rozliczeń finansowych.

Rozwój i pakowanie

Uruchamiaj z pełnego repozytorium źródłowego (testy nie są częścią ZIP instalacyjnego). Node.js 20+ oraz dostęp do rejestru npm Orbito:

Lokalnie (omm dev) klucze aplikacji czytane są z pliku .env w katalogu modułu — skopiuj .env.example. Plik .env jest poza Git i poza paczką.

npm ci
npm test
npm run check
omm pack --dry-run
omm pack -o ../release-packages/core-amazon-1.4.0.zip

Testy wykorzystują atrapy Amazon/Orbito, obejmując m.in. OAuth, izolację kont, deduplikację, przerwanie po zapisie zamówienia i utratę odpowiedzi createFeed. Nie zastępują próby na autoryzowanym koncie Amazon. Wydanie nie było testowane przez sieć z danymi aplikacji Sandbox ani z kontem produkcyjnym; testy połączenia wykonuje się po konfiguracji.

Kontrakty i eksploatacja · Rejestracja aplikacji · Test uruchomieniowy