# Contrato de integração HighTV / Xtream

## Objetivo

O APK analisado não consome diretamente `player_api.php`. Ele usa um contrato próprio de catálogo e dispositivos, com autenticação por token Bearer. O painel fará a ingestão de uma lista M3U autorizada, normalizará canais, filmes e séries em SQLite e responderá simultaneamente ao contrato nativo do APK e às ações Xtream compatíveis.

## Endpoint exclusivo

A base gravada no APK continuará sendo `https://hightv.gtvapps.shop`. No painel, a URL é autodetectada por requisição a partir de `HTTP_HOST`, `SERVER_NAME`, HTTPS e `X-Forwarded-Proto`; `HTV_BASE_URL` é somente um override opcional. Assim, o painel pode ser movido para outra hospedagem/domínio sem editar o código. Todos os arquivos do pacote ficam diretamente na raiz do document root, sem pasta `public/`.

## Rotas nativas do APK

| Método | Rota | Autenticação | Resposta esperada |
| --- | --- | --- | --- |
| GET | `/api/health` | pública | JSON HTTP 2xx |
| GET | `/api/public/config?product=tv` | pública | objeto com `settings`, `titles`, `genres`, `liveCategories` |
| POST | `/api/device/register` | pública | objeto com `registrationSecret` |
| POST | `/api/device/status` | pública | objeto com `deviceToken`, `status`, `expiresAt` |
| POST | `/api/device/heartbeat` | Bearer | objeto com `expiresAt` |
| GET | `/api/categories` | pública ou Bearer | array de categorias de TV ao vivo |
| GET | `/api/device/channels?mac=...` | pública | array de canais |
| GET | `/api/epg?channelIds=...&scope=now-next&limit=...` | pública | array de programas |
| GET | `/api/stream-domains` | pública | array de domínios de stream |
| GET | `/api/catalog?compact=1&type=movie&limit=35...` | Bearer | objeto com `titles`, e opcionalmente `historyTitleIds`, `progress`, `progressUpdatedAt`, `historyUpdatedAt` |
| GET | `/api/catalog?compact=1&type=series&limit=28&offset=...` | Bearer | mesmo formato, filtrado por série |
| GET | `/api/title-playback?titleId=...` | Bearer | objeto com `sources` ou dados de playback |
| GET | `/api/title-episodes?titleId=...` | Bearer | objeto com array `episodes` |
| POST | `/api/device/favorites` | Bearer | objeto com `favorites` |
| POST | `/api/log` | pública | JSON de confirmação |
| GET | `/api/app-update` | pública | objeto com `packageName`, `versionCode`, `versionName`, `apkUrl`, `sha256`, `notes` |

## Campos mínimos de títulos

Cada item em `titles` terá, conforme disponível, `id`, `title`, `type`, `poster`, `backdrop`, `bannerBackdrop`, `description`, `year`, `rating`, `imdbRating`, `category`, `genreIds`, `active` e `sources`. Para filmes, `sources` conterá pelo menos uma fonte com `url`, `type` e `label`. Para séries, os episódios serão entregues em `/api/title-episodes`.

## Campos mínimos de canais

Cada canal terá `id`, `name`, `stream_url`, `logo_url`, `image_url`, `category_id`, `category_name`, `group_title`, `group_name`, `category` e, quando disponível, `epg_channel_id`. Os nomes de grupo da M3U serão convertidos em categorias estáveis.

## Compatibilidade Xtream

Também serão expostas as ações mais comuns de `player_api.php`:

- `get_live_categories` e `get_live_streams`;
- `get_vod_categories`, `get_vod_streams` e `get_vod_info`;
- `get_series_categories`, `get_series` e `get_series_info`;
- `get_short_epg` e `get_simple_date_table`.

Serão fornecidos ainda `get.php` para M3U gerada e `xmltv.php` para EPG básica. O painel não retransmitirá nem alterará os fluxos: ele entregará as URLs presentes na lista autorizada.

## Fluxo M3U

O administrador cola ou envia o conteúdo M3U. O parser reconhece `tvg-id`, `tvg-name`, `tvg-logo`, `group-title`, `type`, `category_id` e outros atributos estendidos. Cada par `#EXTINF`/URL é salvo como item. Itens marcados como `movie`, com extensão de vídeo ou em grupos de filmes são classificados como VOD; os demais são canais ao vivo. A interface oferece ajuste manual de tipo e categoria antes da publicação.

## Segurança

O painel usa autenticação administrativa, token CSRF, consultas preparadas PDO, validação de URL, limite de tamanho para M3U e tokens aleatórios para dispositivos. O conteúdo deve ser de titularidade do administrador ou utilizado com autorização válida. As credenciais administrativas não são embutidas no APK.