GetNewEvents (V8)
Возвращает ленту событий в ящике.
GET /V8/GetNewEvents
Параметры запроса
boxId— идентификатор ящика организации в формате GUID.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— идентификатор ящика контрагента в формате GUID. Необязательный параметр.orderBy— порядок сортировки документов в выдаче по времени возникновения. Принимает значения:Ascending,Descending. Необязательный параметр. По умолчанию имеет значениеAscending.limit— максимальное количество элементов, возвращаемых на одной странице в ответе. Не влияет на общее количество найденных событий BoxEventList.TotalCount. Принимает значения от 1 до 500, по умолчанию равен 100. Необязательный параметр.
Заголовки запроса
Authorization— данные, необходимые для авторизации.
Коды ответа
200— операция успешно завершена.400— данные в запросе имеют неверный формат или отсутствуют обязательные параметры.401— в запросе отсутствует HTTP-заголовокAuthorizationили в этом заголовке содержатся некорректные авторизационные данные.402— у указанного ящика закончилась подписка на API.403— доступ к ящику с предоставленным авторизационным токеном запрещен.405— используется неподходящий HTTP-метод.429— превышено ограничение на количество запросов в единицу времени.500— при обработке запроса возникла непредвиденная ошибка.
Тело ответа
Тело ответа содержит список событий в ящике, представленный структурой BoxEventList.
Если у пользователя есть доступ ко всем документам организации, параметр departmentID можно не указывать, иначе он является обязательным: укажите в нем идентификатор подразделения, к документам которого у пользователя есть доступ. Подразделение указано в поле UserDepartmentId структуры OrganizationUserPermissions. Уровень доступа указан в поле DocumentAccessLevel структуры OrganizationUserPermissions.
Если задан параметр departmentId, метод вернет события только по указанному подразделению.
К подразделению организации привязываются все события, произошедшие с 15.03.2017. События, произошедшие до этой даты, может получить только пользователь, который имеет доступ ко всем документам организации.
Если у пользователя есть доступ ко всем документам организации, в ленту попадут события по всему ящику. Доступ пользователя можно увидеть в поле DocumentAccessLevel структуры OrganizationUserPermissions, для пользователя с доступом ко всем документам организации значение будет DocumentAccessLevel = AllDocuments.
События по черновикам доступны пользователям, у которых есть доступ ко всем документам организации, так как черновики не имеют привязки к подразделению.
Список событий Events в ответе BoxEventList может содержать не больше 500 элементов. Поэтому:
-
Если найденных событий меньше 500, то метод вернет их полностью.
-
Если найденных событий больше 500, то в ответе
Eventsвернутся только первые 500 элементов. При этом параметрTotalCountбудет содержать общее количество найденных событий, а параметрTotalCountTypeпокажет, точно ли посчитано значениеTotalCountили подсчет был ограничен.В этом случае получить весь список найденных событий можно постранично. Для этого вызывайте метод
GetNewEventsс теми же параметрами запроса и с указанием параметраafterIndexKeyдо тех пор, пока список событий не будет вычитан полностью. В качестве параметраafterIndexKeyнужно указывать ключ события из поля BoxEvent.IndexKey, предварительно закодировав его в URL-формат.
В зависимости от значения параметра afterIndexKey метод работает следующим образом:
- Если в запросе отсутствует параметр
afterIndexKey, то метод вернет начало списка найденных событий. - Если в запросе указан параметр
afterIndexKey, то метод вернет список событий, следующих за событием с ключомafterIndexKey; событие с ключомafterIndexKeyв этот список не попадает.
Если параметры afterEventId или afterIndexKey отсутствуют в запросе, то метод возвращает самые старые события из ящика boxId.
Сохраните в своем интеграционном решении идентификатор BoxEvent.IndexKey для конкретного ящика. При следующем вызове метода GetNewEvents укажите его в параметре afterIndexKey: так вы сможете узнать, какие изменения произошли в ящике с момента последнего вызова.
Чтобы тело ответа имело небольшой размер, метод возвращает только информацию об изменениях в ящике и не возвращает содержимое документов.
Примеры использования
Пример HTTP-запроса:
GET /V8/GetNewEvents?boxId={{boxId}}&messageType=Letter&documentDirection=Outbound&limit=3 HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: Bearer {{access_token}}
Accept: application/json
Пример тела ответа:
{
"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": "Attachment",
"EntityId": "c5777790-db27-40c0-b1de-410059d50c9d",
"AuthorUserId": "9aa516d1-eec7-4e09-b11e-8772d081a4fa",
"ParentEntityId": "30b20134-319a-4754-967b-86c3c683d6c3",
"Content": {
"Size": 857
},
"AttachmentType": "UniversalMessage",
"FileName": "DP_UNISOOBSCH_2BM-6125600340-732644841-202407101103418496883_2BM-9147414342-757645784-202407101104400484330_20250529_f7a4843a-e2b3-4b33-8ecb-1c3341069c21.xml",
"NeedRecipientSignature": false,
"RawCreationDate": 638841169233170302,
"NeedReceipt": false,
"IsApprovementSignature": false,
"IsEncryptedContent": false,
"Labels": [],
"ContentTypeId": "receipt_uni_01",
"UniversalMessageInfo": {
"CodeGroup": "Receipt",
"Events": [
{
"StatusCode": 1999,
"PlainText": ""
}
],
"UniversalMessageCreator": {
"BoxId": "1f208d03-2a60-4f64-91b1-b7aad54cfaf3",
"DepartmentId": "00000000-0000-0000-0000-000000000000"
},
"IsOutOfWorkflow": false
}
},
{
"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": 2,
"TotalCountType": "Equal"
}
См. также
Инструкции:
Методы для работы с событиями по документам:
- GetEvent (V3) — возвращает событие по указанному идентификатору
- GetLastEvent (V2) — возвращает последнее событие в ящике
- GetNewEvents (V8) — возвращает ленту событий в ящике