GetDocuments (V3)
Возвращает список документов, соответствующих заданным параметрам.
- GET /V3/GetDocuments
- Query Parameters:
boxId – идентификатор ящика организации, в котором осуществляется поиск документов.
filterCategory – категория, по которой нужно отфильтровать список документов. Обязательный параметр.
counteragentBoxId – идентификатор ящика контрагента, используется для фильтрации. Необязательный параметр, не имеет смысла для внутренних документов.
fromDepartmentId – идентификатор подразделения отправителя, используется для фильтрации. Необязательный параметр, имеет смысл только для внутренних документов.
toDepartmentId – идентификатор подразделения получателя, используется для фильтрации. Необязательный параметр, имеет смысл только для внутренних документов.
documentNumber – номер первичного документа. Необязательный параметр.
timestampFromTicks – метка времени, задающая начальную точку периода, по которому требуется фильтрация. Необязательный параметр.
timestampToTicks – метка времени, задающая конечную точку периода, по которому требуется фильтрация. Необязательный параметр.
fromDocumentDate – дата документа в формате «ДД.ММ.ГГГГ», задающая начальную точку периода, по которому требуется фильтрация. Необязательный параметр.
toDocumentDate – дата документа в формате «ДД.ММ.ГГГГ», задающая конечную точку периода, по которому требуется фильтрация. Необязательный параметр.
departmentId – идентификатор подразделения, в котором производится поиск документов. Необязательный параметр. Если не указан, поиск производится в головном подразделении.
excludeSubdepartments – параметр, указывающий, что из поиска нужно исключить дочерние подразделения организации.
afterIndexKey – ключ для постраничного получения списка найденных документов, указывающий на начало очередной страницы. Ключ может содержать недопустимые символы, поэтому должен быть закодирован в URL-формат. Необязательный параметр.
sortDirection – параметр, задающий порядок сортировки документов в ответе. Принимает значения
AscendingилиDescending. Необязательный параметр, по умолчанию равенAscending.count – максимальное количество элементов, возвращаемых на одной странице в ответе. Не влияет на общее количество найденных документов DocumentList.TotalCount. Принимает значения от 0 до 100, по умолчанию равен 100. Необязательный параметр.
- Request Headers:
Authorization – данные, необходимые для авторизации.
- 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:
Тело ответа содержит список документов, соответствующих указанным параметрам, представленный структурой DocumentList.
В ответе вернутся только те документы, к которым у пользователя есть доступ.
Элементы в списке DocumentList.Documents идут в порядке возрастания соответствующих меток времени, хранящихся в полях с именем Document.[...]TimestampTicks:
для исходящих отправленных документов — по Document.SendTimestampTicks;
для входящих документов — по Document.DeliveryTimestampTicks.
Содержимое документов не включается в ответ метода: поле Document.Content.Data документов в ответе будет иметь значение null. Получить содержимое документа можно с помощью метода GetEntityContent (V4).
Параметры запроса
filterCategory
Параметр filterCategory задается строкой в формате <DocumentType>.<DocumentClass><DocumentStatus>.
<DocumentType> задает тип документа и принимает значения:
<TypeNamedId>— строковый идентификатор типа документа. Доступные типы можно получить с помощью метода GetDocumentTypes (V2). Например:Invoice,XmlAcceptanceCertificate,Nonformalizedи т.п.
Any— агрегированный запрос для всех документов в ящике без учета по типу.
AnyInvoiceDocumentType— значение больше не поддерживается. Агрегированный запрос только для типовInvoice,InvoiceRevision,InvoiceCorrection,InvoiceCorrectionRevision.
AnyBilateralDocumentType— значение больше не поддерживается. Агрегированный запрос только для типовNonformalized,Torg12,AcceptanceCertificate,XmlTorg12,XmlAcceptanceCertificate,TrustConnectionRequest,PriceList,PriceListAgreement,CertificateRegistry,ReconciliationAct,Contract,Torg13.
AnyUnilateralDocumentType— значение больше не поддерживается. Агрегированный запрос только для типовProformaInvoice,ServiceDetails.
<DocumentClass> задает класс документа и принимает значения:
Inbound— только входящие.
Outbound— только исходящие.
Internal— только внутренние.
Proxy— только документы, переданные через промежуточного получателя.
<DocumentStatus> задает статус документа и принимает значения:
Пустое значение — любой документ указанного класса.
NotRead— документ не прочитан.
NoRecipientSignatureRequest— документ без запроса ответной подписи.
WaitingForRecipientSignature— документ в ожидании ответной подписи.
WithRecipientSignature— документ с ответной подписью.
WithRecipientPartiallySignature— документ с ответной подписью с разногласиями.
WithSenderSignature— документ с подписью отправителя.
RecipientSignatureRequestRejected— документ с отказом от формирования ответной подписи.
WaitingForSenderSignature— документ, требующий подписания и отправки.
InvalidSenderSignature— документ с невалидной подписью отправителя, требующий повторного подписания и отправки.
InvalidRecipientSignature— документ с невалидной подписью получателя, требующий повторного подписания и отправки.
Approved— согласованный документ.
Disapproved— документ с отказом согласования.
WaitingForResolution— документ, находящийся на согласовании или подписи.
SignatureRequestRejected— документ с отказом в запросе подписи сотруднику.
Finished— документ с завершенным документооборотом.
HaveToCreateReceipt— нужно подписать извещение о получении.
NotFinished— документ с незавершенным документооборотом.
InvoiceAmendmentRequested— документ, по которому было запрошено уточнение.
RevocationIsRequestedByMe— документ, по которому было запрошено аннулирование.
RequestsMyRevocation— документ, по которому контрагент запросил аннулирование.
RevocationAccepted— аннулированный документ.
RevocationRejected— документ, запрос на аннулирование которого был отклонен.
RevocationApproved— документ, запрос на аннулирование которого был согласован.
RevocationDisapproved— документ с отказом согласования запроса на аннулирование.
WaitingForRevocationApprovement— документ, находящийся на согласовании запроса аннулирования.
NotRevoked— неаннулированный документ.
WaitingForProxySignature— документ в ожидании подписи промежуточного получателя.
WithProxySignature— документ с подписью промежуточного получателя.
InvalidProxySignature— документ с невалидной подписью промежуточного получателя, требующий повторного подписания и отправки.
ProxySignatureRejected— документ с отказом от формирования подписи промежуточным получателем.
WaitingForInvoiceReceipt— документ в ожидании получения извещения о получении счета-фактуры.
WaitingForReceipt— документ в ожидании получения извещения о получении.
RequestsMySignature— документ, по которому контрагент запросил подпись.
RoamingNotificationError— документ с ошибкой доставки в роуминге.
HaveToCancelTtGisFixation— документ, для которого требуется отмена сведений об отгрузке маркированных товаров.
Примеры строки filterCategory:
Any.InboundNotRevoked— все входящие неаннулированные документы.
XmlTorg12.OutboundWithRecipientSignature— все исходящие формализованные ТОРГ-12, подписанные контрагентом.
InvoiceCorrection.OutboundInvoiceAmendmentRequested— все исходящие КСФ, по которым контрагент запросил уточнение.
counteragentBoxId
Параметр counteragentBoxId ограничивает результат поиска теми документами, у которых идентификатор ящика контрагента совпадает с counteragentBoxId.
documentNumber
Параметр documentNumber позволяет получить документ по номеру первичного документа.
Важно
Нельзя одновременно указывать параметры DocumentNumber и timestampFromTicks/timestampToTicks в одном запросе: метод вернет ошибку 400 (Bad Request).
timestampFromTicks и timestampToTicks
Параметры timestampFromTicks и timestampToTicks задают интервал, в котором должна находиться метка времени документа.
В зависимости от типа документа для фильтрации используются следующие метки времени документа:
исходящие отправленные документы — Document.SendTimestampTicks;
входящие документы — Document.DeliveryTimestampTicks.
Если указаны один или оба этих параметра, то метка времени документа, попавшего в результат, будет лежать в интервале [timestampFromTicks, timestampToTicks], включая границы. Если какой-то параметр отсутствует в запросе, то его значение неявно принимается равным -/+ бесконечности соответственно.
Не используйте фильтрацию по метке времени для исходящих неотправленных документов: их можно отфильтровать по статусу.
fromDocumentDate и toDocumentDate
Параметры fromDocumentDate и toDocumentDate задают интервал времени, в котором должен находится реквизит «Дата документа».
Если один или оба параметра заданы, то в ответ метода GetDocuments попадут только те документы, у которых заполнен реквизит «Дата документа».
Фильтрация документов производится по дате формирования документа в учетной системе (реквизиту самого документа), а не по метке времени, связанной с загрузкой документа в ящик Диадока.
Параметры fromDocumentDate и toDocumentDate задаются в формате «ДД.ММ.ГГГГ», то есть представляют собой только даты, а не полноценные метки времени.
Если указаны один или оба этих параметра, то дата документа (поле Document.DocumentDate), попавшего в результат, будет лежать в интервале [fromDocumentDate, toDocumentDate], включая границы. Если какой-то параметр отсутствует в запросе, то его значение неявно принимается равным +/- бесконечности.
Важно
Нельзя одновременно указывать параметры timestampFromTicks/timestampToTicks и fromDocumentDate/toDocumentDate в одном запросе: фильтрация производится либо по дате документа, либо по метке времени.
Ключи Document.IndexKey, полученные при фильтрации по дате документа (с помощью параметров fromDocumentDate и toDocumentDate) и при фильтрации по метке времени (с помощью параметров timestampFromTicks и timestampToTicks), для одного и того же документа могут различаться.
afterIndexKey
Параметр afterIndexKey позволяет получить список найденных документов постранично. Ключ может содержать недопустимые символы, поэтому перед вызовом метода его нужно URL-кодировать.
Список документов Documents в ответе DocumentList может содержать не больше 100 элементов. Поэтому:
Если найденных документов меньше 100, то метод вернет их полностью.
Если найденных документов больше 100, то в ответе
Documentsвернутся только первые 100 элементов. При этом параметрTotalCountбудет содержать общее количество найденных документов.В этом случае получить весь список найденных документов можно постранично. Для этого вызывайте метод
GetDocumentsс теми же параметрами запроса и с указанием параметраafterIndexKeyдо тех пор, пока список документов не будет вычитан полностью. В качестве параметраafterIndexKeyнужно указывать ключ документа из поля Document.IndexKey, предварительно закодировав его в URL-формат.
В зависимости от значения параметра afterIndexKey метод работает следующим образом:
Если в запросе отсутствует параметр
afterIndexKey, то метод вернет начало списка найденных документов.Если в запросе указан параметр
afterIndexKey, то метод вернет список документов, следующих за документом с ключомafterIndexKey; документ с ключомafterIndexKeyв этот список не попадает.
Примеры использования
Пример HTTP-запроса:
GET /V3/GetDocuments?filterCategory=Any.Outbound&boxId={{boxId}} HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: Bearer {{access_token}}
Content-Type: application/json charset=utf-8
Accept: application/json
Пример тела ответа:
{
"Documents": [
{
"AmendmentRequestMetadata": {
"AmendmentFlags": 0,
"ReceiptStatus": "GeneralReceiptStatusNotAcceptable"
},
"ConfirmationMetadata": {
"DateTimeTicks": 638884242438275571,
"ReceiptStatus": "GeneralReceiptStatusNotAcceptable"
},
"Content": {
"Size": 3703
},
"CounteragentBoxId": "1f208d032a604f6491b1b7aad54cfaf3@diadoc.ru",
"CreationTimestamp": "2025-07-18T08:30:43.3705569Z",
"CreationTimestampTicks": 638884242433705569,
"CustomData": [
],
"DeliveryTimestampTicks": 638884242438275571,
"DepartmentId": "00000000-0000-0000-0000-000000000000",
"DocflowStatus": {
"PowerOfAttorneyGeneralStatus": {
"Errors": [
],
"Severity": "Warning",
"StatusNamedId": "IsNotAttached",
"StatusText": "Не приложена доверенность"
},
"PrimaryStatus": {
"Severity": "Warning",
"StatusText": "Ожидается подпись контрагента. Ожидается извещение о получении"
}
},
"DocumentDate": "01.02.2014",
"DocumentDirection": "Outbound",
"DocumentNumber": "InvoicRejectedByRecipient_20460",
"DocumentType": "UniversalTransferDocument",
"EditingSettingId": "",
"EntityId": "9b4a541e-68e3-4c6f-b5a0-6009f906d554",
"EntityIdGuid": "9b4a541e-68e3-4c6f-b5a0-6009f906d554",
"FileName": "ON_NSCHFDOPPR_2BM-9147414342-757645784-202407101104400484330_2BM-6125600340-732644841-202407101103418496883_20250618_f10ef098-fa5d-44b0-97b8-dad54e25c408_0_1_1_0_0_00.xml",
"ForwardDocumentEvents": [
],
"FromDepartmentId": "00000000-0000-0000-0000-000000000000",
"Function": "СЧФДОП",
"HasCustomPrintForm": false,
"IndexKey": "0210E18CEC96D6BAF1EE082212096424D6BC5D5BFF441193B0EC6981B7CEFE2A12091E544A9BE3686F4C11B5A06009F906D554",
"InitialDocumentIds": [
],
"IsDeleted": false,
"IsEncryptedContent": false,
"IsRead": true,
"IsTest": false,
"LastModificationTimestampTicks": 638884243587901388,
"LockMode": "None",
"MessageId": "bcd62464-5b5d-44ff-93b0-ec6981b7cefe",
"MessageIdGuid": "bcd62464-5b5d-44ff-93b0-ec6981b7cefe",
"Metadata": [
{
"Key": "FileName",
"Value": "ON_NSCHFDOPPR_2BM-9147414342-757645784-202407101104400484330_2BM-6125600340-732644841-202407101103418496883_20250618_f10ef098-fa5d-44b0-97b8-dad54e25c408_0_1_1_0_0_00.xml"
},
{
"Key": "DocumentNumber",
"Value": "InvoicRejectedByRecipient_20460"
},
{
"Key": "DocumentDate",
"Value": "01.02.2014"
},
{
"Key": "TotalSum",
"Value": "10100002.57"
},
{
"Key": "TotalVat",
"Value": "10100003.56"
},
{
"Key": "CurrencyCode",
"Value": "643"
},
{
"Key": "TotalVat10",
"Value": "10.00"
},
{
"Key": "TotalVat18",
"Value": "0"
},
{
"Key": "TotalVat20",
"Value": "0"
},
{
"Key": "SellerInn",
"Value": "0273077980"
}
],
"PacketId": "9cc70246-25eb-445f-b21a-dd01ad19d350",
"PacketIsLocked": false,
"ProxySignatureStatus": "ProxySignatureStatusNone",
"RecipientReceiptMetadata": {
"ConfirmationMetadata": {
"DateTimeTicks": 0,
"ReceiptStatus": "GeneralReceiptStatusNotAcceptable"
},
"ReceiptStatus": "WaitingForReceipt"
},
"RecipientResponseStatus": "WaitingForRecipientSignature",
"RevocationStatus": "RevocationStatusNone",
"RoamingNotificationStatus": "RoamingNotificationStatusNone",
"SenderReceiptMetadata": {
"ReceiptStatus": "GeneralReceiptStatusNotAcceptable"
},
"SenderSignatureStatus": "SenderSignatureCheckedAndValid",
"SendTimestampTicks": 638884242433705569,
"SubordinateDocumentIds": [
{
"EntityId": "9585bd62-0999-4d34-ad4e-92a435ffc3e3",
"MessageId": "bcd62464-5b5d-44ff-93b0-ec6981b7cefe"
}
],
"Title": "УПД №InvoicRejectedByRecipient_20460 от 01.02.14",
"ToDepartmentId": "00000000-0000-0000-0000-000000000000",
"TtGisFixationCancellationStatus": "TtGisFixationCancellationStatusNone",
"TypeNamedId": "UniversalTransferDocument",
"UniversalTransferDocumentMetadata": {
"ConfirmationDateTimeTicks": 638884350433705569,
"Currency": 643,
"DocumentFunction": "СЧФДОП",
"DocumentStatus": "OutboundWaitingForInvoiceReceiptAndRecipientSignature",
"Grounds": "",
"InvoiceAmendmentFlags": 0,
"Total": "10100002.57",
"Vat": "10100003.56"
},
"Version": "utd970_05_03_01",
"WorkflowId": 18
},
{
"AmendmentRequestMetadata": {
"AmendmentFlags": 0,
"ReceiptStatus": "GeneralReceiptStatusNotAcceptable"
},
"ConfirmationMetadata": {
"DateTimeTicks": 638884246401807596,
"ReceiptStatus": "GeneralReceiptStatusNotAcceptable"
},
"Content": {
"Size": 24368
},
"CounteragentBoxId": "1f208d032a604f6491b1b7aad54cfaf3@diadoc.ru",
"CreationTimestamp": "2025-07-18T08:37:19.8030543Z",
"CreationTimestampTicks": 638884246398030543,
"CustomData": [
],
"DeliveryTimestampTicks": 638884246401807596,
"DepartmentId": "00000000-0000-0000-0000-000000000000",
"DocflowStatus": {
"PowerOfAttorneyGeneralStatus": {
"Errors": [
],
"Severity": "Warning",
"StatusNamedId": "IsNotAttached",
"StatusText": "Не приложена доверенность"
},
"PrimaryStatus": {
"Severity": "Info",
"StatusText": "Документооборот завершен"
}
},
"DocumentDate": "",
"DocumentDirection": "Outbound",
"DocumentType": "Nonformalized",
"EditingSettingId": "",
"EntityId": "8844ce29-51de-4339-926e-27b25d87d71a",
"EntityIdGuid": "8844ce29-51de-4339-926e-27b25d87d71a",
"FileName": "image1.png",
"ForwardDocumentEvents": [
],
"FromDepartmentId": "00000000-0000-0000-0000-000000000000",
"Function": "default",
"HasCustomPrintForm": false,
"IndexKey": "0210CFA597F9E4BAF1EE08221209C8667F20ECE4C04411AC55CA470353895C2A120929CE4488DE51394311926E27B25D87D71A",
"InitialDocumentIds": [
],
"IsDeleted": false,
"IsEncryptedContent": false,
"IsRead": true,
"IsTest": false,
"LastModificationTimestampTicks": 638884246401807596,
"LastOuterDocflows": [
],
"LockMode": "None",
"MessageId": "207f66c8-e4ec-44c0-ac55-ca470353895c",
"MessageIdGuid": "207f66c8-e4ec-44c0-ac55-ca470353895c",
"Metadata": [
{
"Key": "FileName",
"Value": "image1.png"
}
],
"NonformalizedDocumentMetadata": {
"DocumentStatus": "OutboundNoRecipientSignatureRequest",
"ReceiptStatus": "ReceiptStatusNone"
},
"PacketId": "92bccade-bfa0-4310-8051-a0761b5ec0a7",
"PacketIsLocked": false,
"ProxySignatureStatus": "ProxySignatureStatusNone",
"RecipientReceiptMetadata": {
"ConfirmationMetadata": {
"DateTimeTicks": 0,
"ReceiptStatus": "GeneralReceiptStatusNotAcceptable"
},
"ReceiptStatus": "GeneralReceiptStatusNotAcceptable"
},
"RecipientResponseStatus": "RecipientResponseStatusNotAcceptable",
"RevocationStatus": "RevocationStatusNone",
"RoamingNotificationStatus": "RoamingNotificationStatusNone",
"SenderReceiptMetadata": {
"ReceiptStatus": "GeneralReceiptStatusNotAcceptable"
},
"SenderSignatureStatus": "SenderSignatureCheckedAndValid",
"SendTimestampTicks": 638884246398030543,
"SubordinateDocumentIds": [
{
"EntityId": "deed95ff-1838-449f-a5a9-f494e8daff13",
"MessageId": "207f66c8-e4ec-44c0-ac55-ca470353895c"
}
],
"Title": "Image1.png",
"ToDepartmentId": "00000000-0000-0000-0000-000000000000",
"TtGisFixationCancellationStatus": "TtGisFixationCancellationStatusNone",
"TypeNamedId": "Nonformalized",
"Version": "v1",
"WorkflowId": 1
}
],
"HasMoreResults": false,
"TotalCount": 2
}
См. также
- Инструкции:
- Методы для работы с документами:
Delete — отмечает указанный документ как удаленный
GetContent — возвращает XSD-схему документа
GetDocument (V3) — возвращает данные документа по указанному идентификатору
GetDocuments (V3) — возвращает список документов, соответствующих заданным параметрам
GetDocumentsByMessageId — возвращает список документов из указанного сообщения
GetDocumentTypes (V2) — возвращает список типов документов, доступных в ящике
MoveDocuments — перемещает документы в указанное подразделение организации
Restore — восстанавливает документ из удаленных