Перейти к основному содержимому

С чего начать

Эта страница описывает работу с электронной авианакладной.

Порядок первых шагов

  1. Ознакомьтесь со статьями про авторизацию, порядок документооборота и устройство документооборота авианакладной.
  2. Определите роли, в которых выступает ваша организация (подробнее — Роли организации).
  3. Подготовьте интеграционное решение и соберите справочник ящиков с API-ключами и доступами пользователей (подробнее — Подготовка интеграционного решения).
  4. Научитесь создавать документы (подробнее — Создание документов).
  5. Реализуйте чтение ленты событий по каждому ящику с фильтром typeNamedId = LogisticsAirWaybill.
  6. В событиях определяйте титулы и связывайте их с подписями по идентификатору ParentEntityId (подробнее — Обработка идентификаторов).
  7. После регистрации титула Т1 сохраните УИД из тега mt-id и используйте его для объединения титулов одной перевозки (подробнее — kl-id и mt-id).
  8. Реализуйте обработку обязательных титулов Т1—Т4 (подробнее — Обработка потоков документов).
  9. Реализуйте обработку статусов регистрации титулов в ГИС ЭПД и событий об ошибках.

Как устроен документооборот авианакладной

Электронная авианакладная состоит из четырех обязательных титулов, которые участники перевозки формируют, подписывают и отправляют последовательно. Диадок передает титулы в ГИС ЭПД, возвращает статусы их обработки и доставляет документы участникам.

  • титул Т1 — информация перевозчика,
  • титул Т2 — информация грузоотправителя,
  • титул Т3 — прием груза грузополучателем,
  • титул Т4 — выдача груза перевозчиком.
к сведению

В Диадоке реализована работа только с обязательными титулами Т1—Т4. Необязательные титулы Т5—Т8 — изменение финансового состояния и изменение сведений о грузополучателе — пока не поддерживаются.

Роли организации

Каждая организация-участник документооборота авианакладной играет свою роль в этом документообороте. От роли зависит, какие титулы организация подписывает и какой поток документов у нее появится.

Роли организации в авианакладной

РольУчастие в документооборотеЧто подписывает
ПеревозчикУчаствует. Перевозит груз и выдает его грузополучателютитулы Т1 и Т4; титулы Т5 и Т8*
Уполномоченный агент перевозчикаУчаствует. Может действовать от имени перевозчика при оформлении титула Т1любой титул, если у агента есть
соответствующие полномочия
ГрузоотправительУчаствует. Передает груз перевозчику и указывает сведения о немтитул Т2; титулы Т6 и Т7*
ГрузополучательУчаствует. Принимает груз от перевозчикатитул Т3

* Титулы Т5—Т8 организация подписывает при необходимости. В Диадоке эти титулы пока не поддерживаются.

Стадии

Участники документооборота оформляют авианакладную так:

  • титул Т1 — перевозчик направил информацию о перевозке,
  • титул Т2 — грузоотправитель подтвердил сведения о грузе,
  • титул Т3 — грузополучатель принял груз,
  • титул Т4 — перевозчик зафиксировал выдачу груза.

Прием груза

Перевозчик подписывает титул Т1 и отправляет его грузоотправителю. Полномочия на оформление титула Т1 может иметь уполномоченный агент перевозчика. Данные титула Т1 направляются в ГИС ЭПД. Грузоотправитель получает входящий титул Т1 и формирует в ответ титул Т2. Данные титула Т2 направляются в ГИС ЭПД. После отправки титула Т2 грузополучатель получает комплект титулов Т1 и Т2. Получение только титула Т1 до оформления титула Т2 не предусмотрено.

В результате участники документооборота получают титулы:

  • грузоотправитель получает титул Т1 с подписью перевозчика;
  • перевозчик получает титул Т2 с подписью грузоотправителя;
  • грузополучатель получает комплект титулов Т1 и Т2.

Выдача груза

