Перейти до змісту

ShipCore — Phase 2 UA Integrations Deep Dive

Контекст: decisions-2026-05-12 § C7 зафіксував v1 execution = UA-only + UA→Constanța (Black Sea коридор). Phase 8 (EU expansion) винесено у v1.5. Це робить UA-інтеграції критично важливими — на них стоїть весь v1 revenue. Документ розглядає 7 треків глибше за поверхневий список з integration-matrix.

Методологія: web-research май-2026 + поточний стан кодбази (backend/baf_sync/, backend/medoc_exchange/, backend/fleet/ для eTTN). Невпевнені факти позначено (?). Сирі джерела — внизу кожної секції.

Бюджет читання: ~30 хв. Дія: вибрати 1-2 рекомендації з кожного треку для Phase 4-7 backlog.

TL;DR — рекомендації за треками

# Трек v1 рекомендація Phase
1 УЗ Cargo (rail) direct API access через офіційну заявку до ГІОЦ УЗ + AsMAP як fallback на дозволи. Scraping — відмовитись. 6
2 eTTN providers Vchasno + M.E.Doc як два первинні (мають REST API, BAS connector, мажоритарний market share); EDI NETWORK як третій лише за вимогою клієнта. 4
3 Last-mile Нова Пошта в v1 (де-факто стандарт), Укрпошта в v1.1. Meest/Justin/Rozetka/Делівері — за demand. 5
4 BAF Sync (BAS) Відмовитись від побудови «BAF API клієнта» — продакшн-міст робимо через акредитованого EDI-провайдера (Vchasno/M.E.Doc), які вже мають готові BAS-конектори. Поточний backend/baf_sync/ залишити як direct-HTTP fallback. 4-5
5 M.E.Doc Через офіційний M.E.Doc REST Web API (SignAndSendDocument) для ePN/ЄРПН + reuse існуючого medoc_exchange/UKTZED. Митні декларації → через QDPro або брокера, не M.E.Doc. 4 + 6
6 Banking Privat24 Business + Mono Business — production-ready (вже частково в essentials.bank_statement_import). Raiffeisen Aval Cash Management Open API — додати у Phase 5. FUIB/OTP/Universal — long-tail, mt940/csv import. вже є
7 Black Sea / Constanța Не «integration», а playbook + master data: MarketCorridor записи + customs broker registry + ePhyto/insurance довідники. ICS2 R3 — у v1.5. 5

Track 1 — Укрзалізниця Cargo API

1.1 Поточний state

