# Webhook API - Video Management System

Manual de integração para envio de vídeos via webhook.

---

## Endpoint

```
POST /api/webhook_video.php
```

---

## Autenticação

Atualmente o webhook está aberto (sem autenticação). CORS está habilitado para todas as origens.

---

## Métodos de Envio

O webhook aceita vídeos de duas formas:

### 1. Upload Direto de Arquivo

Envie o arquivo de vídeo diretamente via `multipart/form-data`.

### 2. URL do Vídeo

Envie uma URL e o sistema fará o download automaticamente.

---

## Parâmetros

| Parâmetro | Tipo | Obrigatório | Descrição |
|-----------|------|-------------|-----------|
| `arena` | string | Sim | Nome da arena (ex: "Arena Central") |
| `court` | string | Sim | Nome da quadra (ex: "Quadra 1") |
| `type` | string | Não | Tipo/categoria do vídeo (padrão: "general") |
| `datetime` | string | Não | Data/hora do vídeo (padrão: hora atual) |
| `video` | file | Sim* | Arquivo de vídeo (MP4) |
| `video_url` | string | Sim* | URL para download do vídeo |

> *Obrigatório enviar `video` OU `video_url` (um dos dois)

---

## Limites e Restrições

| Configuração | Valor |
|--------------|-------|
| Tamanho máximo do arquivo | 500 MB |
| Formatos aceitos | MP4 |
| Timeout de download (URL) | 300 segundos |

---

## Exemplos de Uso

### Exemplo 1: Upload de Arquivo (cURL)

```bash
curl -X POST "https://seu-dominio.com/api/webhook_video.php" \
  -F "arena=Arena Central" \
  -F "court=Quadra 1" \
  -F "type=partida" \
  -F "datetime=2024-01-15 14:30:00" \
  -F "video=@/caminho/para/video.mp4"
```

### Exemplo 2: Upload de Arquivo (JavaScript/Fetch)

```javascript
const formData = new FormData();
formData.append('arena', 'Arena Central');
formData.append('court', 'Quadra 1');
formData.append('type', 'partida');
formData.append('datetime', '2024-01-15 14:30:00');
formData.append('video', arquivoVideo); // File object

const response = await fetch('/api/webhook_video.php', {
  method: 'POST',
  body: formData
});

const result = await response.json();
console.log(result);
```

### Exemplo 3: Envio via URL (cURL)

```bash
curl -X POST "https://seu-dominio.com/api/webhook_video.php" \
  -H "Content-Type: application/json" \
  -d '{
    "arena": "Arena Central",
    "court": "Quadra 1",
    "type": "partida",
    "datetime": "2024-01-15 14:30:00",
    "video_url": "https://exemplo.com/videos/partida123.mp4"
  }'
```

### Exemplo 4: Envio via URL (JavaScript/Fetch)

```javascript
const response = await fetch('/api/webhook_video.php', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    arena: 'Arena Central',
    court: 'Quadra 1',
    type: 'partida',
    datetime: '2024-01-15 14:30:00',
    video_url: 'https://exemplo.com/videos/partida123.mp4'
  })
});

const result = await response.json();
console.log(result);
```

### Exemplo 5: Python (requests)

```python
import requests

# Upload de arquivo
files = {'video': open('video.mp4', 'rb')}
data = {
    'arena': 'Arena Central',
    'court': 'Quadra 1',
    'type': 'partida',
    'datetime': '2024-01-15 14:30:00'
}

response = requests.post(
    'https://seu-dominio.com/api/webhook_video.php',
    files=files,
    data=data
)
print(response.json())
```

```python
# Via URL
import requests

response = requests.post(
    'https://seu-dominio.com/api/webhook_video.php',
    json={
        'arena': 'Arena Central',
        'court': 'Quadra 1',
        'type': 'partida',
        'datetime': '2024-01-15 14:30:00',
        'video_url': 'https://exemplo.com/videos/partida123.mp4'
    }
)
print(response.json())
```

---

## Respostas da API

### Sucesso (HTTP 201)

