# Общий доступ к папкам и проектам через API


API открывает общий доступ к папке или проекту по публичной ссылке. В Kinescope этот механизм называется шерингом (sharing), а в API используются пути и поля `shares`, `share_id` и `reset-token`. Получателю не нужен аккаунт Kinescope: он видит видео и подпапки в браузере, а при необходимости вводит пароль.

Эндпоинты `/v1/shares` помогают создать ссылку из LMS, CRM или собственного бэкенда, настроить её и закрыть доступ. Перед началом работы прочитайте [общие правила API](https://docs.kinescope.ru/instrukcii-dlya-razrabotchikov/api-obshchie-pravila/).

## Когда настраивать общий доступ из кода

* **LMS выдаёт доступ после оплаты.** Бэкенд создаёт ссылку на папку с уроками и отправляет её студенту.
* **Нужен временный доступ.** Укажите дату окончания для подрядчика или партнёра.
* **Ссылка попала не тому получателю.** Сбросьте её и передайте новый адрес, не меняя остальные настройки.
* **Подписка закончилась.** Отзовите доступ ко всем материалам одной командой.

Если хотя бы один сценарий вам знаком — читайте дальше.

## Как работает общий доступ

1. Вы создаёте общий доступ к папке или проекту и получаете `share_id`, `token` и готовую ссылку.
2. Получатель открывает ссылку `https://kinescope.io/sh/{token}` и видит каталог без входа в Kinescope.
3. Для одной папки или проекта существует только одна активная ссылка.
4. Через `PATCH` можно изменить пароль, срок доступа, разрешение на скачивание или название.
5. `reset-token` выдаёт новый адрес, а `DELETE` окончательно отзывает доступ.

Папка и проект используют один механизм: в запросе достаточно передать ID нужного объекта в `entity_id`.

## Что подготовить

* API-токен рабочей зоны в заголовке `Authorization: Bearer YOUR_API_TOKEN`.
* Платный тариф: создание ссылки на бесплатном тарифе недоступно.
* ID папки или проекта. Получить их можно при [загрузке файлов через API](https://docs.kinescope.ru/instrukcii-dlya-razrabotchikov/zagruzka-faylov-cherez-api/#подготовка-получение-id-проекта-или-папки).
* Роль admin, editor+, editor или manager. Роль viewer может читать настройки существующей ссылки, но не изменять их.

## Создайте публичную ссылку

`POST https://api.kinescope.io/v1/shares`

```bash
curl -X POST 'https://api.kinescope.io/v1/shares' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity_id": "5b8a54a1-1f4f-4a5f-9a3a-2a4b0e2f1c77",
    "display_name": "Курс по Python — поток 12",
    "password": "python-2026",
    "allow_download": true,
    "expires_at": "2026-12-01T00:00:00Z"
  }'
```

Поля запроса:

| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| `entity_id` | UUID | да | ID папки или проекта |
| `display_name` | string | нет | Название ссылки, до 255 символов |
| `password` | string | нет | Пароль из четырёх или более символов |
| `allow_download` | boolean | нет | Разрешает скачивание видео; по умолчанию `false` |
| `starts_at` | RFC3339 | нет | Момент, с которого ссылка начинает работать |
| `expires_at` | RFC3339 | нет | Момент, после которого ссылка перестаёт работать |

Если заданы обе даты, `starts_at` должен быть раньше `expires_at`. Пароль короче четырёх символов не пройдёт проверку API.

Успешный запрос возвращает `201 Created`:

```json
{
  "data": {
    "share_id": "9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41",
    "entity_id": "5b8a54a1-1f4f-4a5f-9a3a-2a4b0e2f1c77",
    "display_name": "Курс по Python — поток 12",
    "has_password": true,
    "allow_download": true,
    "starts_at": null,
    "expires_at": "2026-12-01T00:00:00Z",
    "is_active": true,
    "token": "iVv6uEZ5V3DZ2ytZ28RUru",
    "link": "https://kinescope.io/sh/iVv6uEZ5V3DZ2ytZ28RUru"
  }
}
```

Сохраните `share_id`: он понадобится для последующих запросов. Отправьте получателю значение `link`.

> **Внимание:**

Не передавайте API-токен в браузер или мобильное приложение. Создавайте и меняйте ссылки только из вашего бэкенда.



## Получите настройки существующей ссылки

Если известен `share_id`, запросите настройки напрямую:

```bash
curl 'https://api.kinescope.io/v1/shares/9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```

Если известен только ID папки или проекта, используйте `entity_id`:

```bash
curl 'https://api.kinescope.io/v1/shares/entity/5b8a54a1-1f4f-4a5f-9a3a-2a4b0e2f1c77' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```

Оба запроса возвращают активную ссылку. После отзыва она не находится ни по `share_id`, ни по `entity_id`.

## Измените пароль, сроки и скачивание

`PATCH https://api.kinescope.io/v1/shares/{share_id}`

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

```bash
curl -X PATCH 'https://api.kinescope.io/v1/shares/9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "password": "new-password",
    "allow_download": false,
    "expires_at": "2027-01-15T00:00:00Z"
  }'
```

| Что передать | Результат |
|---|---|
| Не передавать поле | Значение не изменится |
| `"password": "new-password"` | Пароль будет установлен или заменён |
| `"password": ""` | Пароль будет удалён |
| `"display_name": ""` | Пользовательское название будет удалено |
| `"starts_at": null` или `"expires_at": null` | Ограничение по дате будет снято |

Смена или удаление пароля завершает активные сессии получателей. Им потребуется открыть ссылку и пройти проверку доступа заново.

## Смените адрес ссылки

Если ссылку нужно заменить, вызовите `reset-token`:

```bash
curl -X POST 'https://api.kinescope.io/v1/shares/9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41/reset-token' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```

В ответе придёт новый объект общего доступа с новыми `share_id`, `token` и `link`. Все настройки сохранятся, а старый адрес перестанет работать сразу. Обновите сохранённый `share_id` и отправьте получателям новую ссылку.

## Отзовите доступ

`DELETE https://api.kinescope.io/v1/shares/{share_id}`

```bash
curl -X DELETE 'https://api.kinescope.io/v1/shares/9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```

После отзыва ссылка и все глубокие ссылки на видео или подпапки перестают работать. Чтобы снова открыть доступ, создайте новую ссылку.

## Обработайте типовые ошибки

| HTTP | Когда возникает |
|---|---|
| `403 Forbidden` | У токена нет нужной роли, нет доступа к объекту или тариф не поддерживает шеры |
| `404 Not Found` | Не найдена ссылка или объект |
| `409 Conflict` | У объекта уже есть активная ссылка или нельзя сбросить отозванный доступ |
| `422 Unprocessable Entity` | Не прошли проверку пароль, даты или другие поля |

При повторном `POST` для одной папки или проекта API возвращает `409`. Сначала получите существующую ссылку по `entity_id`, затем обновите или отзовите её.

## Что дальше?

1. **[Загрузка файлов через API](https://docs.kinescope.ru/instrukcii-dlya-razrabotchikov/zagruzka-faylov-cherez-api/)** — получите ID проекта или папки и наполните её видео.
2. **[Общие правила API](https://docs.kinescope.ru/instrukcii-dlya-razrabotchikov/api-obshchie-pravila/)** — авторизация, формат ошибок и лимиты запросов.
3. **[Как поделиться папкой или проектом](https://docs.kinescope.ru/katalog-i-upravlenie-video/sharing-papok-i-proektov/)** — кабинетный сценарий и поведение для получателя.

Остались вопросы? Напишите в [чат поддержки](https://t.me/kinescope_bot) — специалисты помогут.