Jak zautomatyzować import ładunków z Amazona do systemu TMS przy użyciu N8N?

N8N to open-source’owa platforma do automatyzacji procesów, która pozwala łączyć systemy, API i bazy danych przez wizualny edytor przeciągnij-upuść z możliwością pisania JavaScriptu, gdy logika robi się bardziej złożona. Działa na własnej infrastrukturze, bez uzależnienia od zewnętrznych chmur. W kontekście danych logistycznych przetwarzanych w dużej skali ta różnica jest istotna.

Ten artykuł opisuje, czym jest N8N, dlaczego wybraliśmy to narzędzie i jak za jego pomocą rozwiązaliśmy konkretny problem: klient systemu zarządzania transportem TMS wprowadzał ładunki z Amazona ręcznie, jeden po jednym, codziennie.

Czym jest N8N?

N8N to platforma automatyzacji oparta na wizualnych blokach-konektorach. Każdy blok robi jedną rzecz: odczytuje plik, wywołuje API, uruchamia fragment kodu, wysyła wiadomość na Slacka. Bloki łączysz w kolejności i masz workflow. Biblioteka integracji obejmuje Google Workspace, Microsoft 365, AWS, Slack, standardowe REST API i większość popularnych baz danych.

Dwie rzeczy odróżniają N8N od alternatyw takich jak Zapier czy Make.

Po pierwsze, jest open-source i można go postawić na własnym serwerze. Jeśli Twoja firma ma wymagania dotyczące miejsca przechowywania danych albo uruchamiasz automatyzacje przy dużej liczbie requestów, posiadanie własnej infrastruktury zmienia rachunek ekonomiczny. Narzędzie chmurowe rozliczające się per-egzekucja potrafi być kosztowne przy tysiącach ładunków miesięcznie.

Po drugie, N8N jest użyteczny dla deweloperów. Osoby bez doświadczenia technicznego mogą budować proste automatyzacje bez kodu, ale gdy potrzebujesz prawdziwej logiki:  transformacji danych, obsługi błędów, pętli, warunkowych rozgałęzień  możesz pisać JavaScript bezpośrednio w bloku kodu. W tej kategorii narzędzi to rzadkość.

N8N vs Zapier vs Make – najważniejsze różnice

Wybór N8N ma sens, gdy masz wymagania dotyczące danych albo potrzebujesz logiki, która wykracza poza proste reguły if-then. Zapier i Make wygrywają prostotą przy standardowych, liniowych automatyzacjach.

Problem: Amazon nie udostępnia API

Jeden z klientów FireTMS – systemu TMS z 14 000 aktywnych użytkowników w 10 krajach i ponad 8,5 miliona zleceń obsłużonych przez platformę — zarządza ładunkami pozyskiwanymi przez platformę transportową Amazona. Kluczowe ograniczenie, które zdeterminowało wszystko: Amazon nie ma publicznego API dla danych o ładunkach. Jedyną drogą wyprowadzenia tych danych jest pobranie eksportu w formacie CSV.

Ten plik CSV zawierał wszystko potrzebne do utworzenia ładunku w FireTMS: miejsce załadunku, adres dostawy, dane kierowcy, szczegóły towaru, cenę. FireTMS nie miał jednak natywnego importu CSV. Pracownik klienta wprowadzał więc każdy ładunek ręcznie.

Przy 100 ładunkach na import to kilka godzin kopiowania danych dziennie. A przy takim rytmie błędy są nieuniknione: przestawiona cyfra w cenie, zły identyfikator miejsca odbioru, brakujące wymagane pole. W systemie TMS takie błędy nie zostają jako problem z danymi — stają się błędami tras, sporami fakturowymi i zgłoszeniami do supportu.

Klient był wystarczająco sfrustrowany, żeby rozważać rezygnację z FireTMS. To był rzeczywisty kontekst biznesowy dla tej automatyzacji.

Jak działa automatyzacja?

Workflow składa się z pięciu etapów.

Formularz webowy. N8N dostarcza natywny komponent formularza. Zbudowaliśmy prosty formularz, w którym klient wgrywa plik CSV z Amazona, podaje swój NIP i klucz API do FireTMS. Na tym etapie uruchamia się walidacja – pliki o nieprawidłowym formacie nie przechodzą dalej.

Parsowanie CSV. N8N odczytuje wgrany plik przez dedykowany blok, ale samo rozbicie na pojedyncze obiekty ładunków wymaga wyklikania odpowiedniej opcji i dopisania kawałka kodu w JavaScript. To nie jest w pełni natywne rozwiązanie, wymaga konfiguracji.

Transformacja danych. Tu jest sedno i typowy przykład zadania z obszaru automatyzacji przetwarzania danych. Amazon używa wewnętrznych identyfikatorów dla miejsc załadunku i rozładunku coś w stylu „RDS2” dla konkretnego magazynu. FireTMS potrzebuje pełnego adresu, nie kodu Amazona. Zbudowaliśmy warstwę mapowania, która tłumaczy te ID-ki na podstawie słownika utrzymywanego po stronie FireTMS. Tu działa też normalizacja cen: Amazon czasem wysyła ładunki z wartością zero, które domyślnie ustawiamy na 0 EUR i flagujemy. Cała logika transformacji to około 100 linii JavaScriptu w jednym bloku kodu N8N.

