Загрузка истории статусов

Запрос: POST /v4/statuses/history

HTTP-заголовки:

Authorization: Bearer access_token
Content-Type: application/json
Accept: application/json

Тело запроса:

{
    "BoxId": "string",      // идентификатор ящика, для которого запрашивается история
    "MaxStatusesCount": 0,  // максимальное количество элементов в ответе
    "LastStatusId": 0       // идентификатор последнего статуса
}

Описание запроса

Запрос позволяет получить историю статусов для ящика. В поле LastStatusId указывается идентификатор последнего статуса. Значения идентификаторов новых статусов будут больше, чем LastStatusId.

В поле MaxStatusesCount указывается максимальное количество элементов в ответе. Поле опциональное. Если его не указывать, то по умолчанию возвращается до 100 новых статусов. Максимально в ответе можно вернуть до 2000 новых статусов.

Ответ на запрос

Ответ на запрос содержит объект вида:

{
    "LastStatusId":   // идентификатор последнего статуса
    "Statuses": [     // коллекция статусов документов
    ]
}

В поле LastStatusId возвращается идентификатор последнего статуса. Его нужно передать в следующем запросе истории статусов.

В поле Statuses возвращается коллекция статусов документов.

Структура данных статуса

{
    "StatusId": 0,
    "DocumentId": "guid",   // идентификатор документа, с которым произошло изменение
    "Event": {              // событие, которое привело к появлению статуса в истории
    },
    "Content": {            // вложение-контент, на которое ссылается статус
    },
    "Printform": {          // вложение-печатная форма, на которое ссылается статус
    },
    "QrCode":{              // вложение-QR-код для ЭТрН, на которое ссылается статус
    }
}

Структура данных события

Статус порождается каким-то событием (документ передан оператору, документ отправлен, документ получен, и т. д.). Данные статуса содержат информацию о событии.

{
    "EventId": "guid",                              // идентификатор события
    "StatusCode": {                                 // код статуса для события
        "CanChangeDocumentCurrentStatus": false,    // признак того, что этот код статуса может менять текущий статус документа
        "Value": "string",                          // значение кода статуса
        "Description": "string"                     // читаемое описание статуса
    },
    "Comment": "string",                            // комментарий к событию
    "OperatorDateTime": "YYYY-MM-DDThh:mm:ss.fffZ", // операторские дата и время события в UTC
    "ErrorText": "string",                          // текст ошибки, если событие сигнализирует об ошибке
    "IsOutput": false                               // признак того, что событие относится к исходящему документу
}

Идентификатор события может быть сохранен во внешней системе для целей диагностики.

Поле CanChangeDocumentCurrentStatus сигнализирует об изменении текущего статуса документа. Если оно равно true, то статус изменил текущий статус документа. В противном случае статус информационный, а текущий статус документа не изменился.

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

Структура данных вложения

Статус может ссылаться на вложение-контент, вложение-печатную форму и вложение-QR-код для ЭТрН. Все три вложения опциональны. Структура данных вложения представлена ниже.

{
    "EventId": "guid",  // идентификатор события, которому принадлежит вложение
    "Name": "string",   // имя файла вложения
    "Type": 1,          // тип вложения
    "LinkId": "string", // ссылка на вложение в архиве
    "IsValid": true,    // признак того, что вложение прошло валидацию
    "Signatures": [     // подписи под вложением
    ]
}

Идентификатор события, которому принадлежит вложение, может отличаться от идентификатора события, породившего статус. Он может быть сохранен во внешней системе для целей диагностики.

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

По ссылке, заданной в LinkId, можно загрузить содержимое вложения из архива.

Если в настройках Продукта включена валидация вложений, то поле IsValid содержит результат валидации вложения. Подробнее см. Валидация и подписи.

Структура данных подписи

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

