Transport Order · specyfikacja dokumentu
Co musi znaleźć się na zleceniu transportowym
Specyfikacja powstała z analizy 7 rzeczywistych zleceń transportowych (przewóz aut/pojazdów). Mimo różnych layoutów wszystkie zawierają ten sam rdzeń informacyjny. Poniżej wyłuszczone pola — pogrupowane w sekcje, z oznaczeniem czy są dynamiczne (zmieniają się per zlecenie), czy stałe/półstałe. Cel: jeden dokument w języku angielskim, zgodny ze standardem CMR.
zt1 multi-drop (1 → 3) · pozycje rozliczeniowe
zt2 GPS · deklarowana wartość · 2 kierowców
zt3 wymiary i waga ładunku
zt5 · zt6 przypadek prosty (1 → 1)
zt7 prawo LT · kwota słownie
zt8 prawo LT · osobna naczepa
dynamiczne (per zlecenie)
stałe / półstałe
required pole wymagane
00
Cel projektowy — dokument międzynarodowy (EN, standard CMR)
Templatka generuje dokument w języku angielskim, zgodny z międzynarodowymi standardami przewozu drogowego, a nie z polską specyfiką. Punktem odniesienia jest Konwencja CMR (Geneva 1956). Zlecenie (Transport Order) to umowa poprzedzająca CMR i używa tej samej terminologii: consignor/sender, consignee, carrier, place of taking over the goods, place of delivery.
Terminologia PL → EN (standard)
| PL (z dokumentów) | EN (standard) |
|---|
| Zleceniodawca / Spedytor / Płatnik | Customer / Principal / Ordering party (freight forwarder) |
| Zleceniobiorca / Przewoźnik | Carrier / Contractor (Haulier) |
| Nadawca | Consignor / Sender |
| Odbiorca | Consignee |
| Załadunek | Loading / Place of taking over the goods (pick-up) |
| Rozładunek | Unloading / Place of delivery (drop-off) |
| Fracht | Freight / Carriage charge |
| List przewozowy CMR | CMR consignment note / waybill |
| NIP | VAT number |
| REGON | Company registration No. (Reg. No.) |
Formaty międzynarodowe
Daty
ISO 8601 (YYYY-MM-DD), godziny 24h, kraje pełną nazwą (Netherlands / Poland / Germany…), waluty wg
ISO 4217 (EUR, PLN…). Prawo właściwe to
pole (nie „sąd w PL") — w zleceniach pojawiają się jurysdykcje PL i LT; domyślnie odwołanie do CMR Convention.
00a
Model white-label (multi-tenant) — dwie warstwy marki
Dokument generuje nasza platforma (CargoStock), ale w imieniu różnych spedytorów/klientów. Na jednym dokumencie współistnieją więc dwie warstwy marki.
| Warstwa | Gdzie na dokumencie | Charakter |
|---|
Tenant / Consumer
(spedytor) | nagłówek, blok „Customer", podpis | dynamiczny per tenant — logo, nazwa, adres, VAT, kontakt, uwagi, Terms |
Platforma
(CargoStock) | stopka na każdej stronie | stały branding generatora — logo, „CargoStock", URL |
Konsekwencja
To consumer jest „wystawcą" treści (jego logo i dane w nagłówku, jego Terms, jego podpis). CargoStock
nie udaje wystawcy — marka platformy żyje wyłącznie w stałej stopce.
tenant.* i
platform.* to dwa osobne obiekty danych.
01 – 04
Dane na dokumencie: nagłówek, strony, pojazd, finanse
1 · Nagłówek / identyfikacja
Tytuł dokumentu
„Transport Order" / odpowiednik w języku lokalnym — zależny od języka
Numer / ID zlecenia required
różne formaty per wystawca, np. CS/TO/2025/06/…, ZL/010550/2026, WY/5337/2026/D
Data wystawienia required
ISO 8601
Miejscowość wystawienia
opcjonalne — przy generowaniu przez platformę bywa niejednoznaczne
Logo / dane wystawcy w nagłówku
logo + nazwa spedytora (tenant)
Numer strony (paginacja)
auto — „Page X / Y" przy wielostronicowych
2 · Strony umowy
Customer (Ordering party) required
nazwa, adres, VAT, Reg. No., telefon, e-mail — zwykle = tenant (nasz klient)
Carrier (Haulier) required
nazwa, adres, VAT — Reg. No. nie zawsze obecne
Osoba kontaktowa (po stronie zleceniodawcy)
imię i nazwisko, telefon, e-mail — czasem 2 osoby
3 · Pojazd transportujący i kierowca
Nr rejestracyjny pojazdu (ciągnik/laweta) required
Nr rejestracyjny naczepy
osobne pole
Kierowca / kierowcy
imię i nazwisko + telefon — może być więcej niż jeden (lista); puste pole → „—"
Link / GPS do śledzenia
„Link to the carrier"
4 · Warunki finansowe
Stawka frachtu (netto) required
„Freight / Carriage charge" — dominuje wskazanie NETTO
Waluta required
ISO 4217 — dominuje EUR
Termin płatności + warunek liczenia
30 / 45 / 60 dni; warunek liczenia (np. „od faktury + CMR") zwykle wynika z OWU klienta
Deklarowana wartość towaru
do CMR / ubezpieczenia
05
Trasa — punkty odbioru i dostawy rdzeń logistyczny
To najważniejsza, powtarzalna lista. Zlecenie może mieć wiele punktów odbioru oraz wiele punktów dostawy (1 odbiór → 3 dostawy; 1 → 2; 1 → 1). Templatka nie może zakładać po jednym punkcie każdego typu.
Model rekomendowany
Jedna uporządkowana lista przystanków
stops[], gdzie każdy ma typ
pickup | dropoff i własną kolejność. Obsługuje dowolne kombinacje N odbiorów → M dostaw (multi-pickup / multi-drop / milk-run). Relacja
punkt ↔ pojazd jest N:N — jeden VIN ładowany w punkcie A, rozładowywany w B. Pod każdym punktem renderujemy przypisane auta.
Pola każdego przystanku
Typ — Loading / Unloading required
Godzina
opcjonalna — czasem zakres / „00:00–23:59"
Nazwa miejsca / firmy required
np. zakład produkcyjny pojazdów, fabryka, terminal / centrum dystrybucji
Adres: ulica, kod, miasto, kraj required
kraj pełną nazwą (Netherlands / Poland / Germany…)
Współrzędne GPS
opcjonalne
Nr załadunku / rozładunku (reference)
Lista VIN-ów obsługiwanych w punkcie
które auta ładowane/rozładowywane tutaj (N:N)
Uwagi do punktu
opcjonalne
06
Przedmiot przewozu — transportowane pojazdy
Auta muszą mieć identyfikatory — wynika to z Konwencji CMR (art. 6: „cechy i numery") oraz z OWU (faktura musi zawierać nr transportowanych pojazdów). Lista 1..N pojazdów.
Hierarchia identyfikatorów per auto
1 · VIN / numer nadwozia required
jedyny jednoznaczny identyfikator — pole pierwszorzędne (CMR art. 6)
2 · LOT / Load number
numer producenta — pomocniczy
3 · Make / Model
czytelny dla człowieka, nieunikalny — sam nie wystarcza
Pozostałe pola pojazdu: ilość (domyślnie 1), waga (kg), wymiary (L/H), powiązanie VIN ↔ punkt zał./rozł. Jeśli VIN nieznany przy generowaniu — fallback (Make/Model + LOT) i oznaczenie „do uzupełnienia na CMR".
07
Uwagi, instrukcje i wymagania (per zlecenie)
Uwagi consumera (Additional information) kluczowe
wolne pole tekstowe — każdy consumer wpisuje własne uwagi per zlecenie (zbierane przy wystawianiu); tu też trafiają wymagania producenta, GPS, daty na CMR itp.
Wymagania producenta / pojazdu
VDI 2700, klasa Euro 5+, mocowania, reguły konkretnych producentów (kary specjalne per marka)
Wymóg GPS / udostępnienia lokalizacji
08 – 09
Wymagane dokumenty & Terms — plik klienta + akceptacja
Model docelowy
Terms
nie są drukowane w treści zlecenia. Każdy klient
wgrywa własny plik OWU na platformę; przewoźnik
musi go zaakceptować ZANIM złoży ofertę. Na dokumencie umieszczamy
tylko link do regulaminu +
zapis akceptacji (kto, kiedy, wersja).
Model danych Terms
tenant.terms_url required
link do pliku OWU — niemutowalny per wersja (np. .../gtc-2026-01.pdf, nigdy .../latest.pdf)
tenant.terms_version / terms_label
wersja i nazwa regulaminu (np. „GTC v2026-01")
terms_acceptance
accepted, accepted_at, accepted_by, terms_version (pinned), opcj. document_hash
Wymagane dokumenty (zwykle też w OWU)
Faktura VAT z nr zlecenia i nr pojazdów · oryginał CMR z pieczęcią i podpisem odbiorcy · podpisane zlecenie · termin dosłania dokumentów · obowiązek przesłania skanu CMR w X h od rozładunku.
10
Akceptacja / podpisy + stopka platformy
Customer — signature
nazwa firmy klienta (stempel niewymagany; dokument generowany automatycznie)
Carrier — accepted, signature
puste do wypełnienia przez przewoźnika
Stopka CargoStock — NA KAŻDEJ STRONIE
logo + „CargoStock" + URL + paginacja; jedyne miejsce marki platformy, wizualnie oddzielone od treści i podpisów
11
Schemat danych (EN) + etykiety — kontrakt dla generatora
Klucze danych i angielskie etykiety wyświetlane na dokumencie.
Branding
| Klucz | Etykieta EN | Wym. | Uwagi |
|---|
| platform.* | (stopka) | tak | name, logo, url, footer_note — stałe, na każdej stronie |
| tenant.name | (nagłówek) | tak | spedytor, w którego imieniu wystawiamy |
| tenant.logo | (nagłówek) | tak | logo consumera; fallback monogram, gdy brak |
| tenant.terms_url | Terms & Conditions | tak | link do OWU klienta |
Identyfikacja & strony
| Klucz | Etykieta EN | Wym. | Format / uwagi |
|---|
| order_number | Transport Order No. | tak | string |
| order_date | Date | tak | ISO 8601 |
| issue_place | Place of issue | nie | string |
| customer.* | Customer (Ordering party) | tak | name, address, vat_number, reg_number, phone, email |
| carrier.* | Carrier | tak | name, address, vat_number, reg_number |
| contact_person.* | Contact / Issued by | tak | name, phone, email |
Pojazd transportujący & finanse
| Klucz | Etykieta EN | Wym. | Uwagi |
|---|
| truck_plate | Truck plate no. | tak | |
| trailer_plate | Trailer plate no. | nie | |
| drivers[] | Driver | nie | lista 1..N — name, phone |
| tracking_link | Tracking link | nie | GPS |
| freight_amount | Freight charge (net) | tak | number |
| currency | Currency | tak | ISO 4217 |
| freight_amount_words | Amount in words | nie | |
| payment_term_days | Payment term | nie | zależny od OWU klienta |
| declared_cargo_value | Declared value of goods | nie | do CMR / ubezpieczenia |
Trasa — stops[] (dowolnie wiele pickup i dropoff)
| Klucz | Etykieta EN | Wym. | Uwagi |
|---|
| stops[].type | Loading / Unloading | tak | pickup | dropoff |
| stops[].sequence | (kolejność) | tak | integer |
| stops[].date | Date | tak | ISO 8601 |
| stops[].time | Time | nie | HH:MM lub zakres |
| stops[].company_name | Company / Site | tak | |
| stops[].street / postal_code / city | Address | tak | |
| stops[].country | Country | tak | pełna nazwa kraju |
| stops[].geo | (GPS) | nie | lat/long |
| stops[].reference | Loading/Unloading ref. | nie | |
| stops[].vehicle_vins | (auta w punkcie) | nie | lista VIN — N:N |
| stops[].notes | Notes | nie | |
Ładunek — vehicles[]
| Klucz | Etykieta EN | Wym. | Uwagi |
|---|
| vehicles[].vin | VIN | tak | twardy identyfikator |
| vehicles[].lot_number | LOT / Load no. | nie | |
| vehicles[].make_model | Make / Model | nie | |
| vehicles[].pickup_stop / dropoff_stop | (→ przystanek) | tak* | * wymagane przy multi-pickup / multi-drop |
Uwagi, Terms & podpisy
| Klucz | Etykieta EN | Wym. | Uwagi |
|---|
| notes | Additional information | nie | wolne uwagi consumera per zlecenie |
| terms_acceptance.accepted_by | Accepted by | nie | osoba/firma przewoźnika |
| terms_acceptance.accepted_at | Accepted on | nie | timestamp |
| customer_signature | Customer — signature | tak | nazwa firmy klienta |
| carrier_signature | Carrier — accepted, signature | tak | puste do wypełnienia |
12
Wnioski projektowe
- Dokument po angielsku, wg standardu CMR — terminologia consignor/consignee/carrier, daty ISO 8601, kraje i waluty ISO. Polskie pojęcia mapujemy na międzynarodowe.
- Wiele punktów odbioru i dostawy — jedna lista stops[] z typem i kolejnością, bez założenia „1 załadunek + 1 rozładunek".
- Dwa poziomy list: przystanki (stops[]) i pojazdy (vehicles[]) z powiązaniem N:N (VIN ↔ pickup/dropoff).
- Najprostszy przypadek: 1 odbiór + 1 dostawa + 1 auto — bez zbędnych pól.
- Terms = plik OWU klienta + link (nie drukujemy treści); akceptacja przed ofertą, zapis kto/kiedy/wersja.
- White-label: dokument należy wizualnie do consumera; CargoStock tylko w stałej stopce.
- Uwagi consumera — wolne pole per zlecenie, zawsze dostępne.
- VIN to twardy identyfikator — wymagany (CMR art. 6); fallback Make/Model + LOT, gdy VIN nieznany.
13
Kontrakt danych dla backendu engineering
Rendererem PDF zostaje istniejący OpenPdfTransportOrderDocumentService (OpenPDF, układ budowany w Javie). Templatka HTML/CSS nie jest wczytywana przez backend — pełni rolę wiążącego podglądu / projektu docelowego. To tu decydujemy co się pokazuje; Java ma się dopasować. Poniżej różnice między obecnym a docelowym modelem.
Mapowanie: podgląd → obecny backend
| Podgląd (cel) | Obecny backend | Co zrobić |
|---|
| customer | content.hauler() | Zmienić rolę na „Customer". Dodać address, vat, reg, email. |
| carrier | content.carrier() | Dodać address, vat_number, reg_number. |
| drivers[] | driver() / additionalDriver() | Dodać telefon; obsłużyć N kierowców. |
| freight / currency | priceAmount / priceCurrency | OK (1:1). |
| stops[] | adresy per cargoItem + globalne okna dat | Największa zmiana — przebudowa trasy na listę przystanków (typ, kolejność, data, ref., VIN-y). |
| vehicles[] z VIN | cargoItems[] (brand, model, count) | Dodać VIN/LOT per auto + relację N:N do stops[]. |
| tenant.* (white-label) | brak — logo zaszyte na sztywno | Dodać warstwę brandingu wystawcy. |
| terms_acceptance | brak | Dodać model + sekcję Terms (link + akceptacja). |
| podpisy, governing_law | brak w renderze | Dodać bloki podpisów; governing_law jako pole. |
Główne zmiany w modelu (podsumowanie)
- Przebudowa trasy na stops[] (typ, kolejność, data+godzina, firma, adres, kraj, ref., VIN-y w punkcie).
- VIN na poziomie pojedynczego auta + relacja N:N auto ↔ przystanek.
- Warstwa white-label (tenant.*) w nagłówku/danych/Terms/podpisie; platform.* tylko w stopce.
- Sekcja Terms: terms_url + terms_acceptance (link niemutowalny per wersja).
- Uzupełnić strony: adres, VAT, Reg. No., e-mail + osoba kontaktowa.
- Dodać bloki podpisów i pole governing_law.
