eTTN Compliance Deep Dive¶

Призначення документа. Phase 1 (standards-matrix.md, phase1-summary.md § Surprise 5) ідентифікував eFTI як критичний gap, що не був врахований у Phase 0 decisions. Цей документ — глибокий verified research для прийняття архітектурних рішень про compliance-by-design у Phase 4-5: чи створювати окремий додаток shipcore.efti_compatibility/, як будувати pipeline eTTN → eCMR → eFTI, чи можлива поетапна реалізація.

Reliability legend. ✅ підтверджено офіційним джерелом (EUR-Lex, UNECE, kmu.gov.ua, zakon.rada.gov.ua) · 🟡 підтверджено двома незалежними вторинними джерелами (IRU, eFTI4EU, CLECAT, профільні TMS-вендори) · ⚠️ суперечливі дані між джерелами — обидві версії показані · (?) невпевнено, треба окремий research у Phase 3.

Бюджет рисерчу. ~50 хв (8 паралельних треків web-search + 2 GitHub-fetch). За точність цього документа платить майбутнє: ShipCore інвестує 3-5 тижнів refactoring на основі його висновків.

0. TL;DR¶

Три стандарти — три рівні: eFTI (EU, umbrella) ⊃ eCMR (UNECE, road sub-domain) ⊃ еTTN (UA, national road implementation). Технічно вони НЕ ідентичні, але семантично узгоджуються через UN/CEFACT Multimodal Transport Reference Data Model (MMT RDM).
eFTI mandatory дата для public authorities — 9 липня 2027 ✅. Для economic operators — voluntary з січня 2026, з очікуваним розширенням mandatory вікна 2027-2029 (deferred у delegated acts) (?).
eCMR mandatory дата для останніх 8 EU member states — кінець 2026 🟡 (за заявами IRU/CLECAT, не окремий регуляторний акт — наслідок eFTI Reg deadline).
eTTN UA — це НЕ національний eCMR. Це внутрішнє обов'язкове рішення для domestic UA-перевезень (КМУ #629-2024-п замінив старі пілотні постанови). UA ратифікувала eCMR Protocol окремо 13.07.2020 ✅, але не має національної implementation eCMR — лише domestic eTTN.
Архітектурне implication для ShipCore: треба 3 окремі projections одного логічного Waybill, не 3 окремі моделі. Cross-cutting concern на shared core (з абстрактною моделлю ShipmentDocument), плюс EftiExporter / EcmrExporter / EttnExporter як three services. Окремий додаток shipcore.compliance/ для signing + audit.
Open source бази є: EFTI4EU reference-implementation (Java, gate-based) і Open Logistics Foundation eCMR (live с 2025-06). Python ecosystem — signxml як основний XAdES tool. Інтеграція з UA Дія.Підпис/КЕП — окремий код, відсутній eFTI-аналог.
Рекомендація Phase 4: НЕ будувати full eFTI у Phase 4 — це premature optimization. Закласти abstraction layer (ShipmentDocument.to_canonical_dict() + plug-and-play exporters), фактичні exporters додавати у Phase 8 EU expansion. Винятки — eTTN (готувати з Phase 4 для UA pilot), eCMR (Phase 5 — мінімальний PDF + base64 signature).

Part 1 — Точна термінологія + ієрархія¶

1.1 Три рівні стандартів¶

Стандарт	Рівень	Видавець	Sub-domain	Юрид. сила
eFTI (electronic Freight Transport Information)	EU regulation	European Commission	All modes (road / rail / inland waterway / air)	Regulation (EU) 2020/1056 ✅ — directly applicable у всіх EU member states
eCMR (electronic Consignment Note)	International protocol	UNECE Working Party (SC.1)	Road only — international carriage	Additional Protocol 2008 to CMR Convention 1956. Bilaterally binding між ratified states
eTTN (e-Товарно-Транспортна Накладна)	UA national act	Cabinet of Ministers of Ukraine	Road domestic — UA internal	КМУ #629 від 30.05.2024 (експериментальний проєкт, 2 роки) ✅ + старіші пілотні постанови

1.2 Hierarchical relationship (як вони перетинаються)¶

                  ┌────────────────────────────────────┐
                  │  eFTI Data Set (umbrella schema)   │
                  │  EU Reg 2020/1056                  │
                  │  Sub-domains: road / rail / IWT /  │
                  │  air                               │
                  └─────────────┬──────────────────────┘
                                │ road sub-domain aligned with
                                ▼
                  ┌────────────────────────────────────┐
                  │  eCMR Data Model (UNECE BRS 2024)  │
                  │  UNECE Additional Protocol 2008    │
                  │  39 ratified countries (incl. UA)  │
                  └─────────────┬──────────────────────┘
                                │ semantic mapping, NOT regulatory hierarchy
                                ▼
                  ┌────────────────────────────────────┐
                  │  eTTN UA (domestic XML schema)     │
                  │  КМУ #629/2024 + provider APIs     │
                  │  25+ accredited providers          │
                  └────────────────────────────────────┘

Що це означає на практиці:

✅ Single source of truth — UN/CEFACT MMT RDM (Multimodal Transport Reference Data Model). eFTI офіційно посилається на MMT RDM як common interface для multimodal data exchange (UNECE Skopje workshop 2024).
🟡 eCMR — це РОЗШИРЕННЯ MMT RDM road sub-domain з digital signature layer. UNECE опублікував eCMR BRS (Business Requirements Specification) у жовтні 2024.
⚠️ eTTN — це власна UA XML schema (центральна БД через Мінрозвитку), яка частково alignment з eCMR data fields, але має UA-specific (РНОКПП, УКТЗЕД, dual-signed by carrier і shipper КЕП). Офіційного mapping eTTN ↔ eCMR не існує — UA Cabinet seeks to join EU eFTI system (gmk.center 2025 повідомлення) (?), але технічна сумісність — задача operators.

1.3 Спільні елементи (cross-standard intersection)¶

Усі три стандарти містять core minimum:

