GetDocuments

GET /V3/GetDocuments
Query Parameters:
 
  • boxId – идентификатор ящика, в котором осуществляется поиск документов;
  • filterCategory – категория, по которому требуется отфильтровать список документов;
  • counteragentBoxId – идентификатор ящика контрагента, по которому требуется дополнительная фильтрация (может отсутствовать, не имеет смысла при фильтрации внутренних документов);
  • fromDepartmentId – идентификатор подразделения отправителя, по которому требуется дополнительная фильтрация (может отсутствовать, имеет смысл только при фильтрации внутренних документов);
  • toDepartmentId – идентификатор подразделения получателя, по которому требуется дополнительная фильтрация (может отсутствовать, имеет смысл только при фильтрации внутренних документов);
  • 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 – закончилась подписка на API
  • 403 Forbidden – доступ к ящику с предоставленным авторизационным токеном запрещен
  • 404 Not Found – в указанном ящике нет пользователя с указанным идентификатором
  • 405 Method Not Allowed – используется неподходящий HTTP-метод
  • 500 Internal Server Error – при обработке запроса возникла непредвиденная ошибка

В теле ответа содержится список документов из ящика boxId, подходящих под определенный фильтр. Список выдается в виде сериализованной структуры данных DocumentList.

Элементы в списке DocumentList.Documents идут в порядке возрастания меток времени (поля Document.TimestampTicks). В поле DocumentList.TotalCount указывается общее количество документов, удовлетворяющих запросу.

В массиве DocumentList.Documents содержится не более 1000 элементов; для получения остальных документов нужно вызывать метод GetDocuments с теми же параметрами, меняя значение afterIndexKey.

При получении списков документов их содержимое в протобуфер не включается – поле Document.Content.Data у них будет равно NULL. В случае необходимости содержимое документа всегда можно получить при помощи метода GetEntityContent.

Обязательный параметр 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 задает класс документа и может принимать следующие значения:

Возможные варианты <DocumentClass>
Вариант Описание
Inbound Только входящие
Outbound Только исходящие
Internal Только внутренние
Proxy Только документы, переданные через промежуточного получателя

Строка DocumentStatus задает статус документа и может принимать следующие значения:

Возможные варианты <DocumentStatus>
Вариант Описание
Пустое значение Любой документ указанного класса Class
NotRead Документ не прочитан
NoRecipientSignatureRequest Документ без запроса ответной подписи
WaitingForRecipientSignature Документ в ожидании ответной подписи
WithRecipientSignature Документ с ответной подписью
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.

Необязательные параметры timestampFromTicks и timestampToTicks позволяют задать интервал времени, в котором осуществляется поиск.

То есть, если один или оба этих параметра заданы, то метка времени документа (поле Document.CreationTimestampTicks), попадающего в выдачу, будет лежать в интервале [timestampFromTicks, timestampToTicks], включая границы.

Если какой-то из этих параметров отсутствует в запросе, то его значение неявно принимается равным -/+ бесконечности соответственно.

Необязательные параметры fromDocumentDate и toDocumentDate также позволяют задать интервал времени, в котором осуществляется поиск.

Однако при этом фильтрация списка документов производится по дате формирования документа в учетной системе (реквизиту самого документа), а не по метке времени, связанной с загрузкой документа в ящик Диадока.

Если один или оба параметра fromDocumentDate и toDocumentDate заданы, то дата документа (поле Document.DocumentDate), попадающего в выдачу, будет лежать в интервале [fromDocumentDate, toDocumentDate], включая границы.

Если какой-то параметр отсутствует в запросе, то его значение неявно принимается равным +/- бесконечности. В выдачу метода GetDocuments попадают только те документы, у которых заполнен реквизит «Дата документа».

Параметры fromDocumentDate и toDocumentDate задаются в формате ДД.ММ.ГГГГ, то есть представляют собой только даты, а не полноценные метки времени.

Смешивать параметры timestampFromTicks, timestampToTicks и fromDocumentDate, toDocumentDate в одном запросе нельзя - фильтрация производится либо по дате документа, либо по метке времени его загрузки в ящик Диадока.

Ключи Document.IndexKey, полученные при фильтрации по дате документа (при помощи параметров fromDocumentDate и toDocumentDate) и при фильтрации по метке времени (при помощи параметров timestampFromTicks и timestampToTicks), для одного и того же документа могут различаться.

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

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

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