GetDocuments

GetDocuments

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

HTTP метод: GET

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

• boxId: идентификатор ящика, в котором осуществляется поиск документов;

• filterCategory: статус, по которому требуется отфильтровать список документов;

• counteragentBoxId: идентификатор ящика контрагента, по которому требуется дополнительная фильтрация (может отсутствовать, не имеет смысла при фильтрации внутренних документов);

• toDepartmentId: идентификатор подразделения получателя, по которому требуется дополнительная фильтрация (может отсутствовать, имеет смысл только при фильтрации внутренних документов);

• timestampFromTicks: метка времени, задающая начальную точку периода, по которому требуется дополнительная фильтрация (может отсутствовать);

• timestampToTicks: метка времени, задающая конечную точку периода, по которому требуется дополнительная фильтрация (может отсутствовать);

• fromDocumentDate: дата документа в формате ДД.ММ.ГГГГ, задающая начальную точку периода, по которому требуется дополнительная фильтрация (может отсутствовать);

• toDocumentDate: дата документа в формате ДД.ММ.ГГГГ, задающая конечную точку периода, по которому требуется дополнительная фильтрация (может отсутствовать);

• departmentId: идентификатор подразделения, из которого производится выборка документов (может отсутствовать, в этом случае выборка производится из головного подразделения);

• excludeSubdepartments: если присутствует - исключить из выборки дочерние подразделения;

• afterIndexKey: уникальный ключ документа, позволяющий итерироваться по всему списку документов, удовлетворяющих фильтру (может отсутствовать);

• sortDirection: задает порядок сортировки документов в выдаче, принимает одно из значений "Ascending", или "Descending" (может отсутствовать, значение по умолчанию - "Ascending");

В запросе должен присутствовать 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)
• NoRecipientSignatureRequest (документ без запроса ответной подписи)
• WaitingForRecipientSignature (документ в ожидании ответной подписи)
• WithRecipientSignature (документ с ответной подписью)
• RecipientSignatureRequestRejected (документ с отказом от формирования ответной подписи)
• WaitingForSenderSignature (документ, требующий подписания и отправки)
• InvalidSenderSignature (документ с невалидной подписью отправителя, требующий повторного подписания и отправки)
• Approved (согласованный документ)
• Disapproved (документ с отказом согласования)
• WaitingForResolution (документ, находящийся на согласовании или подписи)
• SignatureRequestRejected (документ с отказом в запросе подписи сотруднику)
• Finished (документ с завершенным документооборотом)
• NotFinished (документ с незавершенным документооборотом)
• InvoiceAmendmentRequested (имеет смысл только для счетов-фактур; документ, по которому было запрошено уточнение)
• RevocationIsRequestedByMe (документ, по которому было запрошено аннулирование)
• RequestsMyRevocation (документ, по которому контрагент запросил аннулирование)
• RevocationAccepted (аннулированный документ)
• RevocationRejected (документ, запрос на аннулирование которого был отклонен)
• NotRevoked (неаннулированный документ)

Примеры строки filterCategory:

• AnyUnilateralDocumentType.InboundNotRevoked (все входящие односторонние неаннулированные документы).
• XmlTorg12.OutboundWithRecipientSignature (все исходящие формализованные ТОРГ-12, подписанные контрагентом).
• InvoiceCorrection.OutboundInvoiceAmendmentRequested (все исходящие КСФ, по которым контрагент запросил уточнение).

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

Необязательные параметры timestampFromTicks и timestampToTicks позволяют задать интервал времени, в котором осуществляется поиск. То есть, если один или оба этих параметра заданы, то метка времени документа (поле Document.TimestampTicks), попадающего в выдачу, будет лежать в интервале [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) - при обработке запроса возникла непредвиденная ошибка.