Входящие и исходящие документы
Информация о разделе
Страница содержит сценарии использования API для обработки исходящих и входящих документов
Общая информация
Набор методов в контроллере Docflows Actions API позволяет интегратору обработать исходящий/входящий документ на любом этапе документооборота. Чтобы просмотреть список документов или получить информацию по каждому, можно воспользоваться набором методов в контроллере Docflows API
Обработка исходящего документооборота
После подписания и отправки документа получателю для него запускается исходящий документооборот. Для подписания и отправки документа можно воспользоваться группой методов для работы с черновиками в контроллере Drafts API.
Документооборот можно создать без предварительного импорта документа в систему, для этого можно воспользоваться методом [POST]/api/v2/docflows. Чтобы документооборот успешно был создан, в обязательном порядке необходимо передать следующие входные параметры:
- в заголовке запроса передать параметр abonentId, в значении которого указать идентификатор абонента в системы, для которого создается документооборот,
- в теле запроса передать:Дополнительные параметры опциональны.
- параметр DocumentFile, в значении которого передаем файл документа, который необходимо отправить;
- параметр SignDocumentFile, в значении которого передаем файл подписи к этому документу (подпись должна быть открепленная).
Для получения списка исходящих документов необходимо использовать метод [GET]/api/v2/docflows/outgoing В теле ответа вернется модель DocflowSummaryResultList содержащая массив исходящих документов, где помимо основной информации будет возвращаться текущий статус документа. Статусная модель исходящего документа, в зависимости от его типа, показана на рисунке 1. Смена статусов происходит в зависимости от поступившего от контрагента/оператора служебного документа.
Обработка входящего документооборота
При поступлении входящего документа (титула продавца) ему присваивается статус "NeedToSignReceiptConfirmation" (Требуется подписать ИОП). Статусная модель входящего документа, в зависимости от его типа, показана на рисунке 2.
Чтобы понять какое действие необходимо совершить с текущим документом, необходимо вызвать метод [GET]/api/v1/docflows/{docflowId}/actions, который по запрошенному идентификатору документооборота вернет список доступных для него действий. Доступное действие зависит от типа документа, текущего статуса и состояния служебного документа в системе, который формируется для исходящего/входящего документа (находится ли служебный документ на этапе формирования или подписания). После получения успешного ответа необходимо вызвать метод для создания соответствующего действия над документом.
Для документа в статусе "NeedToSignReceiptConfirmation" (Требуется подписать ИОП) необходимо сформировать ИОП: подтвердить получение документа. Для этого создайте файл действия над документооборотом с помощью метода [PATCH]/api/v2/docflows/{docflowId}, где в параметре action передайте значение полученное в методе [GET]/api/v1/docflows/{docflowId}/actions: SignAutomaticTransactions (Сформировать и подписать автоматическую служебную транзакцию: ИОП)
В HTTP заголовках метода, в content-disposition, вернется идентификатор документа действия над ДО в параметре filename. В теле ответа вернется файл, который необходимо скачать и подписать открепленной подписью.
После создания файла подписи необходимо прикрепить его к документу с помощью метода [POST]/api/v2/docflows/AttachActionSign/{documentId}, передав в теле запроса в параметре documentSign. При этом необходимо указать идентификатор документа действия над ДО в параметре documentId (значение полученное с помощью метода [PATCH]/api/v2/docflows/{docflowId} в параметре filename). После успешного прикрепления подписи, входящий документооборот перейдет:
- в статус "Completed" (Завершен), если было подтверждено получение одностороннего документа:
- УПД с функцией СЧФ,
- УКД с функцией КСЧФ,
- неформализованный документ (без запроса ответной подписи),
- в статус "ResponseSignatureRequired" (Требуется ответная подпись), если было подтверждено получение двухстороннего документа:
- УПД с функцией СЧФДОП и ДОП,
- УКД с функцией КСЧФДИС и ДИС,
- Акт выполненных работ (документ о передаче результатов работ (документ об оказании услуг),
- Торг-12 (документ о передаче товаров при торговых операциях),
- неформализованный документ (с запросом ответной подписи).
Для подписания входящего документа ответной подписью, необходимо вызвать метод [PATCH]/api/v2/docflows/{docflowId}, где в параметре action передать значение Sign. В результате будет создан файл действия над входящим документом:
- для формализованного двухстороннего документа - титул покупателя;
- для неформализованного документа - уведомление о принятии.
Для данных служебных документов необходимо создать файл подписи и прикрепить его к документу также с помощью метода [POST]/api/v2/docflows/AttachActionSign/{documentId}. После успешного прикрепления подписи документ перейдет в статус "Completed".
Для отклонения входящего документа с помощью метода [PATCH]/api/v2/docflows/{docflowId} передается значение Reject в параметре action и далее прикрепляется подпись к ранее сформировавшемуся уведомлению об уточнении методом [POST]/api/v2/docflows/AttachActionSign/{documentId}. В результате документ перейдет в статус "Rejected" (Отклонен).
Инициирование аннулирования документа
Запрос на аннулирование можно отправить для исходящего/входящего документа в статусе Completed (Завершен) и для исходящего документа в статусе:
- AwaitingRecipient Response (Ожидается ответ от получателя),
- WaitingReceipt Confirmation (Ожидается извещение о получении),
- WaitingResponse Signature (Ожидается ответная подпись).
Чтобы сформировать предложение об аннулировании необходимо вызвать метод [PATCH]/api/v2/docflows/{docflowId}, где в параметре action передать значение RequestCancellation. В результате необходимо подписать данный файл и прикрепить подпись с помощью метода [POST]/api/v2/docflows/AttachActionSign/{documentId}, как ранее уже описывалось. После успешного прикрепления подписи и последующей отправки предложения об аннулировании получателю, документ перейдет в статус "WaitingCancellationResponse" (Ожидается аннулирование). Статусная модель при инициировании аннулирования документа показана на рисунке 3.
Далее, в зависимости от поступившего ответа на предложение об аннулировании, документ перейдет в статус:
- Cancelled (Аннулирован), если получено согласие на предложение об аннулировании документа,
и
- Completed (Завершен),
- AwaitingRecipientResponse (Ожидается ответ от получателя),
- WaitingReceiptConfirmation (Ожидается извещение о получении),
- WaitingResponseSignature (Ожидается ответная подпись), если получен отказ на предложение об аннулировании документа.
Обработка запроса на аннулирование документа
Запрос на аннулирование документа может поступить для исходящего/входящего документа в статусе "Completed" (Завершен) или для входящего документа в статусе:
- NeedToSignReceiptConfirmation (Требуется подписать ИОП),
- ResponseSignatureRequired (Требуется ответная подпись). В этом случае документ перейдет в статус "CancellationResponseRequired" (Требуется аннулирование).
Для того, чтобы сформировать согласие с аннулированием, необходимо с помощью метода [PATCH]/api/v2/docflows/{docflowId}в параметре action передать значение AcceptCancellation. Для вернувшего в ответе документа создать подпись и прикрепить её с помощью метода [POST]/api/v2/docflows/AttachActionSign/{documentId}, как ранее уже описывалось. После успешного прикрепления подписи и последующей отправки согласия с аннулированием, документ перейдет в статус "Cancelled" (Аннулирован). Статусная модель при получении запроса на аннулирование документа показана на рисунке 4.
Если же необходимо отказать в аннулирования документа, необходимо воспользоваться методами, описанным в предыдущем абзаце, но при вызове метода [PATCH]/api/v2/docflows/{docflowId} в параметре action передать значение RejectCancellation. В результате документ вернется в один из предыдущих статусов, который был выставлен до получения предложения об аннулировании:
- Completed (Завершен),
- NeedToSignReceiptConfirmation (Требуется подписать ИОП),
- ResponseSignatureRequired (Требуется ответная подпись).
Лента событий
Состояние исходящего/входящего документа может измениться в следующих случаях:
- при создании исходящего документа;
- при поступлении в систему входящего документа;
- когда меняется статус исходящего/входящего документа;
- при смене подразделения владельца документа (сотрудника отправившего документ).
Отслеживать изменения с исходящим/входящим документом можно с помощью ленты событий - для этого используйте метод [GET]/api/v1/docflows/newEvents. Этот метод возвращает хронологически упорядоченный список идентификаторов документов, с которыми произошли изменения и дату этого изменения. Метод может фильтровать изменения по дате и подразделению, в котором лежат запрашиваемые документы.
Справочная информация, термины
- ИОП - извещение о получении
- УОУ - уведомление об уточнении
- ПОА - предложение об аннулировании