Документы

Группа методов /api/v1/documents даёт доступ к хранилищу документов Skailer: папкам, метаданным документов и самим файлам.

Папки и типы документов

Каждый документ лежит в папке, а тип папки определяет, кому принадлежит документ:

Тип папки	Значение
`organization`	Документы организации (политики, регламенты, шаблоны)
`employee`	Документы конкретного сотрудника (договоры, справки, сканы)

Для документа в папке типа employee поле employee_id содержит id сотрудника, которому он принадлежит. Для документа организации employee_id равен null.

Получить список папок по типу

GET /api/v1/documents/folders/{folder_type}

folder_type - organization или employee.

Поля ответа (каждая папка):

Поле	Тип	Описание
`id`	integer	ID папки
`title`	string	Название папки
`type`	string	Тип папки: `organization`, `employee`
`document_count`	integer	Количество документов в папке

Права: для type=organization в ответ попадают папки, доступ к которым выдан правилами просмотра/редактирования папок, либо все папки при settings_document_folders=edit. Для type=employee требуется settings_document_folders=edit.

Пример ответа:

[
  {
    "id": 12,
    "title": "Политики компании",
    "type": "organization",
    "document_count": 8
  }
]

Получить папки сотрудника

GET /api/v1/documents/employees/{employee_id}/folders

Возвращает папки типа employee, доступные для указанного сотрудника. Поля ответа те же, что выше.

Права: settings_document_folders=edit, settings_roles_permissions=edit или employee_folder_permissions=view на папку.

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

POST /api/v1/documents/search

Возвращает постраничный список документов.

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

Поле	Тип	Описание
`folder_id`	integer	Поиск внутри одной конкретной папки
`folder_type`	string	Поиск по всем доступным папкам типа: `organization`, `employee`
`employee_id`	integer	Фильтр по сотруднику, которому принадлежат документы
`title`	string	Фильтр по названию документа
`page_number`	integer	Номер страницы, начинается с `1`

Важно: должен быть задан ровно один из параметров folder_id или folder_type. Если передать оба или ни одного, метод вернёт 422.

Поля ответа (каждый документ):

Поле	Тип	Описание
`id`	integer	ID документа
`title`	string	Название документа
`employee_id`	integer \| null	Сотрудник, которому принадлежит документ; `null` для документа организации
`uploaded_by_employee_id`	integer	Сотрудник, загрузивший документ
`folder`	object	Папка: `id`, `title`, `type`
`file`	object	Файл: `name`, `file_type`, `size`, `mime_type`, `uuid`, `url`
`datetime_created_at`	string	Дата и время создания
`datetime_updated_at`	string	Дата и время последнего изменения

Права: для папки type=organization требуется settings_document_folders=edit либо доступ, выданный правилами просмотра/редактирования папки. Для папки type=employee требуется employee_folder_permissions=view; для поиска с folder_type=employee дополнительно нужен settings_document_folders=edit.

Пример запроса:

{
  "folder_id": 12,
  "title": "договор",
  "page_number": 1
}

Пример ответа:

{
  "items": [
    {
      "id": 4501,
      "title": "Трудовой договор",
      "employee_id": 123,
      "uploaded_by_employee_id": 7,
      "folder": {
        "id": 12,
        "title": "Договоры",
        "type": "employee"
      },
      "file": {
        "name": "employment_contract.pdf",
        "file_type": "employee_documents",
        "size": 148213,
        "mime_type": "application/pdf",
        "uuid": "3f1c2b90-5d1a-4c8e-9a77-0b2d61f4e8aa",
        "url": null
      },
      "datetime_created_at": "2026-05-14 09:12:00",
      "datetime_updated_at": "2026-05-14 09:12:00"
    }
  ],
  "metadata": {
    "page_number": 1,
    "total_pages": 1,
    "items": 1,
    "items_per_page": 20,
    "total_items": 1
  }
}

Загрузить документ

POST /api/v1/documents/upload

Загружает файл и сразу создаёт из него документ одним запросом. Тело запроса - multipart/form-data.

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

Поле	Тип	Описание
`file`	file	Загружаемый файл (обязательно)
`folder_id`	integer	ID папки, в которую загружается документ (обязательно)
`employee_id`	integer	Сотрудник, которому принадлежит документ; не указывается для документа организации

Название документа берётся из имени файла без расширения и позже может быть изменено через PUT /api/v1/documents/{document_id}.

Права: для папки type=organization требуется settings_document_folders=edit либо доступ, выданный правилами редактирования папки. Для папки type=employee требуется employee_folder_permissions=edit.

Пример запроса:

curl -X POST 'https://<api-domain>/api/v1/documents/upload' \
  -H 'Authorization: Bearer <your_access_token>' \
  -F 'folder_id=12' \
  -F 'employee_id=123' \
  -F 'file=@employment_contract.pdf'

В ответе возвращается созданный документ в том же формате, что и в поиске.

Получить документ по id

GET /api/v1/documents/{document_id}

Возвращает метаданные документа.

Скачать файл документа

GET /api/v1/documents/{document_id}/download

Возвращает исходный файл бинарным ответом. Имя файла передаётся в заголовке Content-Disposition.

Права: те же, что и для просмотра документа.

Переименовать документ

PUT /api/v1/documents/{document_id}

Меняет название документа. Сам файл при этом не заменяется.

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

Поле	Тип	Описание
`title`	string	Новое название документа (обязательно)

Пример запроса:

{
  "title": "Трудовой договор 2026"
}

Удалить документ

DELETE /api/v1/documents/{document_id}

Удаляет документ. Возвращает {"success": true}.

Типовой сценарий интеграции

Задача: складывать подписанные договоры из внешнего документооборота в папку сотрудника.

Найти папку сотрудника (один раз на сотрудника, результат можно кэшировать):
```
GET /api/v1/documents/employees/{employee_id}/folders
```
Проверить, что документа ещё нет, чтобы не создавать дубликаты:
```
POST /api/v1/documents/search
```
Передайте folder_id и title.
Загрузить файл:
```
POST /api/v1/documents/upload
```
Передайте folder_id, employee_id и file.
Задать итоговое название, если имя файла отличается от нужного названия:
```
PUT /api/v1/documents/{document_id}
```

Совет: для синхронизации в обратную сторону - выгрузки документов из Skailer - проходите по страницам POST /api/v1/documents/search с параметром folder_type, а затем скачивайте каждый файл через GET /api/v1/documents/{document_id}/download.