GetNewEvents (V7)
Внимание
Метод устарел и будет удален из API после 03 апреля 2027 года. Подробнее в истории изменений. Используйте актуальную версию метода — GetNewEvents (V8).
Возвращает ленту событий в ящике.
- GET /V7/GetNewEvents
- Query Parameters:
boxId – идентификатор ящика организации.
afterEventId – идентификатор последнего полученного события. Параметр устарел, рекомендуем использовать параметр
afterIndexKey.afterIndexKey – ключ для постраничного получения списка найденных событий, указывающий на начало очередной страницы. Ключ может содержать недопустимые символы, поэтому должен быть закодирован в URL-формат. Нельзя указывать одновременно с
afterEventId. Необязательный параметр.departmentId – идентификатор подразделения, из которого производится выборка документов.
messageType –
тип cообщения. Можно указать несколько значений через запятую. Необязательный параметр. Принимает значения:
Draft— черновик,Letter— письмо,Template— шаблон.
typeNamedId – строковый идентификатор типа документа. Доступные типы можно получить с помощью метода GetDocumentTypes (V3). Можно указать несколько значений через запятую. Необязательный параметр.
documentDirection –
направление документа относительно текущего ящика. Можно указать несколько значений через запятую. Необязательный параметр. Принимает значения:
Inbound— входящие,Outbound— исходящие,Internal— внутренние.
timestampFromTicks – метка времени, задающая начальную точку периода. Задается целое число тиков, прошедших с момента времени 00:00:00 01.01.0001. Необязательный параметр.
timestampToTicks – метка времени, задающая конечную точку периода. Задается целое число тиков, прошедших с момента времени 00:00:00 01.01.0001. Необязательный параметр.
counteragentBoxId – идентификатор ящика контрагента. Необязательный параметр.
orderBy – порядок сортировки документов в выдаче по времени возникновения. Принимает значения:
Ascending,Descending. Необязательный параметр. По умолчанию имеет значениеAscending.limit – максимальное количество элементов, возвращаемых на одной странице в ответе. Не влияет на общее количество найденных событий BoxEventList.TotalCount. Принимает значения от 1 до 500, по умолчанию равен 100. Необязательный параметр.
- Request Headers:
Authorization – данные, необходимые для авторизации.
- Status Codes:
200 OK – операция успешно завершена.
400 Bad Request – данные в запросе имеют неверный формат или отсутствуют обязательные параметры.
401 Unauthorized – в запросе отсутствует HTTP-заголовок
Authorizationили в этом заголовке содержатся некорректные авторизационные данные.402 Payment Required – у указанного ящика закончилась подписка на API.
403 Forbidden – доступ к ящику с предоставленным авторизационным токеном запрещен.
405 Method Not Allowed – используется неподходящий HTTP-метод.
500 Internal Server Error – при обработке запроса возникла непредвиденная ошибка.
- Response Body:
Тело ответа содержит список событий в ящике, представленный структурой BoxEventList.
Если у пользователя есть доступ ко всем документам организации, параметр departmentID можно не указывать, иначе он является обязательным: укажите в нем идентификатор подразделения, к документам которого у пользователя есть доступ. Подразделение указано в поле UserDepartmentId структуры OrganizationUserPermissions. Уровень доступа указан в поле DocumentAccessLevel структуры OrganizationUserPermissions.
Если задан параметр departmentId, метод вернет события только по указанному подразделению.
Важно
К подразделению организации привязываются все события, произошедшие с 15.03.2017. События, произошедшие до этой даты, может получить только пользователь, который имеет доступ ко всем документам организации.
Если у пользователя есть доступ ко всем документам организации, в ленту попадут события по всему ящику. Доступ пользователя можно увидеть в поле DocumentAccessLevel структуры OrganizationUserPermissions, для пользователя с доступом ко всем документам организации значение будет DocumentAccessLevel = AllDocuments.
События по черновикам доступны пользователям, у которых есть доступ ко всем документам организации, так как черновики не имеют привязки к подразделению.
Список событий Events в ответе BoxEventList может содержать не более того количества элементов, которое было указано в параметре limit. Поэтому:
Если количество найденных событий меньше указанного в
limit, то метод вернет их полностью.Если количество найденных событий больше указанного в
limit, то в ответеEventsвернется только первая часть элементов в запрошенном количестве. При этом параметрTotalCountбудет содержать общее количество найденных событий, а параметрTotalCountTypeпокажет, точно ли посчитано значениеTotalCountили подсчет был ограничен.В этом случае получить весь список найденных событий можно постранично. Для этого вызывайте метод
GetNewEventsс теми же параметрами запроса и с указанием параметраafterIndexKeyдо тех пор, пока список событий не будет вычитан полностью. В качестве параметраafterIndexKeyнужно указывать ключ события из поля BoxEvent.IndexKey, предварительно закодировав его в URL-формат.
В зависимости от значения параметра afterIndexKey метод работает следующим образом:
Если в запросе отсутствует параметр
afterIndexKey, то метод вернет начало списка найденных событий.Если в запросе указан параметр
afterIndexKey, то метод вернет список событий, следующих за событием с ключомafterIndexKey; событие с ключомafterIndexKeyв этот список не попадает.
Если параметры afterEventId или afterIndexKey отсутствуют в запросе, то метод возвращает самые старые события из ящика boxId.
Сохраните в своем интеграционном решении идентификатор BoxEvent.IndexKey для конкретного ящика. При следующем вызове метода GetNewEvents укажите его в параметре afterIndexKey: так вы сможете узнать, какие изменения произошли в ящике с момента последнего вызова.
Чтобы тело ответа имело небольшой размер, метод возвращает только информацию об изменениях в ящике и не возвращает содержимое документов.
Примеры использования
Пример HTTP-запроса:
GET /V7/GetNewEvents?boxId={{boxId}}&messageType=Letter&documentDirection=Outbound&limit=3 HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: Bearer {{access_token}}
Accept: application/json; charset=utf-8
Пример тела ответа:
{
"Events": [
{
"EventId": "3ebd9963-9c29-4cd7-a28b-93b9c5e294cc",
"Message": {
"MessageId": "3ebd9963-9c29-4cd7-a28b-93b9c5e294cc",
"TimestampTicks": 638562073540225572,
"LastPatchTimestampTicks": 638562073540225572,
"FromBoxId": "09ae254c5cd0408284de7ccb46d86f82@diadoc.ru",
"FromTitle": "Организация-отправитель",
"ToBoxId": "1f208d032a604f6491b1b7aad54cfaf3@diadoc.ru",
"ToTitle": "Организация-получатель",
"Entities": [
{
"EntityType": "Attachment",
"EntityId": "4bf9d9b4-93e6-4bda-85ed-5c83e1b075cb",
"AuthorUserId": "",
"ParentEntityId": "",
"Content": {
"Size": 11061
},
"AttachmentType": "UniversalTransferDocument",
"FileName": "ON_NSCHFDOPPR_2BM-966259685098-20231024083946535138700000000_2BM-9616675014-961601000-202310240839360601227_20240710_b6ee65a3-040e-405c-a2fa-5080df8a3d34_1_1_0_0_1_00.xml",
"NeedRecipientSignature": false,
"DocumentInfo": {
"MessageId": "3ebd9963-9c29-4cd7-a28b-93b9c5e294cc",
"EntityId": "4bf9d9b4-93e6-4bda-85ed-5c83e1b075cb",
"CreationTimestampTicks": 638562073531053865,
"CounteragentBoxId": "09ae254c5cd0408284de7ccb46d86f82@diadoc.ru",
"DocumentType": "UniversalTransferDocument",
"InitialDocumentIds": [],
"SubordinateDocumentIds": [],
"Content": {
"Size": 11061
},
"FileName": "ON_NSCHFDOPPR_2BM-966259685098-20231024083946535138700000000_2BM-9616675014-961601000-202310240839360601227_20240710_b6ee65a3-040e-405c-a2fa-5080df8a3d34_1_1_0_0_1_00.xml",
"DocumentDate": "01.02.2003",
"DocumentNumber": "444",
"IsDeleted": false,
"DepartmentId": "00000000-0000-0000-0000-000000000000",
"IsTest": true,
"FromDepartmentId": "00000000-0000-0000-0000-000000000000",
"ToDepartmentId": "00000000-0000-0000-0000-000000000000",
"RevocationStatus": "RevocationStatusNone",
"SendTimestampTicks": 638562073531053865,
"DeliveryTimestampTicks": 638562073540225572,
"ForwardDocumentEvents": [],
"RoamingNotificationStatus": "RoamingNotificationStatusNone",
"HasCustomPrintForm": false,
"CustomData": [],
"DocumentDirection": "Inbound",
"LastModificationTimestampTicks": 638562073540225572,
"IsEncryptedContent": false,
"SenderSignatureStatus": "SenderSignatureCheckedAndValid",
"IsRead": false,
"PacketIsLocked": false,
"UniversalTransferDocumentMetadata": {
"DocumentStatus": "InboundNotFinished",
"Total": "10000.00",
"Vat": "456.00",
"Grounds": "ОснПер-РеквНаимДок №567 от 14.02.2020",
"DocumentFunction": "СЧФ",
"Currency": 643,
"ConfirmationDateTimeTicks": 638562181540225572,
"InvoiceAmendmentFlags": 0
},
"ProxySignatureStatus": "ProxySignatureStatusNone",
"TypeNamedId": "UniversalTransferDocument",
"Function": "СЧФ",
"WorkflowId": 17,
"Title": "УПД №444 от 01.02.03",
"Metadata": [
{
"Key": "FileName",
"Value": "ON_NSCHFDOPPR_2BM-966259685098-20231024083946535138700000000_2BM-9616675014-961601000-202310240839360601227_20240710_b6ee65a3-040e-405c-a2fa-5080df8a3d34_1_1_0_0_1_00.xml"
},
{
"Key": "DocumentNumber",
"Value": "444"
},
{
"Key": "DocumentDate",
"Value": "01.02.2003"
},
{
"Key": "TotalSum",
"Value": "10000.00"
},
{
"Key": "TotalVat",
"Value": "456.00"
},
{
"Key": "CurrencyCode",
"Value": "643"
},
{
"Key": "Grounds",
"Value": "ОснПер-РеквНаимДок №567 от 14.02.2020"
},
{
"Key": "TotalVat10",
"Value": "0"
},
{
"Key": "TotalVat18",
"Value": "0"
},
{
"Key": "TotalVat20",
"Value": "2000.00"
},
{
"Key": "SellerInn",
"Value": "9103624367"
}
],
"RecipientReceiptMetadata": {
"ReceiptStatus": "HaveToCreateReceipt",
"ConfirmationMetadata": {
"ReceiptStatus": "GeneralReceiptStatusNotAcceptable",
"DateTimeTicks": 0
}
},
"ConfirmationMetadata": {
"ReceiptStatus": "GeneralReceiptStatusNotAcceptable",
"DateTimeTicks": 638562073540225572
},
"RecipientResponseStatus": "RecipientResponseStatusNotAcceptable",
"AmendmentRequestMetadata": {
"AmendmentFlags": 0,
"ReceiptStatus": "GeneralReceiptStatusNotAcceptable"
},
"EditingSettingId": "",
"LockMode": "None",
"SenderReceiptMetadata": {
"ReceiptStatus": "GeneralReceiptStatusNotAcceptable"
},
"Version": "utd970_05_02_01",
"LastOuterDocflows": [],
"DocflowStatus": {
"PrimaryStatus": {
"Severity": "Warning",
"StatusText": "Требуется отправить уведомление"
}
},
"TtGisFixationCancellationStatus": "TtGisFixationCancellationStatusNone",
"HasUnreadOutOfWorkflowUniversalMessages": false,
"Participants": [
{
"Participant": {
"BoxId": "09ae254c5cd0408284de7ccb46d86f82@diadoc.ru",
"DepartmentId": "00000000-0000-0000-0000-000000000000",
"Role": "default:sender",
"Flags": {
"IsRoaming": false,
"IsCrossborder": false,
"IsForeign": false
},
"Type": "Sender",
"IsCurrentBox": false
},
"RecipientResponseStatus": "RecipientResponseStatusUnknown"
},
{
"Participant": {
"BoxId": "1f208d032a604f6491b1b7aad54cfaf3@diadoc.ru",
"DepartmentId": "00000000-0000-0000-0000-000000000000",
"Role": "default:recipient",
"Flags": {
"IsRoaming": false,
"IsCrossborder": false,
"IsForeign": false
},
"Type": "Recipient",
"IsCurrentBox": true
},
"RecipientResponseStatus": "RecipientResponseStatusNotAcceptable"
}
],
"MessageIdGuid": "3ebd9963-9c29-4cd7-a28b-93b9c5e294cc",
"EntityIdGuid": "4bf9d9b4-93e6-4bda-85ed-5c83e1b075cb",
"CreationTimestamp": "2024-07-10T11:22:33.1053865Z"
},
"RawCreationDate": 638562073531053865,
"NeedReceipt": false,
"IsApprovementSignature": false,
"IsEncryptedContent": false,
"Labels": [],
"Version": "utd970_05_02_01",
"ContentTypeId": "utd970_schf_orig_05_02_01"
},
{
"EntityType": "Signature",
"EntityId": "d7a99a73-80bb-4422-a33e-9792ae858386",
"AuthorUserId": "",
"ParentEntityId": "4bf9d9b4-93e6-4bda-85ed-5c83e1b075cb",
"Content": {
"Size": -1
},
"AttachmentType": "Nonformalized",
"NeedRecipientSignature": false,
"SignerBoxId": "09ae254c5cd0408284de7ccb46d86f82@diadoc.ru",
"RawCreationDate": 638562073540225572,
"SignerDepartmentId": "00000000-0000-0000-0000-000000000000",
"NeedReceipt": false,
"IsApprovementSignature": false,
"IsEncryptedContent": false,
"Labels": [],
"ContentTypeId": "",
"PowerOfAttorneyAttachmentStatus": {
"StatusName": "PowerOfAttorneyNotRequired"
}
},
{
"EntityType": "Attachment",
"EntityId": "8e51deee-da1c-43a5-a34a-4987e1989238",
"AuthorUserId": "",
"ParentEntityId": "4bf9d9b4-93e6-4bda-85ed-5c83e1b075cb",
"Content": {
"Size": 5535
},
"AttachmentType": "InvoiceConfirmation",
"FileName": "DP_PDOTPR_2BM-9147414342-757645784-202407101104400484330_2BM_20240710_8e51deee-da1c-43a5-a34a-4987e1989238.xml",
"NeedRecipientSignature": false,
"RawCreationDate": 638562073540225572,
"NeedReceipt": false,
"IsApprovementSignature": false,
"IsEncryptedContent": false,
"Labels": [],
"ContentTypeId": "delivery_confirmation_133_01_03"
},
{
"EntityType": "Signature",
"EntityId": "86139cb2-4a6f-4035-9645-4d2fc0ea66ce",
"AuthorUserId": "",
"ParentEntityId": "8e51deee-da1c-43a5-a34a-4987e1989238",
"Content": {
"Size": -1
},
"AttachmentType": "Nonformalized",
"NeedRecipientSignature": false,
"SignerBoxId": "00000000000000000000000000000000@diadoc.ru",
"RawCreationDate": 638562073540225572,
"SignerDepartmentId": "00000000-0000-0000-0000-000000000000",
"NeedReceipt": false,
"IsApprovementSignature": false,
"IsEncryptedContent": false,
"Labels": [],
"ContentTypeId": "",
"PowerOfAttorneyAttachmentStatus": {
"StatusName": "PowerOfAttorneyNotRequired"
}
}
],
"IsDraft": false,
"DraftIsLocked": false,
"DraftIsRecycled": false,
"CreatedFromDraftId": "",
"DraftIsTransformedToMessageIdList": [],
"IsDeleted": false,
"IsTest": true,
"IsInternal": false,
"IsProxified": false,
"ProxyBoxId": "",
"ProxyTitle": "",
"PacketIsLocked": false,
"LockMode": "None",
"MessageType": "Letter",
"IsReusable": false
},
"IndexKey": "CNyg0piE5Zs"
},
{
"EventId": "ff88d292-6bb8-4376-85cf-cbf792c10ca4",
"Patch": {
"MessageId": "3e1eb004-91ff-466f-ae47-3f16817a58cf",
"TimestampTicks": 638841169233170302,
"Entities": [
{
"EntityType": "Attachment",
"EntityId": "d4b75add-5554-4bbb-b3e3-40baa4a6ccfb",
"AuthorUserId": "",
"ParentEntityId": "30b20134-319a-4754-967b-86c3c683d6c3",
"Content": {
"Size": 5710
},
"AttachmentType": "InvoiceReceipt",
"FileName": "DP_IZVPOL_2BM-6125600340-732644841-202407101103418496883_2BM-9147414342-757645784-202407101104400484330_20250529_fd5efff4-b2ba-49ec-8347-e0de9a8cd726.xml",
"NeedRecipientSignature": false,
"RawCreationDate": 638841169233170302,
"NeedReceipt": false,
"IsApprovementSignature": false,
"IsEncryptedContent": false,
"Labels": [],
"ContentTypeId": "receipt_133_01_03"
},
{
"EntityType": "Signature",
"EntityId": "bd705578-5acd-49a4-b242-eaafad95713f",
"AuthorUserId": "9aa516d1-eec7-4e09-b11e-8772d081a4fa",
"ParentEntityId": "d4b75add-5554-4bbb-b3e3-40baa4a6ccfb",
"Content": {
"Size": -1
},
"AttachmentType": "Nonformalized",
"NeedRecipientSignature": false,
"SignerBoxId": "1f208d032a604f6491b1b7aad54cfaf3@diadoc.ru",
"RawCreationDate": 638841169233170302,
"SignerDepartmentId": "00000000-0000-0000-0000-000000000000",
"NeedReceipt": false,
"IsApprovementSignature": false,
"IsEncryptedContent": false,
"Labels": [],
"ContentTypeId": "",
"PowerOfAttorneyAttachmentStatus": {
"StatusName": "PowerOfAttorneyRequired",
"Comment": "Документ подписан сертификатом физ. лица без МЧД"
}
}
],
"ForDraft": false,
"DraftIsRecycled": false,
"DraftIsTransformedToMessageIdList": [],
"DraftIsLocked": false,
"MessageIsDeleted": false,
"EntityPatches": [],
"MessageIsRestored": false,
"MessageIsDelivered": false,
"PatchId": "ff88d292-6bb8-4376-85cf-cbf792c10ca4",
"MessageType": "Letter"
},
"IndexKey": "CN2eqKAXxdI"
}
],
"TotalCount": 248,
"TotalCountType": "Equal"
}
См. также
- Инструкции:
- Методы для работы с событиями по документам:
GetEvent (V3) — возвращает событие по указанному идентификатору
GetLastEvent (V2) — возвращает последнее событие в ящике
GetNewEvents (V8) — возвращает ленту событий в ящике