Обмен формализованными транспортными накладными - Synerdocs/synerdocs-sdk GitHub Wiki

В Synerdocs реализован обмен формализованными транспортными накладными (далее ТрН), которые позволяют перевести документальное сопровождение перевозок в электронный вид тем самым сократить затраты и ускорить бизнес-процесс. ТрН, по аналогии с другими формализованными документами, состоит из пяти основных титулов:

• Грузоотправителя;
• Водителя при приеме груза для доставки;
• Водителя при сдаче груза;
• Грузополучателя;
• Перевозчика (Транспортной компании).

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

Кроме приведенных выше титулов, в рамках обмена документооборота ТрН может быть отправлен титул Изменения места доставки. Данный титул может быть отправлен один или несколько раз. Наличие или отсутствие данного титула не влияет на статус завершенности документооборота. Титул изменения места доставки не может быть отправлен после завершения документооборота.

Титулы представляют собой электронные документы в формате XML, структура и правила заполнения которых были разработаны специалистами Synerdocs. XSD-схемы для формирования и проверки титулов предоставляются по запросу в техническую поддержку сервиса.

Отправка титулов ТрН осуществляется с помощью метода SendMessage. При отправке необходимо указывать корректные типы для титулов, которые приведены в перечислении DocumentType.

В качестве получателей титула Грузоотправителя должны быть указаны организации-абоненты сервиса, которые играют роль Грузополучателя, Перевозчика (ТЛК) и Водителя. Участники обмена указываются с помощью заполнения массива получателей документа при отправке, а их роли с помощью заполнения массива Document.DocumentFlowParticipants[].

Для остальных титулов в качестве получателя указывается только организация, которая инициировала обмен ТрН, т.е. отправитель титула Грузоотправителя; сервис автоматически генерирует сообщения с отправленным титулом для всех остальных участников обмена. Титул Грузоотправителя является родительским документом, к которому отправляются все остальные, т.е. при отправке титула отличного от титула Грузоотправителя должно быть заполнено свойство Document.parentDocumentId.

Каждый из титулов должен быть подписан. Для подписания может быть использована квалифицированная или простая ЭП.

При отправке титула Водителя при приеме груза, титула Грузополучателя и титула Водителя при сдаче груза сервис автоматически добавляет к титулу Грузоотправителя тэги "CargoReceived", "SignedByConsignee" и "CargoDelivered" соответственно. Эти тэга могут быть использованы для отражения актуальной информации по документообороту ТрН.

Для работы с ТрН через API реализовали методы:

• по генерации титулов из модели:
  • GenerateTransportWaybillConsignorTitle
  • GenerateTransportWaybillCargoReceivedTitle
  • GenerateTransportWaybillCargoDeliveredTitle
  • GenerateTransportWaybillConsigneeTitle
  • GenerateTransportWaybillCarrierTitle
  • GenerateTransportWaybillExpeditorTitle
  • GenerateTransportWaybillDeliveryPlaceChangeTitle
• парсингу в модель этих титулов.
  • ParseTransportWaybillConsignorTitle
  • ParseTransportWaybillCargoReceivedTitle
  • ParseTransportWaybillCargoDeliveredTitle
  • ParseTransportWaybillConsigneeTitle
  • ParseTransportWaybillCarrierTitle
  • ParseTransportWaybillDeliveryPlaceChangeTitle
• для генерации печатной формы ТрН может быть использован DownloadPdfDocument. Стоит отметить, что генерируемая сервисом печатная форма, по умолчанию используется только для просмотра документов, т.е. является одним из вариантов его представления. Для того чтобы такое представление ТрН имело юридическую силу, необходимо заверить его как копию в соответствующем порядке.

Для получения полной информации по ТрН рекомендуется использовать метод GetFlowDocumentInfo или GetFullDocumentInfo. По умолчанию сервис хранит все документы и ЭП к ним, однако для обеспечения долговременного хранения рекомендуется хранить все артефакты документооборота на стороне пользователя.

Общий сценарий интеграции:

1. Если абонент, который будет являться отправителем или получателем ТрН, не зарегистрирован в сервисе, то его регистрация может быть реализована за счет метода RegisterSubscriber, например RegisterSubscriber_LegalEntityAndUserWithPromoCodeAndWithoutEmailNotification.

