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: - 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 – при обработке запроса возникла непредвиденная ошибка
В теле ответа содержится список документов из ящика boxId, подходящих под определенный фильтр. Список выдается в виде сериализованной структуры данных DocumentList.
Элементы в списке DocumentList.Documents идут в порядке возрастания меток времени (поля Document.TimestampTicks). В поле DocumentList.TotalCount указывается общее количество документов, удовлетворяющих запросу.
В массиве DocumentList.Documents содержится не более 100 элементов; для получения остальных документов нужно вызывать метод GetDocuments с теми же параметрами, меняя значение afterIndexKey.
При получении списков документов их содержимое в протобуфер не включается – поле Document.Content.Data у них будет равно NULL. В случае необходимости содержимое документа всегда можно получить при помощи метода GetEntityContent.
Обязательный параметр filterCategory задается строкой в формате <DocumentType>.<DocumentClass><DocumentStatus>
.
Первая часть этой строки задает тип документа и может следующие значения:
Вариант | Описание | Примечание |
---|---|---|
<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 задает статус документа и может принимать следующие значения:
Вариант | Описание |
---|---|
Пустое значение | Любой документ указанного класса 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 в выдачу при этом не попадает. Если данный параметр в запросе отсутствует, то выдается начало списка документов, удовлетворяющих фильтру.