Лента событий для ЭТрН

Эта страница описывает, как по ленте событий узнать стадию перевозки и отличить ошибки. Работа с лентой событий для перевозочных документов описана на странице Работа с событиями.

Стадия перевозки 

Стадия перевозки фиксируется в теге kl-status. Диадок.Логистика записывает его в пользовательские данные титула в поле DocumentInfo.CustomData и обновляет при каждом изменении. Подробнее — на странице Теги и статусы ЭТрН.

Ключевые события документооборота 

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

Кроме них на любой стадии документооборота могут произойти следующие события:

Отказ — завершает документооборот по перевозке. Обработайте его, иначе перевозка останется в промежуточном статусе.
Ошибка — сущность с AttachmentType = OuterDocflow и статусом Type = Error. Код и текст ошибки находятся в Status.Details.

Любое событие хранится в структуре BoxEvent: новое сообщение — в поле Message, дополнение к уже существующему сообщению — в поле Patch.

Для работы с событиями могут потребоваться следующие поля:

MessageId — идентификатор сообщения.
EntityId — идентификатор сущности внутри сообщения. У титула это идентификатор документа.
ParentEntityId — идентификатор родительской сущности. У подписи это документ, который она подписывает. У второго титула — первый титул цепочки.
FromBoxId, ToBoxId — идентификаторы ящиков отправителя и получателя.
DocumentNumber, DocumentDate — номер и дата документа.
FileName — имя файла, ИдФайл.
TypeNamedId — тип документа. Пригодится для отбора, если фильтр не был задан в самом запросе.
ContentTypeId — версия и вид титула. По нему титулы различаются между собой.
DocumentDirection — направление документа: Inbound — входящий, Outbound — исходящий.
RecipientResponseStatus — статус ответа получателя.

Отправлен титул Т1 

Событие отправки титула приходит в поле Message со следующими признаками:

EntityType = Attachment;
AttachmentType = Title;
ContentTypeId = kl_trn_ot_t1_mt_05_01_v1.

Подпись титула — соседняя сущность Signature. Ее ParentEntityId совпадает с EntityId титула Т1.

Пример события:

{
    "Message": {
        "MessageId": "{{messageId}}",
        "FromBoxId": "{{fromBoxId}}",
        "ToBoxId": "{{toBoxId}}",
        "Entities": [
            {
                "EntityType": "Attachment",
                "EntityId": "{{entityId_t1}}",
                "AttachmentType": "Title",
                "DocumentInfo": {
                    "DocumentDirection": "Outbound",
                    "TypeNamedId": "LogisticsWaybill",
                    "Function": "reception",
                    "Version": "kl_trn_mt_05_01",
                    "RecipientResponseStatus": "WaitingForRecipientSignature"
                },
                "ContentTypeId": "kl_trn_ot_t1_mt_05_01_v1"
            },
            {
                "EntityType": "Signature",
                "ParentEntityId": "{{entityId_t1}}"
            }
        ]
    }
}

Присвоен УИД 

Ответ ГИС ЭПД приходит в поле Patch со следующими признаками:

EntityType = Attachment;
AttachmentType = OuterDocflow;
DocflowNamedId = KlMt.

Пример события:

{
    "Patch": {
        "MessageId": "{{messageId}}",
        "Entities": [
            {
                "EntityType": "Attachment",
                "ParentEntityId": "{{entityId_t1}}",
                "AttachmentType": "OuterDocflow",
                "OuterDocflow": {
                    "DocflowNamedId": "KlMt",
                    "Status": {
                        "NamedId": "4000211000",
                        "Type": "Success",
                        "Details": [
                            {
                                "Code": "mt-id",
                                "Text": "{{mtId}}"
                            }
                        ]
                    }
                }
            }
        ]
    }
}

* Статус 4000211000 в примере — принят новый документ.

Водитель подтвердил титул Т2 

Водитель подтверждает титул Т2 простой электронной подписью. Событие приходит в поле Patch со следующими признаками:

EntityType = Attachment;
AttachmentType = OuterDocflow;
DocflowNamedId = KlDriverConfirm.

ParentEntityId сущности совпадает с EntityId титула Т1.

Пример события:

{
    "Patch": {
        "MessageId": "{{messageId}}",
        "Entities": [
            {
                "EntityType": "Attachment",
                "ParentEntityId": "{{entityId_t1}}",
                "AttachmentType": "OuterDocflow",
                "OuterDocflow": {
                    "DocflowNamedId": "KlDriverConfirm",
                    "Status": {
                        "NamedId": "Confirm",
                        "Type": "Success"
                    }
                }
            }
        ]
    }
}

Грузоотправитель получил титул Т2 

Когда грузоотправитель отправляет титул Т1, сведения о титуле Т2 приходят в то же сообщение, в поле Patch со следующими признаками:

EntityType = Attachment;
AttachmentType = Title;
ContentTypeId = kl_trn_ot_t2_mt_05_01_v1.

ParentEntityId титула Т2 совпадает с EntityId титула Т1. В том же дополнении может быть подтверждение оператора о дате доставки с признаками AttachmentType = InvoiceConfirmation и FileName = DP_PDOTPR. Подтверждение приходит получателю титула.

Пример события:

{
    "Patch": {
        "MessageId": "{{messageId}}",
        "Entities": [
            {
                "EntityType": "Attachment",
                "EntityId": "{{entityId_t2}}",
                "ParentEntityId": "{{entityId_t1}}",
                "AttachmentType": "Title",
                "Version": "kl_trn_mt_05_01",
                "ContentTypeId": "kl_trn_ot_t2_mt_05_01_v1"
            },
            {
                "EntityType": "Signature",
                "ParentEntityId": "{{entityId_t2}}"
            }
        ]
    }
}

