GetDocuments (V4)

Возвращает список документов, соответствующих заданным параметрам.

POST /V4/GetDocuments

Query Parameters:

boxId – идентификатор ящика организации, в котором осуществляется поиск документов, в формате GUID.

Request Headers:

Authorization – данные, необходимые для авторизации.

Request Body:

Тело запроса должно содержать запрос на получение документов по заданным параметрам GetDocumentsV4Request.

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).

Список документов Documents в ответе DocumentList может содержать не больше 100 элементов. Поэтому:

Если найденных документов меньше 100, то метод вернет их полностью.

Если найденных документов больше 100, то в ответе Documents вернутся только первые 100 элементов. При этом параметр TotalCount будет содержать общее количество найденных документов.

В этом случае получить весь список найденных документов можно постранично. Для этого вызывайте метод GetDocuments с теми же параметрами запроса и с указанием параметра AfterIndexKey в теле запроса до тех пор, пока список документов не будет вычитан полностью. В качестве параметра AfterIndexKey нужно указывать ключ документа из поля Document.IndexKey.

В зависимости от значения параметра AfterIndexKey метод работает следующим образом:

Если в запросе отсутствует параметр AfterIndexKey, то метод вернет начало списка найденных документов.

Если в запросе указан параметр AfterIndexKey, то метод вернет список документов, следующих за документом с ключом AfterIndexKey; документ с ключом AfterIndexKey в этот список не попадает.

Примеры использования

Пример HTTP-запроса:

POST /V4/GetDocuments?boxId={{boxId}} HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: Bearer {{access_token}}
Accept: application/json

Пример тела запроса:

{
    "CounteragentBoxIds": ["bc84b3aa-f4bb-4924-b291-dd5569053639", "7e78d486-a9d8-49ea-ba46-62ae88fff59e"],
    "FromDepartmentIds": ["00000000-0000-0000-0000-000000000000"],
    "ToDepartmentIds": ["00000000-0000-0000-0000-000000000000"],
    "Departments": [
        {
            "DepartmentId": "6c569959-4ab1-479f-85b5-aa1c50df3a7d",
            "excludeSubdepartments": true
        }
    ],
    "DocumentTypeNamedIds": ["Invoice", "Nonformalized"],
    "DocumentCategory": "Incoming",
    "DocumentStatuses": ["WaitingForRecipientSignature", "WithRecipientSignature", "WaitingForReceipt"],
    "FileNames": ["a4731614e4c149dbd65691c434dedd56.jpg"],
    "DocumentNumbers": ["444", "123"],
    "FromDocumentDate": "01.01.2026",
    "ToDocumentDate": "01.02.2026",
    "FromTimestamp": {"Ticks": "639068662000000000"},
    "ToTimestamp": {"Ticks": "639068662661337759"},
    "TotalSums": ["10000.00","1002"],
    "FromTotalSum": "9999.99",
    "ToTotalSum": "10000.00",
    "CustomData": [
        {
            "Key": "test",
            "Value": "UniversalTransferDocument_ДОП_utd970_05_03_01"
        },
    ],
    "SortDirection": "Descending",
    "Count": "100",
    "AfterIndexKey": "0210D59CECD4FEB19BEF08221209532D622D8BAC4D4B11B6F97584435249992A1209E0C78CFBDB83E545118BFEFE3300CEC486",
}

Пример тела ответа:

{
    "TotalCount": 1,
    "Documents": [
        {
            "IndexKey": "0210D8E1BA8B81B29BEF0822120933A16DE30799744E11A58802B08DFC5B322A1209F8542FCA3BC8524211B49E88C98FC83A49",
            "MessageId": "e36da133-9907-4e74-a588-02b08dfc5b32",
            "EntityId": "ca2f54f8-c83b-4252-b49e-88c98fc83a49",
            "CreationTimestampTicks": 639068662661337760,
            "CounteragentBoxId": "bc84b3aaf4bb4924b291dd5569053639@diadoc.ru",
            "DocumentType": "Invoice",
            "InitialDocumentIds": [],
            "SubordinateDocumentIds": [],
            "Content": {
                "Size": 24330
            },
            "FileName": "ON_NSCHFDOPPR_2BM-966259685098-20231024083946535138700000000_2BM-9616675014-961601000-202310240839360601227_20190507_944a71c2-22b8-48cd-842e-7b552b1ebcda_1_1_0_0_1_00.xml",
            "DocumentDate": "01.02.2003",
            "DocumentNumber": "444",
            "InvoiceMetadata": {
                "InvoiceStatus": "InboundNotFinished",
                "Total": "10000",
                "Vat": "456.00",
                "Currency": 643,
                "ConfirmationDateTimeTicks": 639068770668374232,
                "InvoiceAmendmentFlags": 0
            },
            "IsDeleted": false,
            "DepartmentId": "6c569959-4ab1-479f-85b5-aa1c50df3a7d",
            "IsTest": false,
            "FromDepartmentId": "00000000-0000-0000-0000-000000000000",
            "ToDepartmentId": "00000000-0000-0000-0000-000000000000",
            "ResolutionStatus": {
                "Type": "ApprovementRequested",
                "Target": {
                    "Department": "Department 3",
                    "DepartmentId": "6c569959-4ab1-479f-85b5-aa1c50df3a7d",
                    "User": ""
                },
                "AuthorUserId": "d43qe847-0db0-4540-b271-9473946387ts",
                "AuthorFIO": "Иванов Иван Иванович"
            },
            "RevocationStatus": "RevocationStatusNone",
            "SendTimestampTicks": 639068662661337760,
            "DeliveryTimestampTicks": 639068662668374232,
            "ForwardDocumentEvents": [],
            "RoamingNotificationStatus": "RoamingNotificationStatusNone",
            "HasCustomPrintForm": false,
            "CustomData": [
                {
                    "Key": "Key",
                    "Value": "Value"
                }
            ],
            "DocumentDirection": "Inbound",
            "LastModificationTimestampTicks": 639075415878994825,
            "IsEncryptedContent": false,
            "SenderSignatureStatus": "SenderSignatureCheckedAndValid",
            "IsRead": true,
            "PacketIsLocked": false,
            "ProxySignatureStatus": "ProxySignatureStatusNone",
            "TypeNamedId": "Invoice",
            "Function": "default",
            "WorkflowId": 17,
            "Title": "Счет-фактура №444 от 01.02.03",
            "Metadata": [
                {
                    "Key": "FileName",
                    "Value": "ON_NSCHFDOPPR_2BM-966259685098-20231024083946535138700000000_2BM-9616675014-961601000-202310240839360601227_20190507_944a71c2-22b8-48cd-842e-7b552b1ebcda_1_1_0_0_1_00.xml"
                },
                {
                    "Key": "DocumentNumber",
                    "Value": "444"
                },
                {
                    "Key": "DocumentDate",
                    "Value": "01.02.2003"
                },
                {
                    "Key": "TotalSum",
                    "Value": "10000"
                },
                {
                    "Key": "TotalVat",
                    "Value": "456.00"
                },
                {
                    "Key": "CurrencyCode",
                    "Value": "643"
                },
                {
                    "Key": "Grounds",
                    "Value": "ОснПер-РеквНаимДок №567 от 14.02.2020"
                },
                {
                    "Key": "TotalVat10",
                    "Value": "1000.000000000000000"
                },
                {
                    "Key": "TotalVat18",
                    "Value": "0"
                },
                {
                    "Key": "TotalVat20",
                    "Value": "2000.000000000000000"
                },
                {
                    "Key": "SellerInn",
                    "Value": "9103624367"
                }
            ],
            "RecipientReceiptMetadata": {
                "ReceiptStatus": "HaveToCreateReceipt",
                "ConfirmationMetadata": {
                    "ReceiptStatus": "GeneralReceiptStatusNotAcceptable",
                    "DateTimeTicks": 0
                }
            },
            "ConfirmationMetadata": {
                "ReceiptStatus": "GeneralReceiptStatusNotAcceptable",
                "DateTimeTicks": 639068662668374232
            },
            "RecipientResponseStatus": "RecipientResponseStatusNotAcceptable",
            "AmendmentRequestMetadata": {
                "AmendmentFlags": 0,
                "ReceiptStatus": "GeneralReceiptStatusNotAcceptable"
            },
            "EditingSettingId": "",
            "LockMode": "None",
            "SenderReceiptMetadata": {
                "ReceiptStatus": "GeneralReceiptStatusNotAcceptable"
            },
            "Version": "utd970_05_03_01",
            "LastOuterDocflows": [],
            "DocflowStatus": {
                "PrimaryStatus": {
                    "Severity": "Warning",
                    "StatusText": "Требуется отправить уведомление"
                },
                "SecondaryStatus": {
                    "Severity": "Info",
                    "StatusText": "На согласовании"
                },
                "PowerOfAttorneyGeneralStatus": {
                    "Severity": "Warning",
                    "StatusNamedId": "IsNotAttached",
                    "StatusText": "Не приложена доверенность",
                    "Errors": []
                }
            },
            "TtGisFixationCancellationStatus": "TtGisFixationCancellationStatusNone",
            "MessageIdGuid": "e36da133-9907-4e74-a588-02b08dfc5b32",
            "EntityIdGuid": "ca2f54f8-c83b-4252-b49e-88c98fc83a49",
            "CreationTimestamp": "2026-02-16T19:17:46.133776Z"
        }
    ],
    "HasMoreResults": false
}

См. также

Инструкции:

Получение документов

Методы для работы с документами:

Delete — отмечает указанный документ как удаленный
GetContent — возвращает XSD-схему документа
GetDocument (V3) — возвращает данные документа по указанному идентификатору
GetDocuments (V3) — возвращает список документов, соответствующих заданным параметрам
GetDocuments (V4) — возвращает список документов, соответствующих заданным параметрам
GetDocumentsByMessageId — возвращает список документов из указанного сообщения
GetDocumentTypes (V2) — возвращает список типов документов, доступных в ящике, и дату перехода на универсальные сообщения
GetDocumentTypes (V3) — возвращает список типов документов, доступных в ящике
MoveDocuments — перемещает документы в указанное подразделение организации
Restore — восстанавливает документ из удаленных

Предыдущие версии метода:

GetDocuments (V3)