Елемент	eFTI Common Data Set	eCMR (CMR §6)	eTTN (UA)
Sender (shipper)	✅	✅	✅
Consignee (receiver)	✅	✅	✅
Carrier	✅	✅	✅
Place + date of taking over goods	✅	✅	✅
Place designated for delivery	✅	✅	✅
Description of goods + packaging	✅	✅	✅
Gross weight	✅	✅	✅
Charges (freight, duties)	✅ (optional)	✅	⚠️ (партіально, в основному вартість послуги)
Document reference / unique ID	✅ (mandatory unique ID)	✅	✅
Electronic signature(s)	✅ (qualified by eIDAS)	✅ (Article 3 Protocol)	✅ (КЕП Дія.Підпис)

1.4 Різниці (де перетинання НЕ працює)¶

Розбіжність	eFTI	eCMR	eTTN
Geographic scope	EU + EEA	International road (39 countries)	UA domestic only
Modal scope	Multimodal	Road only	Road only
Signature standard	eIDAS qualified (XAdES)	Protocol Art.3 — "reliable methods" (loose)	UA КЕП (Дія, ЦСК через qualified providers)
Data format	XML/JSON via certified eFTI platform	Defined по UNECE BRS — XML/EDIFACT/CMR-XML	Власна UA XML schema (через провайдер API)
Authority access	Inspection request → QR / unique link	Direct platform request (no standard)	Central DB query through provider
Mandatory date	2027-07-09 (authorities) / 2027-2029 economic (?)	По country ratification + EU end-2026	UA domestic effective with phased rollout (?)

Part 2 — eFTI Data Set specification (детально)¶

2.1 Legal basis і timeline¶

Regulation (EU) 2020/1056 of 15 July 2020 on electronic freight transport information ✅
Published OJ L 249, 31.7.2020, p. 33-48
URL: https://eur-lex.europa.eu/eli/reg/2020/1056/oj/eng
Commission Delegated Regulation (EU) 2024/2024 (26.07.2024) ✅ — establishes the eFTI common data set і eFTI data subsets
Commission Delegated Regulation (EU) 2024/2025 (15.07.2024) ✅ — amendments to Part B of Annex I (national-law requirements references)
First Implementing Act (05.07.2024) ✅ — adopted by DTTF Committee
Entry into force: 9 January 2025 — Member States can begin IT preparation
Voluntary operations: from January 2026 — eFTI platforms можуть подавати на certification
Mandatory authority acceptance: from 9 July 2027 ✅ — Member State authorities must accept eFTI data via certified platforms

⚠️ Mandatory для economic operators (≠ public authorities): Regulation НЕ зобов'язує operators використовувати eFTI — лише гарантує, що якщо вони використовують certified platform, authorities ЗОБОВ'ЯЗАНІ приймати. Очікувані расширення mandatory operators 2027-2029 — це інтерпретація від CLECAT/transport-community аналітиків (?), не зафіксована в primary тексті Reg 2020/1056.

2.2 eFTI Common Data Set — структура¶

Технологічний підкладок ✅: - Reference model: UN/CEFACT MMT RDM (Multimodal Transport Reference Data Model) - Serialization: Syntax-independent — RDM-based, можна реалізувати як XML, JSON, RDF/JSON-LD, REST API - Alignment: Union Customs Code data model + European Maritime Single Window environment (EMSWe) - Schema publication: UNECE supplements з 2024 — UN/CEFACT package of standards for multimodal transport (October 2024)

Структура (high-level — за Annex I Reg 2020/1056 + Delegated Reg 2024/2024):

eFTI Data Set
├── 1. Identifier & metadata (mandatory)
│   ├── Document unique ID (UUID)
│   ├── Version + revision
│   ├── eFTI platform reference
│   └── Carrier of record
│
├── 2. Parties (mandatory: shipper, consignee, carrier; optional: notify party, freight forwarder)
│   ├── Legal name, address, country code
│   ├── Tax ID (VAT / EORI / national equivalent)
│   └── Contact (email, phone)
│
├── 3. Consignment / goods (mandatory)
│   ├── Description, HS code (6 digit minimum)
│   ├── Quantity, gross/net weight, dimensions
│   ├── Dangerous goods (UN number, ADR class) if applicable
│   ├── Packaging type
│   └── Marks & numbers
│
├── 4. Transport (mode-specific subsets)
│   ├── Road subset (eCMR-aligned): vehicle registration, driver, route
│   ├── Rail subset (CIM/SMGS-aligned): wagon number, train number
│   ├── IWT subset: vessel name, voyage
│   ├── Air subset: AWB number, flight
│   └── Sea (NB: NOT in current eFTI core, see § 2.5)
│
├── 5. Itinerary
│   ├── Place + datetime of taking over
│   ├── Place + datetime of delivery
│   ├── Stops / transfers (multimodal)
│   └── Border-crossing events
│
├── 6. Customs / regulatory references
│   ├── MRN (Movement Reference Number for transit / NCTS)
│   ├── T1/T2 declaration ref
│   ├── EORI of declarant
│   └── Special permits (waste shipment, dual-use, sanctions checks)
│
└── 7. Signatures + audit trail
    ├── Operator signature (qualified eIDAS, typically XAdES-LTA)
    ├── Timestamps (qualified time-stamp authority)
    └── Inspection log (each authority access)

2.3 Mandatory vs optional elements per transport mode¶

🟡 За Annex I Reg 2020/1056 і Delegated Reg 2024/2024 — subsets per mode:

Sub-domain	Status у eFTI	Mandatory minimum	Optional
Road	✅ Active (aligns with eCMR)	Sender, consignee, carrier, vehicle reg, goods desc, weight, places + dates, charges	Driver info, route waypoints, customs refs
Rail	✅ Active (aligns with CIM/SMGS)	Sender, consignee, carrier, wagon/train, goods, weight, places + dates	Sealing, dangerous goods specific, RIV/RIC
Inland Waterway Transport (IWT)	✅ Active	Operator, vessel, ENI number, voyage, cargo, ports	Bunker, port calls
Air	✅ Active (aligns with IATA Cargo-XML / ONE Record)	AWB number, shipper, consignee, agent, goods, weight	Charter, ULD
Sea / maritime	⚠️ NOT in core eFTI	— (covered by EU Maritime Single Window environment EMSWe separately)	—

