API para desenvolvedores

Grátis, para qualquer pessoa: leia e grave o que você assiste a partir de players (Kodi, Jellyfin, Plex), apps e scripts. Autenticação por token Bearer; apps de terceiros usam OAuth 2.0 com PKCE.

Como usar

Base: https://www.apertaplay.com/api/v1 · Limite: 120 requisições por minuto por token e 300 por conta · Respostas em JSON.

# Quem é você
curl -H "Authorization: Bearer ap_..." https://www.apertaplay.com/api/v1/eu

# Marcar como assistido (escopo escrita)
curl -X POST -H "Authorization: Bearer ap_..." -H "Content-Type: application/json" \
  -d '{"tipo":"movie","tmdb_id":550}' https://www.apertaplay.com/api/v1/historico

# Episódio
  -d '{"tipo":"tv","tmdb_id":1396,"temporada":1,"episodio":2}'

# Scrobble de player: iniciar | pausar | parar (parar com 80%+ grava)
curl -X POST ... -d '{"acao":"parar","tipo":"movie","tmdb_id":550,"progresso":92}' https://www.apertaplay.com/api/v1/scrobble

# Sem o tmdb_id: id do IMDb (do filme ou do episódio), do TVDB (do episódio) ou o nome
  -d '{"acao":"iniciar","tipo":"movie","imdb_id":"tt0137523"}'
  -d '{"acao":"parar","tipo":"tv","serie":"Breaking Bad","temporada":1,"episodio":2,"progresso":100}'
  • GET /eu · GET /busca?q=nome (acha o tmdb_id)
  • GET|POST /historico · GET|POST|DELETE /watchlist · GET|POST /notas
  • GET /continuar — próximo episódio de cada série em andamento
  • POST /scrobble — para players
  • Especificação OpenAPI 3.1 (para Swagger UI, Postman e geradores de cliente): /api/v1/openapi.json

Seus tokens

    Seus apps (OAuth 2.0)

    Para apps usados por outras pessoas. Fluxo: código de autorização + PKCE (S256) obrigatório. Envie a pessoa para https://www.apertaplay.com/oauth/autorizar?response_type=code&client_id=…&redirect_uri=…&scope=leitura%20escrita&state=…&code_challenge=…&code_challenge_method=S256 e troque o código em POST https://www.apertaplay.com/api/oauth/token.

      Plex

      Registra sozinho o que você assiste no Plex (precisa de Plex Pass). Gere o link e cole em Plex → Configurações → Webhooks → Adicionar webhook.

      Jellyfin

      No Jellyfin, instale o plugin Webhook (Painel → Plugins → Catálogo). Adicione um destino Generic com o link gerado, marque os eventos Playback Start, Playback Progress e Playback Stop, os tipos Movies e Episodes, e use este modelo:

      {
  "NotificationType": "{{NotificationType}}",
  "NotificationUsername": "{{NotificationUsername}}",
  "ItemType": "{{ItemType}}",
  "Name": "{{Name}}",
  "SeriesName": "{{SeriesName}}",
  "Year": "{{Year}}",
  "SeasonNumber": "{{SeasonNumber}}",
  "EpisodeNumber": "{{EpisodeNumber}}",
  "Provider_tmdb": "{{Provider_tmdb}}",
  "Provider_imdb": "{{Provider_imdb}}",
  "Provider_tvdb": "{{Provider_tvdb}}",
  "PlaybackPositionTicks": "{{PlaybackPositionTicks}}",
  "RunTimeTicks": "{{RunTimeTicks}}",
  "PlayedToCompletion": "{{PlayedToCompletion}}",
  "IsPaused": "{{IsPaused}}"
}

      Emby

      No Emby (precisa de Emby Premiere): Configurações → Webhooks → Adicionar webhook. Cole o link gerado e marque os eventos de reprodução (início, pausa, parada) e "Marcado como assistido".

      Kodi

      O addon Aperta Play (pasta integracoes/kodi do projeto) registra sozinho o que você assiste no Kodi. Instale pelo arquivo .zip (Configurações → Addons → Instalar via arquivo .zip), abra as configurações do addon e cole um token criado acima com "Pode gravar". Ele usa os ids do IMDb, TVDB ou TMDB que o Kodi já conhece; sem eles, o nome do filme ou da série.