После приема груза грузополучатель подписывает титул Т3 и отправляет его перевозчику. Данные титула Т3 направляются в ГИС ЭПД. Перевозчик получает входящий титул Т3 и формирует в ответ титул Т4 — выдачу груза. Данные титула Т4 направляются в ГИС ЭПД. После выдачи груза грузоотправитель получает титулы Т3 и Т4.

В результате участники документооборота получают титулы:

  • перевозчик и грузоотправитель получают титул Т3 с подписью грузополучателя;
  • грузополучатель и грузоотправитель получают титул Т4 с подписью перевозчика.

Подготовка интеграционного решения

Чтобы настроить интеграцию для обмена авианакладными, нужно для каждой организации-участника документооборота получить следующие данные:

  • Идентификатор ящика BoxId: его можно получить методом GetMyOrganizations. Этот идентификатор постоянный для каждого ящика и не изменяется.
  • API-ключ.
  • Лицензия, купленная для этого ящика.
  • Учетная запись пользователя с доступом в ящик и возможностью авторизации по OIDC. Назначьте пользователю доступ к отдельным наборам ящиков организаций, а не ко всем ящикам сразу, или заведите техническую учетную запись.

Спроектируйте интеграционное решение следующим образом:

  1. Заведите справочник организаций и их API-ключей.

  2. Создайте единственную техническую учетную запись пользователя с доступом ко всем ящикам или реализуйте добавление и удаление пользователей, например, на случай найма/увольнения сотрудника. Подробнее — на странице Работа с сотрудниками.

  3. Реализуйте обновление токена доступа с помощью Обновление токена.

    к сведению

    При обновлении токена доступа с помощью refresh_token вы получите новую пару токенов, и повторное подтверждение авторизации со стороны пользователя не потребуется. Подтверждение авторизации запрашивается только один раз — при первом выпуске токена. Подробнее — на странице Авторизация.

Создание документов

Чтобы создать авианакладную:

  1. Изучите формат электронной грузовой накладной, утвержденный приказом ФНС России от 27.04.2026 № ЕД-1-26/276@, и требования к XML-файлам.
  2. Сформируйте XML-файл титула в вашей учетной системе; подробнее — на странице Работа с авианакладной.

При создании учитывайте тип, версию и функцию каждого титула. Каждый титул отправляют отдельным сообщением методом PostMessage (V3).

Тип, версия и функция

Каждый титул авианакладной в Диадоке имеет свой набор параметров, определяющих его поведение, — тип документа, версию и функцию. Отправитель документа задает их при создании документа в структуре DocumentAttachment. Получить эти значения для существующего документа можно из структуры Document.

Параметры титула авианакладной

ПараметрОписаниеДоступные значения
TypeNamedIdТип документаLogisticsAirWaybill
FunctionФункция титула в документооборотеreception_carrier — информация перевозчика (титул Т1);
reception_consignor — информация грузоотправителя (титул Т2);
delivery_consignee — прием груза грузополучателем (титул Т3);
delivery_carrier — выдача груза перевозчиком (титул Т4);
cost_carrier — изменение финансового состояния (титул Т5);
cost_consignor — подтверждение изменения финансового состояния
(титул Т6);
readdress_consignor — изменение сведений о грузополучателе
(титул Т7);
readdress_carrier — подтверждение изменения грузополучателя
(титул Т8).
VersionВерсия документаkl_awb_05_02_01

Титулы Т5—Т8 в Диадоке пока не поддерживаются.

Обработка идентификаторов

MessageId и EntityId

Для работы с авианакладной в ящике организации нужны два идентификатора — MessageId и EntityId. Это идентификаторы документа в Диадоке. С помощью этих идентификаторов можно найти документ в ящике, сформировать следующий титул или выполнить другие действия с документом.

Каждое сообщение Message — отдельный пакет с набором сущностей Entity. Сущностью может быть документ, подпись, машиночитаемая доверенность (МЧД) и другие объекты.