Важливо: eFTI core scope у Reg 2020/1056 Art.2(1) — road, rail, inland waterway, air. Maritime (sea) НЕ входить у eFTI прямо — він покривається окремою EU Reg 2019/1239 (EMSWe). Це впливає на ShipCore-Sea (див. § 5.3 нижче).

2.4 eFTI Platform Service architecture¶

🟡 За eFTI4EU reference implementation + первинні Implementing Act 2024:

Архітектура — gate-based federated (НЕ centralized, НЕ pure peer-to-peer):
Кожна member state operates national eFTI gate (interface to її authorities)
Economic operators використовують certified eFTI platforms (commercial або in-house)
Authority inspection — through eDelivery access points (CEF eDelivery — EU infrastructure)
Registry of identifiers — спільна служба registry для consignment unique IDs
Authentication:
eFTI4EU reference implementation — very limited authentication based on OpenID (треба адаптувати до national identity providers)
Production-ready certification — Delegated Act з certification framework планується до September 2025 ✅ (станом на 2025-01 article)
Signing:
Qualified electronic signature per eIDAS Regulation (910/2014)
Typically XAdES-LTA (long-term archive) для legal weight
Time-stamps from Qualified Time-Stamp Authority (QTSA)
Authority access protocol:
Pull model: authority issues inspection request via QR code / unique URL → operator's platform responds з data slice
No bulk access — кожне розкриття data — explicit, audit-trailed
Machine-readable за specification (XML/JSON over HTTPS via eDelivery)

2.5 Інтеграція з NCTS (T1/T2 transit)¶

🟡 eFTI ≠ NCTS, але aligned:

NCTS (New Computerised Transit System) — окрема EU customs system для transit declarations (Common Transit Convention)
eFTI — для commercial freight data exchange (transport documents)
Alignment: eFTI data model designed to align with WCO Data Model (через Union Customs Code) — тому eFTI Data Set містить slot для MRN (Movement Reference Number) генерованого NCTS

Передача даних: - НЕ "eFTI Data Set передається з NCTS" — це 2 окремі streams - Economic operator вводить дані ОДИН раз → платформа MAY генерує одночасно NCTS T1 declaration (через broker integration) + eFTI Data Set (для transport authorities) - Це operator's responsibility — eFTI Reg не зобов'язує платформу integrate з NCTS

Для ShipCore implication: Phase 8 (EU expansion) має mati EftiExporter separately від NctsExporter (через M.E.Doc/QDPro broker). Не намагайтесь робити один pipeline.

Part 3 — eCMR Protocol detail¶

3.1 Legal text + ratification status¶

✅ Treaty: Additional Protocol to the CMR Convention concerning the electronic consignment note, Geneva, 20 February 2008 - Full text: https://unece.org/fileadmin/DAM/trans/conventn/e-CMRe.pdf - Adopted: 20.02.2008, Entry into force: 05.06.2011

Ratification numbers: - ✅ 58 contracting parties до основної CMR Convention 1956 - ✅ 39 countries ratified/acceded до eCMR Additional Protocol (станом на end-2024 / early-2025)

Confirmed ratifying countries 🟡 (per TransFollow + IRU за 2024-2025):

Country	Ratification year	Notes
Austria	2024-08-13	EU
Azerbaijan	(?)	UNECE roadmap signed 2025
Belarus	early adopter	—
Bulgaria	ratified	EU
Czech Republic	ratified	EU
Denmark	ratified	EU
Estonia	ratified	EU
Finland	ratified	EU
France	ratified	EU
Germany	ratified	EU
Greece	ratified	EU
Hungary	2024-08-28	EU
Iran	ratified	—
Italy	2024-07-03	EU (35th ratifier)
Latvia	ratified	EU
Lithuania	ratified	EU
Luxembourg	ratified	EU (Benelux pilot extends to 2027-07-09)
Moldova	ratified	—
Netherlands	ratified	EU (Benelux pilot)
Norway	ratified	EEA
Oman	ratified	—
Poland	ratified	EU
Portugal	ratified	EU
Romania	ratified	EU
Russia	ratified	—
Slovakia	ratified	EU
Slovenia	ratified	EU
Spain	ratified	EU
Sweden	ratified	EU
Switzerland	ratified	EFTA
Tajikistan	ratified	—
Turkey	ratified	—
Turkmenistan	ratified	—
Ukraine	2020-07-13 ✅	27th country at time
United Kingdom	ratified	post-Brexit retained
Uzbekistan	ratified	—
Kyrgyzstan	ratified	—
Armenia	2024-10-08	—

⚠️ Конфлікт дат для UA: - Користувач у завданні зазначив 2018 — це неправильно. - IRU + ERTICO + UNECE підтверджують 13 липня 2020 як deposit date instrument of ratification. - 2019 — Ministry of Infrastructure UA issued decree (12.07.2019) допускаючи domestic e-CMR usage. - 2020 — UA officially became 27th country.

3.2 EU member states still NOT ratified (2026-05 baseline)¶

🟡 За trans.info + TransFollow (2024 review): - Belgium (Benelux pilot, не ratified повноцінно — extension до 2027-07-09) - Croatia - Cyprus (?) - Ireland - Malta (?)

CLECAT/IRU declares "all remaining EU Member States must ratify by end of 2026" — це expected, але формально це не окремий регуляторний deadline, а necessary consequence eFTI Reg 2020/1056 deadline 9.07.2027.

3.3 eCMR specifications — digital signature requirements¶

✅ Per Protocol Article 3(1)-(3): - Може використовуватись будь-який "reliable method" for identification і linking signature до document - НЕ зобов'язує конкретний стандарт (XAdES / CAdES / PAdES) — Protocol intentionally technology-neutral - Practical interpretation: для EU operators — XAdES-BES / XAdES-LTA через eIDAS qualified signatures - For UNECE compatibility — UNECE eCMR BRS (October 2024) recommends XAdES-based signatures aligned with ETSI

