# Regras Gerais da API


Esta página descreve as regras gerais para trabalhar com a Kinescope API que se aplicam a todos os endpoints. Se você é novo na API, comece por aqui.

## Para quem é este artigo

* **Desenvolvedores** — precisam começar a usar a Kinescope API
* **Desenvolvedores backend** — precisam entender as regras básicas de autorização e formatos de solicitação
* **Engenheiros DevOps** — precisam integrar o Kinescope em processos automatizados

## **Informações básicas**

### URL base

Todas as solicitações da API são feitas para:

```
https://api.kinescope.io
```

### Versões da API

A Kinescope API usa versionamento via prefixos de URL:

| Versão | Prefixo | Descrição |
|--------|---------|----------|
| v1 | `/v1/*` | Versão estável da API |

## **Autorização**

### Formato do token

Para autorização na API pública, use o cabeçalho `Authorization` com o tipo `Bearer`:

```
Authorization: Bearer SEU_TOKEN_DE_API
```

**Importante:** O token de API deve estar no formato UUID (por exemplo, `e51e55a1-7615-493e-9055-10ac9cc44ccd`). Você pode obter um token no [Dashboard do Kinescope](https://app.kinescope.io) em **Configurações → Tokens de API**.

### Workspace e tokens

Cada token de API está vinculado a um workspace específico. Ao fazer uma solicitação, o workspace é determinado automaticamente a partir do token — você não precisa passá-lo separadamente.

Todos os endpoints requerem o cabeçalho `Authorization: Bearer ...`.

## **Formato de resposta**

### Resposta bem-sucedida

Todas as respostas bem-sucedidas são retornadas em formato JSON com um wrapper:

```json
{
  "data": {
    "id": "video-uuid",
    "title": "Meu Vídeo",
    "status": "done"
  }
}
```

### Resposta de lista com paginação

As listas são retornadas com metadados de paginação e ordenação:

```json
{
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 10,
      "total": 156
    },
    "order": {
      "created_at": "desc"
    }
  },
  "data": [
    {"id": "video-1", "title": "Primeiro Vídeo"},
    {"id": "video-2", "title": "Segundo Vídeo"}
  ]
}
```

### Cabeçalhos de resposta

Todas as respostas da API incluem o cabeçalho `X-Request-ID` com um identificador único de solicitação. Use-o ao entrar em contato com o suporte:

```
X-Request-ID: 7127f2d7-0e96-40d0-9a03-2e987c096466
```

## **Paginação**

Use parâmetros de paginação para recuperar listas:

| Parâmetro | Tipo | Padrão | Descrição |
|----------|-----|--------------|----------|
| `page` | inteiro | 1 | Número da página (começa em 1) |
| `per_page` | inteiro | 10 | Número de itens por página |

**Exemplo:**

```bash
curl "https://api.kinescope.io/v1/videos?page=2&per_page=25" \
  -H "Authorization: Bearer SEU_TOKEN_DE_API"
```

## **Ordenação**

Use o parâmetro `order` para ordenar os resultados:

```
order=campo.direção,campo2.direção
```

- **campo** — nome do campo para ordenação
- **direção** — direção: `asc` (crescente) ou `desc` (decrescente)
- Múltiplos campos podem ser especificados separados por vírgulas

**Exemplos:**

```bash
# Mais recentes primeiro, depois em ordem alfabética
curl "https://api.kinescope.io/v1/videos?order=created_at.desc,title.asc" \
  -H "Authorization: Bearer SEU_TOKEN_DE_API"

# Por data de criação crescente apenas
curl "https://api.kinescope.io/v1/videos?order=created_at.asc" \
  -H "Authorization: Bearer SEU_TOKEN_DE_API"
```

Se um campo for especificado sem direção, `asc` é usado por padrão.

> **Importante:** Nem todos os campos suportam ordenação. Se um campo inválido for especificado, a API retornará um erro com código `400216` (NOT_ALLOWED_ORDER_FIELD).

## **Formato de data**

### Para analytics e intervalos de tempo

Os parâmetros `from` e `to` suportam dois formatos:

1. **Formato curto:** `YYYY-MM-DD` (por exemplo, `2024-01-01`)
2. **Formato completo:** RFC3339 `YYYY-MM-DDTHH:MM:SSZ` (por exemplo, `2024-01-01T00:00:00Z`)

**Exemplo:**

```bash
curl "https://api.kinescope.io/v1/analytics/overview?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer SEU_TOKEN_DE_API"
```

Ambos os parâmetros são obrigatórios para endpoints de analytics.

## **Tratamento de erros**

### Formato de erro

Todos os erros são retornados em um formato consistente:

```json
{
  "error": {
    "code": 404404,
    "message": "video not found",
    "detail": "The requested video does not exist or has been deleted"
  }
}
```

### Códigos de resposta HTTP

| Código | Descrição | Quando ocorre |
|-----|----------|-----------------|
| 200 | OK | Solicitação concluída com sucesso |
| 400 | Bad Request | Formato de solicitação ou parâmetros inválidos |
| 401 | Unauthorized | Token inválido |
| 402 | Payment Required | Limites do plano excedidos |
| 403 | Forbidden | Sem permissão para executar a operação |
| 404 | Not Found | Recurso não encontrado |
| 413 | Request Entity Too Large | Tamanho da solicitação excede o limite |
| 422 | Unprocessable Entity | Erro de validação de dados |
| 429 | Too Many Requests | Limite de taxa de solicitações excedido |
| 500 | Internal Server Error | Erro no lado do servidor |

### Erro de validação

Para erros de validação, a resposta também inclui um array `invalid_params`:

```json
{
  "error": {
    "code": 400400,
    "message": "validation error",
    "invalid_params": [
      {
        "name": "title",
        "reason": "required",
        "message": "Title is required"
      },
      {
        "name": "privacy_type",
        "reason": "oneof",
        "message": "Must be one of: anywhere, nowhere, custom"
      }
    ]
  }
}
```

## **Formatos especiais de resposta**

### Exportação CSV

Alguns endpoints suportam exportação de dados em formato CSV via sufixo `.csv` na URL:

**Exemplo:**

```bash
# JSON (padrão)
curl "https://api.kinescope.io/v1/billing/invoices/123" \
  -H "Authorization: Bearer SEU_TOKEN_DE_API"

# CSV
curl "https://api.kinescope.io/v1/billing/invoices/123.csv" \
  -H "Authorization: Bearer SEU_TOKEN_DE_API"
```

> **Importante:** O formato CSV não é suportado por todos os endpoints. Verifique a documentação do endpoint específico ou tente adicionar `.csv` à URL — se o formato não for suportado, JSON será retornado.

## **Limites e restrições**

| Recurso | Limite |
|--------|-------|
| Solicitações por segundo | 10 |
| Solicitações por minuto | 300 |
| Tamanho da solicitação | 10 MB |
| Itens por página | Depende do endpoint (geralmente até 100) |

Se os limites forem excedidos, a API retornará `429 Too Many Requests`.

## O que fazer a seguir?

Agora que você conhece as regras gerais da API, pode prosseguir para seções específicas:

1. **[Upload de arquivos via API](https://docs-br.kinescope.com/developer-guides/file-upload-via-api/)** — upload de vídeos e materiais complementares
2. **[Referência da API](https://docs-br.kinescope.com/api/)** — documentação completa da API
3. **[Analytics](https://docs-br.kinescope.com/catalog-and-video-management/analytics/)** — obtendo estatísticas de visualização via API
4. **[Autenticação JWT para chat](https://docs-br.kinescope.com/developer-guides/jwt-authentication-for-stream-chat/)** — configurando autorização do chat de stream
5. **[Backend de autorização](https://docs-br.kinescope.com/developer-guides/authorization-backend/)** — controle de acesso a vídeos

Ainda tem dúvidas? Escreva para o chat de suporte na interface do Kinescope — nossos especialistas vão ajudar!