Перейти к основному содержимому

Создать группу

POST 
/api/v1/clients/:clientId/documentGroups

Описание метода​

Создаёт группу из одного или нескольких документов. Один документ — это группа из одного элемента, поэтому массив documents[] должен содержать хотя бы один документ. Вызывать метод может сотрудник с ролью «Кадровик».

Сервер возвращает созданную группу с присвоенными идентификаторами. Конвертация исходных файлов в PDF/A выполняется асинхронно: статус готовности группы проверяйте отдельным запросом.

Возможные ошибки: 400 — невалидное тело запроса, 401 — нет или невалидный токен, 403 — недостаточно прав, 429 — превышен rate limitlimit Параметр пагинации — количество элементов в ответе. Значение по умолчанию — 50 (для отдельных эндпоинтов может отличаться)..

Парные поля «внутренний ID» / «внешний ID»​

Для каждой пары допустимо передать только одно значение. Если переданы оба, приоритет — у внутреннего IDid Внутренний идентификатор сущности в формате UUID, генерируемый HRlink при создании. Неизменяемый, используется во всех внутренних операциях. HRlink.

  • creatorId и creatorExternalId — кадровик-создатель документа. Заполните, чтобы создателем стал указанный пользователь клиента, а не владелец токена.
  • documents[].legalEntityId и documents[].legalEntityExternalId — юрлицо документа.
  • documents[].headManagerId и documents[].headManagerExternalId — руководитель-подписант.
  • documents[].employeeIds и documents[].employeeExternalIds — сотрудники-подписанты.
  • documents[].watcherIds и documents[].watcherExternalIds — наблюдатели. Наблюдатели не подписывают документ, но получают уведомление о подписании руководителем и могут скачать архив с подписью.
  • documents[].participants[].employeeId и documents[].participants[].employeeExternalId — участники этапов маршрута подписания.
  • documents[].routeTemplateId и documents[].routeTemplateExternalId — шаблон маршрута подписания.
  • documents[].sourceDocumentId и documents[].sourceDocumentExternalId — документ-источник.

Парные поля несовместимы с documents[].fileId: при одновременной передаче запрос завершится ошибкой. fileId получите заранее через метод загрузки файла. Допустимые форматы: .pdf, .doc, .docx, .rtf, .xls, .xlsx, .jpeg, .jpg, .bmp, .png, .tiff.

documents[].externalId — идентификатор документа во внешней системе. Тип — строка, ограничений на длину нет. Используйте, чтобы в других методах обращаться к документу по внешнему IDexternalId Внешний идентификатор сущности — произвольная строка, задаваемая интегратором при создании. Связывает сущность HRlink с записью во внешней системе (1С, SAP и др.) без хранения маппинга UUID., а не по IDid Внутренний идентификатор сущности в формате UUID, генерируемый HRlink при создании. Неизменяемый, используется во всех внутренних операциях. HRlink.

Порядок подписания​

  • MANAGER_FIRST — первым подписывает руководитель со стороны юрлица. documents[].watcherIds и documents[].watcherExternalIds не заполняйте.

  • EMPLOYEE_FIRST — первым подписывает сотрудник. documents[].watcherIds и documents[].watcherExternalIds не заполняйте.

  • EMPLOYEE_ONLY — подписывает только сотрудник, руководитель не участвует. documents[].headManagerId, documents[].headManagerExternalId, documents[].watcherIds, documents[].watcherExternalIds не заполняйте.

  • MANAGER_ONLY — подписывает только руководитель. Можно указать наблюдателей. documents[].employeeIds и documents[].employeeExternalIds не заполняйте.

  • ROUTE — очерёдность задаётся шаблоном маршрута подписания, переданным в routeTemplateId. Участников маршрута заполняйте по их типу:

    • тип EMPLOYEE — в employeeIds или employeeExternalIds;

    • тип EMPLOYER — в headManagerId или headManagerExternalId;

    • тип требуемого действия RECEIVING — в watcherIds или watcherExternalIds;

    • типы SELECTABLE_EMPLOYEE и FIXED_EMPLOYEE (не получатели) — в participants.