Implication для ShipCore: реалізація eCMR signing повинна вибирати XAdES для compatibility з обома EU (eIDAS-compliant) і non-EU (UNECE-conforming) operators. signxml Python library — primary choice ✅.

3.4 Authorized eCMR platforms¶

🟡 Список active platforms (2025-2026):

Platform	Country origin	API	Pricing model	Status
TransFollow	NL	REST API, integrated з 25+ TMS	Per-document або subscription tier (точна ціна — contact sales, public price не публікують) ⚠️	Market leader EU
DigiCMR	NL (часто синонім TransFollow ecosystem)	REST	Subscription	Active
OpenCMR (Open Logistics Foundation eCMR)	DE (Fraunhofer IML)	Open-source (GitLab) ✅	Free (open source)	Production-ready з June 2025
IRU eCMR-EPD	International	Web app + (?) API	Pricing TBD	Pilot, focus на TIR-EPD integration
Pionira	(referenced)	—	Monthly fee based on annual transactions, no setup	Active
Eclipse Open Logistics Foundation (formal home of OpenCMR)	DE	Apache-2.0 license	Free	Live with 28 members (Rhenus, Dachser, Blue Yonder, Markant)

Cost estimate ⚠️ (немає public price для TransFollow як ринкового лідера): - TransFollow API integration — orientation EUR 0.10-0.50 per document + base subscription (per партнерські обговорення, треба verify у Phase 2 outreach) - Open Logistics Foundation eCMR — 0 EUR (open source), але потребує self-hosting + integration effort

3.5 Open source reference implementations¶

✅ Confirmed: - Open Logistics Foundation eCMR ✅ — GitLab https://git.openlogisticsfoundation.org/explore/projects - Launched at transport logistic 2025 (Munich) - 28 industry members co-developed - Apache-2.0 license, freely downloadable - 60% time reduction measured in Markant pilot - eFTI4EU reference-implementation ✅ — GitHub https://github.com/EFTI4EU/reference-implementation - eFTI gate reference (Java/Spring Boot stack — inferred from EU enterprise patterns) - Modules: Gate core, Registry of identifiers, eDelivery connector, Web Service Client, Common library, Platform/gate simulator - "Reference, not production-ready" — must be adapted

3.6 eCMR data передача до митниці (T1/NCTS interaction)¶

🟡 No direct pipe — стандартний UA-EU workflow: 1. Truck departs UA → carrier prepares eCMR (digital, signed XAdES-LTA) for cross-border leg 2. Customs broker (UA side) generates T1 transit declaration in NCTS — separate process 3. At border crossing — authorities check both: eCMR via platform link/QR + T1 MRN via NCTS 4. Single touch-point only через certified eFTI platform from 2027-07-09 — operator's platform shows both projections

Тобто eCMR і T1 — два окремі документи, але post-eFTI вони будуть two projections one consolidated dataset, що ховається за certified platform.

3.7 Cost of integration (DigiCMR / TransFollow)¶

⚠️ Public price НЕ опублікований — обидва провайдери (TransFollow як ринковий лідер) використовують enterprise sales model: - TransFollow Connect (для software providers) — API access за contracted pricing - Estimated TCO для ~5000 documents/month forwarder — EUR 2000-6000/month range (включно з platform fees) (?) — потребує verify в Phase 2 sales call - Open Logistics Foundation eCMR — EUR 0/license, але self-hosting + Dev effort (~2-4 тижні integration)

Part 4 — eTTN UA detail¶

4.1 Регуляторна база ⚠️¶

Користувач у завданні вказав КМУ #207-2021-п — це не вірно, ймовірно помилка. Реальна chronology:

Postanova	Дата	Зміст
КМУ (early pilot, extended до 30.07.2021) ✅	2020-04-?	Перший експериментальний проект e-TTN
КМУ #378-2021	21.04.2021	Зміни до Порядку ведення (related, не eTTN-specific)
Закон про автомобільний транспорт зміни	вступ в силу 2021-10-01	Визначає реєстр транспортних документів
Наказ МІУ #497	15.06.2023	Дослідна експлуатація ПЗ електронної ТТН
КМУ rollout — обов'язкова e-TTN	from 2023-08-01 (?)	За оголошенням KMU news, конкретна постанова не повністю знайдена ⚠️
КМУ #629 ✅	30.05.2024	Експериментальний проект e-TTN у внутрішніх вантажних перевезеннях — діє з 2024-06-04, тривалість 2 роки
Порядок функціонування системи е-ТТН (наказ) ✅	дія з 20.03.2025	Технічний порядок

✅ Current source of truth: КМУ #629 від 30.05.2024 — це активна постанова (заміняє раніші пілотні). URL: https://zakon.rada.gov.ua/go/629-2024-%D0%BF

Action item для Phase 2: коректно процитувати fully всі постанови у standards-matrix.md — є застаріле посилання "#207-2021-п" (де? — треба audit existing документу). Поточний research показує НЕМАЄ КМУ #207 безпосередньо про eTTN; КМУ #207-2016 — це про реєстрацію місця проживання, КМУ #207-2022 — це зміни до постанови #1424-2021.

4.2 Scope і mandatory dates¶

🟡 За Vchasno.UA + kmu.gov.ua news: - 2022-08-01 — e-TTN стала обов'язковою для базової групи товарів (юр. особи) ✅ - 2023-08-01 — розширення на full domestic transport (originally planned, скориговане війною) - 2024-06-04 — старт експерименту по КМУ #629 (overhauls earlier pilot) - 2026-06-04 — закінчення 2-річного experiment terms — далі очікується постійна обов'язкова система (?)

4.3 XML schema specification¶

⚠️ No public XSD URL knew (Phase 2 task — direct request до Мінрозвитку або через provider): - Central database operates через API integration з провайдерами — не з direct end users - Schema details — інкорпоровані в provider SDK (Vchasno.TTN, M.E.Doc, EDIN тощо) - Public-facing docs обмежені у scope: e-ttn.miu.gov.ua FAQ описує high-level workflow без schema URL

