GetDocuments

Имя ресурса: /V3/GetDocuments

HTTP метод: GET

Параметры строки запроса:

  • boxId: идентификатор ящика, в котором осуществляется поиск документов;
  • filterCategory: статус, по которому требуется отфильтровать список документов;
  • counteragentBoxId: идентификатор ящика контрагента, по которому требуется дополнительная фильтрация (может отсутствовать, не имеет смысла при фильтрации внутренних документов);
  • toDepartmentId: идентификатор подразделения получателя, по которому требуется дополнительная фильтрация (может отсутствовать, имеет смысл только при фильтрации внутренних документов);
  • timestampFromTicks: метка времени, задающая начальную точку периода, по которому требуется дополнительная фильтрация (может отсутствовать);
  • timestampToTicks: метка времени, задающая конечную точку периода, по которому требуется дополнительная фильтрация (может отсутствовать);
  • fromDocumentDate: дата документа в формате ДД.ММ.ГГГГ, задающая начальную точку периода, по которому требуется дополнительная фильтрация (может отсутствовать);
  • toDocumentDate: дата документа в формате ДД.ММ.ГГГГ, задающая конечную точку периода, по которому требуется дополнительная фильтрация (может отсутствовать);
  • departmentId: идентификатор подразделения, из которого производится выборка документов (может отсутствовать, в этом случае выборка производится из головного подразделения);
  • excludeSubdepartments: если присутствует - исключить из выборки дочерние подразделения;
  • afterIndexKey: уникальный ключ документа, позволяющий итерироваться по всему списку документов, удовлетворяющих фильтру (может отсутствовать);
  • sortDirection: задает порядок сортировки документов в выдаче, принимает одно из значений «Ascending», или «Descending» (может отсутствовать, значение по умолчанию - «Ascending»);
  • count: максимальное количество документов в ответе (может отсутствовать, в этом случае в ответе будет не больше 100 документов). Может принимать значения от 0 до 100.

В запросе должен присутствовать HTTP-заголовок Authorization с необходимыми данными для авторизации.

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

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

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

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

Обязательный параметр filterCategory задается строкой в формате «[DocumentType].[DocumentClass][DocumentStatus]».

Первая часть этой строки задает тип документа и может принимать либо одно из значений перечисления DocumentType, либо одно из специальных значений:

  • AnyInvoiceDocumentType - соответствует набору из четырех типов документов СФ/ИСФ/КСФ/ИКСФ (Invoice, InvoiceRevision, InvoiceCorrection, InvoiceCorrectionRevision),
  • AnyBilateralDocumentType - соответствует любому типу двусторонних документов (Nonformalized, Torg12, AcceptanceCertificate, XmlTorg12, XmlAcceptanceCertificate, TrustConnectionRequest, PriceList, PriceListAgreement, CertificateRegistry, ReconciliationAct, Contract, Torg13),
  • AnyUnilateralDocumentType - соответствует любому типу односторонних документов (ProformaInvoice, ServiceDetails),
  • Any - соответствует любому типу документа.

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

  • Inbound (входящий документ),
  • Outbound (исходящий документ),
  • Internal (внутренний документ)

Строка 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:

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

Возможные HTTP-коды возврата:

  • 200 (OK) - операция успешно завершена;
  • 400 (Bad Request) - данные в запросе имеют неверный формат или отсутствуют обязательные параметры;
  • 401 (Unauthorized) - в запросе отсутствует HTTP-заголовок Authorization, или в этом заголовке содержатся некорректные авторизационные данные;
  • 403 (Forbidden) - доступ к ящику с предоставленным авторизационным токеном запрещен;
  • 405 (Method not allowed) - используется неподходящий HTTP-метод;
  • 500 (Internal server error) - при обработке запроса возникла непредвиденная ошибка.