diff --git a/v2/swagger.yaml b/v2/swagger.yaml index 7571e4c..0a9950c 100644 --- a/v2/swagger.yaml +++ b/v2/swagger.yaml @@ -59,8 +59,22 @@ tags: description: Methods for working with corporate shop. Требуется право доступа shop-usage "Магазин". - name: workflow description: Methods for working with workflow. - - name: kedo - description: Методы для работы с КЭДО. + - name: kedo-document + description: Кадровые документы на подпись + - name: kedo-instance + description: Экземпляры документа (по подписантам) + - name: kedo-sign-request + description: Создание/отмена запроса на подпись + - name: kedo-template + description: Шаблоны документов КЭДО + - name: kedo-enum + description: Справочники КЭДО + - name: mchd + description: МЧД — список и просмотр + - name: mchd-signing + description: МЧД — генерация, подписание, отзыв + - name: mchd-reference + description: МЧД — справочники paths: /mobile/bind/{id}/{token}: @@ -6134,426 +6148,626 @@ paths: 500: description: Server Error - /enum/document-type: + /kedo/document: get: - tags: - - kedo - summary: Тип документа - operationId: /enum/document-type + tags: [kedo-document] + summary: Мои документы (отправленные мной на подпись) + description: | + Список активных документов, где текущий пользователь — инициатор (`user_id`). + operationId: kedoDocumentIndex + parameters: + - $ref: '#/components/parameters/PageParam' + - $ref: '#/components/parameters/PerPageParam' + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/DocumentNameParam' + - $ref: '#/components/parameters/CreatedAtRangeParam' + - $ref: '#/components/parameters/DeadlineAtRangeParam' + - $ref: '#/components/parameters/CancelledAtRangeParam' + - $ref: '#/components/parameters/SignRequestStatusFilterParam' + - $ref: '#/components/parameters/DocumentTypeFilterParam' responses: - 200: - description: OK + '200': + description: Список документов content: application/json: schema: - $ref: '#/components/schemas/typeIdString' - 401: - description: Unauthorized - 403: - description: Unauthorized - 500: - description: Server Error + type: array + items: { $ref: '#/components/schemas/KedoDocument' } + '401': { $ref: '#/components/responses/KedoUnauthorized' } + '403': { $ref: '#/components/responses/KedoDisabled' } - /enum/sign-request-slot-type: + /kedo/document/need-signed: get: - tags: - - kedo - summary: Тип слота - operationId: /enum/sign-request-slot-type + tags: [kedo-document] + summary: Документы, ожидающие моей подписи + operationId: kedoDocumentNeedSigned + parameters: + - $ref: '#/components/parameters/PageParam' + - $ref: '#/components/parameters/PerPageParam' + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/DocumentNameParam' + - $ref: '#/components/parameters/CreatedAtRangeParam' + - $ref: '#/components/parameters/DeadlineAtRangeParam' + - $ref: '#/components/parameters/CancelledAtRangeParam' + - $ref: '#/components/parameters/SignRequestStatusFilterParam' + - $ref: '#/components/parameters/DocumentTypeFilterParam' responses: - 200: - description: OK + '200': + description: Список документов на подпись content: application/json: schema: - $ref: '#/components/schemas/typeIdInteger' - 401: - description: Unauthorized - 403: - description: Unauthorized - 500: - description: Server Error + type: array + items: { $ref: '#/components/schemas/KedoDocument' } - /enum/sign-request-status: + /kedo/document/archive: get: - tags: - - kedo - summary: Статус запроса на подпись документа - operationId: /enum/sign-request-status + tags: [kedo-document] + summary: Архив — уже подписанные мной документы + operationId: kedoDocumentArchive + parameters: + - $ref: '#/components/parameters/PageParam' + - $ref: '#/components/parameters/PerPageParam' + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/DocumentNameParam' + - $ref: '#/components/parameters/CreatedAtRangeParam' + - $ref: '#/components/parameters/DeadlineAtRangeParam' + - $ref: '#/components/parameters/CancelledAtRangeParam' + - $ref: '#/components/parameters/SignRequestStatusFilterParam' + - $ref: '#/components/parameters/DocumentTypeFilterParam' responses: - 200: - description: OK + '200': + description: Архив content: application/json: schema: - $ref: '#/components/schemas/status' - 401: - description: Unauthorized - 403: - description: Unauthorized - 500: - description: Server Error + type: array + items: { $ref: '#/components/schemas/KedoDocument' } - /document/index: + /kedo/document/view: get: - tags: - - kedo - summary: Список запросов на подпись документа для текущего пользователя - operationId: /document/index + tags: [kedo-document] + summary: Просмотр документа по ID + operationId: kedoDocumentView parameters: - name: id in: query - description: Идентификатор запроса на подпись. Можно передать несколько идентификаторов разделенные запятой. - schema: - type: string - format: uuid - example: edee4e11-dab5-4aac-93ac-43c379aab6b2 - - name: created_at - in: query - description: Дата создания - schema: - type: string - example: 2025-01-01|2025-01-01 - - name: deadline_at - in: query - description: Дата дедлайна запроса на подпись - schema: - type: string - example: 2025-01-01|2025-01-01 - - name: cancelled_at - in: query - description: Дата отмены запроса на подпись - schema: - type: string - example: 2025-01-01|2025-01-01 - - name: sign_request_status_id - in: query - description: Статус запроса на подпись. Можно передать несколько идентификаторов разделенные запятой. - schema: - type: string - example: '1' - - name: org_employment_file_type_id - in: query - description: Тип документа. Можно передать несколько идентификаторов разделенные запятой. - schema: - type: string - example: example - responses: - 200: - description: OK - content: - application/json: - schema: - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/kedoDocumentIndex' - _links: - $ref: '#/components/schemas/_links' - _meta: - $ref: '#/components/schemas/_meta' - 400: - description: Bad Request - 401: - description: Unauthorized - 403: - description: Unauthorized - 500: - description: Server Error - - /document/view: - get: - tags: - - kedo - summary: Запрос на подпись документа - operationId: /document/view - parameters: - - name: id - in: query - description: Идентификатор запроса на подпись - schema: - type: string required: true - example: edee4e11-dab5-4aac-93ac-43c379aab6b2 + schema: { type: string, format: uuid } responses: - 200: - description: OK + '200': + description: Документ content: application/json: - schema: - $ref: '#/components/schemas/kedoDocumentView' - 400: - description: Bad Request - 401: - description: Unauthorized - 403: - description: Unauthorized - 404: - description: Not found - 500: - description: Server Error + schema: { $ref: '#/components/schemas/KedoDocument' } + '404': { $ref: '#/components/responses/KedoNotFound' } - /sign-request/create: + /kedo/document/sign: post: - tags: - - kedo - summary: Создание запроса на подпись документа - operationId: /sign-request/create + tags: [kedo-document] + summary: Подписать документ (UNEP — KedoCa) + description: | + Подписание неквалифицированной подписью (УНЭП) через внутренний CA HRBox. + Подпись формируется сервером — в запросе передаётся только ID документа. + + `kedo_instance_ids` опционален: если не передан, подпишутся все экземпляры, + доступные текущему юзеру. Можно передать как массив UUID, так и строку через запятую. + + При подписании по доверенности — передать `mchd_id`. + operationId: kedoDocumentSign requestBody: required: true content: application/json: - schema: - type: array - items: - $ref: '#/components/schemas/kedoSignRequestCreateRequestBody' + schema: { $ref: '#/components/schemas/KedoDocumentSignRequest' } responses: - 200: - description: OK + '200': + description: Результат подписания content: application/json: - schema: - $ref: '#/components/schemas/kedoSignRequestCreateResponse' - 401: - description: Unauthorized - 500: - description: Server Error + schema: { $ref: '#/components/schemas/HttpJsonResult' } + '422': { $ref: '#/components/responses/KedoValidationError' } - /sign-request/cancel: + /kedo/document/sign-ukep: post: - tags: - - kedo - summary: Отмена запроса на подпись документа - operationId: /sign-request/cancel + tags: [kedo-document] + summary: Подписать документ (УКЭП — КриптоПро) + description: | + Подписание квалифицированной подписью. Подпись (CAdES-T detached, base64) + формируется на фронте через КриптоПро Browser Plugin и передаётся в поле `ukep`. + + `kedo_instance_ids` опционален: если не передан, подпишутся все экземпляры, + доступные текущему юзеру. + + При подписании по доверенности — передать `mchd_id`. + operationId: kedoDocumentSignUkep requestBody: required: true content: application/json: - schema: - type: array - items: - $ref: '#/components/schemas/kedoSignRequestCancelRequestBody' + schema: { $ref: '#/components/schemas/KedoDocumentSignUkepRequest' } responses: - 200: - description: OK + '200': + description: Результат подписания content: application/json: - schema: - $ref: '#/components/schemas/kedoSignRequestCancelResponse' - 401: - description: Unauthorized - 403: - description: Forbidden - 404: - description: Not found - 500: - description: Server Error + schema: { $ref: '#/components/schemas/HttpJsonResult' } + '422': { $ref: '#/components/responses/KedoValidationError' } - /instance/index: + /kedo/document/reject: + post: + tags: [kedo-document] + summary: Отклонить подписание документа + operationId: kedoDocumentReject + requestBody: + required: true + content: + application/json: + schema: { $ref: '#/components/schemas/KedoDocumentRejectRequest' } + responses: + '200': + description: Документ отклонён + content: + application/json: + schema: { $ref: '#/components/schemas/HttpJsonResult' } + + /kedo/instance: get: - tags: - - kedo - summary: Список экземпляров на подпись документа - operationId: /instance/index + tags: [kedo-instance] + summary: Экземпляры документа + description: Экземпляры создаются по числу подписантов (по slot-правилам). + operationId: kedoInstanceIndex parameters: - name: kedo_document_id in: query - description: Идентификатор запроса на подпись required: true - schema: - type: string - format: uuid - example: edee4e11-dab5-4aac-93ac-43c379aab6b2 + schema: { type: string, format: uuid } responses: - 200: - description: OK + '200': + description: Список экземпляров content: application/json: schema: - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/kedoInstanceIndex' - _links: - $ref: '#/components/schemas/_links' - _meta: - $ref: '#/components/schemas/_meta' - 400: - description: Bad Request - 401: - description: Unauthorized - 403: - description: Forbidden - 500: - description: Server Error + type: array + items: { $ref: '#/components/schemas/KedoInstance' } - /instance/view: + /kedo/instance/view: get: - tags: - - kedo - summary: Просмотр экземпляра на подпись документа - operationId: /instance/view + tags: [kedo-instance] + summary: Просмотр экземпляра + operationId: kedoInstanceView parameters: - name: id in: query - description: Идентификатор экземпляра required: true - schema: - type: string - format: uuid - example: edee4e11-dab5-4aac-93ac-43c379aab6b2 + schema: { type: string, format: uuid } responses: - 200: - description: OK + '200': + description: Экземпляр content: application/json: - schema: - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/kedoInstanceView' - 400: - description: Bad Request - 401: - description: Unauthorized - 403: - description: Forbidden - 404: - description: Not found - 500: - description: Server Error + schema: { $ref: '#/components/schemas/KedoInstance' } + '403': + description: Нет доступа на просмотр этого экземпляра + '404': { $ref: '#/components/responses/KedoNotFound' } - /instance/sign: - post: - tags: - - kedo - summary: Подписание документа - operationId: /instance/sign - requestBody: - required: true - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/kedoInstanceSignRequestBody' - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/kedoInstanceSignResponse' - 401: - description: Unauthorized - 403: - description: Forbidden - 404: - description: Not found - 500: - description: Server Error - - /instance/reject: - post: - tags: - - kedo - summary: Отклонить подписание документа - operationId: /instance/reject - requestBody: - required: true - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/kedoInstanceRejectRequestBody' - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/kedoInstanceRejectResponse' - 401: - description: Unauthorized - 403: - description: Forbidden - 404: - description: Not found - 500: - description: Server Error - - /instance/download-sign: + /kedo/instance/need-signed: get: - tags: - - kedo - summary: Скачать подпись *.p7s - operationId: /instance/download-sign + tags: [kedo-instance] + summary: Мои экземпляры, ожидающие подписи + operationId: kedoInstanceNeedSigned + parameters: + - name: kedo_document_id + in: query + required: false + description: Опциональный фильтр по документу + schema: { type: string, format: uuid } + responses: + '200': + description: Экземпляры на подпись + content: + application/json: + schema: + type: array + items: { $ref: '#/components/schemas/KedoInstance' } + + /kedo/instance/download-sign: + get: + tags: [kedo-instance] + summary: Скачать файл подписи .p7s + operationId: kedoInstanceDownloadSign parameters: - name: id in: query - description: Идентификатор экземпляра required: true - schema: - type: string - format: uuid - example: edee4e11-dab5-4aac-93ac-43c379aab6b2 + description: ID экземпляра + schema: { type: string, format: uuid } + - name: sign_type + in: query + required: true + schema: { $ref: '#/components/schemas/KedoSignType' } responses: - 200: - description: OK + '200': + description: Файл подписи content: application/pkcs7-signature: schema: type: string format: binary - 400: - description: Bad Request - 401: - description: Unauthorized - 403: - description: Forbidden - 404: - description: Not found - 500: - description: Server Error + '404': + description: Подпись указанного типа не найдена - /instance/stamp: + /kedo/instance/document-with-stamp: get: - tags: - - kedo - summary: Скачать штамп подписи - operationId: /instance/stamp + tags: [kedo-instance] + summary: PDF документ с наложенным штампом подписи + operationId: kedoInstanceDocumentWithStamp parameters: - name: id in: query - description: Идентификатор экземпляра required: true - schema: - type: string - format: uuid - example: edee4e11-dab5-4aac-93ac-43c379aab6b2 + description: ID экземпляра + schema: { type: string, format: uuid } responses: - 200: - description: OK + '200': + description: PDF со штампом content: - image/png: + application/pdf: schema: type: string format: binary - 400: - description: Bad Request - 401: - description: Unauthorized - 404: - description: Not found - 500: - description: Server Error + + /kedo/sign-request/create: + post: + tags: [kedo-sign-request] + summary: Создать запрос на подпись документа + description: | + Создание запроса на подпись. Поддерживается два режима: + + 1. **По файлу** — передать `file_id` уже загруженного PDF + 2. **По шаблону** — передать `template_id` + `field_values` (значения полей), + PDF сгенерируется из шаблона автоматически + + `request_users` задаёт подписантов через механизм UserList: + - `users` — массив условий (slot types) + - `key` — массив ключей UserList (отделы/группы/конкретные юзеры) + operationId: kedoSignRequestCreate + requestBody: + required: true + content: + application/json: + schema: { $ref: '#/components/schemas/KedoSignRequestCreate' } + responses: + '200': + description: Документ создан + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/HttpJsonResult' + - type: object + properties: + data: + $ref: '#/components/schemas/KedoDocument' + '422': { $ref: '#/components/responses/KedoValidationError' } + + /kedo/sign-request/cancel: + post: + tags: [kedo-sign-request] + summary: Отменить запрос на подпись + description: Отменить можно только если `isSignRequestCancelAllowed = true`. + operationId: kedoSignRequestCancel + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [id] + properties: + id: { type: string, format: uuid } + responses: + '200': + description: Результат отмены + content: + application/json: + schema: { $ref: '#/components/schemas/HttpJsonResult' } + '403': + description: Отмена не разрешена + '404': { $ref: '#/components/responses/KedoNotFound' } + + /kedo/template: + get: + tags: [kedo-template] + summary: Список активных шаблонов + operationId: kedoTemplateIndex + responses: + '200': + description: Шаблоны + content: + application/json: + schema: + type: array + items: { $ref: '#/components/schemas/KedoTemplate' } + + /kedo/template/view: + get: + tags: [kedo-template] + summary: Шаблон + автозаполненные значения для текущего юзера + operationId: kedoTemplateView + parameters: + - name: id + in: query + required: true + schema: { type: string, format: uuid } + responses: + '200': + description: Шаблон с autoFillValues + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/KedoTemplate' + - type: object + properties: + autoFillValues: + type: object + additionalProperties: { type: string } + description: 'Маппинг: key поля → предзаполненное значение' + '404': { $ref: '#/components/responses/KedoNotFound' } + + /kedo/template/preview: + post: + tags: [kedo-template] + summary: Предпросмотр PDF из шаблона + description: Генерирует PDF с подставленными значениями, без сохранения. + operationId: kedoTemplatePreview + requestBody: + required: true + content: + application/json: + schema: { $ref: '#/components/schemas/KedoTemplateSubmit' } + responses: + '200': + description: Готовый PDF + content: + application/pdf: + schema: + type: string + format: binary + '422': { $ref: '#/components/responses/KedoValidationError' } + + /kedo/enum/document-type: + get: + tags: [kedo-enum] + summary: Типы документов КЭДО + operationId: kedoEnumDocumentType + responses: + '200': + description: Enum + content: + application/json: + schema: + type: array + items: { $ref: '#/components/schemas/KedoEnumItem' } + + /kedo/enum/sign-request-status: + get: + tags: [kedo-enum] + summary: Статусы запроса на подпись + operationId: kedoEnumSignRequestStatus + responses: + '200': + description: Enum + content: + application/json: + schema: + type: array + items: { $ref: '#/components/schemas/KedoEnumItem' } + + /kedo/enum/sign-request-slot-type: + get: + tags: [kedo-enum] + summary: Типы слотов подписания + operationId: kedoEnumSignRequestSlotType + responses: + '200': + description: Enum + content: + application/json: + schema: + type: array + items: { $ref: '#/components/schemas/KedoEnumItem' } + + /kedo/mchd: + get: + tags: [mchd] + summary: Список МЧД текущего пользователя + description: | + Объединённый список: + - МЧД, созданные пользователем (`is_owner: true`) — все статусы + - МЧД, где он представитель (`is_owner: false`) — по умолчанию только SIGNED + + Дедупликация: если юзер и создал, и является представителем — запись одна с `is_owner: true`. + operationId: mchdIndex + parameters: + - name: status + in: query + schema: { $ref: '#/components/schemas/MchdStatus' } + responses: + '200': + description: Список МЧД + content: + application/json: + schema: + type: array + items: + allOf: + - $ref: '#/components/schemas/MchdRecord' + - type: object + properties: + is_owner: { type: boolean } + + /kedo/mchd/my: + get: + tags: [mchd] + summary: Мои действующие МЧД (для модалки подписания) + description: SIGNED МЧД где я — представитель. + operationId: mchdMy + responses: + '200': + description: Список + content: + application/json: + schema: + type: array + items: { $ref: '#/components/schemas/MchdRecord' } + + /kedo/mchd/{id}: + get: + tags: [mchd] + summary: Получить МЧД по ID + operationId: mchdView + parameters: + - $ref: '#/components/parameters/MchdId' + responses: + '200': + description: МЧД + content: + application/json: + schema: { $ref: '#/components/schemas/MchdRecord' } + '404': { $ref: '#/components/responses/KedoNotFound' } + + /kedo/mchd/batch: + get: + tags: [mchd] + summary: Пакетное получение МЧД по ID (до 50) + operationId: mchdBatch + parameters: + - name: ids + in: query + required: true + schema: { type: string, example: 'uuid1,uuid2' } + responses: + '200': + description: МЧД + content: + application/json: + schema: + type: array + items: { $ref: '#/components/schemas/MchdRecord' } + + /kedo/mchd/org-info: + get: + tags: [mchd-reference] + summary: Реквизиты организации из CA-сертификата + operationId: mchdOrgInfo + responses: + '200': + description: Реквизиты + content: + application/json: + schema: { $ref: '#/components/schemas/OrgInfo' } + + /kedo/mchd/power-codes: + get: + tags: [mchd-reference] + summary: Коды полномочий из классификатора ЕСНСИ + operationId: mchdPowerCodes + responses: + '200': + description: Коды + content: + application/json: + schema: + type: array + items: { $ref: '#/components/schemas/PowerCode' } + + /kedo/mchd/generate: + post: + tags: [mchd-signing] + summary: Сгенерировать XML МЧД + description: | + Генерирует XML в формате EMCHD_1 (кириллические теги, namespace `urn://x-artefacts/EMCHD_1`). + **Даты в формате DD.MM.YYYY.** + + Требует роль `mchd-manage`. + operationId: mchdGenerate + requestBody: + required: true + content: + application/json: + schema: { $ref: '#/components/schemas/MchdGenerateRequest' } + responses: + '200': + description: Сгенерированный XML + content: + application/json: + schema: { $ref: '#/components/schemas/MchdGenerateResponse' } + '422': { $ref: '#/components/responses/KedoValidationError' } + + /kedo/mchd/save: + post: + tags: [mchd-signing] + summary: Сохранить МЧД + description: | + Сохраняет МЧД в БД. Если передан `signature` — статус `SIGNED`, иначе `DRAFT`. + + Требует роль `mchd-manage`. + operationId: mchdSave + requestBody: + required: true + content: + application/json: + schema: { $ref: '#/components/schemas/MchdSaveRequest' } + responses: + '200': + description: Сохранённая МЧД + content: + application/json: + schema: { $ref: '#/components/schemas/MchdRecord' } + + /kedo/mchd/{id}/sign: + post: + tags: [mchd-signing] + summary: Подписать черновик МЧД (DRAFT → SIGNED) + description: | + Принимает detached CAdES-T (base64). Требует роль `mchd-manage`. + operationId: mchdSign + parameters: + - $ref: '#/components/parameters/MchdId' + requestBody: + required: true + content: + application/json: + schema: + type: object + required: [signature] + properties: + signature: + type: string + format: byte + responses: + '200': + description: МЧД подписана + content: + application/json: + schema: { $ref: '#/components/schemas/MchdRecord' } + + /kedo/mchd/{id}/revoke: + post: + tags: [mchd-signing] + summary: Отозвать МЧД + description: 'Статус → REVOKED. Требует роль `mchd-manage`.' + operationId: mchdRevoke + parameters: + - $ref: '#/components/parameters/MchdId' + responses: + '200': + description: МЧД отозвана + content: + application/json: + schema: { $ref: '#/components/schemas/MchdRecord' } /user-note: get: @@ -11088,222 +11302,456 @@ components: # КЭДО --> - kedoDocument: + KedoSignType: + type: integer + enum: [1, 2] + description: | + - `1` UNEP — через KedoCa (внутренний CA) + - `2` UKEP — УКЭП через КриптоПро + + KedoSignRequestStatus: + type: integer + enum: [1, 2, 3, 4] + description: | + - `1` WAIT — ожидает подписи + - `2` CANCELLED — отменён + - `3` SIGNED — подписан + - `4` REQUESTED — запрошен + + KedoSignRequestSlotType: + type: integer + enum: [1, 2, 3] + description: | + - `1` AND — каждый подписывает свой экземпляр + - `2` OR — любой один + - `3` ALL — все обязательно + + KedoTemplateFieldTypeEnum: + type: integer + enum: [1, 2, 3] + description: 'STRING=1, DATE=2, NUMBER=3' + + KedoAutoFillSource: + type: string + enum: + - employee_full_name + - employee_short_name + - employee_position + - employee_department + - organization_name + - org_head_name + - date_today + - employee_tab_number + + MchdStatus: + type: string + enum: [DRAFT, SIGNED, PROCESSING, ACTIVE, REVOKED, EXPIRED, REJECTED] + + KedoEnumItem: type: object properties: id: - description: Идентификатор запроса на подпись + oneOf: + - { type: integer } + - { type: string } + name: { type: string } + + KedoDocument: + type: object + properties: + id: { type: string, format: uuid } + created_at: { type: string, format: date-time } + sign_request_status_id: { $ref: '#/components/schemas/KedoSignRequestStatus' } + org_employment_file_type_id: + type: string + nullable: true + description: Тип кадрового документа (KedoDocumentType) + deadline_at: + type: string + format: date + nullable: true + cancelled_at: + type: string + format: date-time + nullable: true + comment: + type: string + nullable: true + file: + $ref: '#/components/schemas/KedoFileRef' + user: + $ref: '#/components/schemas/KedoUserRef' + description: Инициатор + documentTypeName: + type: string + description: Человеко-читаемое название типа + signRequestStatusName: + type: string + isCurrentUserSigned: { type: boolean } + isCurrentUserCanSign: { type: boolean } + instancesCount: { type: integer } + signedInstancesCount: { type: integer } + currentUserInstance: { $ref: '#/components/schemas/KedoInstance' } + currentUserInstanceCount: { type: integer } + slotsUsersTotalCount: { type: integer } + signedUsersCount: { type: integer } + firstInstance: { $ref: '#/components/schemas/KedoInstance' } + + KedoDocumentSignRequest: + type: object + required: [id] + properties: + id: type: string format: uuid - example: a91fe4d9-b486-4e94-9114-18589aad7c7e - created_at: - description: Дата создания + description: ID документа + sign_type: { $ref: '#/components/schemas/KedoSignType' } + kedo_instance_ids: + description: | + Опционально. Если не передано — подпишутся все доступные текущему юзеру экземпляры. + Можно передать массив UUID или строку UUID через запятую. + oneOf: + - type: array + items: { type: string, format: uuid } + - type: string + example: 'uuid1,uuid2' + mchd_id: type: string - format: 'date-time' - example: 2025-01-01 00:00:00 - sign_request_status_id: - description: Статус запроса на подпись - type: integer - example: 1 - deadline_at: - description: Дедлайн подписания - type: string - format: 'date-time' - example: 2025-01-01 00:00:00 - cancelled_at: - description: Дата отмены запроса на подпись - type: string - format: 'date-time' - example: 2025-01-01 00:00:00 - comment: - description: Комментарий - type: string - example: Текст комментария - org_employment_file_type_id: - description: Тип документа - type: string - example: example - file: - $ref: '#/components/schemas/file' - user: - $ref: '#/components/schemas/userInfo' - isCurrentUserSigned: - description: Текущий пользователь подписал документ - type: boolean - example: true + format: uuid + nullable: true + description: UUID МЧД, если подписываем по доверенности - kedoDocumentIndex: - $ref: '#/components/schemas/kedoDocument' - - kedoDocumentView: - $ref: '#/components/schemas/kedoDocument' - - kedoSignRequestCreateRequestBody: + KedoDocumentSignUkepRequest: type: object + required: [id, sign_type, ukep] + properties: + id: { type: string, format: uuid } + sign_type: { $ref: '#/components/schemas/KedoSignType' } + ukep: + type: string + format: byte + description: Base64 CAdES-T detached подпись + kedo_instance_ids: + description: Опционально. Массив UUID или строка через запятую. + oneOf: + - type: array + items: { type: string, format: uuid } + - type: string + mchd_id: + type: string + format: uuid + nullable: true + + KedoDocumentRejectRequest: + type: object + required: [id, comment] + properties: + id: { type: string, format: uuid } + kedo_instance_ids: + description: Опционально. Массив UUID или строка через запятую. + oneOf: + - type: array + items: { type: string, format: uuid } + - type: string + comment: + type: string + maxLength: 255 + description: Причина отклонения + + KedoInstance: + type: object + properties: + id: { type: string, format: uuid } + kedo_document_id: { type: string, format: uuid } + sign_request_status_id: { $ref: '#/components/schemas/KedoSignRequestStatus' } + isCurrentUserSigned: { type: boolean } + isCurrentUserCanSign: { type: boolean } + isCurrentUserSigner: { type: boolean } + isExistUkep: { type: boolean } + isExistUnep: { type: boolean } + signersCount: { type: integer } + signedCount: { type: integer } + mainSignerUser: { $ref: '#/components/schemas/KedoUserRef' } + mchdIds: + type: array + items: { type: string, format: uuid } + description: МЧД использованные при подписании + kedoDocument: { $ref: '#/components/schemas/KedoDocument' } + signers: + type: array + items: { $ref: '#/components/schemas/KedoUserRef' } + + KedoSignRequestCreate: + type: object + required: [document_type_id, request_users] properties: file_id: - description: Идентификатор файла - required: true type: string format: uuid + description: ID предварительно загруженного PDF (обязателен если нет template_id) + template_id: + type: string + format: uuid + description: ID шаблона (альтернатива file_id) + field_values: + type: object + additionalProperties: true + description: 'Значения полей шаблона {key: value}' document_type_id: - description: Тип документа - required: true - type: number - example: 1 - deadline_at: - description: Дата дедлайна подписания документа type: string - format: 'date-time' - example: 2025-01-01 00:00:00 - comment: - description: Комментарий - type: string - format: 'date-time' - example: Example text + description: Тип документа (KedoDocumentType) + example: employment-contract request_users: - description: Подписанты - required: true + type: object + description: Подписанты через механизм UserList + properties: + users: + type: array + items: { $ref: '#/components/schemas/KedoSignRequestSlotType' } + description: Массив типов слотов (AND/OR/ALL) по количеству групп подписантов + key: + type: array + items: { type: string } + description: Ключи UserList для каждой группы (отделы/юзеры) + deadline_at: + type: string + format: date + nullable: true + description: 'Дедлайн подписания (не в прошлом!)' + comment: + type: string + maxLength: 2000 + nullable: true + slots: type: array - items: - type: object - properties: - users: - description: Идентификаторы слотов из /enum/sign-request-slot-type - type: array - items: - type: integer - example: - - 1 - - 2 - - 3 - key: - description: Идентификаторы user_list_key виджета выбора структуры - type: array - items: - type: string - example: - - 'a83fc7ec-db7c-49b3-b0db-4ad4cba2c69b' - - '5db5ee50-75f9-44f3-bc46-ccfa566563eb' - - 'd968f01a-0151-4685-8104-c496e4e8946b' + items: { type: object } + description: Дополнительные настройки слотов (необязательно) - kedoSignRequestCreateResponse: - $ref: '#/components/schemas/responseObject' - properties: - data: - $ref: '#/components/schemas/kedoDocument' - - kedoSignRequestCancelRequestBody: + KedoTemplate: type: object properties: - id: - description: Идентификатор запроса на подпись - required: true + id: { type: string, format: uuid } + name: { type: string } + status_id: { type: integer } + document_type_id: type: string - format: uuid - - kedoSignRequestCancelResponse: - $ref: '#/components/schemas/responseObject' - - kedoInstanceIndex: - type: object - properties: - id: - description: Идентификатор экземпляра + description: KedoDocumentType + documentTypeName: { type: string } + downloadUrl: type: string - format: uuid - example: 073f11ed-3329-4c95-9966-f25b15846ea2 - kedo_document_id: - description: Идентификатор запроса на подпись - type: string - format: uuid - example: a91fe4d9-b486-4e94-9114-18589aad7c7e - mainSignerUser: - $ref: '#/components/schemas/userInfo' - signersCount: - description: Количество подписантов - type: string - format: integer - example: 5 - signedCount: - description: Количество подписавших - type: string - format: integer - example: 2 - - kedoInstanceView: - type: object - properties: - id: - description: Идентификатор экземпляра - type: string - format: uuid - example: 073f11ed-3329-4c95-9966-f25b15846ea2 - kedo_document_id: - description: Идентификатор запроса на подпись - type: string - format: uuid - example: a91fe4d9-b486-4e94-9114-18589aad7c7e - signersCount: - description: Количество подписантов - type: string - format: integer - example: 5 - signedCount: - description: Количество подписавших - type: string - format: integer - example: 2 - isSigned: - description: Документ подписан + format: uri + description: URL скачивания исходного PDF + isLocalTemplate: type: boolean - example: true - signers: - description: Список подписантов экземпляра + description: Встроенный (не редактируемый) шаблон + fields: type: array - items: - type: object - properties: - user: - $ref: '#/components/schemas/userInfo' - signed_at: - description: Дата подписания - type: string - format: 'date-time' - example: 2025-01-01 00:00:00 - rejected_at: - description: Дата отклонения подписания - type: string - format: 'date-time' - example: 2025-01-01 00:00:00 - kedoDocument: - $ref: '#/components/schemas/kedoDocument' + items: { $ref: '#/components/schemas/KedoTemplateField' } - kedoInstanceSignRequestBody: + KedoTemplateField: type: object properties: - id: - description: Идентификатор экземпляра - required: true + key: type: string - format: uuid - example: 073f11ed-3329-4c95-9966-f25b15846ea2 + description: Имя плейсхолдера в PDF + example: ДатаНачала + label: + type: string + description: Человеко-читаемое название + example: Дата начала + type: { $ref: '#/components/schemas/KedoTemplateFieldTypeEnum' } + required: { type: boolean } + auto_fill: + type: string + nullable: true + description: Источник автозаполнения (KedoAutoFillSource) - kedoInstanceSignResponse: - $ref: '#/components/schemas/responseObject' + KedoTemplateSubmit: + type: object + required: [template_id, field_values] + properties: + template_id: { type: string, format: uuid } + field_values: + type: object + additionalProperties: true + description: 'Значения полей {key: value}. Даты — YYYY-MM-DD.' - kedoInstanceRejectRequestBody: + KedoFileRef: type: object properties: - id: - description: Идентификатор экземпляра - required: true - type: string - format: uuid - example: 073f11ed-3329-4c95-9966-f25b15846ea2 + id: { type: string, format: uuid } + file_type: { type: integer } + ext: { type: string, example: pdf } + name: { type: string } + url: { type: string, format: uri } - kedoInstanceRejectResponse: - $ref: '#/components/schemas/responseObject' + KedoUserRef: + type: object + properties: + id: { type: string, format: uuid } + name: { type: string } + iconUrl: { type: string, format: uri, nullable: true } + + HttpJsonResult: + type: object + description: Стандартный ответ операций КЭДО + properties: + success: { type: boolean } + message: + type: object + properties: + type: { type: string, enum: [success, error, info, warning] } + text: { type: string } + data: + type: object + nullable: true + errors: + type: array + items: { type: string } + + MchdRecord: + type: object + properties: + id: { type: string, format: uuid } + tenant_id: { type: integer } + principal_inn: { type: string, example: '7707083893' } + principal_kpp: { type: string, example: '770701001' } + principal_ogrn: { type: string, example: '1027700132195' } + principal_name: { type: string, example: 'ООО Рога и Копыта' } + representative_inn: { type: string, example: '770312345678' } + representative_snils: { type: string, example: '123-456-789 01' } + representative_name: { type: string, example: 'Иванов Иван Иванович' } + representative_user_id: { type: string, format: uuid, nullable: true } + xml_content: { type: string, description: 'XML EMCHD_1' } + signature: + type: string + format: byte + nullable: true + description: Detached CAdES-T base64 + powers: + type: array + nullable: true + items: { $ref: '#/components/schemas/PowerCode' } + valid_from: { type: string, format: date } + valid_to: { type: string, format: date } + status: { $ref: '#/components/schemas/MchdStatus' } + cprr_status: { type: string, nullable: true } + cprr_operator: { type: string, nullable: true } + cprr_response: { type: object, nullable: true } + created_at: { type: string, format: date-time } + updated_at: { type: string, format: date-time, nullable: true } + revoked_at: { type: string, format: date-time, nullable: true } + + MchdGenerateRequest: + type: object + required: + - principal_inn + - principal_name + - ceo_last_name + - ceo_first_name + - representative_last_name + - representative_first_name + - representative_inn + - valid_from + - valid_to + properties: + principal_name: { type: string } + principal_inn: { type: string, example: '7707083893' } + principal_kpp: { type: string, example: '770701001' } + principal_ogrn: { type: string, example: '1027700132195' } + ceo_last_name: { type: string } + ceo_first_name: { type: string } + ceo_middle_name: { type: string } + ceo_inn: { type: string } + ceo_position: { type: string, example: 'Генеральный директор' } + representative_last_name: { type: string } + representative_first_name: { type: string } + representative_middle_name: { type: string } + representative_inn: { type: string } + representative_snils: { type: string } + representative_user_id: { type: string, format: uuid } + valid_from: { type: string, description: 'DD.MM.YYYY', example: '01.01.2026' } + valid_to: { type: string, description: 'DD.MM.YYYY', example: '01.01.2027' } + powers_text: { type: string } + power_codes: + type: array + items: { $ref: '#/components/schemas/PowerCode' } + + MchdGenerateResponse: + type: object + properties: + id: { type: string, format: uuid } + xml_content: { type: string } + file_name: + type: string + example: ON_EMCHD_20260101_a1b2c3d4-e5f6-7890-abcd-ef1234567890.xml + + MchdSaveRequest: + type: object + required: + - id + - principal_inn + - principal_name + - representative_inn + - representative_name + - xml_content + - valid_from + - valid_to + properties: + id: { type: string, format: uuid, description: 'UUID из ответа /generate' } + principal_inn: { type: string } + principal_kpp: { type: string } + principal_ogrn: { type: string } + principal_name: { type: string } + representative_inn: { type: string } + representative_snils: { type: string } + representative_name: { type: string } + representative_user_id: { type: string, format: uuid } + xml_content: { type: string } + signature: + type: string + format: byte + description: Если передана — SIGNED, иначе DRAFT + powers: + type: array + items: { $ref: '#/components/schemas/PowerCode' } + valid_from: { type: string, description: 'DD.MM.YYYY' } + valid_to: { type: string, description: 'DD.MM.YYYY' } + + OrgInfo: + type: object + properties: + has_cert: { type: boolean } + name: { type: string } + inn: { type: string } + ogrn: { type: string } + + PowerCode: + type: object + properties: + code: { type: string, example: '101' } + name: { type: string, example: 'Подписание кадровых документов' } + + KedoError: + type: object + properties: + name: { type: string } + message: { type: string } + code: { type: integer } + status: { type: integer } + + KedoValidationErrorBody: + allOf: + - $ref: '#/components/schemas/KedoError' + - type: object + properties: + errors: + type: array + items: + type: object + properties: + field: { type: string } + message: { type: string } # КЭДО <-- @@ -11781,6 +12229,87 @@ components: type: string description: Без черновиков + # КЭДО --> + MchdId: + name: id + in: path + required: true + description: UUID МЧД (= НомДовер в XML) + schema: { type: string, format: uuid } + + PageParam: + name: page + in: query + required: false + schema: { type: integer, minimum: 1, default: 1 } + + PerPageParam: + name: per-page + in: query + required: false + schema: { type: integer, minimum: 1, maximum: 20, default: 10 } + + SortParam: + name: sort + in: query + required: false + description: | + Поле сортировки. Префикс `-` — DESC. По умолчанию `-created_at`. + Допустимые: `created_at`, `deadline_at`, `sign_request_status_id`, + `org_employment_file_type_id`, `file.name`, `updated_at`. + schema: + type: string + example: -created_at + + # --- Фильтры для списков KedoDocument (/kedo/document, /need-signed, /archive) --- + DocumentNameParam: + name: document_name + in: query + required: false + description: Поиск по названию файла (ILIKE, без учёта регистра) + schema: { type: string } + + CreatedAtRangeParam: + name: created_at + in: query + required: false + description: | + Дата создания. Одиночное значение или диапазон через `|`. + Пример: `2025-01-01|2025-12-31`. + schema: { type: string } + + DeadlineAtRangeParam: + name: deadline_at + in: query + required: false + description: Дедлайн подписания. Диапазон через `|`. + schema: { type: string } + + CancelledAtRangeParam: + name: cancelled_at + in: query + required: false + description: Дата отмены. Диапазон через `|`. + schema: { type: string } + + SignRequestStatusFilterParam: + name: sign_request_status_id + in: query + required: false + description: Статус запроса на подпись (1=WAIT, 2=CANCELLED, 3=SIGNED, 4=REQUESTED) + schema: + type: integer + enum: [1, 2, 3, 4] + + DocumentTypeFilterParam: + name: org_employment_file_type_id + in: query + required: false + description: | + Тип кадрового документа. Список значений — `GET /kedo/enum/document-type`. + schema: { type: string } + # КЭДО <-- + responses: GoalIndexResponse: 200: @@ -11831,6 +12360,46 @@ components: $ref: '#/components/schemas/GoalItem' description: Цели которые не были обработаны + # КЭДО --> + KedoUnauthorized: + description: Не авторизован + content: + application/json: + schema: { $ref: '#/components/schemas/KedoError' } + example: + name: Unauthorized + message: Your request was made with invalid credentials. + code: 0 + status: 401 + + KedoDisabled: + description: 'КЭДО отключён (feature flag enableKedo = false) или нет нужной роли' + content: + application/json: + schema: { $ref: '#/components/schemas/KedoError' } + example: + name: Forbidden + message: You are not allowed to perform this action. + code: 0 + status: 403 + + KedoNotFound: + description: Не найдено + content: + application/json: + schema: { $ref: '#/components/schemas/KedoError' } + example: + name: Not Found + code: 0 + status: 404 + + KedoValidationError: + description: Ошибка валидации + content: + application/json: + schema: { $ref: '#/components/schemas/KedoValidationErrorBody' } + # КЭДО <-- + security: - SessionAuth: [ ] - ApiKeyAuth: [ ] \ No newline at end of file