4.4 Provider list (accredited)¶

🟡 За Vchasno.UA (April 2024 article — 25+ providers):

Provider	Status	API	Pricing	Notes
Вчасно.ТТН (Vchasno)	active ✅	REST	Subscription per company (~UAH 200-1000/month tiers — public у Vchasno портал)	Largest UA provider
M.E.Doc TTN	active ✅	API через MEDoc desktop	Subscription	UA legacy enterprise standard
EDIN (Edinet)	active ✅	REST	Subscription	Wiki: wiki.edin.ua
Agrichain eTTN	active	API	TBD	Niche — agriculture vertical
СОТА	active (?)	—	—	—
20+ smaller providers	active	varies	varies	Listed в periodic updates на e-ttn.miu.gov.ua

4.5 Cross-border coverage¶

🟡 eTTN — DOMESTIC ONLY (UA→UA). Для cross-border: - UA→PL та інші — eCMR (UA ratified 2020-07-13, можна domestically issue + recognize cross-border in 39 contracting states) - Cross-border partnerships — Vchasno + EU eIDAS — Ukraine seeks accession to EU electronic trust services system (КМУ постанова про взаємне визнання e-trust services Україна-ЄС, ID 1311-221122) ✅

Implication для ShipCore: НЕ можна напряму exporting eTTN format у PL/RO/BG. ShipCore generates parallel eCMR document для cross-border leg.

4.6 eTTN ↔ eCMR data interoperability¶

⚠️ Офіційного mapping table не існує — це open task для ShipCore (див. § 5.1):

eTTN UA-specific fields: РНОКПП (taxpayer ID), УКТЗЕД (UA goods classification), КЕП-signature blob
eCMR international fields: EORI (EU operator ID), HS codes, XAdES signature

Action item для Phase 2 / Phase 4: створити internal mapping table (project responsibility — це наш wedge feature для UA-EU forwarders). Початкова версія наведена в § 5.1.

4.7 API integration з eTTN providers¶

🟡 Узагальнено по public docs (Vchasno + EDIN): - REST API з token-based authentication - Endpoints: create document, attach КЕП signature, send to recipient, query status, query central DB sync state - Webhooks для real-time status updates - KEP integration — through ЦСК (Certification Authority) — Дія.Підпис як preferred user flow для individuals, для legal entities — qualified KEP from accredited CA

Part 5 — eFTI ↔ eCMR ↔ eTTN data mapping¶

5.1 Mapping table (high-level, road sub-domain focus)¶