Валидации запроса​

Клиент и пользователь

  • Клиент по clientId существует и не удалён.
  • clientId соответствует формату UUID.
  • Пользователь, выполняющий операцию, относится к клиенту.
  • У пользователя клиента есть право DOCUMENTS_CREATE. Если в теле запроса ни у одной сущности не указано юрлицо — право проверяется на уровне пользователя клиента или сотрудника. Если юрлицо указано — право проверяется в этом юрлице на уровне пользователя клиента или сотрудника.
  • У пользователя клиента есть доступ к отделам клиента сотрудников-подписантов.
  • Все указанные типы документов входят в список типов, разрешённых пользователю.

Группа документов

  • Тело запроса задано.
  • Название группы документов задано.
  • Список documents[] содержит хотя бы один документ, ни один элемент не null.
  • Лимит на конвертацию файлов в PDF/A для тенантаTenant Экземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов. не превышен.
  • Кадровик-создатель определён; если указан другой пользователь клиента, у вызывающего пользователя есть право назначать другого создателя.

Документ

  • Все списки в данных документа либо не заданы, либо не содержат пустых элементов.
  • Внешний IDexternalId Внешний идентификатор сущности — произвольная строка, задаваемая интегратором при создании. Связывает сущность HRlink с записью во внешней системе (1С, SAP и др.) без хранения маппинга UUID. документа уникален в пределах клиента.
  • documents[].fileId задан и не null.
  • Файл по fileId корректен.
  • Срок подписания в днях задан корректно.

Тип документа

  • Если documentTypeId задан — тип документа существует, не скрыт и входит в список доступных типов для индекса документа в группе.

Юрлицо

  • Если legalEntityId или legalEntityExternalId задан — юрлицо существует и принадлежит клиенту.

Руководитель-подписант

  • Если задан headManagerId или headManagerExternalId — сотрудник существует, принадлежит клиенту, не уволен и имеет права руководителя в своём юрлице.
  • Если юрлицо руководителя не совпадает с юрлицом документа — у пользователя есть активный сотрудник-руководитель в юрлице документа либо право руководителя в указанном юрлице через связку прав сотрудника.
  • Если headManagerId не задан, но задан headManagerExternalId и IDid Внутренний идентификатор сущности в формате UUID, генерируемый HRlink при создании. Неизменяемый, используется во всех внутренних операциях. юрлица руководителя — юрлицо задано корректно.

Сотрудники-подписанты

  • Сотрудники по указанным IDid Внутренний идентификатор сущности в формате UUID, генерируемый HRlink при создании. Неизменяемый, используется во всех внутренних операциях. существуют, принадлежат клиенту и работают.
  • Среди employeeIds и employeeExternalIds нет пустых элементов.

Наблюдатели

  • Среди watcherIds и watcherExternalIds нет пустых элементов.
  • Сотрудники-наблюдатели существуют и принадлежат клиенту.

Принадлежность одному юрлицу

  • Сотрудник-подписант, наблюдатели, участники маршрута и сам документ относятся к одному юрлицу.

Порядок подписания

  • EMPLOYEE_FIRST или MANAGER_FIRST — не заданы наблюдатели, участники маршрута и шаблон маршрута.
  • MANAGER_ONLY — не заданы сотрудники-подписанты, участники маршрута и шаблон маршрута.
  • EMPLOYEE_ONLY — не заданы руководитель, наблюдатели, участники маршрута и шаблон маршрута.
  • ROUTE — задан корректный шаблон маршрута, данные документа соответствуют этапам шаблона.
  • Если порядок подписания не задан, но задан routeTemplateId или routeTemplateExternalId — порядок считается ROUTE.

