Transport CSV Import

PL: Instrukcja importu transportów z pliku CSV

Overview / Przegląd

The CSV import creates transport drafts in bulk and optionally triggers a SENT workflow for each successfully imported row. PL: Import CSV pozwala na zbiorcze tworzenie szkiców transportów z opcjonalnym wyzwoleniem zgłoszenia SENT dla każdego poprawnie zaimportowanego wiersza.

Entry points / Punkty wejścia:

UI path	PL opis
`Administracja → Data import → Import transportów CSV`	Widok administracyjny
`Dodaj z innego źródła → Import transportów z CSV`	Lista transportów

Import Flow / Przebieg importu

Download the template — use the "Pobierz szablon" button on the import screen to get a CSV with the correct column order and a sample row.
PL: Pobierz szablon — kliknij "Pobierz szablon", aby uzyskać plik z właściwą kolejnością kolumn i przykładowym wierszem.
Fill in rows — one row per transport. Do not change or reorder header names.
PL: Wypełnij wiersze — jeden wiersz = jeden transport. Nie zmieniaj ani nie przestawiaj nazw nagłówków.
Upload and preview — the preview validates every row and returns errors and warnings without saving anything.
PL: Prześlij i podejrzyj — podgląd waliduje każdy wiersz i zwraca błędy/ostrzeżenia bez zapisywania danych.
Set a default post-action (optional) — applied to rows that leave the postAction column blank.
PL: Ustaw domyślną akcję wysyłki (opcjonalnie) — stosowana do wierszy, które nie definiują postAction.
Execute import — rows without errors are saved as drafts. Rows with errors are skipped (or the entire import is stopped when the "stop on first error" option is active).
PL: Wykonaj import — wiersze bez błędów zostają zapisane jako szkice. Wiersze z błędami są pomijane (lub cały import zatrzymuje się, gdy opcja "zatrzymaj przy błędzie" jest aktywna).

File Format / Format pliku

Property	Value
Delimiter / Separator	`;` (semicolon)
Quotes / Cudzysłowy	supported / obsługiwane
Encodings / Kodowanie	UTF-8, Windows-1250
Header row / Wiersz nagłówka	required, row 1 / wymagany, wiersz 1
One row =	one transport / jeden transport

Header names are case-insensitive and whitespace-tolerant — SenderName, sendername, and sender name are all equivalent.
PL: Nazwy nagłówków są nierozróżniające wielkości liter i tolerują spacje — SenderName, sendername i sender name są sobie równoważne.

Post-Actions / Akcje wysyłki

The postAction column controls what happens after a draft is created.
PL: Kolumna postAction steruje tym, co dzieje się po utworzeniu szkicu.

Value	PL nazwa	Description / Opis
`None`	Brak	Draft only; no SENT message is sent. / Tylko szkic; żadna wiadomość SENT nie jest wysyłana.
`Sent100`	SENT 100	Start of transport notification. Source coordinates required. / Zgłoszenie rozpoczęcia transportu. Wymagane współrzędne miejsca załadunku.
`Sent105`	SENT 105	Full transport notification. Both location coordinates and driver data required. / Pełne zgłoszenie. Wymagane współrzędne obu lokalizacji i dane kierowcy.
`Sent200`	SENT 200	End of transport notification. Destination coordinates required. / Zgłoszenie zakończenia transportu. Wymagane współrzędne miejsca dostawy.

If communication with PUESC fails after import, the system preserves the locally-created draft instead of rolling back the row.
PL: Jeśli komunikacja z PUESC nie powiedzie się po imporcie, system zachowuje lokalnie utworzony szkic zamiast cofać cały wiersz.

Column Reference / Opis kolumn

Legend / Legenda:

M — Mandatory / Wymagane
O — Optional / Opcjonalne
C — Conditional (depends on other fields or post-action) / Warunkowe

1. Transport

Column	Status	Format / Values	PL Opis	EN Description
`name`	M	text	Nazwa transportu, unikalny identyfikator w imporcie	Transport name, unique identifier in the import
`transportType`	M	`National` `Import` `Export` `Transit` `Railway` `National_Export`	Rodzaj transportu	Transport type
`postAction`	O	`None` `Sent100` `Sent105` `Sent200`	Akcja po imporcie; jeśli puste, stosowana jest wartość domyślna z UI	Post-import action; blank = UI-level default is used
`plannedStartDate`	M	`yyyy-MM-dd`	Planowana data rozpoczęcia	Planned start date
`startDate`	M	`yyyy-MM-dd`	Faktyczna data rozpoczęcia	Actual start date
`endDate`	M	`yyyy-MM-dd`	Data zakończenia transportu	End date of transport
`transportDocumentType`	C	PUESC CDT code e.g. `CMR`	Rodzaj dokumentu przewozowego. Wymagane dla `Sent105`	Transport document type. Required for `Sent105`
`transportDocumentReference`	M	text	Numer/referencja dokumentu przewozowego	Transport document reference number
`remarks`	O	text	Uwagi	Remarks