Идентификатор сообщения MessageId идентифицирует сообщение, а не отдельный документ. После отправки сообщения сохраните его: по нему можно получить все данные сообщения методом GetMessage (V6).

Идентификаторы сущности EntityId уникальны в каждом ящике. У каждого получателя при появлении новой сущности возникают собственные события. События из ящика отправителя в ящик получателя не передаются.

Каждый титул авианакладной создается как новое сообщение со своей функцией документооборота. Сущности подписи и статусов ссылаются на титул через идентификатор ParentEntityId.

к сведению

Не используйте идентификатор сообщения MessageId для группировки титулов одной авианакладной. Все титулы находятся в разных сообщениях.

kl-id и mt-id

Для работы с авианакладной в учетных системах отслеживайте идентификаторы kl-id, mt-id и УИД_АвиаГН:

  • kl-id — внутренний идентификатор перевозки в Логистике; его можно использовать для поиска документов в конкретном ящике;
  • mt-id — уникальный идентификатор авианакладной. ГИС ЭПД присваивает его после регистрации титула Т1;
  • УИД_АвиаГН — тот же уникальный идентификатор в XML-файле титула по формату ФНС.

Они хранятся в Диадоке как пользовательские данные документа — в поле DocumentInfo.CustomData сущности документа, которая в свою очередь входит в состав сообщения Message. Поле CustomData содержит список тегов CustomDataItem с полями Key и Value.

После регистрации титула Т1 в ГИС ЭПД в ленте появится событие с обновленным состоянием документа. УИД_АвиаГН будет записан в DocumentInfo.CustomData в теге с Key = "mt-id". Это значение указывают в элементе УИД_АвиаГН всех следующих титулов авианакладной. Каждый титул авианакладной передается отдельным сообщением: для связи документов одной перевозки используйте mt-id и kl-id. Подробнее о статусах ГИС ЭПД — в разделе Информация о статусе обработки.

Подробнее про возможные теги авианакладной — в разделе Пользовательские данные (теги).

Хранение идентификаторов

Для обработки авианакладной сохраните в учетной системе идентификаторы:

Идентификаторы авианакладной

Что хранитьДля чего
BoxIdЧитать нужную ленту событий и получать документы
MessageIdПолучать информацию по каждому сообщению и статусы титула
EntityId титулаСкачать XML и связать подпись или статус с титулом
mt-idСвязать статусы ГИС ЭПД с авианакладной в учетной системе
УИД_АвиаГНУказывать в последующих титулах авианакладной. Значение должно совпадать во всех титулах
одной авианакладной
IndexKey последнего событияПродолжить чтение ленты без пропусков

Сохраните идентификатор mt-id и используйте его для группировки титулов, событий и статусов ГИС ЭПД, даже если титулы находятся в разных сообщениях.

Статусы обработки в ГИС ЭПД

Статус обработки титула во внешнем документообороте хранится в сущности Entity с полями:

  • EntityType = Attachment,
  • AttachmentType = OuterDocflow.

Поле Entity.OuterDocflow содержит структуру OuterDocflowInfo. В ней хранятся:

  • DocflowNamedId — идентификатор внешнего документооборота; статусы ГИС ЭПД можно определить по значению DocflowNamedId = KlMt;
  • Status — статус обработки титула;
  • дополнительные данные в Status.Details, в том числе mt-id, mt-rid и kl-id.

Если обработка завершилась с ошибкой, Entity.OuterDocflow.Status.Type будет иметь значение Error. Код и текст ошибки можно найти в элементах Entity.OuterDocflow.Status.Details.

Чтобы определить титул, к которому относится статус:

  1. Получите ParentEntityId сущности Entity с типом OuterDocflow — это идентификатор родительской сущности в том же сообщении.
  2. Найдите по идентификатору ParentEntityId родительскую сущность; обратите внимание, что она могла появиться в сообщении раньше, чем событие со статусом.
  3. Используйте идентификатор сообщения MessageId события, чтобы получить сообщение методом GetMessage (V6).

