Перейти к основному содержимому

GetDocuments (V3)

подсказка

Для этого метода существует новая версия — GetDocuments (V4). В интеграционных решениях рекомендуем использовать именно ее.

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

GET /V3/GetDocuments

Параметры запроса

  • boxId — идентификатор ящика организации, в котором осуществляется поиск документов, в формате GUID.
  • filterCategory — категория, по которой нужно отфильтровать список документов. Обязательный параметр.
  • counteragentBoxId — идентификатор ящика контрагента, используется для фильтрации. Необязательный параметр, не имеет смысла для внутренних документов.
  • fromDepartmentId — идентификатор подразделения отправителя, используется для фильтрации. Необязательный параметр, имеет смысл только для внутренних документов.
  • toDepartmentId — идентификатор подразделения получателя, используется для фильтрации. Необязательный параметр, имеет смысл только для внутренних документов.
  • documentNumber — номер первичного документа. Необязательный параметр.
  • timestampFromTicks — метка времени, задающая начальную точку периода, по которому требуется фильтрация. Необязательный параметр.
  • timestampToTicks — метка времени, задающая конечную точку периода, по которому требуется фильтрация. Необязательный параметр.
  • fromDocumentDate — дата документа в формате «ДД.ММ.ГГГГ», задающая начальную точку периода, по которому требуется фильтрация. Необязательный параметр.
  • toDocumentDate — дата документа в формате «ДД.ММ.ГГГГ», задающая конечную точку периода, по которому требуется фильтрация. Необязательный параметр.
  • departmentId — идентификатор подразделения, в котором производится поиск документов. Необязательный параметр. Если не указан, поиск производится в головном подразделении.
  • excludeSubdepartments — параметр, указывающий, что из поиска нужно исключить дочерние подразделения организации.
  • afterIndexKey — ключ для постраничного получения списка найденных документов, указывающий на начало очередной страницы. Ключ может содержать недопустимые символы, поэтому должен быть закодирован в URL-формат. Необязательный параметр.
  • sortDirection — параметр, задающий порядок сортировки документов в ответе. Принимает значения Ascending или Descending. Необязательный параметр, по умолчанию равен Ascending.
  • count — максимальное количество элементов, возвращаемых на одной странице в ответе. Не влияет на общее количество найденных документов DocumentList.TotalCount. Принимает значения от 0 до 100, по умолчанию равен 100. Необязательный параметр.

Заголовки запроса

Коды ответа

  • 200 — операция успешно завершена.
  • 400 — данные в запросе имеют неверный формат или отсутствуют обязательные параметры.
  • 401 — в запросе отсутствует HTTP-заголовок Authorization или в этом заголовке содержатся некорректные авторизационные данные.
  • 402 — у указанного ящика закончилась подписка на API.
  • 403 — доступ к ящику с предоставленным авторизационным токеном запрещен.
  • 404 — не найден ящик с указанным идентификатором.
  • 405 — используется неподходящий HTTP-метод.
  • 429 — превышено ограничение на количество запросов в единицу времени.
  • 500 — при обработке запроса возникла непредвиденная ошибка.

Тело ответа

Тело ответа содержит список документов, соответствующих указанным параметрам, представленный структурой DocumentList.

В ответе вернутся только те документы, к которым у пользователя есть доступ.

С помощью этого метода нельзя получить шаблон или черновик. О том, как получить шаблон, написано в разделе Получение шаблонов и событий, а получение черновика — на странице Работа с черновиками.

Элементы в списке DocumentList.Documents идут в порядке возрастания соответствующих меток времени, хранящихся в полях с именем Document.[...]TimestampTicks:

Содержимое документов не включается в ответ метода: поле Document.Content.Data документов в ответе будет иметь значение null. Получить содержимое документа можно с помощью метода GetEntityContent (V4).

Параметры запроса

filterCategory

Параметр filterCategory задается строкой в формате <DocumentType>.<DocumentClass><DocumentStatus>.

<DocumentType> задает тип документа и принимает значения:

  • <TypeNamedId> — строковый идентификатор типа документа. Доступные типы можно получить с помощью метода GetDocumentTypes (V3). Например: 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 — только документы, переданные через промежуточного получателя.
  • Deleted — только документы, помеченные удаленными.

<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 задают интервал, в котором должна находиться метка времени документа.

В зависимости от типа документа для фильтрации используются следующие метки времени документа:

Если указаны один или оба этих параметра, то метка времени документа, попавшего в результат, будет лежать в интервале [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}}
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) — возвращает данные документа по указанному идентификатору
  • GetDocumentActions — возвращает список действий, доступных текущему пользователю для указанного документа, шаблона или черновика
  • GetDocumentHistory — возвращает историю событий по указанному документу, шаблону или черновику
  • GetDocuments (V3) — возвращает список документов, соответствующих заданным параметрам
  • GetDocuments (V4) — возвращает список документов, соответствующих заданным параметрам
  • GetDocumentsByMessageId — возвращает список документов из указанного сообщения
  • GetDocumentTypes (V2) — возвращает список типов документов, доступных в ящике
  • GetDocumentTypes (V3) — возвращает список типов документов, доступных в ящике, и дату перехода на универсальные сообщения
  • MoveDocuments — перемещает документы в указанное подразделение организации
  • Restore — восстанавливает документ из удаленных

Оцените материал страницы

Нашли ошибку или столкнулись с проблемой?

СКБ Контурс 1988 года