Date formats accepted / Obsługiwane formaty dat:
yyyy-MM-dd· yyyy-MM-ddTHH🇲🇲ss· yyyy-MM-ddTHH🇲🇲ssZ

⚠️ Auto-correction / Automatyczna korekta dat: If a date is in the past, the system automatically sets it to today's date while preserving the original time component, and adds a warning to the row result.
PL: Jeśli data jest przeszła, system automatycznie ustawia ją na dzisiejszą datę (zachowując składnik czasu) i dodaje ostrzeżenie do wyniku wiersza.

2. Sender / Nadawca (`sender*`)

Column	Status	Format / Values	PL Opis	EN Description
`senderName`	M	text	Nazwa firmy nadawcy	Sender company name
`senderCode`	M	text, max ~20 chars	Wewnętrzny kod firmy	Internal company code
`senderTraderIdentityType`	M	see below	Typ identyfikatora podmiotu	Trader identity type
`senderTraderIdentityNumber`	M	text	Numer NIP / VAT-UE / inny	Identity number (NIP / VAT-UE / other)
`senderCountryCode`	M	ISO 3166-1 alpha-2, e.g. `PL`	Kod kraju	Country code
`senderPostalCode`	M	text	Kod pocztowy	Postal code
`senderCity`	M	text	Miasto	City
`senderStreet`	M	text	Ulica	Street
`senderHouseNumber`	M	text	Numer domu	House number
`senderFlatNumber`	O	text	Numer lokalu	Flat / unit number
`senderEmailAddress`	O	email	Adres e-mail	Email address
`senderPhoneNumber`	O	text, e.g. `+48500100100`	Numer telefonu	Phone number

TraderIdentityType values / Wartości typu identyfikatora:

Value	PL Opis	EN Description
`NIP`	NIP (PL tax number)	Polish tax identification number
`VATUE` or `VAT-UE`	Numer VAT-UE	EU VAT number
`INNY`	Inny identyfikator	Other identifier
`PESEL`	PESEL	Polish personal ID number
`DO`	Dowód osobisty	Personal identity document
`KS`	Karta stałego pobytu	Permanent residency card
`PJ`	Paszport — podmiot jednostki	Passport — legal entity
`PS`	Paszport — osoba fizyczna	Passport — natural person

3. Recipient / Odbiorca (`recipient*`)

Same field structure as Sender. Replace sender prefix with recipient.
PL: Taka sama struktura pól jak dla nadawcy. Zamień prefiks sender na recipient.

Column	Status	Notes
`recipientName`	M
`recipientCode`	M
`recipientTraderIdentityType`	M	Same values as senderTraderIdentityType
`recipientTraderIdentityNumber`	M
`recipientCountryCode`	M
`recipientPostalCode`	M
`recipientCity`	M
`recipientStreet`	M
`recipientHouseNumber`	M
`recipientFlatNumber`	O
`recipientEmailAddress`	O
`recipientPhoneNumber`	O

4. Carrier / Przewoźnik (`carrier*`)

Same field structure as Sender. Replace sender prefix with carrier.
PL: Taka sama struktura jak dla nadawcy. Prefiks carrier.

Column	Status	Notes / PL Uwagi
`carrierName`	M
`carrierCode`	M
`carrierTraderIdentityType`	M
`carrierTraderIdentityNumber`	M
`carrierCountryCode`	M
`carrierPostalCode`	M
`carrierCity`	M
`carrierStreet`	M
`carrierHouseNumber`	M
`carrierFlatNumber`	O
`carrierEmailAddress`	O	Wymagane przez PUESC dla SENT; w razie braku: ostrzeżenie i reset flagi przewoźnika / Required by PUESC for SENT; if missing: warning and carrier flag reset
`carrierPhoneNumber`	O