Шаблон маршрута подписания

  • Шаблон существует по заданному IDid Внутренний идентификатор сущности в формате UUID, генерируемый HRlink при создании. Неизменяемый, используется во всех внутренних операциях. (внутреннему или внешнему).
  • Шаблон относится к клиенту.
  • Шаблон не деактивирован.
  • Тип подписываемого объекта в шаблоне соответствует типу документа.
  • Если список юрлиц шаблона пуст — шаблон доступен всем юрлицам.
  • Если у документа нет юрлица — шаблону доступен только вариант «доступен всем юрлицам».
  • Если у документа есть юрлицо, а у шаблона задан непустой список юрлиц — юрлицо документа входит в список.

Участники маршрута подписания

  • Если участники заданы — данные участников корректны.
  • Для этапа RECEIVING есть участник с типом SELECTABLE_EMPLOYEE.
  • Каждому IDid Внутренний идентификатор сущности в формате UUID, генерируемый HRlink при создании. Неизменяемый, используется во всех внутренних операциях. наблюдателя соответствует участник с типом FIXED_EMPLOYEE.
  • Все участники относятся к указанному маршруту подписания.
  • Дубликаты IDid Внутренний идентификатор сущности в формате UUID, генерируемый HRlink при создании. Неизменяемый, используется во всех внутренних операциях. участников запрещены, если маршрут это не допускает.
  • Сотрудники участников на одном этапе — разные пользователи клиента, с учётом фиксированных и автоопределяемых участников.
  • Если этап имеет тип RECEIVING — соответствующих участников передавайте в наблюдателях.
  • Если участник имеет тип EMPLOYEE или EMPLOYER — передавайте его в полях сотрудников или руководителя соответственно.
  • Если у этапа SIGNING нет участников с типом EMPLOYER — руководитель не задан.
  • Если в маршруте есть только этап RECEIVING — watcherIds или watcherExternalIds задан и не пуст.
  • У участника типа FIXED_EMPLOYEE IDid Внутренний идентификатор сущности в формате UUID, генерируемый HRlink при создании. Неизменяемый, используется во всех внутренних операциях. сотрудника совпадает с зафиксированным в шаблоне.
  • В данных участника задан IDid Внутренний идентификатор сущности в формате UUID, генерируемый HRlink при создании. Неизменяемый, используется во всех внутренних операциях. сотрудника (внутренний или внешний).

Связи с другими сущностями КЭДОКЭДО Кадровый электронный документооборот — подвид ЭДО для кадровых документов (трудовые договоры, приказы, заявления). Регулируется статьями 22.1–22.3 ТК РФ.

  • Массив связанных сущностей не содержит пустых элементов.
  • У каждой сущности задан тип и IDid Внутренний идентификатор сущности в формате UUID, генерируемый HRlink при создании. Неизменяемый, используется во всех внутренних операциях. (внутренний или внешний).
  • Сущность указанного типа существует по заданному IDid Внутренний идентификатор сущности в формате UUID, генерируемый HRlink при создании. Неизменяемый, используется во всех внутренних операциях..
  • У пользователя есть доступ к сущности.
  • Сущность не удалена.
  • Сущность не черновик, если связь с черновиком запрещена.
  • У пользователя клиента есть право ENTITY_RELATION_CREATE на уровне пользователя клиента или на уровне сотрудника юрлица сущности.

Связь с заявлением сотрудника

  • Заявление существует по заданному IDid Внутренний идентификатор сущности в формате UUID, генерируемый HRlink при создании. Неизменяемый, используется во всех внутренних операциях. (внутреннему или внешнему).
  • Заявление не удалено.
  • Заявление не черновик: хотя бы один подписант принял решение.
  • Пользователь клиента — создатель или заявитель, либо получатель завершённой группы, либо подписант с уже наступившим моментом подписания, либо имеет необходимую роль ROLE-подписанта, либо право на получение заявлений на уровне роли пользователя клиента или сотрудника.

Связь с документом

  • Документ существует по заданному IDid Внутренний идентификатор сущности в формате UUID, генерируемый HRlink при создании. Неизменяемый, используется во всех внутренних операциях. (внутреннему или внешнему).
  • Документ не удалён.
  • Документ не черновик.
  • У пользователя клиента есть права для получения документа.

Request​

Responses​

Успешная операция.