Черновики
Информация о разделе
Страница содержит сценарии использования API для работы с реестром "Черновики".
Общая информация
Сервис предназначенный для работы с реестром "Черновики", направлен на эффективное управление данными. Набор методов API предоставляет возможность интеграторам работать с черновиками документов, учитывая информацию о подразделении сотрудника и правах доступа к данным документам.
При работе с черновиками доступны следующие действия:
- Импорт черновика в систему
- Получить список черновиков
- Получить информацию о черновике
- Прикрепить подпись к черновику
- Старт подписанного черновика
- Обновить Подписанта в черновике и его последующая загрузка
- Удалить черновик
- Обновить информацию в черновике
- Выгрузить файл черновика
- Выгрузить печатную форму черновика
- Получить список измененных черновиков
Импорт черновика в систему
Для загрузки черновика в систему, необходимо вызвать метод [POST]/api/v3/drafts. При успешном выполнении операции метод вернет сведения о загруженном черновике, в модели ImportDraftResult, включая информацию о подразделении пользователя, который выполнил импорт черновика в систему.
В качестве входных параметров необходимо передавать:
- внутренний идентификатор абонента,
- файл черновика для импорта в систему,
- (необязательно) индикатор, показывающий, что черновик доступен только на чтение (по умолчанию значение равно false),
- (необязательно) идентификатор пакета,
- (необязательно) внутренние идентификаторы контрагентов-получателей,
- (необязательно) признак необходимости ответной подписи (данный флаг имеет значение только для НЕформализованного документооборота).
При успешной инициализации запроса, проверяется валидность входных параметров. Если проверка входных параметров не пройдена, то сервер вернет ошибки с текстовым описанием причины в теле ответа (См. таблицу 1).
Таблица 1. Ошибки входных параметров
| Описание ошибки | Причина |
|---|---|
| Пользователь {userId} не имеет доступа к абоненту {abonentId} | Отказано в доступе: некорректно указан abonentId. Аккаунт пользователя не содержит абонента с указанным идентификатором |
| Некорректный формат данных | Переданы некорректные параметры запроса: один или несколько из указанных параметров не соответствуют их формату данных |
(Описание ошибок будет систематически дополняться)
Если все проверки успешно пройдены, то сервер вернет положительный ответ с HTTP-кодом 200 и модель ImportDraftResult, которая будет содержать идентификатор подразделения пользователя, который выполнил импорт черновика в систему.
Получение списка черновиков
Для получения информации о реестре черновиков, необходимо вызвать метод [GET]/api/v1/drafts. При успешном выполнении операции метод вернет список загруженных черновиков в систему, в модели DraftDocumentResultList, включая информацию о подразделении за которым закреплен черновик.
В качестве входных параметров необходимо передавать:
- внутренний идентификатор абонента,
- (необязательно) начальное значение списка,
- (необязательно) количество выводимых значений (по умолчанию: 15),
- (необязательно) поисковый запрос (поиск производится по наименованию документа или наименованию контрагента),
- (необязательно) фильтрация по дате создания (от),
- (необязательно) фильтрация по дате создания (до),
- (необязательно) фильтрация по типам документов:
- типы документов для фильтрации черновиков: Акт, Неформальный ДО, Торг 12, УКД, УПД.
- (необязательно) типы установленных получателей для фильтрации:
- получение списка черновиков, где: присутствуют получатели, отсутствуют получатели, все (значения).
При успешной инициализации запроса, проверяется валидность входных параметров. Если проверка входных параметров не пройдена, то сервер вернет ошибки с текстовым описанием причины в теле ответа (См. таблицу 2).
Таблица 2. Ошибки входных параметров
| Описание ошибки | Причина |
|---|---|
| Пользователь {userId} не имеет доступа к абоненту {abonentId} | Отказано в доступе: некорректно указан abonentId. Аккаунт пользователя не содержит абонента с указанным идентификатором |
| Некорректный формат данных | Переданы некорректные параметры запроса: один или несколько из указанных параметров не соответствуют их формату данных |
(Описание ошибок будет систематически дополняться)
Если все проверки успешно пройдены, то сервер вернет положительный ответ с HTTP-кодом 200 и модель DraftDocumentResultList, которая будет содержать идентификатор подразделения за которым закреплен черновик.
Получение информации о черновике
Для получения информации о черновике, необходимо вызвать метод [GET]/api/v1/drafts/{draftId}. В случае, если у сотрудника ограничен доступ к документу подразделения, к которому принадлежит черновик, тогда система вернет ошибку с информацией об отсутствии доступа. При успешном выполнении операции метод вернет сведения о черновике, в модели DraftDocument, включая информацию о подразделении за которым закреплен черновик.
В качестве входных параметров необходимо передавать:
- внутренний идентификатор абонента,
- идентификатор черновика.
При успешной инициализации запроса, проверяется валидность входных параметров. Если проверка входных параметров не пройдена, то сервер вернет ошибки с текстовым описанием причины в теле ответа (См. таблицу 3).
Таблица 3. Ошибки входных параметров
| Описание ошибки | Причина |
|---|---|
| Пользователь {userId} не имеет доступа к абоненту {abonentId} | Отказано в доступе: некорректно указан abonentId. Аккаунт пользователя не содержит абонента с указанным идентификатором |
| Отсутствует доступ к документу | Отказано в доступе: если у сотрудника нет доступа к документу подразделения |
| Некорректный формат данных | Переданы некорректные параметры запроса: один или несколько из указанных параметров не соответствуют их формату данных |
| Идентификатор черновика не найден | Передан неверный идентификатор черновика |
(Описание ошибок будет систематически дополняться)
Если все проверки успешно пройдены, то сервер вернет положительный ответ с HTTP-кодом 200 и модель DraftDocument, которая будет содержать идентификатор подразделения за которым закреплен черновик.
Прикрепление подписи к черновику
Для прикрепления подписи к черновику, загруженному в систему, необходимо вызвать метод [POST]/api/v2/drafts/{draftId}/sign. В случае, если у сотрудника ограничен доступ к документу подразделения, к которому принадлежит черновик, тогда система вернет ошибку с информацией об отсутствии доступа. При успешном выполнении операции метод: прикрепит подпись к черновику и вернет результат выполнения действия, в модели AttachSignatureResult.
В качестве входных параметров необходимо передавать:
- внутренний идентификатор абонента,
- идентификатор черновика,
- файл подписи черновика,
- (необязательно) номер доверенности (если подпись выдана на физическое лицо, дополнительно необходимо передать номер доверенности. При получении файла подписи, система выполнит проверку данной подписи, и если сертификат выдан на физическое лицо, то потребуется номер доверенности для успешного прикрепления подписи к черновику. Система выполнит проверку доверенности и в случае невалидной доверенности, вернет ошибку).
При успешной инициализации запроса, проверяется валидность входных параметров. Если проверка входных параметров не пройдена, то сервер вернет ошибки с текстовым описанием причины в теле ответа (См. таблицу 4).
Таблица 4. Ошибки входных параметров
| Описание ошибки | Причина |
|---|---|
| Пользователь {userId} не имеет доступа к абоненту {abonentId} | Отказано в доступе: некорректно указан abonentId. Аккаунт пользователя не содержит абонента с указанным идентификатором |
| Сотрудник без права подписи | Отказано в доступе: сотрудник без права подписи |
| Отсутствует доступ к документу | Отказано в доступе: если у сотрудника нет доступа к документу подразделения |
| Некорректный формат данных | Переданы некорректные параметры запроса: один или несколько из указанных параметров не соответствуют их формату данных |
| Идентификатор черновика не найден | Передан неверный идентификатор черновика |
| Отсутствует подпись | Ошибка прикрепления подписи: не передан файл подписи |
| Не передан номер МЧД для подписания документа | По сертификату для подписания документа необходим номер МЧД |
| Доверенность не входит в состав используемых доверенностей | Используемая для подписания МЧД не входит в состав МЧД, которые сотрудник отметил, как используемые |
| Истек срок действия доверенности: {Наименование организации}, номер: {Номер доверенности}, срок действия: {Срок действия до}, полномочия: {Полномочия} | Используемая для подписания МЧД просрочена |
| Доверенность аннулирована. Обратитесь к руководителю, выдавшему доверенность | Используемая для подписания МЧД аннулирована |
(Описание ошибок будет систематически дополняться)
Если все проверки успешно пройдены, то сервер вернет положительный ответ с HTTP-кодом 200 и модель AttachSignatureResult, которая будет содержать результат прикрепления подписи к черновику.
Старт подписанного черновика
Для отправки подписанного черновика, с целью начать документооборот, необходимо вызвать метод [POST]/api/v2/drafts/{draftId}/dispatch. В случае, если у сотрудника ограничен доступ к документу подразделения, к которому принадлежит черновик, тогда система вернет ошибку с информацией об отсутствии доступа. Метод при успешном выполнении операции: отправит подписанный черновик и вернет информацию по документообороту и получателю, в модели StartedDocflow.
Примечание В ответе вернется список идентификаторов документооборота и получателей, в случае если черновик содержал несколько получателей.
В качестве входных параметров необходимо передавать:
- внутренний идентификатор абонента,
- идентификатор черновика.
При успешной инициализации запроса, проверяется валидность входных параметров. Если проверка входных параметров не пройдена, то сервер вернет ошибки с текстовым описанием причины в теле ответа (См. таблицу 5).
Таблица 5. Ошибки входных параметров
| Описание ошибки | Причина |
|---|---|
| Пользователь {userId} не имеет доступа к абоненту {abonentId} | Отказано в доступе: некорректно указан abonentId. Аккаунт пользователя не содержит абонента с указанным идентификатором |
| Сотрудник без права подписи | Отказано в доступе: сотрудник без права подписи |
| Отсутствует доступ к документу | Отказано в доступе: если у сотрудника нет доступа к документу подразделения |
| Некорректный формат данных | Переданы некорректные параметры запроса: один или несколько из указанных параметров не соответствуют их формату данных |
| Идентификатор черновика не найден | Передан неверный идентификатор черновика |
| Ошибка отправки документа. Нет подписи | Ошибка отправки документа: отсутствует подпись у черновика |
(Описание ошибок будет систематически дополняться)
Если все проверки успешно пройдены, то сервер вернет положительный ответ с HTTP-кодом 200 и модель StartedDocflow, которая будет содержать список идентификаторов документооборота и получателей.
Обновление Подписанта в черновике и его последующая загрузка
Для обновления подписанта в черновике, необходимо вызвать метод [POST]/api/v2/drafts/{draftId}/UpdateSigner. В случае, если у сотрудника ограничен доступ к документу подразделения, к которому принадлежит черновик, тогда система вернет ошибку с информацией об отсутствии доступа. Метод при успешном выполнении операции вернет файл черновика, с обновленными сведениями о подписанте.
В качестве входных параметров необходимо передавать:
- внутренний идентификатор абонента,
- идентификатор черновика,
- (необязательно) номер доверенности (МЧД) (если подпись выдана на физическое лицо, дополнительно необходимо передать номер доверенности. При получении файла подписи, система выполнит проверку данной подписи, и если сертификат выдан на физическое лицо, то потребуется номер доверенности для успешного прикрепления подписи к черновику. Система выполнит проверку доверенности и в случае невалидной доверенности, вернет ошибку).
При успешной инициализации запроса, проверяется валидность входных параметров. Если проверка входных параметров не пройдена, то сервер вернет ошибки с текстовым описанием причины в теле ответа (См. таблицу 6).
Таблица 6. Ошибки входных параметров
| Описание ошибки | Причина |
|---|---|
| Пользователь {userId} не имеет доступа к абоненту {abonentId} | Отказано в доступе: некорректно указан abonentId. Аккаунт пользователя не содержит абонента с указанным идентификатором |
| Отсутствует доступ к документу | Отказано в доступе: если у сотрудника нет доступа к документу подразделения |
| Некорректный формат данных | Переданы некорректные параметры запроса: один или несколько из указанных параметров не соответствуют их формату данных |
| Идентификатор черновика не найден | Передан неверный идентификатор черновика |
| Не передан номер МЧД для подписания документа | По сертификату для подписания документа необходим номер МЧД |
| Доверенность не входит в состав используемых доверенностей | Используемая для подписания МЧД не входит в состав МЧД, которые сотрудник отметил, как используемые |
| Истек срок действия доверенности: {Наименование организации}, номер: {Номер доверенности}, срок действия: {Срок действия до}, полномочия: {Полномочия} | Используемая для подписания МЧД просрочена |
| Доверенность аннулирована. Обратитесь к руководителю, выдавшему доверенность | Используемая для подписания МЧД аннулирована |
(Описание ошибок будет систематически дополняться)
Если все проверки успешно пройдены, то сервер вернет положительный ответ с HTTP-кодом 200 и обновленный файл черновика, с измененными сведениями о подписанте.
Удаление черновика
Для удаления черновика, необходимо вызвать метод [DELETE]/api/v1/drafts/{draftId}. В случае, если у сотрудника ограничен доступ к документу подразделения, к которому принадлежит черновик, тогда система вернет ошибку с информацией об отсутствии доступа. Метод при успешном выполнении операции - удалит черновик.
В качестве входных параметров необходимо передавать:
- внутренний идентификатор абонента,
- идентификатор черновика.
При успешной инициализации запроса, проверяется валидность входных параметров. Если проверка входных параметров не пройдена, то сервер вернет ошибки с текстовым описанием причины в теле ответа (См. таблицу 7).
Таблица 7. Ошибки входных параметров
| Описание ошибки | Причина |
|---|---|
| Пользователь {userId} не имеет доступа к абоненту {abonentId} | Отказано в доступе: некорректно указан abonentId. Аккаунт пользователя не содержит абонента с указанным идентификатором |
| Отсутствует доступ к документу | Отказано в доступе: если у сотрудника нет доступа к документу подразделения |
| Некорректный формат данных | Переданы некорректные параметры запроса: один или несколько из указанных параметров не соответствуют их формату данных |
| Идентификатор черновика не найден | Передан неверный идентификатор черновика |
(Описание ошибок будет систематически дополняться)
Если все проверки успешно пройдены, то сервер вернет положительный ответ с HTTP-кодом 200 и с информацией о том, что черновик успешно удален.
Обновление информации в черновике
Для обновление информации в черновике, необходимо вызвать метод [PUT]/api/v1/drafts/{draftId}/metadata. В случае, если у сотрудника ограничен доступ к документу подразделения, к которому принадлежит черновик, тогда система вернет ошибку с информацией об отсутствии доступа. Метод при успешном выполнении операции - обновит информацию в черновике (при необходимости с последующей отправкой документа).
В качестве входных параметров необходимо передавать:
- внутренний идентификатор абонента,
- идентификатор черновика,
- список идентификаторов контрагентов-получателей, которым необходимо отправить документ,
- (необязательно) признак необходимости ответной подписи,
- данный флаг имеет значение только для НЕформализованного документооборота.
- (необязательно) признак того, что после обновления данных в черновике, его сразу же следует отправить.
При успешной инициализации запроса, проверяется валидность входных параметров. Если проверка входных параметров не пройдена, то сервер вернет ошибки с текстовым описанием причины в теле ответа (См. таблицу 8).
Таблица 8. Ошибки входных параметров
| Описание ошибки | Причина |
|---|---|
| Пользователь {userId} не имеет доступа к абоненту {abonentId} | Отказано в доступе: некорректно указан abonentId. Аккаунт пользователя не содержит абонента с указанным идентификатором |
| Отсутствует доступ к документу | Отказано в доступе: если у сотрудника нет доступа к документу подразделения |
| Некорректный формат данных | Переданы некорректные параметры запроса: один или несколько из указанных параметров не соответствуют их формату данных |
| Идентификатор черновика не найден | Передан неверный идентификатор черновика |
| Контрагент не привязан к абоненту {abonentId} | Указанный контрагент не привязан к abonentId |
| Идентификатор контрагента не найден | Передан неверный идентификатор контрагента |
(Описание ошибок будет систематически дополняться)
Если все проверки успешно пройдены, то сервер вернет положительный ответ с HTTP-кодом 200 и с информацией о том, что данные черновика успешно обновлены (в случае отправки, также будет сообщение об успешном запуске ДО).
Выгрузка файла черновика
Для выгрузки файла черновика, необходимо вызвать метод [GET]/api/v1/drafts/{draftId}/file. В случае, если у сотрудника ограничен доступ к документу подразделения, к которому принадлежит черновик, тогда система вернет ошибку с информацией об отсутствии доступа. Метод при успешном выполнении операции вернет файла черновика.
В качестве входных параметров необходимо передавать:
- внутренний идентификатор абонента,
- идентификатор черновика.
При успешной инициализации запроса, проверяется валидность входных параметров. Если проверка входных параметров не пройдена, то сервер вернет ошибки с текстовым описанием причины в теле ответа (См. таблицу 9).
Таблица 9. Ошибки входных параметров
| Описание ошибки | Причина |
|---|---|
| Пользователь {userId} не имеет доступа к абоненту {abonentId} | Отказано в доступе: некорректно указан abonentId. Аккаунт пользователя не содержит абонента с указанным идентификатором |
| Отсутствует доступ к документу | Отказано в доступе: если у сотрудника нет доступа к документу подразделения |
| Некорректный формат данных | Переданы некорректные параметры запроса: один или несколько из указанных параметров не соответствуют их формату данных |
| Идентификатор черновика не найден | Передан неверный идентификатор черновика |
(Описание ошибок будет систематически дополняться)
Если все проверки успешно пройдены, то сервер вернет положительный ответ с HTTP-кодом 200 и файл черновика.
Выгрузка печатной формы черновика
Для выгрузки печатной формы черновика, необходимо вызвать метод [GET]/api/v1/drafts/{draftId}/visualization. В случае, если у сотрудника ограничен доступ к документу подразделения, к которому принадлежит черновик, тогда система вернет ошибку с информацией об отсутствии доступа. Метод при успешном выполнении операции в ответе вернет файл черновика, в формате pdf.
В качестве входных параметров необходимо передавать:
- внутренний идентификатор абонента,
- идентификатор черновика.
При успешной инициализации запроса, проверяется валидность входных параметров. Если проверка входных параметров не пройдена, то сервер вернет ошибки с текстовым описанием причины в теле ответа (См. таблицу 10).
Таблица 10. Ошибки входных параметров
| Описание ошибки | Причина |
|---|---|
| Пользователь {userId} не имеет доступа к абоненту {abonentId} | Отказано в доступе: некорректно указан abonentId. Аккаунт пользователя не содержит абонента с указанным идентификатором |
| Отсутствует доступ к документу | Отказано в доступе: если у сотрудника нет доступа к документу подразделения |
| Некорректный формат данных | Переданы некорректные параметры запроса: один или несколько из указанных параметров не соответствуют их формату данных |
| Идентификатор черновика не найден | Передан неверный идентификатор черновика |
(Описание ошибок будет систематически дополняться)
Если все проверки успешно пройдены, то сервер вернет положительный ответ с HTTP-кодом 200 и файл черновика (в формате pdf).
Получение списка измененных черновиков
Для получения списка измененных черновиков, необходимо вызвать метод [GET]/api/v1/drafts/newEvents. Метод при успешном выполнении операции - возвращает список идентификаторов измененных черновиков, к которым есть доступ у сотрудника.
В качестве входных параметров необходимо передавать:
- внутренний идентификатор абонента,
- (необязательно) дата, с которой необходимо сформировать список идентификаторов, где произошли изменения,
- (необязательно) максимальное количество записей в ответе
- максимальное количество (до 1000 включительно).
При успешной инициализации запроса, проверяется валидность входных параметров. Если проверка входных параметров не пройдена, то сервер вернет ошибки с текстовым описанием причины в теле ответа (См. таблицу 11).
Таблица 11. Ошибки входных параметров
| Описание ошибки | Причина |
|---|---|
| Пользователь {userId} не имеет доступа к абоненту {abonentId} | Отказано в доступе: некорректно указан abonentId. Аккаунт пользователя не содержит абонента с указанным идентификатором |
| Некорректный формат данных | Переданы некорректные параметры запроса: один или несколько из указанных параметров не соответствуют их формату данных |
(Описание ошибок будет систематически дополняться)
Если все проверки успешно пройдены, то сервер вернет положительный ответ с HTTP-кодом 200 и модель DraftChangeInfoChangesListResult, которая будет содержать список черновиков, по которым были внесены изменения.