⚠️ carrierEmailAddress — if left blank, the system adds a warning and clears the carrier flag for PUESC purposes. It is strongly recommended to always provide it.
PL: carrierEmailAddress — jeśli puste, system dodaje ostrzeżenie i zeruje flagę przewoźnika dla PUESC. Zdecydowanie zalecane jest zawsze uzupełniać to pole.

5. Source Location / Miejsce załadunku (`source*`)

Column	Status	Notes / PL Uwagi
`sourceName`	O	Auto-generated from City+Street+HouseNumber if blank. / Generowane automatycznie z Miasto+Ulica+Nr jeśli puste.
`sourceCountryCode`	M	e.g. `PL`
`sourcePostalCode`	M
`sourceCity`	M
`sourceStreet`	M
`sourceHouseNumber`	M
`sourceFlatNumber`	O
`sourceCodeTerc`	M	TERYT code (required always for source). / Kod TERYT (zawsze wymagany dla miejsca załadunku).
`sourceLatitude`	C	Decimal, e.g. `51.1853770`. Required for `Sent100`, `Sent105`. Warning-only for `None`, `Sent200`. / Dziesiętny. Wymagane dla `Sent100`, `Sent105`.
`sourceLongitude`	C	Decimal, e.g. `18.6487120`. Same conditions as Latitude. / Te same warunki co Latitude.

6. Destination Location / Miejsce dostawy (`destination*`)

Column	Status	Notes / PL Uwagi
`destinationName`	O	Auto-generated if blank. / Generowane automatycznie jeśli puste.
`destinationCountryCode`	M
`destinationPostalCode`	M
`destinationCity`	M
`destinationStreet`	M
`destinationHouseNumber`	M
`destinationFlatNumber`	O
`destinationCodeTerc`	C	Required only when `destinationCountryCode = PL`. / Wymagane tylko gdy `destinationCountryCode = PL`.
`destinationLatitude`	C	Required for `Sent105`, `Sent200`. Warning-only for `None`, `Sent100`. / Wymagane dla `Sent105`, `Sent200`.
`destinationLongitude`	C	Same conditions as Latitude. / Te same warunki co Latitude.

Coordinate rules summary / Podsumowanie wymagań współrzędnych:

postAction	sourceLatitude/Longitude	destinationLatitude/Longitude
`None`	optional (warning if missing)	optional (warning if missing)
`Sent100`	required (error)	optional (warning if missing)
`Sent105`	required (error)	required (error)
`Sent200`	optional (warning if missing)	required (error)

When coordinates produce a warning (not an error), the system defaults the missing value to 0 to allow downstream XML processing.
PL: Gdy brak współrzędnych generuje ostrzeżenie (nie błąd), system ustawia brakującą wartość na 0, aby umożliwić dalsze przetwarzanie XML.

7. Driver / Kierowca (`driver*`)

Driver fields are collectively optional — if all fields are blank, no driver is attached and no warning is issued.
If at least one driver field is filled, all five required driver fields must also be provided.
PL: Pola kierowcy są zbiorczo opcjonalne — jeśli wszystkie są puste, kierowca nie jest dołączany i nie ma ostrzeżenia. Jeśli choć jedno pole jest wypełnione, wszystkie pięć wymaganych pól kierowcy musi być obecnych.

Column	Status	Notes / PL Uwagi
`driverFirstName`	C*	Required. PL: Wymagane
`driverLastName`	C*	Required. PL: Wymagane
`driverEmail`	O
`driverPhoneNumber`	O
`driverTruckVrn`	C*	Truck licence plate. Required. / Numer rejestracyjny ciągnika. Wymagane
`driverTrailerVrn`	O	Trailer licence plate. / Numer rejestracyjny naczepy.
`driverRoadPermitReference`	C*	Road permit number. Required. / Numer zezwolenia drogowego. Wymagane
`driverTruckGeoLocatorNumber`	C*	Geolocation device ID (primary). Required. / ID urządzenia geolokalizacji (główne). Wymagane
`driverTruckFailoverGeoLocatorNumber`	O	Geolocation device ID (fallback). / ID urządzenia geolokalizacji (zapasowe).

* = required only when any driver field is populated (see behaviour table below)

Driver validation behaviour / Zachowanie walidacji kierowcy:

Scenario / Scenariusz	Sent105	Other postAction
All driver fields blank	no action	no action
Some required fields missing	error (row blocked)	warning (driver omitted from draft)
All required fields present	driver attached	driver attached

8. Transport Item / Pozycja towarowa (`item*`)