Семантичне поле	eFTI element	eCMR field (UNECE BRS)	eTTN field (UA)	Mapping direction
Document unique ID	`eftiDocumentReference.id` (UUID)	CMR §1 (consignment note number)	unique ID в central DB	bidirectional
Issue date	`documentIssueDate`	CMR §4 (date of taking over)	`data_skladannya`	bidirectional
Sender legal name	`consignor.name`	CMR §1	`vidpravnyk.naimenuvannya`	bidirectional
Sender tax ID	`consignor.taxIdentifier` (EORI prefix EU/EU; UA РНОКПП outside)	n/a (free text)	`vidpravnyk.rnokpp`	one-way (UA→EU lossy: РНОКПП не валідний EORI)
Consignee legal name	`consignee.name`	CMR §2	`oderzhuvach.naimenuvannya`	bidirectional
Carrier	`carrier.name` + `vehicleRegistration`	CMR §3 + §17	`pereviznyk.naimenuvannya` + `transportnyy_zasib`	bidirectional
Place of taking over	`placeOfTakingOver.location`	CMR §4	`pochatkovyy_punkt_perevezennya`	bidirectional
Place of delivery	`placeOfDelivery.location`	CMR §5	`kincevyy_punkt_perevezennya`	bidirectional
Goods description	`consignmentItem.description`	CMR §6	`vantazh.naimenuvannya`	bidirectional
HS code	`consignmentItem.hsCode` (HS 6-digit)	n/a (free text)	`vantazh.kod_uktzed` (10-digit UA УКТЗЕД)	one-way (UA→EU lossy: truncate to 6 digits)
Gross weight	`consignmentItem.grossWeight` (kg)	CMR §7	`vantazh.vaha_brutto` (kg)	bidirectional
Charges	`freightCharges.amount` (EUR)	CMR §13	`vartist_poslug` (UAH)	bidirectional + currency conversion
Carrier signature	`signature.qualified` (XAdES-LTA)	CMR §18 + Protocol Art.3	КЕП Дія/qualified CA	conditional (XAdES from KEP — possible if KEP cert is XAdES-compatible)
Sender signature	`signature.qualified`	CMR §18	КЕП	conditional
Authority access log	`inspectionLog[]`	n/a (no protocol-mandated field)	`auditlog` (central DB)	one-way (eCMR doesn't track; eTTN central DB tracks; eFTI mandates)

5.2 Unique-to-UA elements¶

UA-only element	Чому	Approach to expose у eFTI
РНОКПП (10-digit individual tax №)	UA-specific identifier (немає EU прямого аналога)	Map як `additionalIdentifier` з `schemeId='UA-RNOKPP'` (eFTI allows extension)
УКТЗЕД 10-digit	UA detailed customs classification (HS-based, but extended)	Truncate to HS-6 для eFTI canonical, додатково expose як `additionalAttribute`
КЕП-blob (binary cert + signature)	UA Дія.Підпис specifics, ASN.1 structure proprietary	Re-sign with XAdES-compatible cert if exporting cross-border, OR transmit КЕП-blob as `nationalSignature` extension
Серія/№ свідоцтва про реєстрацію ТЗ	UA-specific vehicle reg cert format	Map як `vehicleRegistration.documentNumber`

5.3 Unique-to-EU elements (для eTTN-only client expose)¶

EU-only element	Чому потрібен	Approach to support у eTTN-only клієнтів
EORI	Mandatory для будь-якого EU customs interaction	ShipCore вводить EORI поверх eTTN domestic flow (extension field — partner.eori)
MRN (Movement Reference Number)	Generated by NCTS для transit	ShipCore stores MRN на Booking model, передає у customs broker (M.E.Doc/QDPro)
AEO status (Authorized Economic Operator)	Reduced inspection benefits	Track як partner attribute, expose at eCMR/eFTI generation
MS-specific national license	Cabotage, ECMT permits	Track в `shipcore.Carrier.permits` JSON

5.4 Concrete use case — UA→PL forwarder with sea leg¶

Scenario: Lviv-based forwarder ships container Kyiv → Gdańsk (cross UA→PL), than sea Gdańsk → Hamburg.

Документи генеровані ShipCore:

┌─────────────────────────────────────────────────────────────────┐
│                   ONE CANONICAL ShipmentDocument                │
│                   (ShipCore master entity)                      │
│                                                                  │
│  - Sender, consignee, carrier(s)                                │
│  - Cargo description, HS, weight                                │
│  - Multi-leg itinerary:                                         │
│    Leg 1: Truck Kyiv→Border (UA)                                │
│    Leg 2: Truck Border→Gdańsk (cross UA-PL)                     │
│    Leg 3: Sea Gdańsk→Hamburg                                    │
│  - Customs refs (T1 MRN, EORI)                                  │
│  - Signatures (КЕП Дія + XAdES export)                          │
└──────────┬────────────────┬────────────────┬───────────────────┘
           │                │                │
           ▼                ▼                ▼
    ┌──────────┐    ┌────────────┐    ┌──────────────┐
    │  eTTN    │    │   eCMR     │    │ eBL (DCSA)   │
    │ (Leg 1)  │    │ (Leg 2)    │    │ (Leg 3)      │
    │  domestic│    │ cross-bdr  │    │  sea         │
    └────┬─────┘    └─────┬──────┘    └──────┬───────┘
         │                │                  │
         ▼                ▼                  ▼
   eTTN provider   eCMR platform       DCSA-compliant
   (Vchasno/etc)   (TransFollow/       eBL platform
                    Open Logistics)    (CargoX etc)
                          │
                          ▼
                   eFTI Data Set
                   (consolidated,
                    submitted to
                    EU eFTI gate
                    from 2027-07-09)

Висновок: 3 окремі проекції одного canonical document, плюс 1 final eFTI Data Set consolidating all для EU authorities. Це НЕ 3 окремі документи з даної логіки клієнта — це 3 outputs одного source-of-truth + 1 EU regulator submission.

Part 6 — Compliance-by-design implications для ShipCore¶

6.1 Phase 4 architecture — окремий додаток vs cross-cutting¶

Рекомендація: Cross-cutting concern на shared core, з окремим додатком shipcore.compliance/ для exporters і signing utilities.

Чому НЕ окремий shipcore.efti_compatibility/: - eFTI data set — це export format, не sutність. Зберігати eFTI як окрему модель — антипатерн (eFTI build from existing Waybill/Booking/BillOfLading). - eCMR / eTTN — теж exports. Хочемо одну canonical модель, багато проекцій.

Запропонована структура:

backend/shipcore/
├── models/
│   └── shipment_document.py    ← abstract base for Waybill/Booking/BL/AWB
│
backend/shipcore/compliance/    ← NEW sub-package (not separate Django app)
├── exporters/
│   ├── base.py                 ← ExporterBase with .to_canonical() + .to_format()
│   ├── efti.py                 ← EftiExporter (XML/JSON-LD per Delegated Reg 2024/2024)
│   ├── ecmr.py                 ← EcmrExporter (XML aligned with UNECE BRS Oct 2024)
│   ├── ettn.py                 ← EttnExporter (provider-specific XML for Vchasno/EDIN/M.E.Doc)
│   ├── ebl.py                  ← EblExporter (DCSA TransportDocument JSON)
│   └── ncts.py                 ← T1/NCTS export (delegated to M.E.Doc/QDPro broker)
├── signing/
│   ├── xades.py                ← XAdES signing via signxml
│   ├── kep.py                  ← UA КЕП Дія.Підпис integration
│   └── timestamps.py           ← Qualified time-stamp авторитети (eIDAS QTSA)
├── mapping/
│   ├── ua_to_eu.py             ← РНОКПП↔EORI, УКТЗЕД↔HS-6, UAH↔EUR (через NBU rate)
│   └── eu_to_ua.py             ← reverse
├── audit/
│   ├── inspection_log.py       ← model для tracking authority access (mandated by eFTI)
│   └── audit_trail.py
└── tests/

Why this structure: - Single canonical model (shipment_document) → many exports (orthogonal) - Signing as orthogonal concern (можна add XAdES без torsion exporter logic) - Mapping as separate module (UA↔EU specifics, легко тестувати) - Audit log — first-class (eFTI mandates inspection trail)

6.2 `to_efti_data_set()` pattern — який підхід¶

Рекомендація: Django serializer-style для consistency з existing DRF stack + Pydantic для strict schema validation.

# backend/shipcore/compliance/exporters/efti.py

class EftiDataSetSerializer(serializers.Serializer):
    """
    Implements eFTI Common Data Set per Commission Delegated Regulation 2024/2024.
    Schema target: UN/CEFACT MMT RDM, syntax JSON-LD or XML (caller choice).
    """
    document_id = serializers.UUIDField()
    document_version = serializers.IntegerField(default=1)
    consignor = PartySerializer()
    consignee = PartySerializer()
    carrier = PartySerializer()
    consignment_items = ConsignmentItemSerializer(many=True)
    itinerary = ItinerarySerializer()
    customs_refs = CustomsReferencesSerializer(required=False)
    signatures = SignatureSerializer(many=True)

    def to_xml(self) -> bytes:
        """Render to UNECE-canonical XML (UN/CEFACT MMT RDM-based XSD)."""
        ...

    def to_json_ld(self) -> dict:
        """Render to JSON-LD per FEDeRATED semantic model."""
        ...

Why DRF over pure Pydantic: - Consistency з existing ShipCore code (DRF — основний stack) - Strict typing через validate_* методи - Output format-independent serialize → render у XML / JSON / JSON-LD downstream

6.3 EftiDataSet storage — окрема модель чи on-demand?¶

Рекомендація: On-demand generation, плюс audit log record.

class EftiSubmission(models.Model):
    """Records submission to EU eFTI gate (для audit, не для caching)."""
    document = models.ForeignKey('shipcore.ShipmentDocument', on_delete=PROTECT)
    submitted_at = models.DateTimeField(auto_now_add=True)
    submitted_payload_hash = models.CharField(max_length=64)  # SHA-256 of submitted payload
    gate_response = JSONField()  # acknowledgment from EU eFTI gate
    inspection_requests = JSONField(default=list)  # authority access events

Why: - Storing full eFTI Data Set duplicates source-of-truth (Waybill/Booking ALREADY contains data) - Audit log requires snapshot — hash + response, не full payload - Re-generation deterministic from canonical model

6.4 eTTN → eCMR → eFTI conversion pipeline¶

Architecture rec:

Waybill / Booking (canonical)
       │
       ├──── EttnExporter.to_xml()  → POST Vchasno API → КЕП signing client-side
       │                            → status webhook → update Waybill.ettn_status
       │
       ├──── EcmrExporter.to_xml() → XAdES-LTA sign via signxml.XAdESSigner
       │                          → POST TransFollow API (OR self-host Open Logistics
       │                            Foundation eCMR)
       │                          → exchange with cross-border partners
       │
       └──── EftiExporter.to_xml() → submit to national eFTI gate (EFTI4EU API)
                                  → from 2027-07-09 mandatory
                                  → audit log via EftiSubmission model

Signature conflicts handling: - УВАГА: КЕП Дія підпис != XAdES out-of-the-box. - UA КЕП сертифікати (видані QualCA у форматі DSTU 4145-2002, ECC over GF(2^257)) — НЕ підтримуються standard XAdES toolchains (signxml працює з RSA/ECDSA over NIST curves) - Conversion path: Phase 4-5 — для cross-border ShipCore signs twice: 1. КЕП for UA-side compliance (eTTN) 2. EU qualified cert (acquired separately for ShipCore SaaS company OR re-signed by EU partner) for eCMR/eFTI - Long-term — UA-EU mutual recognition of e-trust services (КМУ #1311-221122, ongoing implementation) MAY дозволити single signing. Phase 8 monitor.

6.5 Phase 5+ нові моделі¶

shipcore_sea.BillOfLading → eFTI sea sub-domain: - ⚠️ Sea (maritime) НЕ в core eFTI scope (§ 2.3 above) - EU maritime data exchange — separate EU Reg 2019/1239 (EMSWe) - For B/L specifically — DCSA eBL TransportDocument is industry standard, NOT eFTI - Recommendation: BillOfLading → EblExporter (DCSA-aligned), не EftiExporter

shipcore_rail.RailwayWaybill (СМГС/CIM) → eFTI rail: - ✅ Rail IS in core eFTI scope - Map RailwayWaybill → eFTI rail subset - Phase 6 deliverable: RailwayWaybillExporter.to_efti() aligning with CIM/SMGS data model

shipcore_terminal.GateTransaction (VGM, container release) → eFTI relevance: - ⚠️ Marginal — these are operational events, not transport documents - VGM standard — DCSA REST (Nov 2025, per phase1-summary Surprise 6) replaces VERMAS EDIFACT - Recommendation: NO direct eFTI export, but events MAY feed Booking.events timeline used by EftiExporter as audit context

6.6 EU expansion Phase 8 — partial eFTI compliance?¶

✅ YES, partial compliance is acceptable and expected: - Reg 2020/1056 allows operators to choose modes — supporting only road sub-domain initially is valid - Add sea/rail/IWT sub-domains progressively - Phase 4-5: road-only (via eCMR + base eFTI road subset) - Phase 6: + rail - Phase 8 (EU expansion): + IWT (for Danube corridor), + air (if Awery partnership materializes)

What changes when economic operators mandatory дата triggers (2027-2029) (?): - ShipCore SHOULD be eFTI-platform-certified by then (separate Delegated Act regulatory process) - OR partner with already-certified platform (e.g., TransFollow as eFTI platform) - ⚠️ Phase 8 critical decision: build proprietary eFTI platform (high CapEx, regulatory burden) OR resell certified platform (faster, dependency)

Part 7 — Open Source / community resources¶

7.1 DCSA OpenAPI¶

✅ Confirmed scope (per GitHub fetch): - Standards: Track & Trace (TNT), Operational Vessel Schedules (OVS), Commercial Schedules (CS), Just-in-Time PortCalls (JIT), Booking (BKG), Electronic Bill of Lading (EBL) (incl. issuance + surrender), Platform Interoperability (PINT) - License: Apache-2.0, GitHub https://github.com/dcsaorg/DCSA-OpenAPI - Latest stable: v2.0.1 (May 2021) — НО конкретні sub-spec (EBL, PINT) мають окремі releases newer

⚠️ eFTI compatibility: NOT mentioned у DCSA OpenAPI docs. DCSA covers sea — eFTI does NOT cover sea (orthogonal). Alignment with UN/CEFACT MMT RDM — NOT confirmed direct (DCSA has own data model that may or may not align — Phase 2 deep-dive task).

Implication ShipCore-Sea: use DCSA OpenAPI as basis for sea Booking + B/L. NOT use eFTI for sea.

7.2 FEDeRATED project deliverables¶

🟡 Open source semantic model as deliverable. URL: https://www.federatedplatforms.eu/

Focus: decentralized data sharing infrastructure for logistics
Open source artifacts: data model + reference architecture
Status: research project (active 2020-2023), influenced eFTI architecture decisions

Not a drop-in solution — використовуйте як reference при design EftiExporter.

7.3 eFTI4EU project pilot¶

✅ Reference implementation public on GitHub: https://github.com/EFTI4EU/reference-implementation - 9 EU member states involved - Java/Spring Boot stack inferred from typical EU patterns (need verify) - "Reference, not production-ready" caveat - Useful as architecture template for ShipCore EftiExporter design

7.4 Eclipse / Open Logistics Foundation eCMR¶

✅ Production-ready з June 2025 (Munich transport logistic 2025 launch): - 28 industry co-developers (Rhenus, Dachser, Blue Yonder, Markant, інші) - License: Apache-2.0 - GitLab repo: https://git.openlogisticsfoundation.org/explore/projects - 60% time reduction reported (Markant pilot) - Recommendation для ShipCore: VERY strong candidate — self-host OpenCMR + add signxml integration for XAdES signing. Avoid EUR 2000-6000/month TransFollow subscription.

7.5 IRU TIR-EPD¶

✅ Reference materials public: - IRU TIR-EPD and RTS Web Services Interface V2 — публічно доступний WSDL technical specification - User guides: https://www.iru.org/system/files/TIR-EPD%20User%20Guide%20ENG.pdf (Jan 2024 version) - Application portal: https://tirepd.iru.org/tirepd/ - Free для TIR carnet holders (через carnet usage), integration через IRU technical contract

7.6 XAdES library recommendation для Django¶

✅ Primary recommendation: signxml (Python XML Signature and XAdES library) - GitHub: https://github.com/XML-Security/signxml - PyPI: signxml (active development, v4.x current 2025) - Provides XMLSigner, XMLVerifier, XAdESSigner, XAdESVerifier - Uses lxml + libxml2 (battle-tested, XML attack-resistant) - W3C XML Signature standard compliant - License: Apache-2.0

Alternative для ASN.1 / non-XML signing: cryptography (Python cryptographic recipes) + custom ASN.1 handling. Use ONLY if XAdES not applicable (e.g., interfacing with UA КЕП Дія API directly).

Part 8 — Recommended action items для ShipCore¶

P0 must-do у Phase 4 (refactor existing modules)¶

[x] P0.1 — створити backend/shipcore/compliance/ package (не окремий Django app) з пустими submodules: exporters/, signing/, mapping/, audit/
[ ] P0.2 — додати ShipmentDocument abstract base model з методом to_canonical_dict() (foundation для всіх exporters)
[ ] P0.3 — імплементувати EttnExporter (UA wedge — потрібно для pilot форвардера у Phase 4)
[ ] P0.4 — інтегрувати з Vchasno.TTN API (зробити full POC end-to-end: create document → КЕП sign → submit → webhook receive)
[ ] P0.5 — створити модель EftiSubmission (audit log, навіть якщо EftiExporter ще пустий)
[ ] P0.6 — оновити standards-matrix.md з коректним КМУ #629 (audit існуючої згадки #207)

P1 must-do у Phase 5 (multimodal forwarder)¶

[ ] P1.1 — імплементувати EcmrExporter з XAdES-LTA через signxml
[ ] P1.2 — досліджувати Open Logistics Foundation eCMR (selfhost vs partnership): clone repo, run mock pilot
[ ] P1.3 — реалізувати UA↔EU mapping (compliance/mapping/ua_to_eu.py): РНОКПП→additionalIdentifier, УКТЗЕД→HS-6, UAH→EUR
[ ] P1.4 — DCSA EBL для Sea (Phase 5): використати DCSA OpenAPI 2.0.x як basis для BillOfLading model
[ ] P1.5 — створити Booking → multiple-exports orchestrator (ShipmentDocumentManager.export_all())
[ ] P1.6 — додати inspection log model (mandated for eFTI compliance from 2027)

P2 must-do до 2027-07-09 (Phase 8 EU expansion)¶

[ ] P2.1 — імплементувати full EftiExporter (XML + JSON-LD outputs)
[ ] P2.2 — інтегрувати з EFTI4EU national gate API (національна eFTI infrastructure)
[ ] P2.3 — придбати/отримати EU qualified eIDAS cert для XAdES-LTA signing
[ ] P2.4 — досліджувати: ShipCore as eFTI-platform-certified vs partner-with-certified (TransFollow / Open Logistics) — strategic decision
[ ] P2.5 — Rail eFTI sub-domain — окремий exporter (для shipcore_rail додатку, Phase 6)
[ ] P2.6 — інтеграція з NCTS through M.E.Doc/QDPro broker (для UA→EU transit)
[ ] P2.7 — sanctions screening — використати EU sanctions feed (free XML) у compliance/sanctions/ (per decisions-2026-05-12 § 12)

P3 monitor (post-2027)¶

[ ] P3.1 — economic operators mandatory date (очікувано 2028-2029, не confirmed) — adjust pricing tiers і onboarding flow
[ ] P3.2 — IWT subset (для Danube корідор forwarders) — partial eFTI compliance extension
[ ] P3.3 — Air subset — depending on Awery partnership (Phase 9+)
[ ] P3.4 — UA-EU mutual recognition of e-trust services (КМУ #1311-221122 implementation result) — possibly enable single КЕП↔XAdES path
[ ] P3.5 — UA accession to EU eFTI system (gmk.center 2025 report — UA seeking to join) — re-evaluate UA-specific logic if accession completes

Linkbacks¶

README.md — ShipCore programmatic overview
decisions-2026-05-12.md — Phase 0 12 locked decisions (compliance refs у § 12 sanctions, § 8 tariff)
standards-matrix.md — повна карта стандартів (eCMR/eFTI/eTTN/ICS2/DCSA/etc.) — потребує оновлення з коректним КМУ #629
integration-matrix.md — § 6 Document Standards — eCMR placeholder existing (DigiCMR/TransFollow), потребує доповнення eFTI + Open Logistics Foundation
phase1-summary.md — § Surprise 5 (eFTI ідентифікований як critical gap) — initial flag що mottivated цей deep-dive

Sources (verified web research, 2026-05-12)¶

Primary regulatory sources¶

Industry / project sources¶

Tertiary / context¶

Phase 2 deep-dive — 2026-05-12. Цей документ — критична основа для Phase 4-5 architectural commitments. Перед фактичним початком імплементації Phase 4 — review цього документа з юридичним consultatne щодо EU regulation interpretation (особливо economic operators mandatory дата) і UA Дія integration team щодо КЕП↔XAdES sign-twice strategy.