Переход на электронный документооборот в грузоперевозках — это не просто замена бумаги на файлы. Для каждого участника цепочки поставки меняется привычный регламент работы. Сервис «Контур.Логистика» предлагает API, который автоматизирует создание, подписание и передачу электронной транспортной накладной (ЭТрН) в государственную информационную систему (ГИС ЭПД).
Ключевая особенность системы в том, что функциональность и доступные методы API напрямую зависят от того, кем является пользователь в цепочке перевозки. Разберем детально сценарии для каждой роли, а также структуру титулов Т1–Т8, которыми они обмениваются.
Структура титулов ЭТрН (Т1–Т8)
Прежде чем переходить к ролям, важно понять, из каких юридически значимых частей состоит Транспортная накладная. В цифровом виде каждый раздел — это отдельный XML-файл (титул), который подписывается определенным участником.
Основные титулы транспортной накладной:
- Т1 (Титул грузоотправителя) — первый документ в цепочке. Здесь фиксируются данные о товарной партии (наименование, количество, цена) и транспортном средстве до начала рейса.
- Т2 (Титул перевозчика) — заполняется и подписывается водителем или представителем транспортной компании. Фиксирует фактические даты и состояние приема груза к перевозке.
- Т3 (Титул грузополучателя) — завершающий титул в «идеальном» сценарии. Подписывается на складе выгрузки, подтверждая, что товар доставлен, и фиксируя фактические сроки и состояние.
- Т4 (Титул изменения грузоотправителя) — корректировочный титул. Используется, если грузоотправитель сам нашел ошибку в Т1 и хочет внести изменения до старта движения документа дальше по цепочке.
- Т5 (Титул изменения перевозчика) — инициируется перевозчиком, если при приемке груза обнаружены расхождения с тем, что заявлено в Т1.
- Т6 (Титул изменения грузополучателя) — инициируется получателем, если при выгрузке обнаружены расхождения по сравнению с информацией в Т1 и Т2.
- Т7 (Титул согласования изменений) — вспомогательный титул. Им обмениваются участники, чтобы подтвердить или отклонить изменения, предложенные в Т4, Т5 или Т6.
- Т8 (Титул водителя) — подписывается водителем, удостоверяя, что в рейс направлено именно то транспортное средство и лицо, которое указано в Т1 и Т2, и он принял груз к перевозке.
1. Грузоотправитель: Инициатор процесса (Работа с Т1, Т4, Т7)
Грузоотправитель — это «точка входа» документа в цифровой контур. Он формирует черновик и запускает цепочку подписания.
Бизнес-задача: Сформировать корректный Титул Т1 и передать его следующему участнику, не обращаясь к бумаге.
Работа через API:
- Создание черновика (
POST /documents): В теле запроса обязательно указываетсяtype: "waybill". Система инициирует создание структуры для Титула Т1. - Наполнение данными: Через параметры запроса заполняются основные реквизиты: товарный раздел (груз, вес, стоимость), транспортный раздел, ИНН/КПП контрагентов.
- Подписание и отправка (
POST /documents/{id}/send): Грузоотправитель подписывает своей УКЭП Титул Т1. После этого документ автоматически становится доступен перевозчику.
Действия с изменениями:
- Самостоятельная корректировка (Т4): Если ошибка найдена сразу, до подписания Т2, грузоотправитель может сформировать Титул Т4.
- Реакция на других (Т7): Если перевозчик (через Т5) или получатель (через Т6) нашли расхождение, они направляют запрос. Грузоотправитель обязан сформировать встречный Титул Т7, в котором он либо согласует, либо отклонит предложенную корректировку.
2. Перевозчик: Ключевое звено (Работа с Т2, Т5, Т7, Т8)
Роль перевозчика в API самая насыщенная. Он работает с титулами приема груза, изменений и фиксации водителя.
Бизнес-задача: Оформить Титулы Т2 и Т8, при необходимости инициировать Титул Т5 и обеспечить подписание документа получателем (Т3).
Работа через API:
- Прием груза и рейс (Т2 и Т8):
- Получив уведомление о подписании Т1, перевозчик заполняет Титул Т2 (данные о фактической приемке: дата, время, оговорки).
- Одновременно (или последовательно) оформляется Титул Т8. Его подписывает непосредственно водитель, подтверждая, что именно он и указанное ТС приняли груз.
- Фиксация расхождений (Т5):
- Если при погрузке обнаружены несоответствия (недовес, бой), перевозчик не просто пишет оговорку в Т2. Он инициирует Титул Т5 (Титул изменения перевозчика).
- API позволяет создать этот титул, указав причину расхождения.
- После создания Т5 ожидается ответное подписание Титула Т7 от грузоотправителя.
- Доставка: После завершения рейса перевозчик ожидает от грузополучателя подписания Титула Т3.
3. Грузополучатель: Финализатор приемки (Работа с Т3, Т6, Т7)
Грузополучатель завершает документооборот подписанием своего титула.
Бизнес-задача: Принять груз, зафиксировать фактическое время прибытия и состояние товара, подписать Титул Т3 или инициировать Титул Т6.
Работа через API:
- Идеальная приемка (Т3):
- Получатель видит, что подписаны Т1 и Т2. Ему становится доступен для заполнения Титул Т3.
- Он вносит данные о фактической выгрузке (дата, время, состояние) и подписывает его. Документооборот закрыт.
- Приемка с проблемами (Т6 и Т7):
- Если есть расхождения (недостача, излишки, брак), получатель не подписывает Т3, а формирует Титул Т6 (Титул изменения грузополучателя).
- Этот титул уходит в цепочку согласования. Грузоотправитель (и/или перевозчик) должны ответить Титулом Т7.
- Только после того как все стороны подпишут Т7 и согласуют изменения, документ может быть закрыт с учетом корректировок.
Детальная карта маппинга (Ваша БД → Титулы ЭТрН)
1. Титул Т1 (Грузоотправитель)
Здесь вы выступаете инициатором.
| Ваше поле в БД | Куда мапится в Т1 | Комментарий |
|---|---|---|
Грузоотправитель | Отправитель (юр. лицо) | Основной реквизит титула |
Грузополучатель | Получатель (юр. лицо) | |
Перевозчик | Перевозчик (юр. лицо) | Важно указать, кто везет |
Заказчик / Плательщик | Заказчик перевозки | Если отличается от Отправителя |
Пункт погрузки | Адрес погрузки | |
Пункт разгрузки | Адрес разгрузки | |
Договор / Заявка подачи ТС | Основание перевозки | Номер и дата договора/заявки |
Номер ТН + Дата ТН | Номер и дата Транспортной накладной | |
КолМестГр | Количество грузовых мест | |
Брутто | Масса груза (брутто) | |
ЦенностьГруза | Объявленная стоимость | |
МетодОпрМассы | Способ определения массы | Обязателен для сыпучих грузов |
Сумма | Провозная плата | Может быть вычислена системой |
2. Титул Т2 и Т8 (Перевозчик и Водитель)
Это самая насыщенная часть. Вы передаете эти данные после того, как Т1 создан.
| Ваше поле в БД | Куда мапится (Т2/Т8) | Комментарий |
|---|---|---|
Автомобиль / Госномер | Транспортное средство (Т2/Т8) | Марка, модель и госномер |
Тип_ТС + Грузоподъемность_ТС + Вместимость_ТС | Характеристики ТС (Т2) | Тип, тоннаж, кубатура |
Тип_владения_ТС | Реквизит владения ТС (Т2) | Собственность / Аренда / Лизинг |
Прицеп / Госномер прицепа | Информация о прицепе (Т2) | |
Тип_прицепа + Грузоподъемность_Прицеп… | Характеристики прицепа | |
Водитель (ФИО) | Водитель (Т8) | Фамилия, Имя, Отчество |
Водитель ИНН | ИНН водителя (самозанятого) | Актуально, если водитель — плательщик НПД |
Водительское_уд + Дата выдачи Ву | Данные ВУ (Т8) | Серия, номер, дата выдачи |
Водитель_тел | Контактный телефон водителя | |
Факт подачи ТС / ДатВрОтмет | Дата и время подачи ТС под погрузку (Т2) | Ключевое поле для Т2 |
Дата выгрузки (ожидаемая) | Срок доставки груза (Т2) | Может быть взят из заявки |
3. Титул Т3 (Грузополучатель)
Данные, которые появятся после факта выгрузки.
| Ваше поле в БД | Куда мапится в Т3 | Комментарий |
|---|---|---|
Дата выгрузки (факт) | Дата и время прибытия/выгрузки | Самое важное поле в Т3 |
Факт убытия | Дата и время убытия ТС | |
Пломба | Сведения о пломбах | Статус пломбы (цела/сорвана/повреждена) |
Особые отметки | Оговорки и замечания при приемке | Бой, недостача и т.д. |
Комментарий Грузополучателя | Примечания / Особые отметки | |
Брутто (факт при приемке) | Фактическая масса | Если взвешивали при приемке |
4. Титулы Т4–Т7 (Изменения и согласования)
Ваши служебные поля и триггеры.
| Ваше поле в БД | Логика маппинга |
|---|---|
Кто создал / Когда создал | Если Отгрузка без документов = 1, а потом кто-то вносит правки → это основание для создания Т4 (изменение отправителя). |
Кто изменил / Когда изменил | Если запись меняется после приемки груза (Driver App), это может быть началом Т5 (изменение перевозчика). |
ЕТрН (флаг) | Если ЕТрН = 1, значит, документ уже в цифре. Дальнейшие ручные правки в БД должны быть заблокированы до получения Т7 (согласования). |
Схема базы данных для генерации всех титулов ЭТрН (Т1–Т8)
1. organizations (Организации-участники)
| Поле | Тип | Назначение | Связь с титулами | Варианты значений / Формат |
|---|---|---|---|---|
id | UUID / bigint | Первичный ключ | Автогенерация или GUID | |
full_name | varchar(500) | Полное наименование | Т1–Т7 | «Общество с ограниченной ответственностью «Ромашка»» |
short_name | varchar(200) | Краткое наименование | «ООО «Ромашка»» | |
org_type | enum | Организационно-правовая форма | Т1–Т7 | legal_entity — Юридическое лицо (ООО, АО, ПАО и т.д.); individual — Индивидуальный предприниматель (ИП); self_employed — Самозанятый (плательщик НПД); foreign_company — Иностранная компания |
inn | varchar(12) | ИНН | Т1–Т7 (обязательно) | 10 цифр для ЮЛ, 12 цифр для ИП/ФЛ |
kpp | varchar(9) | КПП (если юрлицо) | Т1–Т7 | 9 цифр, для ИП — NULL |
legal_address | text | Юридический адрес | «г. Москва, ул. Тверская, д. 1, оф. 101» | |
actual_address | text | Фактический адрес (склад) | Т1 (адрес погрузки/разгрузки) | «Московская обл., г. Химки, Вашутинское ш., вл. 15, склад №3» |
edo_id | varchar(50) | Идентификатор в операторе ЭДО | Критично для API | UUID контрагента в Контур.Диадоке или «2BM-…» для ГИС ЭПД |
role | enum | Роль в перевозке (типовая) | Определяет доступные действия | shipper — Грузоотправитель; consignee — Грузополучатель; carrier — Перевозчик; freight_forwarder — Экспедитор; payer — Плательщик; customer — Заказчик перевозки |
2. drivers (Водители)
| Поле | Тип | Назначение | Связь с титулами | Варианты значений / Формат |
|---|---|---|---|---|
id | UUID / bigint | Первичный ключ | Автогенерация или GUID | |
last_name | varchar(100) | Фамилия | Т8 | «Иванов» |
first_name | varchar(100) | Имя | Т8 | «Иван» |
middle_name | varchar(100) | Отчество (при наличии) | Т8 | «Иванович» (может быть NULL для иностранцев) |
inn | varchar(12) | ИНН (если самозанятый/ИП) | Т8 | «123456789012» или NULL |
phone | varchar(20) | Телефон | Т8 | «+7 (999) 123-45-67» |
driver_license | varchar(50) | Серия и номер ВУ | Т8 | «99 01 123456» (российский формат) |
license_issue_date | date | Дата выдачи ВУ | Т8 | «2020-03-15» |
license_expiry_date | date | Срок действия ВУ | Т8 | «2030-03-15» |
organization_id | FK → organizations | Связь с перевозчиком | Т2 | ID организации с role = carrier |
3. vehicles (Транспортные средства — единая таблица)
| Поле | Тип | Назначение | Связь с титулами | Варианты значений / Формат |
|---|---|---|---|---|
id | UUID / bigint | Первичный ключ | Автогенерация или GUID | |
parent_id | FK → vehicles (nullable) | Ссылка на тягач, если это прицеп | Сборка автопоезда | ID тягача или NULL (если сам тягач) |
unit_type | enum | Тип транспортной единицы | Т2 | tractor — Седельный тягач; truck — Грузовой автомобиль (бортовой, фургон без прицепа); trailer — Прицеп; semi_trailer — Полуприцеп; van — Фургон (изотермический, промтоварный); refrigerator — Рефрижератор (автономный); tank — Цистерна; open_platform — Открытая платформа / бортовой; car_transporter — Автовоз; timber_truck — Лесовоз / сортиментовоз; dump_truck — Самосвал; other — Прочее |
brand_model | varchar(200) | Марка, модель | Т2, Т8 | «Volvo FH 500», «Schmitz SKO 24», «ГАЗон NEXT» |
plate_number | varchar(20) | Государственный номер | Т2, Т8 | «А123ВС 197» (тягач), «ЕК 4567 77» (прицеп) |
ownership_type | enum | Тип владения | Т2 | property — Собственность; lease — Договор лизинга; rent — Договор аренды; free_use — Безвозмездное пользование; leasing — Финансовая аренда (если учет требует отдельного кода) |
owner_id | FK → organizations (nullable) | Собственник | Т2 | ID организации-собственника (если отличается от перевозчика) |
capacity_ton | decimal(10,3) | Грузоподъемность, тонн | Т2 | «20.000», «3.500» |
capacity_m3 | decimal(10,3) | Вместимость, м³ | Т2 | «86.000», «33.000» (объем кузова/фургона) |
has_refrigerator | boolean | Холодильная установка | Т2 | true / false |
pallet_capacity | int | Вместимость в паллетах | Т2 | 33 (европаллеты) |
notes | text | Примечания | «Борт 2.8 м, без тента», «Гидроборт», «ADR допуск» |
4. transport_orders (Рейсы / Заявки на перевозку)
Центральная таблица. Один рейс = одна ЭТрН.
| Поле | Тип | Назначение | Связь с титулами | Варианты значений / Формат |
|---|---|---|---|---|
id | UUID / bigint | Первичный ключ (ID ТрН) | Автогенерация или GUID | |
number | varchar(50) | Номер транспортной накладной | Т1 | «ТН-20260529-001» или «ЭТрН-12345» |
date | date | Дата составления ТН | Т1 | «2026-05-29» |
shipper_id | FK → organizations | Грузоотправитель | Т1 | ID организации с role = shipper |
consignee_id | FK → organizations | Грузополучатель | Т1, Т3 | ID организации с role = consignee |
carrier_id | FK → organizations | Перевозчик | Т1, Т2 | ID организации с role = carrier |
payer_id | FK → organizations (nullable) | Плательщик | Т1 | ID организации с role = payer (может совпадать с отправителем или заказчиком) |
customer_id | FK → organizations (nullable) | Заказчик (если не отправитель) | Т1 | ID организации с role = customer |
contract_number | varchar(100) | Договор/Заявка | Т1 | «ДП-2026/05-157 от 01.05.2026» |
loading_point | text | Адрес погрузки | Т1 | «МО, г. Химки, Вашутинское ш., вл.15» |
unloading_point | text | Адрес разгрузки | Т1, Т3 | «г. Санкт-Петербург, Пулковское ш., д.30, корп.2» |
transport_cost | decimal(15,2) | Провозная плата | Т1 | 45000.00 |
cost_nds | enum | Ставка НДС провозной платы | Т1 | without_nds — Без НДС; nds_0 — 0%; nds_10 — 10%; nds_20 — 20%; nds_5 — 5% (УСН); nds_7 — 7% (УСН) |
mass_method | enum | Способ определения массы | Т1 | direct_weight — Прямое взвешивание на весах; calculated_weight — Расчетный (по трафарету, стандартной массе, объему); document_weight — По документам (указана грузоотправителем) |
seals | text | Сведения о пломбах | Т1, Т3 | «Пломба № РЖД 123456, Пломба № 789012» |
loading_instructions | text | Особые указания по погрузке | Т1 | «Температурный режим +2…+4°C», «ADR класс 3» |
tractor_id | FK → vehicles | Тягач | Т2, Т8 | ID ТС с unit_type = tractor |
trailer_id | FK → vehicles (nullable) | Прицеп/полуприцеп | Т2 | ID ТС с unit_type IN (trailer, semi_trailer) |
driver_id | FK → drivers | Водитель | Т8 | ID водителя |
edo_document_id | varchar(50) | UUID документа в ГИС ЭПД | Связка с API | «2BM-XXXX-XXXX-XXXX» |
edo_status | enum | Текущий статус документооборота | Автоматическое отслеживание | draft — Черновик (Т1 еще не подписан); t1_signed — Т1 подписан грузоотправителем; t2_t8_signed — Т2 и Т8 подписаны перевозчиком/водителем; t3_signed — Т3 подписан получателем; completed — Документооборот закрыт без расхождений; mchd_in_progress — Инициирована процедура изменений (Т4/Т5/Т6); mchd_completed — Изменения согласованы (Т7 подписан всеми); terminated — Документооборот аннулирован |
5. order_items (Товарная часть — Строки ТН)
| Поле | Тип | Назначение | Связь с титулами | Варианты значений / Формат |
|---|---|---|---|---|
id | UUID / bigint | Первичный ключ | Автогенерация или GUID | |
order_id | FK → transport_orders | Привязка к рейсу | ID рейса | |
line_number | int | Номер по порядку | Т1 | 1, 2, 3… |
product_name | varchar(500) | Наименование груза | Т1 | «Обои виниловые арт. 45621», «Доска обрезная 40х150х6000» |
danger_class | enum (nullable) | Класс опасности (ADR) | Т1 | class_1 — Взрывчатые вещества; class_2 — Газы; class_3 — ЛВЖ; class_4 — Легковоспламеняющиеся; class_5 — Окисляющие; class_6 — Токсичные; class_7 — Радиоактивные; class_8 — Едкие; class_9 — Прочие опасные; NULL — Неопасный груз |
okei_code | varchar(10) | Код единицы измерения по ОКЕИ | Т1 | «166» (кг), «168» (т), «796» (шт), «112» (л), «113» (м³) |
package_type | varchar(100) | Вид упаковки | Т1 | «Паллета», «Ящик деревянный», «Бочка», «Еврокуб», «Навалом», «Без упаковки» |
places | int | Количество мест | Т1 | 33, 1, 12 |
weight_brutto | decimal(10,3) | Масса брутто | Т1 | 20.500 (в тоннах или кг — зависит от okei_code) |
weight_netto | decimal(10,3) | Масса нетто (опционально) | Т1 | 19.800 |
volume | decimal(10,3) | Объем | Т1 | 82.000 (в м³) |
price_per_unit | decimal(15,2) | Цена за единицу | Т1 | 1500.00 |
total_price | decimal(15,2) | Стоимость позиции | Т1 | 49500.00 |
cargo_nds | enum | Ставка НДС товара | Т1 | without_nds, nds_0, nds_10, nds_20, nds_5, nds_7 |
6. shipment_events (События рейса для Т2 и Т3)
| Поле | Тип | Назначение | Связь с титулами | Варианты значений / Формат |
|---|---|---|---|---|
id | UUID / bigint | Первичный ключ | Автогенерация или GUID | |
order_id | FK → transport_orders | Привязка к рейсу | ID рейса | |
event_type | enum | Тип события | Т2, Т3 | vehicle_submitted — Подача ТС под погрузку; loading_start — Начало погрузки; loading_end — Окончание погрузки; cargo_accepted — Груз принят перевозчиком (подписание Т2); departed — ТС убыло с точки погрузки; arrived — ТС прибыло на точку выгрузки; unloading_start — Начало выгрузки; unloading_end — Окончание выгрузки; cargo_delivered — Груз сдан получателю (подписание Т3); refused — Получатель отказался от приемки |
event_date | datetime | Фактическая дата и время | Т2, Т3 | «2026-05-30 08:30:00» |
address | text | Где произошло событие | «Склад №5, г. Химки» | |
responsible_person | varchar(200) | Ответственное лицо | «Кладовщик Петров А.С.» | |
notes | text | Оговорки и замечания | Т2, Т3 | «Повреждена упаковка паллеты №3», «Недостача 3 мест», «Пломба цела» |
photo_url | varchar(500) | Ссылка на фотофиксацию | «https://cdn.example.com/photos/acc123.jpg« | |
created_by | varchar(100) | Кто внес запись | «Водитель (моб. приложение)» / «Логист Иванов» |
7. revision_requests (Титулы изменений Т4–Т7)
| Поле | Тип | Назначение | Связь с титулами | Варианты значений / Формат |
|---|---|---|---|---|
id | UUID / bigint | Первичный ключ | Автогенерация или GUID | |
order_id | FK → transport_orders | Привязка к рейсу | ID рейса | |
initiator_role | enum | Инициатор изменения | Определяет Т4/Т5/Т6 | shipper — Грузоотправитель (→ Т4); carrier — Перевозчик (→ Т5); consignee — Грузополучатель (→ Т6) |
title_type | enum | Тип титула изменения | T4 — Титул изменения грузоотправителя; T5 — Титул изменения перевозчика; T6 — Титул изменения грузополучателя | |
reason_code | varchar(20) | Код причины расхождения | Т4/Т5/Т6 | shortage — Недостача; surplus — Излишки; damage — Повреждение/бой; re_sorting — Пересорт; weight_deviation — Расхождение по весу; doc_error — Техническая ошибка в документе; seal_broken — Пломба нарушена; delivery_refused — Отказ от приема груза; other — Иное |
description | text | Описание расхождения | Т4/Т5/Т6 | «При приемке обнаружен бой: 15 шт. плитки из 300» |
field_name | varchar(100) | Какое поле меняется | «places», «weight_brutto», «product_name» | |
old_value | text | Старое значение | «300» | |
new_value | text | Новое значение | «285» | |
edo_event_id | varchar(50) | UUID события MCHD в ГИС ЭПД | Связка с API | «2BM-EVT-XXXX» |
status | enum | Статус согласования | Т7 | pending — Ожидает рассмотрения; agreed_by_shipper — Согласован отправителем; agreed_by_carrier — Согласован перевозчиком; agreed_by_consignee — Согласован получателем; fully_agreed — Согласован всеми (Т7 подписан); rejected — Отклонен (с комментарием) |
rejection_reason | text (nullable) | Причина отклонения | Т7 | «Недостача не подтверждена данными весового контроля» |
created_at | datetime | Дата и время запроса | «2026-05-31 12:15:00» | |
resolved_at | datetime | Дата согласования/отклонения | «2026-05-31 15:45:00» |