Wywołania API FireTMS. FireTMS zbudował dedykowany endpoint API na potrzeby tego projektu  ich standardowe API nie obsługiwało tworzenia ładunków z zewnątrz. To klasyczny przypadek, gdzie integracja dwóch systemów wymaga pracy po obu stronach: my zbudowaliśmy workflow, oni udostępnili endpoint. Jedno ograniczenie z ich strony: system przetwarza tylko jeden request naraz. Ustawiliśmy 2-sekundowe opóźnienie między requestami korzystając z mechanizmu batchingu w N8N. Przy 100 ładunkach to 3-4 minuty łącznego czasu przetwarzania.

Obsługa błędów i raportowanie. Wszystkie ładunki są przetwarzane sekwencyjnie. Po zakończeniu workflow przekierowuje do jednego z trzech formularzy odpowiedzi, zależnie od wyniku.

Obsługa błędów: tu leży większość pracy

Jeśli import przebiegł bezbłędnie klient widzi stronę potwierdzenia.

Jeśli pojawiły się błędy typu „nieznany place ID” Amazon przesłał kod lokalizacji, którego FireTMS nie rozpoznaje, klient dostaje komunikat z listą nieznanych ID-ków i informacją, żeby skontaktować się z FireTMS w celu ich dodania do bazy. Logujemy je równolegle w Google Sheets z timestampem i kodami błędów, żebyśmy mogli zbiorowo przesyłać brakujące lokalizacje do FireTMS.

W przypadku innych błędów, brakujące pola wymagane, duplikaty jest trzeci formularz z podziałem na to, co się nie udało i dlaczego.

Kwestia duplikatów jest warta wyjaśnienia. Na początku, jeśli klient przesłał ponownie CSV zawierający już zaimportowane ładunki, FireTMS tworzył duplikaty. Klient musiał wchodzić do systemu i ręcznie je usuwać. FireTMS rozwiązał to po swojej stronie, używając VRID Amazona (zewnętrzny identyfikator ładunku) jako klucza deduplicji. Jeśli ładunek z danym VRID już istnieje, jest pomijany.

Jedna rzecz jest jeszcze w toku. Kiedy z 150 ładunków 50 się nie importuje, klient dostaje listę błędów w formularzu, co nie jest najwygodniejsze do obsługi. Planujemy zwracać plik CSV z błędnymi ładunkami i dodatkową kolumną z kodem błędu. Klient poprawia tylko te wiersze i przesyła ponownie, bez dotykania ładunków, które już trafiły do systemu.

Co to dało?

Czas poświęcany na import ładunków skrócił się z kilku godzin do czasu potrzebnego na wgranie pliku i 3-4 minuty przetwarzania.

Dla FireTMS automatyzacja rozwiązała problem utrzymania klienta. Duży klient ryzykujący odejście, bo ręczny import sprawiał, że system wydawał się niekompletny został, bo problem zniknął.

Jest też argument skalowalności: jeśli wolumen ładunków klienta się podwoi, czas przetwarzania rośnie liniowo wraz z opóźnieniem batchingu, nie z liczbą pracowników. Dodanie kolejnego klienta do tego workflow to zduplikowanie workflow i podmiana danych uwierzytelniających.

Czego N8N nie rozwiązuje dobrze

Obserwowalność jest szczerym ograniczeniem. Wbudowana historia egzekucji w N8N jest wystarczająca do debugowania jednego workflow z garstką klientów. Przestaje wystarczać, gdy potrzebujesz przeszukiwać logi między wieloma workflow, agregować wzorce błędów albo ustawiać alerty. Przy produkcie obsługującym wielu klientów warto od początku podpiąć zewnętrzne logowanie.

Równoległa egzekucja na wspólnym serwerze wymaga osobnego przemyślenia. Jeśli dwóch użytkowników prześle pliki jednocześnie do workflow z 2-sekundowym opóźnieniem między requestami, requesty się zderzą. N8N tym nie zarządza automatycznie. Przy jednym kliencie to nie problem. Przy produkcie multi-tenant, potrzebna jest strategia kolejkowania.

Runtime Pythona jest jeszcze w wersji beta. Jeśli Twoja logika transformacji naturalnie trafia się w Pythona N8N nie jest jeszcze gotowy produkcyjnie na tym froncie.

Następna automatyzacja

Amazon wysyła powiadomienia o anulowaniu ładunków mailem. Teraz ktoś musi te maile czytać i ręcznie anulować ładunki w FireTMS.

Plan: N8N nasłuchuje na dedykowaną skrzynkę Gmail, workflow odpala się na nowe wiadomości od Amazona, wyciągamy VRID z treści maila i wywołujemy endpoint anulowania w FireTMS. Struktura workflow jest już naszkicowana, chodzi głównie o właściwe parsowanie maili i potwierdzenie zachowania API przed wdrożeniem na produkcję.

Podsumowanie

N8N sprawdził się tutaj z jednego prostego powodu: problem nie był skomplikowany technicznie, ale wymagał elastyczności. Połączenia pliku CSV, zewnętrznego API z ograniczeniami i sensownej obsługi błędów dla końcowego użytkownika. Pisanie tego od zera w Pythonie dałoby ten sam efekt, ale z większym kosztem utrzymania i mniejszą przejrzystością dla kogoś, kto przejmuje projekt.

Nie każda automatyzacja potrzebuje N8N. Ale jeśli masz manualny proces, który opiera się głównie na przesyłaniu danych między systemami, warto sprawdzić, czy nie da się go zamknąć w kilku blokach zamiast w kilkuset liniach kodu.

W Fireup.pro budujemy integracje i automatyzacje procesów dla firm z obszaru logistyki, fintechu i healthcare. Jeśli masz podobny problem – API dostawcy, które nie do końca pasuje do Twojego systemu, albo manualny proces, który zaczyna kosztować więcej niż powinien – porozmawiajmy.