2. Вызов методов сервиса требует прохождения аутентификации, которая может быть пройдена с помощью метода Authenticate, например Authenticate_WithApplicationId.

3. Список доступных пользователю ящиков для отправки и получения документов может быть получен с помощью метода GetBoxes. Этот метод полезен в случае, если на стороне вашего решения не хранятся данные по ящикам пользователя.

4. Если при регистрации для организации была подключена опция использования простой ЭП, то необходимо принять регламент ее использования в сервисе. Это может быть реализована за счет вызова метода AcceptSimpleSignatureRegulation

5. В случае обмена ТрН важным аспектом является корректное указание подразделений организации, которые будут являться участниками обмена. Для получения списка подразделений организаций (оргструктуры) предназначен метод GetOrganizationStructure

   5.1. Для добавление новых подразделений может быть использован метод AddOrganizationStructureElement. Использование этого метода особенно актуально для транспортных компаний, у которых в штате состоят водители, так как при работе с ними рекомендуется для каждого такого сотрудника заводить отдельное подразделение, которое будет указано при отправке ТрН.

6. Добавление новых сотрудников организации осуществляется с помощью метода CreateUserAndEmployee, например для добавления пользователя, которому будет доступна возможность использования простой ЭП запрос и ответ будут выглядеть следующим образом CreateUserAndEmployee_WithSimpleSignature.

7. Как было описано выше, каждый из титулов ТрН может быть сгенерирован из объектной модели с помощью метод сервиса. Титул Го ТрН может быть создан с помощью метода GenerateTransportWaybillConsignorTitle, например, GenerateTransportWaybillConsignorTitle_WithoutAutoFillv2.

8. Для того чтобы стартовать документооборот ТрН, необходимо отправить титул ГО и ЭП к нему с помощью метода SendMessage. Пример отправки титула ГО см. SendMessage_ConsignorTitleWithSignatureV2

9. Отслеживание текущего состояния документа может быть реализовано с помощью метода GetFlowDocumentInfo, например, GetFlowDocumentInfo_MinimalForTransportWaybill.

10. Для формирования списков документов, в том числе проверки факта наличия новых документов, может быть использован метод GetDocumentEntries. Запрос на получение документов, по которым ожидается подтверждение приемки или сдачи груза водителем будет выглядеть как GetDocumentEntries_WaitingForCargoReceptionAndWaitingForCargoDelivery.

11. После отправки титула ГО ТрН в общем случае, под документом должен расписаться водитель с целью документирования факта получения груза для доставки. Генерация титула водителя может быть реализована с помощью метода GenerateTransportWaybillCargoReceivedTitle.

12. Если для организации подключена соответствующая опция и пользователю доступно подписание с использованием простой ЭП, то для подписания титула водителя и других титулов ТрН может быть использована простая ЭП. Для формирования простой подписи под документом необходимо использовать метод CreateSimpleSignature. Пример запроса и ответа для формирования простой ЭП для титула водителя при приеме груза CreateSimpleSignature_ForTransportWaybillCargoReceivedTitle.

13. Отправка титула водителя при приеме груза также осуществляется с помощью метода SendMessage, пример отправки см. SendMessage_CargoReceivedTitle.

14. После подписания документа водителем при приеме груза, в общем случае, должен проставить свою подпись грузополучатель, документируя факт приема груза. Сгенерировать титул грузополучателя можно с помощью метода GenerateTransportWaybillConsigneeTitle.

15. Отправка титула грузополучателя также осуществляется с помощью метода SendMessage, пример, см. SendMessage_ConsigneeTitle.

16. Если в документообороте был указан водитель, то после подтверждения приема груза грузополучателем, необходимо отправить титула водителя при сдаче груза, который может быть сгенерирован с помощью метода GenerateTransportWaybillCargoDeliveredTitle

17. Отправка титула водителя при сдаче груза также осуществляется с помощью метода SendMessage, пример см. SendMessage_CargoDeliveredTitle.

18. При наличии участника с ролью перевозчик для завершения документооборота ТрН необходимо отправить соответствующий титул, который может быть сгенерирован с помощью метода GenerateTransportWaybillCarrierTitle.

19. Отправка титула перевозчика ТрН осуществляется с помощью метода SendMessage, пример см. SendMessage_CarrierTitle.