ShipCore — Integration Matrix¶
Phase 0: список (без deep API specs). Категоризовано за типом інтеграції. Phase 2 (наступна): для top-priority інтеграцій — API spec read, auth model, message format, partner contract requirements, оцінка implementation effort.
1. Ocean Carrier APIs (для ShipCore-Sea + Forwarder)¶
| Carrier | API type | Maturity | Phase 2 priority | Notes |
|---|---|---|---|---|
| Maersk Spot + Track & Trace API | REST + OAuth2 | 🟢 high | 🔴 P0 (перший) | Найбільш публічний, документація відкрита, sandbox |
| MSC eBusiness / MSC API | REST (часткове) + EDI | 🟡 mid | 🟡 P1 | EDI-only для booking у багатьох випадках |
| CMA CGM API | REST + INTTRA legacy | 🟡 mid | 🟡 P1 | EU-strong, для RO/PL ports важливо |
| Hapag-Lloyd Quick Quotes API | REST | 🟢 high | 🟡 P1 | Доступний, добра документація |
| ONE (Ocean Network Express) | REST + EDI | 🟡 mid | 🟢 P2 | Asian focus |
| Evergreen | EDI 315/214 | 🔴 low (REST) | 🟢 P2 | Legacy EDI-первичний |
| ZIM | REST зростає, EDI | 🟡 mid | 🟢 P2 | — |
| COSCO | EDI primary | 🔴 low | 🟢 P2 | China focus |
| Yang Ming, HMM | EDI | 🔴 low | 🟢 P3 | — |
| INTTRA → E2open | EDI hub historic | поглинено | 🟢 P3 (моніторинг) | Через E2open сьогодні |
Phase 2 deliverable: Maersk Spot full integration spec (auth, endpoints, rate limits, error handling) як reference.
2. Rail APIs¶
| Carrier | API type | Phase 2 priority | Notes |
|---|---|---|---|
| Укрзалізниця Cargo / Клієнт УЗ | Обмежений (ЕТРАН/B2B-договір) | 🔴 P0 (UA wedge) | Phase 2 task: формальний запит до УЗ Cargo + AsMAP про варіанти |
| DB Cargo | REST + EDI 404/417 | 🟡 P1 | Партнер для UA-DE flows |
| PKP Cargo | Mixed | 🟡 P1 | UA-PL hot route |
| Rail Cargo Austria (ÖBB) | API + EDI | 🟢 P2 | EU intermodal |
| CFR Marfă (RO) | EDI primary | 🟡 P1 | Для Constanța feeder route |
| RailNetEurope (RNE) PCS/TIS | REST | 🟢 P3 (deferred) | pan-EU path requests, для cross-border |
Phase 2 deliverable: документ «УЗ Cargo integration options» (через AsMAP / через посередника / scraping fallback).
3. Last-mile UA / EU¶
| Carrier | API | Phase 2 priority | Notes |
|---|---|---|---|
| Нова Пошта | REST, ключ | 🔴 P0 (UA standard) | Де-факто стандарт UA, всі форвардери мають |
| Укрпошта | REST + OAuth | 🟡 P1 | — |
| Meest | REST | 🟡 P1 | — |
| Justin / Делівері / Rozetka Delivery | REST | 🟢 P2 | Нішеві |
| DPD / DHL Express / GLS / UPS / FedEx / Inpost | REST + label gen | 🟡 P1 (EU expansion) | Стандартний integration set |
Last-mile як integration target, не наш wedge — ShipCore-Forwarder використовує НП/Meest як subcontractor leg.
4. GPS / Telematics¶
| Provider | API | Phase 2 priority | Notes |
|---|---|---|---|
| Wialon (Gurtam) | REST + WebSocket | ✅ DONE | Вже інтегровано у Fleet, де-факто UA/CIS стандарт |
| Geotab | REST | 🟡 P1 | EU/global expansion |
| Samsara | REST | 🟡 P1 | US/EU |
| Verizon Connect / Webfleet (Bridgestone) | REST | 🟢 P2 | EU |
| Trackimo / Teltonika | REST | 🟢 P2 | EU consumer-grade |
| Flespi | вже частково у Fleet | 🟢 done partial | — |
| Freetrack | вже частково | 🟢 done partial | — |
Phase 2 deliverable: уніфікований TelematicsAdapter interface, щоб додавання нового provider було plugin-driven (як зараз з GPS у Fleet).
5. Tracking / Visibility Aggregators¶
| Service | Coverage | Phase 2 priority | Notes |
|---|---|---|---|
| project44 | Multimodal global | 🟡 P1 (partner candidate) | Enterprise pricing, можливе partner pricing |
| FourKites | US-first ocean+road | 🟢 P2 | — |
| Vizion | Ocean container | 🟡 P1 (cheap alternative) | $200-500/міс per ~thousand containers |
| Terminal49 | Ocean container | 🟡 P1 | Конкурент Vizion |
| GoComet | Ocean | 🟢 P2 | — |
| Shipsy | Indian, ocean+last-mile | 🟢 P3 | — |
Decision Phase 2: інтегруємо Vizion/Terminal49 як датасорс ДЛЯ ContainerHub UI, або будуємо власний tracking-layer? Trade-off: build vs buy.
6. Document Standards¶
| Standard | Type | Phase 2 priority | Notes |
|---|---|---|---|
| eCMR | UNECE | 🔴 P0 (EU expansion v1) | DigiCMR / TransFollow платформи; partnership чи власна реалізація? |
| T1 (NCTS) | EU транзит | 🔴 P0 (EU) | Через митного брокера або direct connect через QDPro/M.E.Doc |
| TIR Carnet (IRU TIR-EPD) | IRU | 🟡 P1 | Електронна попередня декларація, важливо для UA carriers |
| AWB (Air Waybill) | IATA Cargo-XML / ONE Record | 🟢 P3 (avia deferred) | — |
| B/L (Bill of Lading) | DCSA eBL, BIMCO | 🟡 P1 | Paperless trend, але paper ще домінує |
| EDIFACT IFTMIN (booking) | UN/EDIFACT | 🟡 P1 | Базовий для ocean carriers EDI |
| EDIFACT IFTSTA (status) | UN/EDIFACT | 🟡 P1 | — |
| EDIFACT IFTMBC (booking confirm) | UN/EDIFACT | 🟡 P1 | — |
| EDIFACT CUSCAR (customs) | UN/EDIFACT | 🟢 P2 | — |
| COPARN (release notes) | EDI | ✅ partial | ContainerHub вже має |
| BAPLIE (bay plan) | EDI | ✅ partial | ContainerHub вже має |
7. UA Regulators / Compliance¶
| Service | Type | Phase 2 priority | Status |
|---|---|---|---|
| eTTN (Дія.Підпис KEP/ed25519) | UA mandatory | ✅ DONE | Вже інтегровано у Fleet (eTTN module з 9 моделями) |
| ePN / ЄРПН | UA mandatory | 🟡 P1 | Через M.E.Doc bridge |
| ЄАІКМ (митна декларація) | UA mandatory для імпорту/експорту | 🟡 P1 | Через QDPro / M.E.Doc / Декларація-Дист |
| DOZVIL_UA (CEMT/двосторонні дозволи) | АсМАП | 🟢 P2 | Для road carriers важливо |
| M.E.Doc | UA EDI hub | ⚠️ partial | UKTZED довідник вже, повна інтеграція planned |
| BAF / BAS Бухгалтерія | UA accounting de-facto | ⚠️ partial | BAF Sync infra MVP-ready (Phase F-3, dry-run by default), real httpx-transport — наступна ітерація |
8. EU Regulators / Compliance¶
| Service | Type | Phase 2 priority | Notes |
|---|---|---|---|
| NCTS Phase 5 | EU транзит, mandatory з 2024 | 🔴 P0 (EU v1) | T1/T2 declarations |
| ATLAS (DE customs) | DE national | 🟡 P1 | Riege Scope strong here |
| CHIEF / CDS (UK customs) | UK national | 🟢 P3 | UK post-Brexit |
| AEO (Authorised Economic Operator) certification | EU compliance | 🟢 P2 | Як filter поле для контрагентів |
9. Banking (UA)¶
| Bank | API | Phase 2 priority | Notes |
|---|---|---|---|
| Privat24 Business | REST, ключ | ✅ partial (Bank Exchange) | Найбільш зрілий UA-API |
| Mono Business / Monobank | REST, ключ | ✅ partial | Developer-friendly |
| Raiffeisen Bank Aval | REST | 🟡 P1 | — |
| FUIB / OTP / Universal Bank | REST mixed | 🟢 P2 | — |
Це через існуючий Bank Exchange integration framework — ShipCore переиспользує без власної роботи.
10. Compliance / Sanctions Screening¶
| Service | Type | Phase 2 priority | Notes |
|---|---|---|---|
| OFAC SDN | US sanctions | 🟡 P1 (EU expansion) | Через Refinitiv World-Check / Comply Advantage SaaS |
| EU sanctions list | EU | 🟡 P1 | Те саме |
| UK HMT | UK | 🟢 P2 | — |
| DPL (Denied Persons List, US BIS) | US export control | 🟢 P3 | — |
Phase 2 deliverable: ComplianceScreening плагін interface — для screening на: (a) створенні Client, (b) створенні Booking, (c) перед Invoice issue.
11. Payment Gateways (для Client Portal billing)¶
| Provider | Phase 2 priority | Notes |
|---|---|---|
| LiqPay | 🟡 P1 (UA SMB) | Для shop.eswf.dev уже планується |
| Fondy | 🟢 P2 | UA |
| Stripe | 🔴 P0 (EU) | EU SaaS standard |
| PayPal | 🟢 P2 | — |
12. Effort estimate (orientation)¶
| Tier | Кількість інтеграцій | Effort оцінка | When |
|---|---|---|---|
| 🔴 P0 (must-have для v1) | ~7 (Maersk, eCMR, T1, УЗ Cargo, eTTN, НП, BAF) | 8-12 тижнів сумарно | Phase 4-7 |
| 🟡 P1 (значне покриття v1.5) | ~15 | 12-16 тижнів додатково | Phase 5-8 |
| 🟢 P2-P3 (long tail) | ~30 | За запитом клієнтів | Phase 8+ |
13. Phase 2 plan (наступна після Phase 1)¶
- Maersk Spot deep spec — auth, endpoints, rate limits, sandbox setup, error handling
- eCMR partnership research — DigiCMR vs TransFollow vs власна реалізація UNECE
- NCTS T1 — direct connect vs broker — оцінка через М.E.Doc bridge vs власне підключення
- УЗ Cargo API quest — формальний запит, AsMAP роль, сторонні агрегатори
- Уніфікований
CarrierAdapterinterface — щоб додавання Hapag/CMA після Maersk було чисто конфігураційне - Compliance screening provider research — Refinitiv World-Check ціни / Comply Advantage / Sanctions.io
- eTTN — як ShipCore-Forwarder пише ETTNDocument (зараз FK тільки на Fleet.TransportInvoice)
Phase 0 list — 2026-05-12. Phase 2 deep API specs — після Phase 1.
Phase 1 Additions (закрито 2026-05-12)¶
Нові integration targets знайдені у Phase 1 research (phase1-summary.md, standards-matrix.md, efti-compliance-deep-dive.md). Інтегровані в Phase 2 deep-dive scope.
14. eFTI Connectors (Reg EU 2020/1056) — CRITICAL gap у Phase 0¶
Scope: road / rail / inland waterway / air sub-domains. SEA — окремо (EMSWe Reg 2019/1239).
| Sub-domain | Що інтегруємо | Phase | Priority |
|---|---|---|---|
| Road | eCMR (Open Logistics Foundation self-host OR DigiCMR/TransFollow partnership) | 8 | 🔴 P0 |
| Rail | CIM/SMGS digital → eFTI Data Set | 8 | 🟡 P1 |
| Inland waterway | CESNI standards → eFTI | 8 | 🟢 P2 |
| Air | IATA ONE Record → eFTI | 9+ | 🟢 P2 |
| eFTI Platform Service | peer-to-peer architecture, FEDeRATED reference | 8 | 🔴 P0 |
Mandatory dates: - 2027-07-09 — public authorities acceptance - 2026-01-01 → onwards — voluntary для economic operators - Phase 8 deadline = 2027-07-09 для public authority acceptance
Architectural placement: backend/shipcore/compliance/exporters/efti_*.py (cross-cutting у thin core, не окремий Django app). Phase 4 foundation.
15. EMSWe (SEA-only, окремо від eFTI)¶
EU Regulation 2019/1239 — European Maritime Single Window environment.
| Інтеграція | Phase | Priority |
|---|---|---|
| EMSWe Single Window submission | 8 | 🔴 P0 (EU sea ports) |
| DCSA eBL TransportDocument (как primary) | 8 | 🔴 P0 |
Important: sea НЕ через eFTI — це часта помилка. DCSA eBL + EMSWe = sea regulatory framework EU.
16. DCSA VGM REST API (заміна VERMAS EDIFACT) — NEW Nov 2025¶
| Інтеграція | Phase | Priority | Notes |
|---|---|---|---|
| DCSA VGM REST | 5 | 🔴 P0 | Заміняє VERMAS EDIFACT для SOLAS VGM compliance. Простіше — не потрібен EDI parser. shipcore_terminal.GateTransaction пише через REST. |
17. eBL Interop Hubs (Phase 8)¶
9 carriers committed 100% eBL до 2030. Інтегруємось через interop хаби, не direct до carriers.
| Hub | Coverage | Phase | Priority |
|---|---|---|---|
| CargoX | широкий carrier coverage | 8 | 🔴 P0 |
| WaveBL | Maersk-friendly | 8 | 🔴 P0 |
| Enigio (trace original) | European focus | 8 | 🟡 P1 |
| TradeGo | Asian carriers | 8 | 🟡 P1 |
| IQAX (GSBN consortium) | ZIM/CMA/HMM | 8 | 🟡 P1 |
Architectural placement: backend/shipcore_sea/integrations/ebl_*.py. Phase 8 deliverable.
18. ICS2 Release 3 connector (EU pre-arrival)¶
EU Import Control System Release 3 — pre-arrival declarations для всіх transport modes.
| Member state | Mandatory date |
|---|---|
| IE / ES / FR / IT / LT / HU / FI / EL / BG | 2026-01-01 |
| HR / LV / PL / RO / SK ⭐ (UA-relevant) | 2026-06-01 |
Implication: будь-який UA→PL/RO/SK/HU транзит з 2026-06-01 потребує ICS2 declaration. У v1 (UA-only) — не блокує. У v1.5 — must-have.
Architectural placement: backend/shipcore/compliance/exporters/ics2.py. Phase 8 deliverable.
19. Open Logistics Foundation eCMR (Eclipse, Apache-2.0, live з June 2025)¶
Self-host alternative до TransFollow/DigiCMR.
| Aspect | OLF eCMR | TransFollow |
|---|---|---|
| Licensing | Apache-2.0 (free) | €2000-6000/міс |
| Self-host | Yes | No (SaaS only) |
| Maturity | Live June 2025, мало production users | Established 10+ years |
| EU recognition | UNECE-compliant | UNECE-certified |
Decision Phase 2: OLF self-host vs TransFollow partnership — buy-vs-build analysis. Якщо OLF stable — економимо ~€50K/рік на 1000 транзакцій.
20. WIN Platform (Phase 7 build-vs-buy для Lane RateView)¶
Riege Scope integrated WIN platform для carrier rate aggregation (EU air+ocean).
| Aspect | WIN partnership | Own build (LaneRateHistory) |
|---|---|---|
| Time-to-value | 1-2 тижні (API integration) | 2-3 тижні + N тижнів data accumulation |
| Coverage | Existing EU air+ocean carriers | Tenant-private data only |
| Pricing | TBD (research Phase 2) | Free (internal) |
| Differentiation | Same data як Riege | Unique tenant insight |
Phase 7 = WIN research first (1-2 дні), потім buy-vs-build decision.
21. Awery API (Phase 9+ partnership для avia)¶
Awery — UA-team з ONE Record lead. Партнерство замість build.
| Phase | Action |
|---|---|
| 4-5 calendar window | Outreach conversation з Awery (CEO/CTO) |
| 9+ | Awery API integration в shipcore_avia module (читаємо їх AWB, наш Booking → їх charter request) |
| Long-term | White-label opportunity (Awery як UA-team може брендувати ShipCore для свого ринку) |
Effort estimate (оновлено з Phase 1)¶
| Tier | Кількість | Effort | Phase |
|---|---|---|---|
| 🔴 P0 v1 (UA-only) | ~10 (Maersk, eTTN, BAF, Wialon, НП, ContainerHub EDI, DCSA VGM REST, M.E.Doc, eCMR foundation OLF, Privat24/Mono) | 12-16 тижнів | Phase 4-7 |
| 🔴 P0 v1.5 (EU expansion) | ~8 (Hapag, CMA, eFTI 4 connectors, ICS2 R3, EMSWe, eBL hub primary) | 8-12 тижнів | Phase 8 |
| 🟡 P1 long tail | ~20+ (MSC, ONE, Vizion fallback, інші eBL хаби, інші tracking aggregators, Awery, WIN) | 12-16 тижнів | Phase 8+ |
| 🟢 P2-P3 | ~30 | За запитом клієнтів | v2-v3 |
Total v1+v1.5 effort: ~30-40 тижнів за поточним темпом 1-2 сесії/тиждень з власником-розробником.
Phase 1 additions закрито 2026-05-12. Phase 2 deep API specs стартує з оновленого scope (~25 інтеграцій).