# Compartilhar Pastas e Projetos pela API


A API compartilha uma pasta ou projeto por um link público. No Kinescope, esse mecanismo é chamado de compartilhamento; a API usa os caminhos `shares` e os campos `share_id` e `reset-token`. Quem recebe o link não precisa de conta no Kinescope: vê vídeos e subpastas no navegador e informa uma senha quando necessário.

Os endpoints `/v1/shares` permitem criar um link a partir de um LMS, CRM ou backend próprio, alterar suas configurações e fechar o acesso. Antes de começar, leia as [regras gerais da API](https://docs-br.kinescope.com/developer-guides/api-general-rules/).

## Quando configurar o compartilhamento por código

* **Um LMS libera acesso após o pagamento.** Seu backend cria um link para a pasta de aulas e o envia ao aluno.
* **Você precisa de acesso temporário.** Defina uma data de expiração para um fornecedor ou parceiro.
* **O link chegou à pessoa errada.** Renove-o e envie o novo endereço sem alterar as outras configurações.
* **Uma assinatura terminou.** Revogue o acesso a todos os materiais com uma única solicitação.

## Como o compartilhamento funciona

1. Você cria um compartilhamento para uma pasta ou projeto e recebe `share_id`, `token` e um link pronto.
2. O destinatário abre `https://kinescope.io/sh/{token}` e vê o catálogo sem entrar no Kinescope.
3. Uma pasta ou projeto pode ter apenas um link ativo.
4. Use `PATCH` para alterar senha, período de acesso, permissão de download ou nome.
5. `reset-token` cria um novo endereço, e `DELETE` revoga o acesso definitivamente.

Pastas e projetos usam o mesmo mecanismo: passe o ID de qualquer um deles em `entity_id`.

## O que você precisa preparar

* Um token de API do workspace no cabeçalho `Authorization: Bearer YOUR_API_TOKEN`.
* Um plano pago: a criação de link não está disponível no plano gratuito.
* O ID da pasta ou do projeto. Você pode obtê-lo no [upload de arquivos via API](https://docs-br.kinescope.com/developer-guides/file-upload-via-api/#preparação-obtendo-o-id-do-projeto-ou-pasta).
* A função admin, editor+, editor ou manager. A função viewer pode consultar as configurações de um link existente, mas não pode alterá-las.

## Crie um link público

`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": "Curso de Python — turma 12",
    "password": "python-2026",
    "allow_download": true,
    "expires_at": "2026-12-01T00:00:00Z"
  }'
```

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `entity_id` | UUID | Sim | ID de uma pasta ou projeto |
| `display_name` | string | Não | Nome do link, com até 255 caracteres |
| `password` | string | Não | Senha com quatro ou mais caracteres |
| `allow_download` | boolean | Não | Permite baixar vídeos; o padrão é `false` |
| `starts_at` | RFC3339 | Não | Momento em que o link começa a funcionar |
| `expires_at` | RFC3339 | Não | Momento em que o link deixa de funcionar |

Se você informar as duas datas, `starts_at` deve ser anterior a `expires_at`. Uma senha com menos de quatro caracteres não passa na validação da API.

Uma solicitação bem-sucedida retorna `201 Created`:

```json
{
  "data": {
    "share_id": "9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41",
    "entity_id": "5b8a54a1-1f4f-4a5f-9a3a-2a4b0e2f1c77",
    "display_name": "Curso de Python — turma 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"
  }
}
```

Guarde o `share_id`: ele será necessário nas próximas solicitações. Envie ao destinatário o valor de `link`.

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

Não exponha o token de API no navegador ou em um aplicativo móvel. Crie e gerencie links somente pelo seu backend.



## Consulte as configurações de um link existente

Se você souber o `share_id`, consulte as configurações diretamente:

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

Se você souber apenas o ID da pasta ou do projeto, use `entity_id`:

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

As duas solicitações retornam o link ativo. Depois da revogação, ele não é encontrado por `share_id` nem por `entity_id`.

## Altere senha, datas ou permissão de download

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

Envie apenas os campos que precisa alterar:

```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"
  }'
```

| Valor enviado | Resultado |
|---|---|
| Omitir um campo | O valor não é alterado |
| `"password": "new-password"` | Define ou substitui a senha |
| `"password": ""` | Remove a senha |
| `"display_name": ""` | Remove o nome personalizado do link |
| `"starts_at": null` ou `"expires_at": null` | Remove a limitação por data |

Alterar ou remover uma senha encerra as sessões ativas dos destinatários. Eles precisam abrir o link e passar pela verificação novamente.

## Renove o endereço do link

Chame `reset-token` quando precisar substituir um link:

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

A resposta contém um novo objeto de compartilhamento, com novos `share_id`, `token` e `link`. As configurações são mantidas, mas o endereço antigo para de funcionar imediatamente. Atualize o `share_id` salvo e envie o novo link aos destinatários.

## Revogue o acesso

`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'
```

Depois da revogação, o link e todos os links diretos para vídeos ou subpastas deixam de funcionar. Crie outro link para compartilhar o item novamente.

## Trate os erros mais comuns

| HTTP | Quando acontece |
|---|---|
| `403 Forbidden` | O token não tem a função ou acesso ao item necessário, ou o plano não permite compartilhamento |
| `404 Not Found` | O link ou item não foi encontrado |
| `409 Conflict` | O item já tem um link ativo, ou não é possível renovar um acesso revogado |
| `422 Unprocessable Entity` | A senha, as datas ou outro campo não passam na validação |

Se você repetir `POST` para a mesma pasta ou projeto, a API retorna `409`. Primeiro obtenha o link existente por `entity_id`; depois atualize-o ou revogue-o.

## O que fazer a seguir?

1. **[Upload de Arquivos via API](https://docs-br.kinescope.com/developer-guides/file-upload-via-api/)** — obtenha o ID de um projeto ou pasta e adicione vídeos.
2. **[Regras Gerais da API](https://docs-br.kinescope.com/developer-guides/api-general-rules/)** — autorização, formato de erros e limites de requisições.
3. **[Como compartilhar uma pasta ou projeto](https://docs-br.kinescope.com/catalog-and-video-management/compartilhar-pastas-e-projetos/)** — o fluxo no painel e a experiência de quem recebe o link.