GetDocuments

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

GET /V3/GetDocuments
Query Parameters:

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

  • filterCategory – категория, по которой нужно отфильтровать список документов. Обязательный параметр.

  • counteragentBoxId – идентификатор ящика контрагента, используется для фильтрации. Необязательный параметр, не имеет смысла для внутренних документов.

  • fromDepartmentId – идентификатор подразделения отправителя, используется для фильтрации. Необязательный параметр, имеет смысл только для внутренних документов.

  • toDepartmentId – идентификатор подразделения получателя, используется для фильтрации. Необязательный параметр, имеет смысл только для внутренних документов.

  • documentNumber – номер первичного документа. Необязательный параметр.

  • timestampFromTicks – метка времени, задающая начальную точку периода, по которому требуется фильтрация. Необязательный параметр.

  • timestampToTicks – метка времени, задающая конечную точку периода, по которому требуется фильтрация. Необязательный параметр.

  • fromDocumentDate – дата документа в формате «ДД.ММ.ГГГГ», задающая начальную точку периода, по которому требуется фильтрация. Необязательный параметр.

  • toDocumentDate – дата документа в формате «ДД.ММ.ГГГГ», задающая конечную точку периода, по которому требуется фильтрация. Необязательный параметр.

  • departmentId – идентификатор подразделения, в котором производится поиск документов. Необязательный параметр. Если не указан, поиск производится в головном подразделении.

  • excludeSubdepartments – параметр, указывающий, что из поиска нужно исключить дочерние подразделения организации.

  • afterIndexKey – уникальный ключ, позволяющий итерироваться по списку документов, удовлетворяющих фильтру. Необязательный параметр.

  • sortDirection – параметр, задающий порядок сортировки документов в ответе. Принимает значения Ascending или Descending. Необязательный параметр, по умолчанию равен Ascending.

  • count – максимальное количество документов в ответе. Необязательный параметр, по умолчанию равен 100. Принимает значения от 0 до 100.

Request Headers:
Status Codes:

  • 200 OK – операция успешно завершена.

  • 400 Bad Request – данные в запросе имеют неверный формат или отсутствуют обязательные параметры.

  • 401 Unauthorized – в запросе отсутствует HTTP-заголовок Authorization или в этом заголовке содержатся некорректные авторизационные данные.

  • 402 Payment Required – у организации с указанным идентификатором boxId закончилась подписка на API.

  • 403 Forbidden – доступ к ящику с предоставленным авторизационным токеном запрещен.

  • 404 Not Found – в указанном ящике нет пользователя с указанным идентификатором.

  • 405 Method Not Allowed – используется неподходящий HTTP-метод.

  • 500 Internal Server Error – при обработке запроса возникла непредвиденная ошибка.

Response Body:

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

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

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

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

Содержимое документов не включается в ответ метода, то есть поле Document.Content.Data документов в ответе будет иметь значение null. Вы можете получить содержимое документа с помощью метода GetEntityContent.

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

filterCategory

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

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

  • <TypeNamedId> — строковый идентификатор любого доступного в организации типа документа, подробнее см. поле TypeNamedId. Например: 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 — документ с ошибкой доставки в роуминге.

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

Список DocumentList.Documents может содержать не более 100 элементов. Чтобы получить остальные элементы, вызовите метод GetDocuments с теми же параметрами и с указанием afterIndexKey. В зависимости от значения параметра afterIndexKey метод работает следующим образом:

  • Если в запросе отсутствует параметр afterIndexKey, то метод вернет начало списка документов, удовлетворяющих фильтру.

  • Если в запросе указан параметр afterIndexKey, то возвращенный список начнется с документа, следующего за документа с ключом afterIndexKey; документ с ключом afterIndexKey в этот список не попадает. Ключ документа указан в поле Document.IndexKey.