С чего начать работу с авианакладной

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

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

  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.

    Примечание

    При обновлении токена доступа с помощью 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. Для группировки титулов, событий и статусов одной авианакладной используйте идентификатор УИД_АвиаГН.