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