```json
{
  "status": "success",
  "message": "Video uploaded successfully",
  "data": {
    "video_id": 123,
    "arena": {
      "id": 1,
      "name": "Arena Central",
      "created": false
    },
    "court": {
      "id": 5,
      "name": "Quadra 1",
      "created": true
    },
    "filename": "2024-01-15_14-30-00_abc12345.mp4",
    "type": "partida",
    "datetime": "2024-01-15 14:30:00",
    "size": 52428800
  }
}
```

**Campos da resposta:**

| Campo | Descrição |
|-------|-----------|
| `video_id` | ID único do vídeo no sistema |
| `arena.id` | ID da arena |
| `arena.name` | Nome da arena |
| `arena.created` | `true` se a arena foi criada agora, `false` se já existia |
| `court.id` | ID da quadra |
| `court.name` | Nome da quadra |
| `court.created` | `true` se a quadra foi criada agora, `false` se já existia |
| `filename` | Nome do arquivo salvo no servidor |
| `type` | Tipo/categoria do vídeo |
| `datetime` | Data/hora do vídeo |
| `size` | Tamanho do arquivo em bytes |

### Erro de Validação (HTTP 400)

```json
{
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "arena": "Arena name is required",
    "file": "Invalid file type. Only MP4 videos are allowed"
  }
}
```

### Método Não Permitido (HTTP 405)

```json
{
  "status": "error",
  "message": "Method not allowed. Use POST."
}
```

### Erro Interno (HTTP 500)

```json
{
  "status": "error",
  "message": "An unexpected error occurred"
}
```

---

## Códigos de Erro de Upload

| Erro | Descrição |
|------|-----------|
| `File exceeds PHP ini max size` | Arquivo maior que o limite do PHP |
| `File exceeds form max size` | Arquivo maior que o limite do formulário |
| `File was only partially uploaded` | Upload incompleto |
| `No file was uploaded` | Nenhum arquivo enviado |
| `Missing temporary folder` | Pasta temporária não encontrada |
| `Failed to write file to disk` | Erro ao gravar arquivo |
| `File upload stopped by extension` | Extensão bloqueou o upload |

---

## Comportamento Automático

### Criação de Arenas e Quadras

O sistema cria automaticamente arenas e quadras que não existem:

- Se enviar `arena: "Nova Arena"` e ela não existir, será criada
- Se enviar `court: "Quadra 5"` e ela não existir na arena, será criada
- A resposta indica se foram criadas (`created: true`) ou já existiam (`created: false`)

### Nomeação de Arquivos

Os arquivos são renomeados automaticamente para evitar conflitos:

```
Formato: YYYY-MM-DD_HH-ii-ss_hashUnico.mp4
Exemplo: 2024-01-15_14-30-00_a1b2c3d4.mp4
```

### Estrutura de Armazenamento

```
storage/
└── videos/
    └── {arena_id}/
        └── {court_id}/
            ├── 2024-01-15_14-30-00_a1b2c3d4.mp4
            └── 2024-01-15_16-45-00_e5f6g7h8.mp4
```

---

## Testando a Integração

Antes de integrar, verifique se o sistema está funcionando:

```bash
# Verificar status do webhook
curl -X GET "https://seu-dominio.com/api/webhook_test.php"
```

---

## Dicas de Integração

1. **Sempre valide a resposta**: Verifique o campo `status` para confirmar sucesso
2. **Use datetime correto**: Formato esperado: `YYYY-MM-DD HH:ii:ss`
3. **Nomes consistentes**: Use os mesmos nomes de arena/quadra para agrupar vídeos
4. **Timeout adequado**: Para uploads grandes, configure timeout de pelo menos 5 minutos
5. **Tratamento de erros**: Implemente retry em caso de falhas de rede

---

## Suporte

Em caso de dúvidas ou problemas, verifique:

1. Se o endpoint está acessível
2. Se os parâmetros obrigatórios foram enviados
3. Se o arquivo é MP4 e está dentro do limite de 500MB
4. Os logs do servidor para mensagens de erro detalhadas