Грузоотправителю переслали титулы Т3 или Т4 

В ящике грузоотправителя титулы Т1 и Т2 входят в одно сообщение и имеют один MessageId. Титулы Т3 и Т4 появляются в ящиках других участников перевозки. Чтобы грузоотправитель мог видеть все титулы, Диадок пересылает сведения о них в его ящик. Пересылка — отдельное сообщение с Function = fwd и новым MessageId, поэтому ее не получится связать с титулами Т1 и Т2 по MessageId. Чтобы связать пересылку с титулами Т1 и Т2, группируйте документы по УИД.

У пересылки следующие признаки:

Version и ContentTypeId равны kl_trn_fwd;
Function = fwd;
DocumentDirection = Inbound;
идентификаторы ящиков FromBoxId и ToBoxId поменялись местами относительно титула Т1;
в CustomData тег kl-func имеет значение delivery;
в CustomData указан тег mt-id — УИД Минтранса: это связь с первыми титулами перевозки;
в InitialDocumentIds указан документ-основание.

В пересылке приходят все наблюдаемые титулы.

Пример события:

{
    "Message": {
        "MessageId": "{{forwardMessageId}}",
        "Entities": [
            {
                "EntityType": "Attachment",
                "AttachmentType": "Title",
                "DocumentInfo": {
                    "InitialDocumentIds": [
                        {
                            "MessageId": "{{initialMessageId}}",
                            "EntityId": "{{initialEntityId}}"
                        }
                    ],
                    "CustomData": [
                        {
                            "Key": "kl-func",
                            "Value": "delivery"
                        },
                        {
                            "Key": "mt-id",
                            "Value": "{{mtId}}"
                        }
                    ],
                    "DocumentDirection": "Inbound",
                    "TypeNamedId": "LogisticsWaybill",
                    "Function": "fwd",
                    "Version": "kl_trn_fwd"
                },
                "ContentTypeId": "kl_trn_fwd"
            }
        ]
    }
}

Ошибки в ленте событий 

Документ не доставлен до контрагента 

Проверить статус доставки можно следующими способами:

По технологическому документу. Ориентируйтесь на DP_PDOTPR в ленте получателя: это подтверждение оператора о дате доставки.
По событию. Если документ не доставлен, в ленте появится дополнение Patch с сущностью EntityType = Attachment и AttachmentType = DeliveryFailureNotification.

Пример уведомления о недоставке:

{
    "AttachmentType": "DeliveryFailureNotification",
    "FileName": "Notification.txt",
    "NotDeliveredEventId": "{{notDeliveredEventId}}"
}

NotDeliveredEventId — идентификатор сообщения или дополнения, который не удалось доставить, — чтобы его получить, вызовите метод GetEvent (V3) и укажите NotDeliveredEventId в параметре eventId.

В этом же событии может быть сущность с причиной недоставки: если подпись оказалась невалидной, ее тип вложения будет иметь значение AttachmentType = SignatureVerificationReport.

Пример протокола проверки подписи:

{
    "EntityType": "Attachment",
    "ParentEntityId": "{{signatureEntityId}}",
    "AttachmentType": "SignatureVerificationReport"
}

Машиночитаемая доверенность не прошла проверку 

Результат проверки машиночитаемой доверенности хранится в сущности со следующими признаками:

EntityType = Attachment;
AttachmentType = PowerOfAttorneyStatus.

Статус проверки хранится в структуре PowerOfAttorneyInfo. При StatusNamedId = ValidationError код ошибки будет храниться в поле OperationError.

Пример события:

{
    "AttachmentType": "PowerOfAttorneyStatus",
    "PowerOfAttorneyInfo": {
        "Status": {
            "Severity": "Error",
            "StatusNamedId": "ValidationError",
            "OperationError": {
                "Code": "PowerOfAttorneyNotFound"
            }
        }
    }
}

Ошибки от ГИС ЭПД 

Результат проверки титула в ГИС ЭПД хранится в сущности со следующими признаками:

EntityType = Attachment;
AttachmentType = OuterDocflow;
DocflowNamedId = KlMt;
Status.Type = Error.

Статусы обработки описаны в разделе Информация о статусе обработки.

Пример события:

{
    "AttachmentType": "OuterDocflow",
    "OuterDocflow": {
        "DocflowNamedId": "KlMt",
        "Status": {
            "NamedId": "2000411000",
            "Type": "Error",
            "Details": [
                {
                    "Code": "mt-id",
                    "Text": "{{mtId}}"
                }
            ]
        }
    }
}

Ошибки из роуминга 

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

Если при отправке документа в роуминг возникла ошибка, она хранится в сущности со следующими признаками:

EntityType = Attachment;
AttachmentType = RoamingNotification.

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

Пример ответа без ошибки:

{
    "EntityType": "Attachment",
    "ParentEntityId": "{{entityId}}",
    "Content": {
        "Size": 0
    },
    "AttachmentType": "RoamingNotification"
}

Пример ответа с ошибкой:

{
    "EntityType": "Attachment",
    "ParentEntityId": "{{entityId}}",
    "Content": {
        "Size": 48
    },
    "AttachmentType": "RoamingNotification"
}

Чтобы узнать, какая ошибка произошла, вызовите метод GetDocument (V3). Текст ошибки будет храниться в поле RoamingNotificationStatusDescription. При ошибке доставки в роуминг статус будет иметь значение RoamingNotificationStatusError.

Пример ответа:

{
    "RoamingNotificationStatus": "RoamingNotificationStatusError",
    "DocumentDirection": "Outbound",
    "RoamingNotificationStatusDescription": "{{errorText}}"
}