GetForwardedDocumentEvents (V2)
Предупреждение
Метод устарел.
Возвращает список событий пересылки документов в указанный ящик.
- POST /V2/GetForwardedDocumentEvents
- Query Parameters:
boxId – идентификатор ящика организации.
- Request Headers:
Authorization – данные, необходимые для авторизации.
- Request Body:
Тело запроса должно содержать структуру
GetForwardedDocumentEventsRequest:message GetForwardedDocumentEventsRequest { required TimeBasedFilter Filter = 1; optional bytes AfterIndexKey = 2; optional bool PopulateForwardedDocuments = 3 [default = false]; optional bool InjectEntityContent = 4 [default = false]; }
Filter— фильтр событий, представленный структурой TimeBasedFilter.AfterIndexKey— ключ для постраничного получения списка найденных событий, указывающий на начало очередной страницы.PopulateForwardedDocuments— признак того, что в ответе нужно заполнить метаифнормацию о документах. Метаинформация вернется в теле ответа метода в полеForwardedDocumentEvent.ForwardedDocument.InjectEntityContent— признак того, что в результат нужно включить содержимое документа и относящихся к нему сущностей.
- Status Codes:
200 OK – операция успешно завершена.
400 Bad Request – данные в запросе имеют неверный формат или отсутствуют обязательные параметры.
401 Unauthorized – в запросе отсутствует HTTP-заголовок
Authorizationили в этом заголовке содержатся некорректные авторизационные данные.402 Payment Required – у указанного ящика закончилась подписка на API.
403 Forbidden – доступ к ящику с предоставленным авторизационным токеном запрещен.
404 Not Found – не найдено сообщение с указанным идентификатором.
405 Method Not Allowed – используется неподходящий HTTP-метод.
500 Internal Server Error – при обработке запроса возникла непредвиденная ошибка.
- Response Body:
Тело ответа содержит список событий пересылки документов в ящик, представленный структурой
GetForwardedDocumentEventsResponse:message GetForwardedDocumentEventsResponse { required int32 TotalCount = 1; repeated ForwardedDocumentEvent Events = 2; required TotalCountType TotalCountType = 3; } message ForwardedDocumentEvent { required Timestamp Timestamp = 1; required ForwardedDocumentId ForwardedDocumentId = 2; required bytes IndexKey = 3; optional ForwardedDocument ForwardedDocument = 4; }
TotalCount— общее количество найденных событий, соответствующих заданным параметрам.Events— список событий, представленных структуройForwardedDocumentEventс полями:Timestamp— время возникновения события, представленная структурой Timestamp.ForwardedDocumentId— идентификатор пересланного документа, представленный структурой ForwardedDocumentId.IndexKey— ключ для постраничного получения списка найденных событий. Его можно передавать в качестве параметраAfterIndexKeyструктурыGetForwardedDocumentEventsRequestв метод GetForwardedDocumentEvents (V2).ForwardedDocument— пересланный документ, представленный структурой ForwardedDocument.
TotalCountType— параметр, указывающий, является ли значениеTotalCountточным или подсчет был ограничен. Принимает значения из перечисления TotalCountType.
Список событий Events в ответе GetForwardedDocumentEventsResponse может содержать не больше 100 элементов. Поэтому:
Если найденных событий меньше 100, то метод вернет их полностью.
Если найденных событий больше 100, то в ответе
Eventsвернутся только первые 100 элементов. При этом параметрTotalCountбудет содержать общее количество найденных событий, а параметрTotalCountTypeпокажет, точно ли посчитано значениеTotalCountили подсчет был ограничен.В этом случае получить весь список найденных событий можно постранично. Для этого вызывайте метод
GetForwardedDocumentEventsс теми же параметрами запроса и с указанием параметраAfterIndexKeyструктуры запросаGetForwardedDocumentEventsRequestдо тех пор, пока список событий не будет вычитан полностью. В качестве параметраAfterIndexKeyнужно указывать ключ события из поляForwardedDocumentEvent.IndexKey.
В зависимости от значения параметра AfterIndexKey метод работает следующим образом:
Если в запросе отсутствует параметр
AfterIndexKey, то метод вернет начало списка найденных событий.Если в запросе указан параметр
AfterIndexKey, то метод вернет список событий, следующих за событием с ключомAfterIndexKey; событие с ключомAfterIndexKeyв этот список не попадает.
Примеры использования
Пример HTTP-запроса:
POST /V2/GetForwardedDocumentEvents?boxId={{boxId}} HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: Bearer {{access_token}}
Accept: application/json; charset=utf-8
Content-Type: application/json
Пример тела запроса:
{
"Filter": {
"FromTimestamp": {
"Ticks": 638908700430343004
}
},
"PopulateForwardedDocuments": "true"
}
Пример тела ответа:
{
"Events": [
{
"ForwardedDocument": {
"DocumentWithDocflow": {
"Docflow": {
"CanDocumentBeRevokedUnilaterallyBySender": false,
"CustomData": [
],
"DeliveryTimestamp": {
"Ticks": 638745087772041933
},
"DepartmentId": "00000000-0000-0000-0000-000000000000",
"DocflowStatus": {
"PrimaryStatus": {
"Severity": "Warning",
"StatusHint": "",
"StatusText": "Ожидается подпись контрагента"
}
},
"DocumentAttachment": {
"Attachment": {
"AttachmentFilename": "ON_NSCHFDOPPR_2BM-9147414342-757645784-202407101104400484330_2BM-6125600340-732644841-202407101103418496883_20250207_30f13ccc-deb2-4d49-8201-0ab211e8683d.xml",
"DisplayFilename": "УПД №123123 от 07.02.25",
"Entity": {
"Content": {
"Size": 2512
},
"CreationTimestamp": {
"Ticks": 638745087768452096
},
"EntityId": "da7cd73e-ff49-4a23-a018-42d27487e536"
}
},
"Signature": {
"Entity": {
"Content": {
"Size": 7011
},
"CreationTimestamp": {
"Ticks": 638745087772041933
},
"EntityId": "278a5359-5ab3-4de1-9656-bc89b0bcd6f0"
},
"IsValid": true,
"SignerBoxId": "09ae254c5cd0408284de7ccb46d86f82@diadoc.ru",
"SignerDepartmentId": "00000000-0000-0000-0000-000000000000"
}
},
"DocumentIsDeleted": false,
"IsFinished": false,
"OutboundUniversalTransferDocumentDocflow": {
"CanDocumentBeReceipted": false,
"CanDocumentBeSignedBySender": false,
"CanDocumentBeSignedOrRejectedByRecipient": true,
"ConfirmationDocflow": {
"ConfirmationAttachment": {
"Attachment": {
"AttachmentFilename": "DP_PDPOL_2BM-6125600340-732644841-202407101103418496883_2BM_20250207_f0183cf1-fcb8-4617-9fcd-6b717207f4ee.xml",
"DisplayFilename": "Подтверждение даты получения",
"Entity": {
"Content": {
"Size": 5534
},
"CreationTimestamp": {
"Ticks": 638745087772041933
},
"EntityId": "f0183cf1-fcb8-4617-9fcd-6b717207f4ee"
}
},
"Signature": {
"Entity": {
"Content": {
"Size": 3364
},
"CreationTimestamp": {
"Ticks": 638745087772041933
},
"EntityId": "493b4408-ae65-442d-ac5f-b4c32bdfe063"
},
"IsValid": true,
"SignerBoxId": "00000000000000000000000000000000@diadoc.ru",
"SignerDepartmentId": "00000000-0000-0000-0000-000000000000"
}
},
"IsFinished": true
},
"ConfirmationTimestamp": {
"Ticks": 638745087772041933
},
"IsAmendmentRequested": false,
"IsCorrected": false,
"IsDocumentRejectedByRecipient": false,
"IsDocumentSignedByRecipient": false,
"IsFinished": false,
"IsReceiptRequested": true,
"IsRecipientSignatureRequested": true,
"IsRevised": false,
"ReceiptDocflow": {
"IsFinished": true,
"ReceiptAttachment": {
"Attachment": {
"AttachmentFilename": "DP_IZVPOL_2BM-6125600340-732644841-202407101103418496883_2BM-9147414342-757645784-202407101104400484330_20250207_c6a07379-b1fb-444a-bfda-500901ac5197.xml",
"DisplayFilename": "Извещение о получении УПД",
"Entity": {
"Content": {
"Size": 5609
},
"CreationTimestamp": {
"Ticks": 638747862189246928
},
"EntityId": "a5b926b6-ffd9-4f5a-911d-2072a16a7783"
}
},
"Signature": {
"Entity": {
"Content": {
"Size": 3213
},
"CreationTimestamp": {
"Ticks": 638747862189246928
},
"EntityId": "2dd2c42c-8104-425c-9aee-e5c550c9ff42"
},
"IsValid": true,
"SignerBoxId": "1f208d032a604f6491b1b7aad54cfaf3@diadoc.ru",
"SignerDepartmentId": "00000000-0000-0000-0000-000000000000"
}
}
}
},
"SendTimestamp": {
"Ticks": 638745087768452096
}
},
"DocumentId": {
"EntityId": "da7cd73e-ff49-4a23-a018-42d27487e536",
"MessageId": "ba04162c-e26f-448f-a370-299b4f15b6d1"
},
"DocumentInfo": {
"CounteragentBoxId": "1f208d032a604f6491b1b7aad54cfaf3@diadoc.ru",
"DocumentDateAndNumber": {
"DocumentDate": "07.02.2025",
"DocumentNumber": "123123"
},
"DocumentDirection": "Outbound",
"DocumentType": "UniversalTransferDocument",
"FromDepartmentId": "00000000-0000-0000-0000-000000000000",
"IsTest": false,
"ToDepartmentId": "00000000-0000-0000-0000-000000000000",
"UniversalTransferDocumentInfo": {
"CurrencyCode": 643,
"Function": "InvoiceAndBasic",
"Grounds": "Без документа-основания",
"Total": "1.00",
"Vat": "1.00"
},
"Version": "utd820_05_01_02_hyphen"
},
"ForwardDocumentEvents": [
{
"Timestamp": {
"Ticks": 638806439880369912
},
"ToBoxId": "efc0c4deaa81428998732035ce4c2bac@diadoc.ru"
},
{
"Timestamp": {
"Ticks": 638806440596039464
},
"ToBoxId": "efc0c4deaa81428998732035ce4c2bac@diadoc.ru"
},
{
"Timestamp": {
"Ticks": 638908700430343004
},
"ToBoxId": "efc0c4deaa81428998732035ce4c2bac@diadoc.ru"
}
],
"InitialDocumentIds": [
],
"LastEventId": "10e0aa00-79f0-11f0-8000-00023a35cd5b",
"LastEventTimestamp": {
"Ticks": 638908700430756352
},
"SubordinateDocumentIds": [
]
},
"ForwardedDocumentId": {
"DocumentId": {
"EntityId": "da7cd73e-ff49-4a23-a018-42d27487e536",
"MessageId": "ba04162c-e26f-448f-a370-299b4f15b6d1"
},
"ForwardEventId": "cd8bf115-41b9-41ec-9e3e-ec6afc4b789f",
"ForwardEventIdGuid": "cd8bf115-41b9-41ec-9e3e-ec6afc4b789f",
"FromBoxId": "09ae254c5cd0408284de7ccb46d86f82@diadoc.ru"
},
"ForwardTimestamp": {
"Ticks": 638908700430343004
}
},
"ForwardedDocumentId": {
"DocumentId": {
"EntityId": "da7cd73e-ff49-4a23-a018-42d27487e536",
"MessageId": "ba04162c-e26f-448f-a370-299b4f15b6d1"
},
"ForwardEventId": "cd8bf115-41b9-41ec-9e3e-ec6afc4b789f",
"ForwardEventIdGuid": "cd8bf115-41b9-41ec-9e3e-ec6afc4b789f",
"FromBoxId": "09ae254c5cd0408284de7ccb46d86f82@diadoc.ru"
},
"IndexKey": "CN3cE/UU6gBMJa4J0FyCQITefMtG2G+CLBYEum/ij0SjcCmbTxW20T7XfNpJ/yNKoBhC0nSH5TYAquAQ8HnwEYAAAAI6Nc1b",
"Timestamp": {
"Ticks": 638908700430756352
}
}
],
"TotalCount": 1,
"TotalCountType": "Equal"
}
Пример запроса с использованием C# SDK:
Получение списка пересланных документов:
var diadoc = new DiadocApi(...);
var authToken = ...;
var myBoxId = ...;
var request = new GetForwardedDocumentEventsRequest { PopulateForwardedDocuments = true };
while (true)
{
var response = diadoc.GetForwardedDocumentEvents(authToken, myBoxId, request);
foreach (var forwardEvent in response.Events)
{
var docInfo = forwardEvent.ForwardedDocument.DocumentWithDocflow.DocumentInfo;
Console.WriteLine("Document type: {0}, number: {1}, date: {2}", docInfo.DocumentType,
docInfo.DocumentDateAndNumber.DocumentNumber, docInfo.DocumentDateAndNumber.DocumentDate);
}
if (response.Events.Count == 0)
break;
request.AfterIndexKey = response.Events.Last().IndexKey;
}
См. также
- Методы для работы с событиями по документам:
GetEvent (V2) — возвращает событие по указанному идентификатору
GetEvent (V3) — возвращает событие по указанному идентификатору
GetLastEvent — возвращает последнее событие в ящике
GetLastEvent (V2) — возвращает последнее событие в ящике
GetNewEvents (V7) — возвращает ленту событий в ящике
GetNewEvents (V8) — возвращает ленту событий в ящике
- Методы для работы с пересланными документами:
ForwardDocument (V2) — пересылает документ в указанный ящик
GenerateForwardedDocumentPrintForm — генерирует печатную форму пересланного документа
GenerateForwardedDocumentProtocol (V2) — генерирует печатную форму протокола передачи документа для адресата пересылки
GetForwardedDocumentEvents (V2) — возвращает список событий пересылки документов в указанный ящик
GetForwardedDocuments (V2) — возвращает список пересланных документов по указанным идентификаторам
GetForwardedEntityContent (V2) — возвращает содержимое указанной сущности пересланного сообщения