Column	Status	Format / Values	PL Opis	EN Description
`itemName`	M	text	Nazwa towaru	Goods name
`itemCnCode`	M	CN code string, e.g. `2710`	Kod CN towaru	CN goods code
`itemPkwiuCode`	O	text, e.g. `19.20.26`	Kod PKWiU (usługi)	PKWiU service classification code
`itemQuantity`	M	decimal, e.g. `1000` or `1000.5`	Ilość towaru	Goods quantity
`itemUnitOfMeasureCode`	M	unit code, e.g. `l`, `kg`, `t`	Jednostka miary	Unit of measure code
`itemGrossWeight`	O	decimal	Masa brutto (kg)	Gross weight (kg)
`itemWasteCode`	O	text	Kod odpadów (jeśli dotyczy)	Waste code (if applicable)
`itemVatRateCode`	O	text	Kod stawki VAT	VAT rate code
`purposeOfTheGoods`	O	text	Przeznaczenie towaru	Purpose of the goods
`itemComments`	O	text	Komentarz do pozycji	Item-level comments

Decimal format / Format liczb dziesiętnych: Both . (dot) and , (comma) are accepted as decimal separators. Thousands-separator variants are also handled.
PL: Akceptowane są zarówno . (kropka), jak i , (przecinek) jako separator dziesiętny.

Validation Summary / Podsumowanie walidacji

Type	PL Nazwa	Behaviour
Error / Błąd	Błąd	Row is invalid. The import skips it (or stops entirely if "stop on first error" is set). / Wiersz jest nieprawidłowy. Import pomija go (lub zatrzymuje się przy opcji "zatrzymaj przy błędzie").
Warning / Ostrzeżenie	Ostrzeżenie	Row is valid and is saved, but something was corrected or is incomplete. Listed in preview and execute results. / Wiersz jest poprawny i zostaje zapisany, ale coś zostało skorygowane lub jest niekompletne.

Common error causes / Częste przyczyny błędów:

Missing required field / Brak wymaganego pola
Invalid date format / Nieprawidłowy format daty
Unknown transportType or postAction value / Nieznana wartość transportType lub postAction
Unknown transportDocumentType code not found in PUESC CDT list / Nieznany kod transportDocumentType (nie znaleziony na liście PUESC CDT)
Missing coordinates for a post-action that requires them / Brak współrzędnych wymaganych dla danej akcji SENT
Missing driver fields when postAction = Sent105/ Brak danych kierowcy dla postAction = Sent105
destinationCodeTerc missing when destination is in Poland / Brak destinationCodeTerc gdy miejsce dostawy jest w Polsce
Invalid decimal value / Nieprawidłowa wartość liczbowa

Auto-corrections / Automatyczne korekty (generate warnings, not errors):

Dates in the past → set to today, time-of-day preserved. / Daty z przeszłości → ustawiane na dzisiaj, zachowana składowa czasu.
Missing optional coordinates with non-required post-action → set to 0. / Brak opcjonalnych współrzędnych → ustawiane na 0.
Driver with missing required fields but non-Sent105 post-action → driver omitted entirely. / Niekompletne dane kierowcy dla akcji innej niż Sent105 → kierowca pomijany.
Blank optional text fields → normalized to null to avoid XML validation issues. / Puste opcjonalne pola tekstowe → normalizowane do null dla uniknięcia problemów z walidacją XML.

Notes / Uwagi

Imported transports are created through the standard transport creation workflow. / Importowane transporty są tworzone przez standardowy przepływ tworzenia transportu.
Existing tenant transport items are reused when the imported data matches current resolver rules. / Istniejące pozycje towarowe dzierżawcy są ponownie używane, gdy dane importu pasują do bieżących reguł rozpoznawania.
The CSV import is intended for admin/operator bulk entry — it does not replace XML/key-based integration paths. / Import CSV jest przeznaczony do zbiorczego wprowadzania danych przez administratorów/operatorów — nie zastępuje ścieżek integracji XML ani kluczowych.

Last modified: 17 March 2026

Transport CSV Import

Overview / Przegląd

Import Flow / Przebieg importu

File Format / Format pliku

Post-Actions / Akcje wysyłki

Column Reference / Opis kolumn

1. Transport

2. Sender / Nadawca (sender*)

3. Recipient / Odbiorca (recipient*)

4. Carrier / Przewoźnik (carrier*)

5. Source Location / Miejsce załadunku (source*)

6. Destination Location / Miejsce dostawy (destination*)

7. Driver / Kierowca (driver*)

8. Transport Item / Pozycja towarowa (item*)