Идентификатор MessageId идентифицирует все сообщение, а не отдельный документ. Конкретный титул нужно определить по родительской сущности ParentEntityId.

Событие со статусом может появиться позже самого титула. Поэтому при обработке ленты сохраняйте такие события и запрашивайте сообщение повторно, если родительская сущность еще не поступила.

Обработка потоков документов

В авианакладной титулы распределяются по подписантам. Все титулы одной авианакладной связывает идентификатор УИД_АвиаГН.

Исходящий поток: перевозчик

Перевозчик формирует, подписывает и отправляет грузоотправителю титул Т1. Полномочия на оформление титула Т1 может иметь уполномоченный агент перевозчика.

После отправки титула Т1 сохраните идентификатор сообщения MessageId и идентификатор сущности EntityId. По идентификатору сообщения MessageId метод GetMessage (V6) возвращает сообщение и статусы обработки титула в поле Entity.OuterDocflow. Чтобы обновить статусы вручную, вызовите этот метод для каждого сохраненного идентификатора MessageId.

Дождитесь события, в котором ГИС ЭПД присвоит УИД. Прочитайте mt-id, как описано в разделе kl-id и mt-id, и сохраните его вместе с идентификаторами отправленного титула.

Перевозчик получает от грузоотправителя титул Т2 и от грузополучателя титул Т3. После приема груза перевозчик формирует, подписывает и отправляет титул Т4.

Обрабатывайте события о появлении титула, подписи и статуса ГИС ЭПД. Необязательно отслеживать все сущности: определите события, которые важны для вашей организации.

Входящий и исходящий поток: грузоотправитель

Грузоотправитель получает от перевозчика титул Т1 и сохраняет сообщение с титулом и связанную подпись.

FromBoxId — это ящик контрагента. Получить его можно как из ленты событий, так и из титула Т1: для этого нужно распарсить титул, получить из него значение ИдФайл и получить из этого значения первый идентификатор в формате GUID. Это значение нужно передать в метод GetOrganization, чтобы получить идентификатор ящика boxId.

Чтобы сформировать титул Т2, используйте элемент УИД_АвиаГН, атрибут ИдФайл и подпись титула Т1. Грузоотправитель формирует, подписывает и отправляет перевозчику титул Т2. Сохраните mt-id зарегистрированной авианакладной.

После выдачи груза грузоотправитель получает титулы Т3 и Т4.

Сохраняйте идентификатор сообщения MessageId, идентификатор сущности EntityId, атрибут ИдФайл и подпись каждого титула. Используйте эти данные для обработки статусов и формирования следующего титула. Каждый титул обрабатывайте отдельно: не рассчитывайте, что несколько титулов находятся в одном сообщении.

Входящий поток: грузополучатель

Грузополучатель после отправки грузоотправителем титула Т2 получает комплект титулов Т1 и Т2. Найдите авианакладную по mt-id и при необходимости получите содержимое титулов Т1 и Т2.

При обработке события:

  1. Получите идентификатор сообщения MessageId и идентификатор сущности EntityId титула.
  2. Вызовите метод GetEntityContent (V4) и загрузите XML-файл титула (необязательно).
  3. Сохраните элемент УИД_АвиаГН, атрибут ИдФайл и подпись титула.
  4. Получите и сохраните статус ГИС ЭПД из поля Entity.OuterDocflow.

После приема груза грузополучатель формирует, подписывает и отправляет перевозчику титул Т3. Затем получает от перевозчика титул Т4 и сохраняет его вместе с остальными титулами авианакладной.

Каждый титул авианакладной обрабатывайте отдельно. Не рассчитывайте, что несколько титулов находятся в одном сообщении или имеют общий идентификатор MessageId. Для группировки титулов, событий и статусов одной авианакладной используйте идентификатор УИД_АвиаГН.

Оцените материал страницы

Нашли ошибку или столкнулись с проблемой?

СКБ Контурс 1988 года