УЗ перевела роботу клієнтів з legacy системи АС «Клієнт УЗ» у новий «е.Портал УЗ-Карго» (https://e-portal.uz.gov.ua/). Перехід завершено приблизно у 2024-2025; стара АС Клієнт відключається. Оператор — філія «Головний інформаційно-обчислювальний центр» (ГІОЦ) АТ «Укрзалізниця» (https://gioc.uz.gov.ua/).

Послуги, доступні через е.Портал УЗ-Карго (підтверджено офіційними матеріалами УЗ): - Створення та узгодження залізничної накладної (СМГС / внутрішньоукраїнська); - Формування заявок на перевезення (форма ГУ-12); - Перегляд історії оплат, актів виконаних робіт; - Підписання документів КЕП (через Дія / IIT ЦСК); - Експорт даних у клієнтську ERP/АСУ через API АС «Клієнт УЗ» (історично — XML SOAP-like інтерфейс через окремий B2B-договір).

1.2 ЕТРАН-наслідник: чи живий, чи API доступний для приватних operators?

ЕТРАН — це історично російська (РЖД) система електронної залізничної накладної, на якій базувалась і UA-АС «Клієнт УЗ» через legacy bridge. Після 2014 цей місток фактично перестав працювати, після 2022 — повністю закритий. УЗ власну версію переробила під «УЗ-Карго»/«АС Клієнт УЗ» поверх української інфраструктури ГІОЦ. Тобто:

  • «ЕТРАН-наслідник» технічно — це АС Клієнт УЗ + е.Портал УЗ-Карго, де ГІОЦ виступає operator-of-record.
  • API АС Клієнт УЗ існує (в офіційній документації прямо вказано: «програмний інтерфейс (API) дозволяє звертатися до баз даних УЗ через АС Клієнт УЗ з наявної АСУ підприємства, написаної на основі будь-якої бухгалтерської системи або Microsoft Dynamics NAV, SAP»).
  • Доступ — тільки через формальний договір з УЗ + ГІОЦ після реєстрації клієнта на е.Порталі. Public sandbox станом на травень 2026 (?) — нема.

1.3 Чи має УЗ Cargo public API documentation (REST/SOAP)?

Public публікації: ні. Документація API АС Клієнт УЗ розповсюджується разом із пакетом доступу після підписання договору. На сайті uz.gov.ua / gioc.uz.gov.ua публічно доступні тільки описи бізнес-процесів і інструкції користувача е.Порталу, не схеми XSD/OpenAPI.

Сторонні інтегратори (artport.pro, totalapi.io, mdoffice.com.ua) пишуть про роботу з даними УЗ через свої проміжні сервіси — це сильний сигнал, що direct API доступний, але через NDA + B2B-договір, не open spec.

1.4 B2B-договір процес — як отримати API access

Процес реконструйований з публічних інструкцій (uz.gov.ua/cargo_transportation/electronic_transportation/as_client_uz/):

  1. Реєстрація юр. особи у е.Порталі УЗ-Карго (потрібен ЕДРПОУ + КЕП директора або уповноваженої особи).
  2. Підписання договору на надання послуг електронного документообігу з АТ «Укрзалізниця».
  3. Окрема заявка на API-інтеграцію до ГІОЦ — з технічними реквізитами клієнтської системи (ERP), статичними IP, переліком ролей.
  4. ГІОЦ надає: токен/сертифікат для API, технічну документацію (XSD-схеми накладної, статусних повідомлень), test environment.
  5. Підключення (історично) — 2-6 тижнів від подачі заявки до production-ready (?).

Для ShipCore це означає: інтеграція не може бути «built once, ship to all» — кожен tenant-форвардер сам отримує доступ під свій ЕДРПОУ. ShipCore має дати infrastructure (UI для введення токенів, парсер відповідей, маппінг на shipcore_rail.RailwayWaybill), але не може давати єдиний spider account.

1.5 Альтернативи

AsMAP як посередник

АсМАП України (Association of International Road Carriers of Ukraine) — насамперед road-orientированна асоціація (TIR Carnet, CEMT/двосторонні дозволи, EU permits). Реальної ролі посередника для УЗ Cargo API в АсМАП нема — це різні модальності (road vs rail). Спроба отримати rail-API access через АсМАП — нереалістична.

Корекція до integration-matrix § 2: «через AsMAP» для УЗ Cargo не працює. AsMAP корисний для road-side: TIR-EPD, CEMT permits, дозволи на двосторонні перевезення. Це окрема інтеграція (Phase 6+, не плутати з УЗ Cargo).

Lardi-Trans / OkCargo як tracking aggregators

  • Lardi-Trans має «Extended API» для freight & transport requests (https://lardi-trans.com/news/introducing-our-new-service-extended-api/). Це road freight exchange, не rail-tracking. УЗ Cargo через Lardi не пройде.
  • OkCargo — також road freight exchange. Same story.

Ні Lardi, ні OkCargo не дають rail-tracking aggregator role для УЗ Cargo. Їхній Phase 6 use-case у ShipCore — freight matching для shipcore_auto (підбір вантажів на порожній пробіг), не rail.

artport.pro (Art:RWL)

artport.pro згадує мобільний AC «Клієнт» (додаток Art:RWL) для роботи з ЗД накладними — це white-label поверх АС Клієнт УЗ, не альтернатива. Підказує що direct-API integration реально працює, але оператор уже своїм UI loвить клієнтів.

Scraping fallback

Legal: ст. 361 КК України (несанкціонований доступ) формально не загрожує при логіні власним токеном клієнта і парсингу свого ж кабінету. Але порушення Terms of Service портал-сервісу + потенційний rate-limit ban → operationally fragile.

Technical: е.Портал — це SPA з anti-bot захистом (CAPTCHA на login, session-based CSRF). Headless-браузер scraper працюватиме 2-4 тижні до першої зміни UI. Не варта ефорту.

Recommendation: scraping — категоричне НІ для production. Як short-term hack для Phase 6 demo — можливо (1-2 endpoints з Playwright), але з explicit warning «pilot-only».

1.6 Recommendation: який path для Phase 6 shipcore_rail

Direct API через ГІОЦ — primary path.

backend/shipcore_rail/integrations/uz_cargo/
├── client.py               ← XML/SOAP requests + сертифікат-based auth
├── mapping.py              ← XSD response → shipcore_rail.RailwayWaybill
├── credentials.py          ← per-tenant config (token, cert, ЕДРПОУ)
├── README.md               ← інструкція тенанту як отримати access (3-4 тижні B2B-договір)
└── tests/

Decision matrix:

Path Pros Cons Verdict
Direct ГІОЦ API Production-ready, повна функціональність NDA, 2-6 тижнів onboarding на тенант, документація закрита ✅ primary
AsMAP-посередник — Не існує для rail ❌
Lardi-Trans aggregator — Не покриває rail ❌
artport.pro white-label UI готовий Залежність від конкурента ⚠️ моніторинг
Scraping Швидкий demo Не production ⚠️ hack-only

Phase 6 deliverable — shipcore_rail.uz_cargo з direct integration + per-tenant credentials UI + інструкція «3 кроки до access» (договір → заявка → токен).

1.7 Sources Track 1

  • е.Портал УЗ-Карго: https://e-portal.uz.gov.ua/
  • ГІОЦ УЗ: https://gioc.uz.gov.ua/
  • АС Клієнт УЗ опис: https://uz.gov.ua/cargo_transportation/electronic_transportation/as_client_uz/
  • artport.pro «Запровадження е.Портал УЗ-Карго»: https://artport.pro/news/v-at-ukrzaliznyczya-zaprovadzheno-elektronnyj-portal-z-vantazhnyh-perevezen-e-portal-uz-kargo/
  • railinsider.com.ua «Відновлено доступ до кабінета»: https://www.railinsider.com.ua/vidnovleno-dostup-do-osobystogo-kabineta-kliyenta-na-e-portal-uz-kargo/
  • railinsider.com.ua «Єдине цифрове вікно з 1 липня»: https://www.railinsider.com.ua/ukrzaliznyczya-vprovadyla-yedyne-czyfrove-vikno-ta-z-1-chervnya-prypynyt-robotu-as-kliyent-uz/
  • TotalAPI Укрзалізниця description: https://totalapi.io/iot-ukrzaliznytsia/
  • Lardi-Trans Extended API: https://lardi-trans.com/en/news/introducing-our-new-service-extended-api/
  • AsMAP UA / IRU: https://www.iru.org/membership/members-directory/asmap-ua

Track 2 — eTTN Providers (Vchasno / M.E.Doc / EDI NETWORK)

2.1 Базовий контекст mandate

Підтверджені дати (logistics-ukraine.com лютий 2026, Мінрозвитку): - 2025-Q4 — перші 3 акредитовані оператори (Вчасно, M.E.Doc, EDI NETWORK) - 2026 — добровільне використання + поетапна акредитація додаткових операторів - 2027-01-01 — mandatory використання е-ТТН для перевезень в Україні (?) - Реєстр операторів: https://e-ttn.gov.ua/provider/

Список акредитованих на травень 2026 (з e-ttn.gov.ua/provider/):

# Оператор Платформа Статус
1 ТОВ «Вчасно сервіс» Vchasno.TTN live (Q4 2025)
2 ТОВ «М.Е.Док» M.E.Doc live (Q4 2025)
3 ТОВ «АТС» EDI NETWORK live (Q4 2025)
4 СМАРТТЕНДЕР Signy testing → акредит. (?)
5 Економічні програми СОТА testing
6 Інтекресі Ділз DEALS live з 2026-04-27
7 111 ХВИЛИН Inn.Logist live з 2026-02-25
8 iFinEDI iFinEDI live з 2026-04-03
9 AP Group е-ТТН від AP Group live з 2026-04-08

Roaming між операторами — заплановано через access-keys видані Мінрозвитку (підтверджено Мінрозвитку публічно). Це означає що інтеграція з 1-2 операторами достатня — документ створений у Vchasno можна підписати/прийняти у M.E.Doc через roaming.

2.2 Vchasno.TTN

Формат API: REST + JSON, OAuth2-like авторизація через API token.

Workflow (з vchasno.ua/integration/ і vchasno.ua/edo-ettn-blog): 1. Tenant отримує API token через особистий кабінет Vchasno. 2. ERP формує eTTN payload (JSON структура: відправник/одержувач/перевізник/вантаж/маршрут/дозвіл). 3. POST /api/v2/ttn/create — повертає UUID документа. 4. Підпис: або через ERP (HSM-токен з КЕП) + POST signature, або через web-UI Vchasno (lifecycle: ERP створив draft → юзер заходить у Vchasno → підписує КЕП). 5. Реєстрація в державному реєстрі (e-ttn.gov.ua) — Vchasno робить автоматично. 6. Webhook POST {tenant_url}/vchasno/webhook зі статусом (підписано отримувачем / прийнято / повернуто).

Pricing (vchasno.ua/rates/): - Free tier: 25 документів/рік (для пілоту достатньо). - Платні плани орієнтовно 4 000 — 300 000 грн/рік залежно від обсягу (точні tiers не публікуються, продаються через manager). - Per-document вартість при великих обсягах (~10 000+ документів/міс) орієнтовно 1-3 грн/документ.

BAS connector: Vchasno має готові обробки для BAS Бухгалтерія + BAF (BAF/BAS UA версії) + 1С 7.7/8.2/8.3. Це підказує integration target №1 для ShipCore: дешево досягнути «client уже на BAS, ми ставимо ShipCore поверх → eTTN залишається на тому ж Vchasno».

Production users в логістиці UA: Zeppelin Ukraine (case study на vchasno.ua/case/zeppelin/), Сільпо, ATB, METRO, Eldorado, ROZETKA. Тобто eTTN-stream Vchasno вже обслуговує ~90% retail-логістики.

2.3 M.E.Doc

Формат API: REST Web API (medoc.ua/page/integrationapi + medoc.ua/faq/opis-metodv-web-api).

Документована structure: - POST /api/createDocument — створити документ (тип, payload XML). - POST /api/signAndSend — підписати КЕП + надіслати контрагенту. - GET /api/getDocumentStatus/{id} — статус (signed/sent/accepted/rejected). - GET /api/getInbox?since={ts} — нові вхідні документи.

Файловий обмін (legacy, але робочий): - Папка IN/ — XML файли від M.E.Doc у форматах опублікованих у medoc.ua/page/integrationxml. - Папка OUT/ — XML файли від ERP, M.E.Doc підбирає та вантажить у систему. - Це поточна основа BAF/1С-інтеграції для більшості UA-користувачів. ShipCore має це підтримати як fallback transport для tenants що не хочуть REST.

Pricing: річна підписка ~3 000 — 30 000 грн залежно від набору модулів і обсягу. Per-document — нема, all-you-can-eat у межах ліцензії. Це робить M.E.Doc дешевшим за Vchasno при високих обсягах, але дорожчим при малих.

Mandatory timeline: M.E.Doc — найстаріший EDI-оператор UA (з 2009, найбільша частка серед SMB-бухгалтерій). Майже всі UA-юр.особи з ЄРПН/ЄАІКМ workflow вже мають ліцензію M.E.Doc.

Дія.Підпис integration: M.E.Doc підтримує всі типи КЕП — ID-картка, Дія, ПриватБанк, Action, IIT-токен. Це native, не через API third-party.

Pов'язані сервіси (від тих самих owners — Інтелект-сервіс): - СОТА (Sota.kiev.ua) — cloud-версія M.E.Doc для SMB. Окремий REST API (?). - Paperless (від ПриватБанку, partnership з Інтелект-сервіс) — спрощений документообіг для МСБ через Privat24. Pricing per-document, без річних підписок. Cheap entry point для shop-customers ShipCore.

2.4 EDI NETWORK (АТС)

Найслабше публічно документований з трьох first-wave операторів. На сайті ats-ua.com — мінімум технічних подробиць; інтеграція працює через partner managers.

Workflow (з фрагментарних джерел): - Тип повідомлень: UN/EDIFACT для retail-chains, JSON REST для модернішого інтерфейсу. - Position у ринку: strong у retail FMCG (METRO, Auchan, Сільпо, Епіцентр) — там де треба orderRESPONSE/DESADV/RECADV у форматі EANCOM. - Для логістики/форвардингу — coverage слабша; eTTN додано лише з Q4 2025 з акредитацією.

Recommendation: EDI NETWORK — третій-tier integration, додавати лише за demand від конкретного клієнта. Не вкладатись у Phase 4-5.

2.5 Recommendation: яких 1-2 providers інтегрувати першими

Phase 4 deliverable: backend/shipcore/compliance/exporters/ettn.py з двома backends:

class VchasnoETTNExporter(ETTNExporter):
    """REST + OAuth token. Webhook for status updates."""

class MEDocETTNExporter(ETTNExporter):
    """REST + file fallback. Uses existing medoc_exchange/ infra."""

Why both, not one: - Vchasno = mass-market, retail-friendly, низький CAC у onboarding. - M.E.Doc = «вже стоїть» у 80% UA-юр.осіб, integration «безкоштовна» з боку клієнта (ліцензія вже куплена для ЄРПН).

Roaming-strategy: ShipCore тенант обирає primary provider у settings → ми пишемо в нього → інші провайдери отримують через roaming автоматично. Це критично — інакше треба дублювати API integration на 9 операторів.

Skip: - EDI NETWORK у v1 — не unique-selling-point, не масовий у форвардингу. - DEALS, Signy, СОТА, Inn.Logist, iFinEDI, AP Group — long-tail, integration по запиту клієнта (Phase 8+).

Існуючий код переусе: backend/fleet/ettn/ уже має 9 моделей (ETTNDocument, Party, TestKey з Ed25519). Phase 4 — підключити до thin core shipcore.compliance як один з projection'ів canonical Waybill (decisions § C-eFTI-byDesign).

2.6 Sources Track 2

  • е-ТТН Мінрозвитку: https://e-ttn.gov.ua/
  • Реєстр акредитованих операторів: https://e-ttn.gov.ua/provider/
  • Vchasno головна: https://vchasno.ua/en/
  • Vchasno tariffs: https://vchasno.ua/en/rates/
  • Vchasno EDI+eTTN: https://vchasno.ua/en/edi-ettn-digital-supply-chain/
  • Vchasno integration з обліковими системами: https://vchasno.ua/en/intehratsiia-vchasno-edo-z-oblikovymy-systemamy/
  • Vchasno case Zeppelin: https://vchasno.ua/en/case/zeppelin/
  • M.E.Doc API: https://medoc.ua/page/integrationapi
  • M.E.Doc REST API methods: https://medoc.ua/faq/opis-metodv-web-api
  • M.E.Doc XML import structures: https://medoc.ua/page/integrationxml
  • Logistics Ukraine «Впровадження е-ТТН 2026-2027»: https://logistics-ukraine.com/2026/02/24/vprovadzhennya-e-ttn-2026-2027/
  • Coneksion EDI providers 2026 overview: https://www.coneksion.com/blog/25-great-edi-service-providers

Track 3 — Last-mile UA (Нова Пошта / Укрпошта / Meest / Justin / Делівері)

3.1 Нова Пошта (NovaPost) — обов'язково в v1

API portal: https://api-portal.novapost.com/ + https://developers.novaposhta.ua/

Endpoints (з developers.novaposhta.ua/documentation): - https://api.novaposhta.ua/v2.0/json/ — primary endpoint, POST JSON. - Архітектура — namespaced operations: Address, Counterparty, InternetDocument, TrackingDocument, Common, ContactPerson, AdditionalService.

Ключові операції для ShipCore: - Address.getCities / getWarehouses / getStreet — каталог відділень/поштоматів. - Counterparty.save — створити отримувача (фіз/юр). - InternetDocument.save — створити ТТН НП (return: Number, Ref, EstimatedDeliveryDate, CostOnSite). - InternetDocument.getDocumentList — список ТТН за період. - InternetDocument.delete — скасувати (тільки до прийому в роботу). - InternetDocument.printMarkings / printDocument — PDF labels. - TrackingDocument.getStatusDocuments — масовий запит статусу.

Auth: API key (header Authorization: <key> або body field apiKey). Sandbox доступний (test API key за запитом).

Pricing: - API доступ — безкоштовно для всіх клієнтів НП (юр. осіб з договором). - Основа monetization — comission з відправок, не з API. - Rate-limits офіційно не публікуються; орієнтовно 10 req/sec на ключ (?).

Production examples: absolute majority UA e-commerce + логістики. Будь-який форвардер що робить дрібні відправки в межах UA — НП.

ShipCore role: shipcore_forwarder.LastMileLeg.carrier='nova_poshta' → at booking confirmation викликає InternetDocument.save, повертає Number → embedded в Booking → tracking event polling кожні 15 хв через TrackingDocument.getStatusDocuments → shipcore.ShipmentEvent records.

Code placement: 

backend/shipcore_forwarder/integrations/last_mile/nova_poshta/
├── client.py           ← REST wrapper (api_key, retries, rate-limit)
├── mapping.py          ← Booking → InternetDocument payload
├── webhooks.py         ← (НП webhook лише за окремою угодою; primary path = polling)
├── credentials.py      ← per-tenant API key
└── tests/

3.2 Укрпошта (Ukrposhta)

API portal: https://dev.ukrposhta.ua/ (документація PDF: https://dev.ukrposhta.ua/uploads/API-documentation-29012025-eng.pdf — версія 29.01.2025).

Auth: Bearer token, видається разом із підписаним договором. Sandbox існує (окремий test bearer).

Endpoints: - POST /ecom/0.0.1/shipments — створити відправлення. - POST /ecom/0.0.1/shipment-groups — групове створення. - GET /ecom/0.0.1/shipments/{barcode} — статус. - GET /status-tracking/0.0.1/statuses/last?barcode= — публічний tracking без token (https://dev.ukrposhta.ua/uploads/shipment-tracking.pdf). - GET /addresses-classifier/0.0.1/regions / districts / cities / streets / postoffices — каталог.

Pricing: API безкоштовний, monetization — тарифи відправлень. SMB-друже (cheaper за НП на дрібні літерні відправлення).

Phase 5 priority — корисно як alternative carrier, але не блокер для v1 launch.

3.3 Meest

Формат API: REST, документація через partner agreement. Третій-tier UA-carrier (focus: international parcel forwarding US/EU↔UA). Для ShipCore-Forwarder UA-внутрішнього — irrelevant.

Інтеграція через aggregators: AfterShip, TrackingMore, Tracktry надають готовий REST endpoint для tracking Meest без direct договору. Це може бути shortcut для tracking-only:

class MeestTrackingAdapter(TrackingAdapter):
    """Use AfterShip/TrackingMore aggregator REST instead of direct Meest API."""

Recommendation: Meest — opt-in за demand клієнта. v1 — skip.

3.4 Justin

Особливості: партнерство з мережею Сільпо (https://justin.ua/) — pickup points у супермаркетах. ~500+ поштоматів/відділень.

API: є за запитом через partnership, документація не публічна (?). E-commerce інтегратори (OpenCart, Bitrix24, KeyCRM) мають готові modules — це підтверджує існування API, але без публічного OpenAPI spec.

Recommendation: Justin — opt-in за demand, не v1.

3.5 Делівері (Delivery)

B2B-orientированная carrier (палети, паллетні відправки, негабарит) — релевантна для логістики, на відміну від parcel-carriers вище. API доступний через partner agreement; публічна документація обмежена.

Recommendation: Phase 6+ якщо є demand від pilot tenant.

3.6 Rozetka Delivery

Особливості: в основному last-mile для e-commerce orders Rozetka marketplace. API закритий — офіційно тільки для Rozetka-merchants (https://github.com/2BAD/rozetka — unofficial REST client).

Recommendation: Skip для ShipCore (irrelevant для форвардингу). Може бути integration target для DOP Client Portal / Shop Manager як alternative carrier.

3.7 ShipCore role у last-mile

Важливе позиціонування (integration-matrix § 3): ShipCore — integration target для last-mile, не competitor. Тобто ShipCore-Forwarder використовує НП/Meest як subcontractor leg у multi-leg shipment, не намагається замінити їх.

Архітектурна модель:

# shipcore_forwarder/models/leg.py
class LastMileLeg(models.Model):
    booking = models.ForeignKey('Booking', ...)
    carrier_code = models.CharField(choices=[
        ('nova_poshta', 'Нова Пошта'),
        ('ukrposhta', 'Укрпошта'),
        ('meest', 'Meest'),
        ...
    ])
    external_tracking_number = models.CharField(...)  # ТТН НП / barcode Укрпошти
    integration_state = models.CharField(...)  # created / picked_up / in_transit / delivered

Phase 5 deliverable: 1. Нова Пошта integration (full create + tracking). 2. Уніфікований LastMileAdapter interface. 3. Укрпошта — як reference 2-й adapter (підтверджує що interface scales). 4. Meest/Justin/Делівері — adapter stubs з docs «implement on demand».

3.8 Sources Track 3

  • Нова Пошта developer portal: https://developers.novaposhta.ua/
  • Нова Пошта API integration platform: https://api-portal.novapost.com/
  • Syndicode «Nova Poshta API portal implementation»: https://syndicode.com/projects/nova-poshta-developers-portal-api-documentation/
  • Укрпошта dev portal: https://dev.ukrposhta.ua/
  • Укрпошта API doc 29.01.2025 PDF: https://dev.ukrposhta.ua/uploads/API-documentation-29012025-eng.pdf
  • Укрпошта status tracking PDF: https://dev.ukrposhta.ua/uploads/shipment-tracking.pdf
  • Meest tracking via AfterShip: https://www.aftership.com/carriers/meest/api
  • Justin: https://justin.ua/
  • Rozetka Delivery (unofficial API): https://github.com/2BAD/rozetka

Track 4 — BAF Sync (BAS Бухгалтерія bridge)

4.1 BAF infrastructure overview

Контекст: після виходу 1С з UA-ринку (2022) український вендор «Інформ-Інвест» перебрендував локалізовану 1С як BAS (Бізнес-Автоматизація-Софт). Конкретні продукти: - BAS Бухгалтерія — direct наслідник «1С Бухгалтерія для України». - BAF (BAS Управління торгівлею / BAS Управління підприємством) — наслідник «1С УТ/УПП». - BAS Малий бізнес, BAS Roznitsa і т.д.

Платформа — на форку 1С 8.3 (v83 → BAS-Платформа). Ринок ~80% UA-SMB (?). Це ICP для ShipCore — особливо shipcore_auto як «автопарк-модуль для BAS-користувачів».

4.2 Існуюча MVP в кодбазі (Phase F-3)

Файли: - backend/baf_sync/models/settings.py — BAFSyncSettings (singleton per tenant: base_url, auth_token, enabled, dry_run=True default). - backend/baf_sync/models/mapping.py — BAFEntityMapping (local Django id ↔ BAF UUID). - backend/baf_sync/models/log.py — BAFSyncLog (per-push audit). - backend/baf_sync/services/sync.py — pluggable BAFTransport Protocol + FakeTransport для dry-run + payload builders для Client/Invoice + push runner з deduplication через payload hash. - backend/baf_sync/views.py + urls.py + tests.

Поточний стан: MVP-ready, dry-run by default, real httpx-transport — TBD.

base_url приклад в коментарях — https://baf.example.com/baf_ua/hs/sync — натякає на HTTP-сервіс зареєстрований всередині BAF (1С/BAS-style HTTP services через конфігуратор). Це підтверджує: інтеграція задумана через HTTP-сервіси на стороні BAF, не через зовнішній «BAF API».

4.3 Чи має BAF public API, чи через файловий обмін

Public public-cloud API: ні. BAF/BAS — це installable on-prem продукт; cloud-варіант лише через certified hosting partners (reds.cloud, ibuh.online і т.п.) з власним API surface, не уніфікованим.

Реальні integration patterns:

  1. HTTP-сервіси всередині BAF/BAS — конфігуратор дозволяє декларувати WSDL/REST endpoint всередині конфігурації. Тоді зовнішня система викликає https://{client-baf}.example.com/baf/hs/{name} з токеном.
  2. Це шлях що вже закладено в backend/baf_sync/.
  3. Pro: standardized REST/JSON.

  4. Con: вимагає що BAF-консультант клієнта розгорнув HTTP-сервіс на його BAF-instance. Більшість SMB-клієнтів цього не зробили.

  5. Файловий обмін через папки (legacy 1С EnterpriseData) — XML/JSON файли в папці, BAF-плагін підбирає за розкладом. Так працює інтеграція з M.E.Doc, Vchasno, Privat24 acquiring і т.д.

  6. Pro: zero конфігурація, працює з будь-яким BAF off-the-shelf.

  7. Con: file-system-coupling, retry/audit складніший.

  8. EnterpriseData XML — BAS-native serialization (EDF — Enterprise Data Format). Стандартизовано Microsoft Dynamics-подібно для obmin-конфігураціями.

  9. Pro: native для BAS, є готові parsers/builders у будь-якому BAS-поставщика.

  10. Con: складніший за просту JSON-payload.

  11. Прямий SQL-доступ до БД BAF — historic, для on-prem інсталяцій. Не recommended (схема БД проrieta + breaking changes між версіями).

  12. Через third-party EDI-провайдера як міст — Vchasno/M.E.Doc мають готові BAS-конектори для синхронізації документів. ShipCore може говорити з Vchasno → Vchasno говорить з BAS клієнта.

4.4 Production users в UA логістиці

Транспортно-логістичні компанії в основному ще на 1С 8.3 (legacy) або вже мігрували на BAS Бухгалтерія/BAF УТ. Конкретні case studies: - Wave 1 UA road carrier архетип (Profile 2, decisions § C8) — типово UA-перевізник 50-150 трактів на BAS Бухгалтерія + Auto на legacy 1C7/1C8 (?). Конкретний клієнт TBD. - ZAMMLER (Wave 2) — крупніший форвардер, ймовірно вже на ERP-стеку (?), не критично для BAF Sync. - Загалом — RemOnline / RO App (https://help.roapp.io/en/articles/1637603-integration-with-bas-accounting-for-ukraine) / KeyCRM / Бітрікс24 — всі мають готові BAS-конектори, бо це масовий запит ринку.

4.5 Recommendation: production deployment plan

Двошарова стратегія:

Шар 1 — direct HTTP-service bridge (поточний backend/baf_sync/)

Призначення: «сильні» клієнти з BAF-розробником на проекті, які можуть розгорнути HTTP-сервіс у BAF.

Phase 4-5 deliverable: 1. Завершити httpx-based BAFTransport (зараз тільки FakeTransport). 2. Додати EnterpriseData XML serialization як альтернативу JSON (для conservative BAF-конфігурацій). 3. UI у Settings → BAF Sync: вмикання dry_run toggle, manual «Push now», log viewer (Kanban-style). 4. Розширити entity coverage: поточно — Client + Invoice. Додати: Item, GoodsReceipt, GoodsShipment, IncomingPayment, OutgoingPayment. 5. Webhook у зворотний бік: BAF → ShipCore коли BAF створив документ напряму (зараз — тільки push з ShipCore у BAF).

Шар 2 — EDI-bridge через Vchasno/M.E.Doc

Призначення: mass-market клієнти без BAF-розробника. Vchasno вже має connector до їх BAS — ShipCore просто говорить з Vchasno, а той із BAS клієнта.

Phase 4-5 deliverable: - Sync статусу eTTN у Vchasno → автоматично відображається у документах BAS клієнта (це Vchasno робить native). - ShipCore-side: документувати workflow «if you're on Vchasno, no BAF Sync needed for ETTN».

Decision matrix для tenant onboarding:

Tenant profile Path
Малий перевізник, BAF off-the-shelf, нема BAF-розробника EDI-bridge через Vchasno (Шар 2)
Середній форвардер, є власний BAF-консультант Direct HTTP-service (Шар 1)
Крупна компанія з ERP-командою Custom integration consulting (out of scope для product)

Не робити: не побудувати «BAF API» як єдиний uniform endpoint — кожен BAF-instance унікальний за конфігурацією. Замість того даємо infrastructure (transport + log + dedup) і дозволяємо partner-консультантам адаптувати під конкретний BAS.

4.6 Sources Track 4

  • BAS Бухгалтерія (reds.cloud): https://reds.cloud/software/bas/accounting?language=english
  • IntegraBAS (BAF/1C consulting): https://integrabas.com.ua/en/
  • IntegraBAS ready-made: https://integrabas.com.ua/en/ready-made-solutions/
  • RO App «Integration with BAS: Accounting for Ukraine»: https://help.roapp.io/en/articles/1637603-integration-with-bas-accounting-for-ukraine
  • Vchasno integration (з BAS connectors): https://vchasno.ua/en/integration/
  • iBuh BAS Online: https://ibuh.online/solutions/ibbaccc?siteLocale=en
  • Власна реалізація: backend/baf_sync/ (project repo)

Track 5 — M.E.Doc deep

5.1 Існуючий стан в кодбазі

Існує: backend/medoc_exchange/ Django app з моделлю UKTZEDDirectory (товарна номенклатура УКТЗЕД, потрібна для митних декларацій + ЄРПН/ЄАІКМ).

Management command: load_uktzed (з backend/CLAUDE.md) — завантажує JSON-каталог УКТЗЕД у БД.

Що НЕ існує: REST API integration з самим M.E.Doc — нема client'а до medoc.ua/api, немає SignAndSend, немає ePN/ЄРПН workflow.

5.2 M.E.Doc API specifications

Деталі вже описано у Track 2 § 2.3 — REST API + file exchange + native КЕП support.

Додатково для митної/податкової частини: - PostDocument з типом J1201209 (ПН) → реєстрація у ЄРПН. - PostDocument з типом J1201210 (РК — розрахунок коригування) → реєстрація у ЄРПН. - Опис XML структур публічно: https://medoc.ua/page/integrationxml.

Multi-party document exchange: https://faq.in.ua/medoc/posibnyk/m-e-doc-zvitnist/949-bagatostoronniy-obmin-dokumentami-v-api-/ — workflow коли документ підписують >2 сторін (характерно для триплетів продавець/покупець/транспортер у складних ланцюгах поставок).

5.3 Пов'язані сервіси

Сервіс Власник Призначення API status
M.E.Doc Інтелект-сервіс Desktop + cloud, EDI hub, ЄРПН, eTTN, ЄАІКМ light REST + XML ✅
СОТА Інтелект-сервіс Cloud-only, для SMB/малих ФОПів REST (?) — обмежена
Paperless ПриватБанк × Інтелект-сервіс Документообіг через Privat24 REST через Privat24 API
Vchasno окрема компанія Independent EDI hub, eTTN, КЕП REST ✅
EDI NETWORK (АТС) окрема компанія Retail FMCG EDI EDIFACT + REST

5.4 Митні декларації

M.E.Doc частково покриває митниці, але профільні tools — окремі продукти:

QDPro (НТФ «Інтес»)

  • Стандарт de-facto для митних брокерів UA (https://www.qdpro.com.ua/).
  • Підтримує NCTS Phase 5 (потрібно для T1/T2 транзитів — критично для UA→Constanța через RO).
  • Локальна desktop application + DB. Інтеграція з ERP — через імпорт XML (структури близькі до M.E.Doc формату для J/F-документів).
  • API integration через файловий обмін (XML), не REST.

Декларація-Дист

  • Схожий profile до QDPro, поширений у regional brokers.
  • File-based integration only.

M.E.Doc Митниця (модуль)

  • Окремий модуль M.E.Doc, додатково ліцензується.
  • Більш light порівняно з QDPro, для простих імпортних декларацій не для повного брокерського workflow.

API Держмитслужби ⭐ NEW

https://customs.gov.ua/en/news/it-transformatsiia-62/post/derzhmitsluzhba-vidkrila-api-dostup-do-mitnikh-deklaratsii-biznes-otrimuie-bilshe-danikh-shvidshe-i-prostishe-2212

Держмитслужба офіційно відкрила API для бізнесу — automated access до власних митних декларацій через REST. Це дозволяє ShipCore read-only стрімити поточний статус декларацій клієнта без QDPro/M.E.Doc, що дуже спрощує: - Tracking «де моя декларація» в Booking lifecycle. - Reconciliation «що митниця бачить vs наш документ».

Phase 6 deliverable: integration з API Держмитслужби (read-only declarations status). Це easier win ніж QDPro-bridge.

5.5 ePN/ЄРПН реєстрація

Workflow в контексті ShipCore-Forwarder:

  1. ShipCore форвардер виставляє Invoice клієнту (через essentials.Invoice).
  2. ПН (податкова накладна) має бути зареєстрована в ЄРПН протягом 5 днів.
  3. Це робить бухгалтерія форвардера у M.E.Doc/Vchasno, не ShipCore.
  4. ShipCore роль — забезпечити що essentials.Invoice має всі поля для ПН (УКТЗЕД код, ставка ПДВ, ознака платника ПДВ контрагента).

Існуючий medoc_exchange/UKTZED — це foundation для цього: при заведенні Item у essentials.Item → user обирає УКТЗЕД код з довідника → коли формується ПН, код прокситься у M.E.Doc.

Recommendation: не дублювати ЄРПН-логіку у ShipCore. Дотримуватись поточної моделі: medoc_exchange/UKTZED як master data → форвардер сам реєструє ПН у M.E.Doc.

5.6 Recommendation: повний M.E.Doc integration scope для ShipCore

Phase 4 (foundation): - Розширити medoc_exchange/ від UKTZED-only до загального M.E.Doc REST client. - Додати MedocCredentials (per-tenant: api_token, default_signature_key). - Створити MedocDocumentExporter для типових документів (Invoice → eAct, GoodsShipment → eShipment-document для multi-party signing).

Phase 6 (customs): - API Держмитслужби — read-only declarations status. Easy win. - QDPro file-bridge (export shipcore_forwarder.Booking → QDPro XML format) — за demand. - M.E.Doc Митниця module — skip, не варта ефорту, бо QDPro покриває кращe.

Phase 8+ (long-tail): - СОТА — окремо для micro-tenants (SMB форвардерів-ФОПів). - Paperless — discovery, чи має сенс через Privat24-bridge.

NOT do: - Не будувати власний КЕП-стек (DSTU 4145). Reuse Дія КЕП через web-flow OR через IIT cryptolib через C++ wrapper. Складність DSTU 4145 + сертифікація CSP — не наша компетенція. - Не competing з QDPro/M.E.Doc у customs. Вони мають 20-річну експертизу.

5.7 Sources Track 5

  • M.E.Doc integration overview: https://medoc.ua/page/integrationapi
  • M.E.Doc REST methods: https://medoc.ua/faq/opis-metodv-web-api
  • M.E.Doc XML structures: https://medoc.ua/page/integrationxml
  • M.E.Doc multi-party API: https://faq.in.ua/medoc/posibnyk/m-e-doc-zvitnist/949-bagatostoronniy-obmin-dokumentami-v-api-/
  • QDPro: https://qdpro.com.ua/
  • QDPro NCTS Фаза 5: https://qdpro.com.ua/uk/customs
  • Держмитслужба API: https://customs.gov.ua/en/news/it-transformatsiia-62/post/derzhmitsluzhba-vidkrila-api-dostup-do-mitnikh-deklaratsii-biznes-otrimuie-bilshe-danikh-shvidshe-i-prostishe-2212
  • Storecove «E-invoice requirements Ukraine»: https://www.storecove.com/blog/en/what-are-the-e-invoice-requirements-in-ukraine/
  • EDICOM «Ukraine SAF-T 2025»: https://edicomgroup.com/blog/ukraine-saft-electronic-tax-invoice
  • Дія КЕП підпис: https://ca.diia.gov.ua/sign
  • DSTU 4145 Python (broken/research): https://github.com/dstucrypt/ukurwa4145

Track 6 — Banking (вже частково існує)

6.1 Існуючий стан

backend/essentials/ має повний Cash & Bank блок (backend/CLAUDE.md): - BankStatement + BankStatementLine — узгодження виписок. - 4 importer'и: mt940 / iso20022 / Privat CSV / Monobank CSV. - bank_statement_import.py, bank_matching_service.py, bank_statement_service.py. - Auto-match scoring, Kanban UI (BankStatement.state='posted' = reconciled, без проводок — лінкований платіж робить проводки; pattern documented decisions).

Це означає: ShipCore вже має production-ready bank-statement import. Phase 4-5 — лише розширення на API-pull замість CSV-import.

6.2 Privat24 Business

API: https://api.privatbank.ua/ + https://privatbank.ua/en/business/intehratsiya — найбільш зрілий UA-API (з 2009, 4900+ partners).

Релевантні endpoints: - Autoclient module — periodic auto-pull statements + auto-push payments. Поточний integration target. - Account balances + statements за період + currency operations. - Payments push (з 2FA через SMS/КЕП). - Acquiring (POS terminals) — для Client Portal billing, не для форвардингу. - Paperless — окремий продукт документообігу (див. Track 5 § 5.3).

Auth: API token + IP whitelisting + 2FA для payment push.

Pricing: API безкоштовний для бізнес-клієнтів Privat24.

ShipCore Phase 5: замінити CSV-import на native Privat24 API pull (Autoclient pattern). bank_statement_import.py отримує новий transport PrivatBankAPIImporter поряд з існуючим PrivatBankCSVImporter.

6.3 Mono Business (Monobank)

API: https://api.monobank.ua/docs/corporate.html — corporate API.

Workflow auth: 1. Generate ECDSA secp256k1 keys (OpenSSL). 2. Email api@monobank.ua з public key + опис проєкту. 3. Apply approved → access via private key signing. 4. User authorizes app у Monobank mobile.

Endpoints: - Account info + balance + statements. - Webhook для real-time транзакцій. - Без rate limits (на відміну від public API). - Recommended для commercial use.

ShipCore Phase 5: MonobankAPIImporter поряд з існуючим CSV-import.

6.4 Raiffeisen Bank Aval

Cash Management Open API: https://raiffeisen.ua/en/aem/korporatyvnym-klientam/open-api.html.

Auth: OAuth 2.0 + JWT, JSON over HTTPS. Onboarding: 1 day після підписаної заявки (sign with digital signature). Coverage: account balances + statements (intraday + end-of-day). Payments push: не підтверджено в публічних матеріалах (?). Контакт: cm.sales@raiffeisen.ua.

Phase 5 priority — MID, додати після Privat24/Mono.

6.5 FUIB / OTP / Universal Bank / Ukreximbank / Ukrgasbank

Stан: - FUIB має API (https://apitracker.io/a/pumb-ua) — full Open Banking API, OAuth 2.0, balances + statements + payment initiation. Production-ready. - OTP Bank Ukraine — API через Click OTPay (https://otpay.com.ua/), документація закрита (?). - Universal Bank — Open Banking aggregator support (https://www.openbankingtracker.com/country/ukraine), direct API не публічний. - Ukreximbank / Ukrgasbank — state-owned, API лише через legacy mt940 file exchange.

Recommendation: mt940 / ISO 20022 file import як baseline для всіх non-top3 банків. ShipCore вже має ці importer'и → нічого нового не потрібно для покриття long-tail.

Phase 8+: додати FUIB native API як 4-й native client (після Privat24 / Mono / Raiffeisen).

6.6 Recommendation summary

Bank Path Phase
Privat24 Business Autoclient API replace CSV 5
Mono Business Corporate API replace CSV 5
Raiffeisen Aval Cash Management Open API 5
FUIB Open Banking API 8
OTP / Universal mt940/ISO 20022 file import (existing) вже є
Ukreximbank / Ukrgasbank / держбанки mt940 file import вже є

6.7 Sources Track 6

  • PrivatBank API: https://api.privatbank.ua/
  • Privat24 Integration: https://privatbank.ua/en/business/intehratsiya
  • Monobank Corporate API: https://api.monobank.ua/docs/corporate.html
  • Monobank Open API community docs: https://github.com/siomochkin/monobank-open-api-documentation
  • Raiffeisen Cash Management Open API: https://raiffeisen.ua/en/aem/korporatyvnym-klientam/open-api.html
  • FUIB API tracker: https://apitracker.io/a/pumb-ua
  • Open Banking Ukraine overview: https://www.openbankingtracker.com/country/ukraine
  • Власна реалізація: backend/essentials/services/bank_statement_import.py

Track 7 — Black Sea Corridor Customs (UA→Constanța + Дунайські порти)

7.1 Контекст

Decisions § C7 — v1 execution = UA-only + UA→Constanța (Black Sea коридор). Цей трек документує що це означає operationally.

7.2 Constanța port operations

Контекст: після блокади UA Чорноморських портів (2022) і часткового відновлення Sea Corridor через тер. води Румунії і Болгарії, Constanța + Дунайські UA-порти (Ізмаїл/Рені/Усть-Дунайськ) стали головним gateway для UA-експорту/імпорту.

Cargo volumes 2024-2025: - UA seaports у 2024: 97.2 млн тонн (+57% YoY) (mindev.gov.ua). - Дунайські порти 2025: 8.9 млн тонн (Ізмаїл/Рені/Усть-Дунайськ). - Sea Corridor: 9 061 vessels у 2024 (4 651 inbound + 4 410 outbound). - Constanța стала bottleneck — congestion при недостатній capacity (gmk.center).

Customs flow для UA-cargo через Constanța:

  1. Vessel приходить у Constanța (термінал DPW Constanța, APMT Constanța, інші).
  2. Карго не випускається в Romania domestic — формується T1 NCTS declaration з кодом виходу ROCT1970 — Biroul Vamal Constanta PORT (специфічний код для in-transit cargo до UA).
  3. Cargo trucks/wagons рухаються до UA-кордону (Орлівка/Рені/Дяковo чи інші).
  4. На UA-кордоні — UA-митниця приймає, відкривається UA-режим (імпорт/реекспорт/etc.).

Critical для форвардера: документ повинен мати notation «In Transit to Ukraine» (CMA CGM publishes this requirement: https://www.cma-cgm.com/local/ukraine/news/194/export-guidelines-in-constanta-port-br-).

Customs broker: обов'язково на RO-стороні для T1 emission. Це не automated — broker submits T1 у NCTS RO, потім CMA/Maersk/agent отримує release.

ShipCore role: не automation T1, а registry customs brokers per corridor + checklist «що подати у Constanța customs» + integration з Tracking aggregator (Vizion/Maersk Track API) для container status у RO термінал.

7.3 Дунайські UA-порти (Ізмаїл / Рені / Усть-Дунайськ)

Profile: - Ізмаїл — крупніший, основний для зернових + контейнерних feeders. - Рені — друге місце, спеціалізація Liquid bulk + general cargo. - Усть-Дунайськ — найменший, нішевий.

UA-internal customs flow (кардинально простіше за Constanța): - Cargo прибуває з Дунаю у UA-порт → standard UA imp/exp процедура → митниця у самому порту. - Дунайські порти експериментують з роботизацією — Bessarabia INFORM лютий 2026: автоматизація операцій terminals. - Plans: залізничний коридор Velchynets–Oknytsya–Beltsy–Ungheni–Chişinău–Kainari (~400 km) для з'єднання UA Дунайських портів з MD/RO mainline. - Industrial parks plans у Ізмаїлі/Рені — приваблення investors.

ShipCore role: Дунайські порти підпадають під C1 (custom TOS для small ports) — shipcore_terminal має own TOS implementation для них (на відміну від bridge для big terminals Constanța/Гданськ).

Decisions § C1 — Phase 5.5 (mini-phase 1-2 тижні) — Дунайські TOS adaptation як reaction на Octopi expansion.

7.4 Чорноморський коридор post-Grain Initiative

Maritime route: - Vessels йдуть близько до берегів UA + RO + BG (територіальні води NATO countries) — захист від російських атак. - Старт у Greater Odesa area (з вересня 2023) → захід уздовж UA + RO coast → Bosphorus → world. - Координує ВМС України (Ukrainian Navy escort). - Joint mine-sweeping initiative TR + RO + BG (2024-2025).

Insurance: - Unity facility (Marsh McLennan + Lloyd's + Ascot lead) — war risk insurance до $50M hull + P&I. - Розширено з grain до всіх non-military cargo (2024). - Ukreximbank + Ukrgasbank — state-backed first-loss compensation funds. - Доступно через всіх Lloyd's-registered brokers.

ShipCore role: master data InsuranceProvider + WarRiskCertificate як FK на Booking. Не automation страхування (це broker territory), а registry + audit trail «який сертифікат покриває це судно».

7.5 Phyto-sanitary, certificate of origin, marine insurance integrators в UA

ePhyto (electronic Phytosanitary Certificate)

З 2025-11-01 — UA повністю переходить на електронні фітосанітарні сертифікати для exports у EU (ukragroconsult.com, agroreview.com).

ShipCore role: Booking перевіряє: cargo type ∈ {grain, plant products} + destination ∈ {EU, RO} → запит ePhyto через Держпродспоживслужбу UA. API публічний? — дослідити Phase 6 (ймовірно через Єдине вікно державних сервісів UA).

Certificate of Origin

  • Видає Торгово-промислова палата (UCCI) — https://ucci.org.ua/.
  • Електронний сертифікат CO/EUR.1 — через portal UCCI з 2023.
  • API не публічний, але є partner agreement для ERP-bridges.

Marine cargo insurance

  • На Дунаю + Чорному морі — через Unity facility + brokers Marsh/Howden/Lockton/Aon UA representatives.
  • Інтеграція — file-based: broker emails сертифікат, форвардер attaches до Booking.
  • ShipCore role — Booking.insurance_certificate FileField + audit. Не automation.

7.6 Recommendation: ShipCore Phase 5 deliverable

Не «integration», а operational playbook + master data:

backend/shipcore/master_data/
├── customs_broker.py         ← per-corridor brokers (RO-side, UA-side)
├── insurance_provider.py     ← Unity, Marsh, Howden + per-policy data
└── ephyto_certificate.py     ← cert numbers + validity + origin

backend/shipcore/services/
└── black_sea_corridor.py     ← validation: для UA→Constanța booking required fields:
                                  - T1 broker assigned
                                  - Insurance certificate present
                                  - ePhyto if cargo_type ∈ {grain, plant}
                                  - Notation «In Transit to Ukraine» on docs

backend/shipcore_forwarder/
├── corridors/
│   ├── black_sea.py          ← Constanța + Dunaj subcorridor configs
│   ├── danube.py             ← Ізмаїл/Рені/Усть-Дунайськ subcorridor
│   └── ua_internal.py        ← без cross-border вимог

Phase 6 add: - API Держмитслужби (read-only declarations status, Track 5 § 5.4). - Tracking aggregator (Vizion P0 fallback) для container status у Constanța terminals.

Phase 8 (v1.5) — EU expansion: - ICS2 R3 (HR/LV/PL/RO/SK з 2026-06-01) — pre-arrival declarations. - NCTS T1 direct connect через QDPro або через broker. - TIR-EPD через АсМАП. - eCMR через OLF self-host або TransFollow (decisions § C-eFTI-byDesign).

7.7 Sources Track 7

  • Constanța transit guidelines (CMA CGM): https://www.cma-cgm.com/local/ukraine/news/194/export-guidelines-in-constanta-port-br-
  • Romania customs regulations (US Trade): https://www.trade.gov/country-commercial-guides/romania-customs-regulations-and-contact-information
  • GMK Center «Constanța congested»: https://gmk.center/en/news/new-routes-needed-for-ukrainian-freight-as-constanta-port-in-romania-congested/
  • Maritime Gateway «Constanța faces congestion»: https://www.maritimegateway.com/port-of-constanta-faces-congestion-as-ukrainian-ports-remain-blocked/
  • USM «Координаційна рада запуск дунайських портів»: https://usm.media/koordynacijna-rada-pidtrymala-zapusk-eksperymentaljnoho-projektu-rozvytku-dunajsjkyx-portiw/
  • Bessarabia INFORM «Роботизація портів на Дунаї»: https://bessarabiainform.com/2026/02/robotyzatsiya-portiv-na-dunayi-avtomatyzatsiya-pidvyshhuye-efektyvnist-ukrayinskoyi-logistyky/
  • Mindev «Управління морським і ВВТ 2025/2026»: https://mindev.gov.ua/news/upravlinnia-morskym-ta-vnutrishnim-vodnym-transportom-u-2025-rotsi-kliuchovi-rezultaty-ta-plany-na-2026-rik
  • railinsider.com.ua «9 млн т на Дунаю»: https://www.railinsider.com.ua/torik-porty-dunayu-obrobyly-majzhe-9-mln-t-vantazhiv
  • Marsh McLennan «Unity expanded»: https://www.marshmclennan.com/news-events/2024/march/unity-insurance-facility-expanded-to-cover-all-shipping-to-and-from-Ukrainian-ports.html
  • Maritime Executive «Ukraine corridor anniversary»: https://maritime-executive.com/article/ukraine-vows-to-expand-black-sea-shipments-on-first-anniversary-of-corridor
  • Kyiv Independent «Is Ukraine's new Black Sea corridor working?»: https://kyivindependent.com/is-ukraines-new-black-sea-corridor-working-experts-say-it-has-potential/
  • Forwarder Law «Ukrainian Maritime Trade 2024-2025»: http://forwarderlaw.com/2025/04/25/ukrainian-maritime-trade-in-2024-2025/
  • ePhyto Ukraine→EU transition: https://ukragroconsult.com/en/news/ukraine-to-switch-to-electronic-phytosanitary-certificates-for-exports-to-the-eu/
  • AgroReview ePhyto: https://agroreview.com/en/newsen/agripolicy/issuance-phytosanitary-certificates-for-the/

Cross-track integration architecture

Для уникнення дублювання логіки crossing tracks, рекомендований pattern:

backend/shipcore/
├── compliance/                          ← cross-cutting (Track 2, 5, частково 7)
│   ├── exporters/
│   │   ├── ettn.py                      ← Vchasno + M.E.Doc backends
│   │   ├── medoc_doc.py                 ← M.E.Doc REST для multi-party docs
│   │   └── customs_status.py            ← Держмитслужба API read-only
│   ├── signing/
│   │   └── kep_dia.py                   ← Дія КЕП wrapper (DSTU 4145)
│   └── credentials/
│       ├── ettn_provider.py             ← per-tenant Vchasno/M.E.Doc tokens
│       └── medoc_account.py
├── master_data/                         ← Track 7
│   ├── customs_broker.py
│   ├── insurance_provider.py
│   ├── ephyto_certificate.py
│   ├── market_corridor.py               ← Black Sea / Danube / UA-internal
│   └── carrier.py                       ← already in [decisions § 7]
└── services/
    └── corridor_validation.py           ← Booking.validate() per corridor

backend/shipcore_rail/
└── integrations/
    └── uz_cargo/                        ← Track 1

backend/shipcore_forwarder/
└── integrations/
    └── last_mile/
        ├── nova_poshta/                 ← Track 3
        └── ukrposhta/

backend/baf_sync/                        ← Track 4 — ALREADY EXISTS, extend
└── (existing structure: settings, mapping, log, services)

backend/medoc_exchange/                  ← Track 5 — ALREADY EXISTS, extend
└── (existing UKTZED + add document REST integration)

backend/essentials/services/
├── bank_statement_import.py             ← Track 6 — extend with API importers
└── (Privat24 Autoclient + Monobank Corp + Raiffeisen)

backend/shipcore/compliance/exporters/
└── ics2.py                              ← Track 7 v1.5 (Phase 8)

Pitfalls/anti-patterns

  1. «Один integration для всіх tenants» — нереалістично для УЗ Cargo, BAF, M.E.Doc. Кожен tenant отримує власні credentials через власні B2B-договори. ShipCore дає infrastructure, не shared spider account.

  2. Будувати власний DSTU 4145 stack — складність + сертифікація + maintenance не варті. Reuse Дія / IIT cryptolib.

  3. Скрейпити е.Портал УЗ-Карго — fragile, проти ToS, sustaining cost > value.

  4. Конкурувати з QDPro / M.E.Doc Митниця — у них 20-річна експертиза, ринок насичений. Reuse через file/REST bridge.

  5. Ставити EDI NETWORK у v1 eTTN — немає market-share value у форвардингу. Vchasno + M.E.Doc покривають 95% pilot tenants.

  6. Будувати ePhyto / Certificate of Origin automation — це регулятор-side, не product-side. ShipCore registers cert numbers, broker submits.

  7. Один HTTP client для BAF — не існує. Двошарова стратегія (direct HTTP-service + EDI-bridge через Vchasno).

  8. Direct-API до 9 операторів eTTN — використовуй roaming через Мінрозвитку. 2 backends достатньо.

Phase 4-7 backlog (concrete)

Phase 4 (compliance foundation)

  • [ ] shipcore/compliance/exporters/ettn.py з 2 backends (Vchasno + M.E.Doc).
  • [ ] Розширити medoc_exchange/ — повний REST client (поки тільки UKTZED).
  • [ ] baf_sync/ — додати реальний httpx transport (зараз тільки FakeTransport).
  • [ ] EnterpriseData XML serialization як alternative payload format у baf_sync.

Phase 5 (last-mile + banking)

  • [ ] shipcore_forwarder/integrations/last_mile/nova_poshta/ — full create + tracking.
  • [ ] shipcore_forwarder/integrations/last_mile/ukrposhta/ — як 2-й adapter.
  • [ ] LastMileAdapter уніфікований interface.
  • [ ] essentials/services/bank_statement_import.py — PrivatBankAPIImporter + MonobankAPIImporter + RaiffeisenAPIImporter.
  • [ ] BAF IncomingPayment / OutgoingPayment push entities.

Phase 5.5 (Дунайські TOS)

  • [ ] shipcore_terminal adaptation для Ізмаїл/Рені/Усть-Дунайськ (mini-phase 1-2 тижні).

Phase 6 (rail + customs)

  • [ ] shipcore_rail/integrations/uz_cargo/ — direct HTTP/SOAP до ГІОЦ + per-tenant credentials UI.
  • [ ] shipcore/compliance/exporters/customs_status.py — Держмитслужба API (read-only).
  • [ ] Інструкція тенанту «3 кроки до УЗ Cargo access» (договір → заявка → токен).
  • [ ] Optional: QDPro file-bridge для booking → declaration export.

Phase 7 (lane rates + master data Black Sea)

  • [ ] shipcore/master_data/{customs_broker, insurance_provider, ephyto_certificate} for Black Sea corridor.
  • [ ] shipcore/services/corridor_validation.py — booking validation per corridor.
  • [ ] WIN platform research (carrier rate aggregation, decisions § C3).

Phase 8 (v1.5 EU expansion — окремо від UA scope)

Phase 2 UA Integrations Deep Dive закрито 2026-05-12. Phase 3 (модуль/UI design ShipCore-Forwarder + Auto refactor) стартує з цих рекомендацій як integration backlog.