{
    "LinkId": "string",                                     // ссылка на подпись в архиве
    "IsValid": true,                                        // признак того, что подпись прошла валидацию
    "IsEnhanced": true,                                     // признак того, что подпись является усовершенствованной (CADES)
    "OriginalLinkId": "string",                             // ссылка на оригинальную подпись в архиве
    "Type": 0,                                              // тип подписи
    "PowerOfAttorney": {                                    // данные МЧД, использованной для подписи
        "ValidationResult": {                               // результаты валидации МЧД
            "TaskId": 0,                                    // идентификатор задачи, поставленной для валидации МЧД
            "UpdateDateTime": "YYYY-MM-DDThh:mm:ss.fffZ",   // дата и время обновления задачи на валидацию МЧД
            "IsValid": true,                                // признак того, что МЧД прошла валидацию; если признак равен null, и задан идентификатор задачи, значит валидация МЧД в процессе выполнения
            "ErrorText": "string"                           // текст ошибки, возникшей при валидации
        },
        "Id": "string",                                     // идентификатор МЧД
        "IssuerInn": "string",                              // ИНН доверителя
        "LinkId": "string",                                 // ссылка на МЧД в архиве
        "SignatureLinkId": "string"                         // ссылка на подпись под МЧД в архиве
    },
    "CertificateV2": {                                      // данные сертификата
        "Thumbprint": "string",                             // отпечаток сертификата
        "ValidFrom": "YYYY-MM-DDThh:mm:ss.fffZ",            // дата и время, с которого действует сертификат
        "ValidTo": "YYYY-MM-DDThh:mm:ss.fffZ",              // дата и время, по которое действует сертификат
        "RawData": "base64",                                // данные сертификата в виде массива байт в Base64
        "PublicKeyRawData": "base64"                        // публичный ключ сертификата в виде массива байт в Base64
        "SerialNumber": "string",                           // серийный номер сертификата
        "Surname": "string",                                // фамилия владельца сертификата
        "FirstName": "string",                              // имя владельца сертификата
        "MiddleName": "string",                             // отчество владельца сертификата
        "CommonName": "string",                             // общее имя владельца сертификата
        "Position": "string",                               // должность владельца сертификата
        "OrganizationName": "string",                       // наименование организации, в которой работает владелец сертификата
        "OrganizationInn": "string",                        // ИНН организации, в которой работает владелец сертификата
        "Inn": "string",                                    // ИНН физического лица или ИП, которые владеют сертификатом
        "Snils": "string",                                  // СНИЛС владельца сертификата
        "Email": "string",                                  // e-mail владельца сертификата
        "Department": "string",                             // подразделение, в котором работает владелец сертификата
        "City": "string",                                   // город (населенный пункт) организации, в которой работает владелец сертификата, или владельца сертификата
        "Street": "string",                                 // улица и номер дома организации, в которой работает владелец сертификата, или владельца сертификата
        "Ogrn": "string",                                   // ОГРН организации, в которой работает владелец сертификата
        "OrgnIp": "string",                                 // ОГРНИП, в которой работает владелец сертификата
        "Region": "string",                                 // регион организации, в которой работает владелец сертификата, или владельца сертификата
        "Locale": "string",                                 // язык сертификата
        "RnsFss": "string",                                 // регистрационный номер страхователя ФСС
        "IssuerSimpleName": "string",                       // простое имя издателя сертификата
        "CertificateType": 0                                // тип сертификата
    }
}

По ссылке, заданной в LinkId, можно загрузить содержимое подписи из архива.

Если в настройках Продукта включена валидация подписей, то поле IsValid содержит результат валидации подписи. Если в настройках Продукта включено совершенствование подписей, то поле IsEnhanced содержит признак того, что подпись усовершенствована (т. е. является CADES-подписью). Подробнее см. Валидация и подписи.

По ссылке, заданной в OriginalLinkId, можно загрузить содержимое оригинальной подписи из архива.

Тип подписи определяет ее направление. В Продукте существует два типа подписей:

• подпись отправителя вложения-контента (тип 14);

• подпись получателя вложения-контента (тип 15).

В большинстве случаев подпись является подписью отправителя, за исключением подписей принимающей стороны под неформализованными документами и предложениями об аннулировании.

Если для подписи была указана доверенность, то ее данные возвращаются в структуре PowerOfAttorney.

См. также:

Передача и получение сведений о доверенности

Поле Certificate содержит сведения о сертификате, с помощью которого сформировали подпись.

Поле PowerOfAttorney содержит сведения об МЧД, использованной вместе с подписью.

Примечание

Вложение-печатная форма и вложение-QR-код для ЭТрН всегда приходят без подписей.