С чего начать работу с СР

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

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

  1. Ознакомьтесь со статьями про авторизацию, порядок документооборота и устройство документооборота СР.

  2. Определите роли, в которых выступает ваша организация: экспедитор формирует, подписывает и отправляет СР, заказчик получает готовый документ (подробнее — Роли организации).

  3. Подготовьте интеграционное решение и соберите справочник ящиков с API-ключами и доступами пользователей (подробнее — Подготовка интеграционного решения).

  4. Научитесь создавать титул экспедитора (подробнее — Создание документов).

  5. Реализуйте чтение ленты событий по каждому ящику методом GetNewEvents (V8) с фильтром typeNamedId = LogisticsWarehouseReceipt.

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

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

  6. В событиях определяйте титул и связывайте его с подписями по идентификатору ParentEntityId (подробнее — Обработка идентификаторов).

  7. Заведите соответствие «УИД — MessageId» и группируйте по нему сущности расписки.

  8. Реализуйте обработку титула экспедитора (подробнее — Обработка потоков документов).

  9. Реализуйте обработку статусов регистрации документа в ГИС ЭПД и событий об ошибках.

Как устроен документооборот СР

СР состоит из одного титула — титула экспедитора. Экспедитор формирует и подписывает его, когда принимает груз на складское хранение. Ответный титул от заказчика транспортно-экспедиционных услуг не требуется.

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

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

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

Роль

Участие в документообороте

Что подписывает

Экспедитор

Участвует. Принимает груз на складское хранение, формирует и отправляет складскую расписку заказчику

титул экспедитора

Заказчик транспортно-экспедиционных услуг

Участвует. Получает подписанную складскую расписку

—

Стадии

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

  • титул экспедитора — экспедитор принял груз на складское хранение и направил расписку заказчику.

Прием на хранение

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

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

  • заказчик получает титул экспедитора с подписью экспедитора.

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

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

  • Идентификатор ящика BoxId: его можно получить методом GetMyOrganizations. Этот идентификатор постоянный для каждого ящика и не изменяется.

  • API-ключ.

  • Лицензия, купленная для этого ящика.

  • Учетная запись пользователя с доступом в ящик и возможностью авторизации по OIDC. Назначьте пользователю доступ к отдельным наборам ящиков организаций, а не ко всем ящикам сразу, или заведите техническую учетную запись.

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

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

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

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

    Примечание

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

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

Чтобы создать СР:

  1. Изучите формат складской расписки, утвержденный приказом ФНС России от 28.04.2026 № ЕД-1-26/277@, и требования к XML-файлам.

  2. Сформируйте XML-файл титула в вашей учетной системе; подробнее — на странице Работа со складскими расписками.

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

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

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

Параметры титула СР

Параметр

Описание

Доступные значения

TypeNamedId

Тип документа

LogisticsWarehouseReceipt

Function

Функция титула в документообороте

default — складская расписка (титул экспедитора).

Version

Версия документа

kl_wr_05_01_01

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

MessageId и EntityId

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

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

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

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

Титул экспедитора создается как новое сообщение. Сущности подписи и статусов ссылаются на титул через идентификатор ParentEntityId.

Для входящей складской расписки заказчик получает подписанный титул и события о связанных сущностях. Для обработки документа связывайте подписи и статусы с титулом по ParentEntityId.

kl-id и mt-id

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

  • kl-id — внутренний идентификатор документа;

  • mt-id — уникальный идентификатор складской расписки. Он связывает события и документы расписки в Диадоке и ГИС ЭПД. ГИС ЭПД присваивает его после регистрации титула;

  • УИД_СкладР — тот же уникальный идентификатор в XML-файле титула по формату ФНС.

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

После регистрации титула в ГИС ЭПД в ленте появится событие с обновленным состоянием документа. УИД_СкладР будет записан в DocumentInfo.CustomData в теге с Key = "mt-id". Подробнее о статусах ГИС ЭПД — в разделе Информация о статусе обработки.

Создайте соответствие «УИД — MessageId». По УИД_СкладР можно определить, к какой записи в учетной системе относится обновление.

При замене складской расписки укажите УИД заменяемого документа в элементе УИД_ПредСкладР. Если ГИС ЭПД вернет ответ об ошибке, экспедитор формирует новую складскую расписку с исправлениями и заполняет элементы ИспрФО, ИдИсхФайл и УИД_СкладР.

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

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

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

Идентификаторы СР

Что хранить

Для чего

BoxId

Читать нужную ленту событий и получать документы

MessageId

Получать титул и его статусы

EntityId титула

Скачать XML и связать подпись или статус с титулом

mt-id

Связать статусы ГИС ЭПД с СР в учетной системе

УИД_СкладР

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

IndexKey последнего события

Продолжить чтение ленты без пропусков

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

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

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

  • EntityType = Attachment,

  • AttachmentType = OuterDocflow.

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

  • DocflowNamedId — идентификатор внешнего документооборота;

  • Status — статус обработки титула;

  • дополнительные данные в Status.Details, в том числе mt-id и kl-id.

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

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

Исходящий поток: экспедитор

Экспедитор принимает груз на складское хранение, формирует, подписывает и отправляет заказчику титул экспедитора.

Настройте обработку так:

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

  2. Читайте ленту событий. Статус регистрации складской расписки в ГИС ЭПД будет передан в сущности OuterDocflow.

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

  4. После успешной регистрации прочитайте в деталях статуса mt-id и сохраните его в учетной системе. Как прочитать mt-id, описано в разделе kl-id и mt-id.

  5. Если статус имеет тип Error, обработайте код и текст ошибки из Status.Details.

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

Входящий поток: заказчик

Заказчик получает подписанный титул экспедитора от экспедитора. Ответный титул не требуется.

Настройте обработку так:

  1. В ленте событий определяйте появление входящей складской расписки.

  2. Получите сообщение по MessageId методом GetMessage (V6), распознайте титул и связанную с ним подпись.

  3. Сохраняйте MessageId, УИД складской расписки и связь с документом в учетной системе.

  4. Вызовите метод GetEntityContent (V4) и загрузите XML-файл титула (необязательно).

  5. При необходимости отслеживайте статусы обработки документа в ГИС ЭПД. Связывайте статусы с титулом по ParentEntityId.