# Googa Developers

> Documentação técnica das APIs da Googa — NovelAI, HistorinhAI e NovelAudio. Integração via API, SSO, entitlements, billing, webhooks, segurança e LGPD.

## Docs

- [Modelo de dados](https://developers.googa.com.br/architecture/data-model.md): O vocabulário de entidades por trás da API — Subscriber, User, Reader/Listener, o grafo de conteúdo, Entitlement e Event — sem expor o schema SQL completo.
- [Modelo multi-tenant](https://developers.googa.com.br/architecture/multi-tenant-model.md): Como o isolamento funciona em dois eixos independentes — entre parceiros que integram a mesma API, e entre produtos com sensibilidade de dado diferente.
- [Visão geral da arquitetura](https://developers.googa.com.br/architecture/overview.md): O mapa de camadas da plataforma Googa e as decisões de engenharia por trás de cada peça.
- [Modelo de autenticação sobre Supabase](https://developers.googa.com.br/architecture/supabase-auth-model.md): Como identidade de leitor, identidade de parceiro e domínio customizado se combinam em cima do Supabase.
- [HistorinhAI API — visão geral](https://developers.googa.com.br/historinhai/overview.md): A API de parceiro do HistorinhAI é deliberadamente pequena: nenhum dado identificável de criança sai do perímetro do produto. Isso é regra de arquitetura, não uma limitação técnica.
- [Métrica de engajamento agregada do período, sem granularidade de criança — planejado](https://developers.googa.com.br/historinhai/reference/engagement/métrica-de-engajamento-agregada-do-período-sem-granularidade-de-criança-—-planejado.md): **Planejado — ainda não implementado.** Este endpoint (e o Partner Gateway próprio e isolado que o servirá) foi deliberadamente adiado para uma revisão dedicada, dado o tratamento de dado de criança. O contrato abaixo é o desenho de destino.
- [Troca client credentials por um token escopado ao HistorinhAI — planejado](https://developers.googa.com.br/historinhai/reference/oauth2/troca-client-credentials-por-um-token-escopado-ao-historinhai-—-planejado.md): **Planejado — ainda não implementado.** Hoje o HistorinhAI **não** emite token próprio: a única credencial de parceiro que ele reconhece é o token emitido pela Platform API (`POST https://api.googa.com.br/v1/oauth2/token`, ver [Platform — OAuth2](/platform/reference/oauth2/troca-client-credentials-p…
- [Googa Developers](https://developers.googa.com.br/index.md): APIs para integrar NovelAI, HistorinhAI e NovelAudio como SVA (Serviço de Valor Agregado) em operadoras e parceiros de distribuição.
- [NovelAI API — visão geral](https://developers.googa.com.br/novelai/overview.md): Catálogo, capítulos liberados pelo drip diário, progresso de leitura e finais ramificados — a API específica de produto do NovelAI.
- [Métricas agregadas de engajamento de leitura, por parceiro e período](https://developers.googa.com.br/novelai/reference/analytics/métricas-agregadas-de-engajamento-de-leitura-por-parceiro-e-período.md): Suporte aos indicadores prometidos na proposta (DAU/MAU do ritual diário, take-rate, retenção) — sempre agregado ao nível do parceiro, nunca por assinante. Nenhuma resposta desta rota inclui `subscriber_id` em nenhum nível; ver [Privacidade & LGPD](/security/lgpd) para o racional.
- [Detalhe de uma novela](https://developers.googa.com.br/novelai/reference/catalog/detalhe-de-uma-novela.md)
- [Lista as categorias/gêneros do catálogo](https://developers.googa.com.br/novelai/reference/catalog/lista-as-categoriasgêneros-do-catálogo.md): Utilitário para montar filtros (`category_id` em `GET /novels`) sem depender de uma lista de slugs fixa. Espelha `public.categories`, tabela de leitura pública mesmo no app oficial (não passa por RLS de leitor).
- [Lista o catálogo de novelas](https://developers.googa.com.br/novelai/reference/catalog/lista-o-catálogo-de-novelas.md): Metadados de catálogo — título, sinopse, categoria, tags editoriais e contagem de capítulos. Não inclui conteúdo de leitura (isso é gated por assinante; ver `GET /novels/{id}/chapters`) nem os finais (`GET /novels/{id}/choices`). Equivalente ao que `public.novels` mais `total_chapters()` expõem hoje…
- [Lista os capítulos de uma novela e, opcionalmente, o estado de liberação para um assinante](https://developers.googa.com.br/novelai/reference/chapters/lista-os-capítulos-de-uma-novela-e-opcionalmente-o-estado-de-liberação-para-um-assinante.md): Sem `subscriber_id`, devolve só o metadado editorial de cada capítulo (número, título, duração estimada) — o equivalente à função interna `list_novel_chapters()`, que não é gated pelo drip porque é metadado, não conteúdo. Com `subscriber_id`, cada capítulo ganha `status` e, quando bloqueado, uma est…
- [Finais disponíveis de uma novela para um assinante](https://developers.googa.com.br/novelai/reference/choices/finais-disponíveis-de-uma-novela-para-um-assinante.md): Os finais só existem, do ponto de vista de conteúdo, quando o drip libera o último capítulo **para aquele assinante especificamente** — é por isso que `subscriber_id` é obrigatório aqui (diferente de `GET /novels/{id}/chapters`, onde é opcional): não há metadado de finais que possa ser mostrado sem…
- [Novelfinished](https://developers.googa.com.br/novelai/reference/novelfinished.md): Disparado quando um assinante escolhe um final e conclui uma novela (`reading_progress.finished_at` passa de nulo para preenchido) — uma escrita discreta, então mapeia bem no modelo de Database Webhooks nativo do Supabase, descrito em [Modelo de autenticação sobre Supabase](/architecture/supabase-au…
- [Progresso de leitura consolidado de um assinante](https://developers.googa.com.br/novelai/reference/progress/progresso-de-leitura-consolidado-de-um-assinante.md): Uma linha por novela que o assinante já abriu — em andamento ou concluída. Nomeado no singular (`subscriber`, não `subscribers`) para seguir a mesma convenção de `GET /subscriber-status/{id}` na Platform API.
- [NovelAudio — visão geral](https://developers.googa.com.br/novelaudio/overview.md): Catálogo em áudio, streaming de capítulo e posição de reprodução — e por que isto vive no domínio do NovelAI.
- [Metadados de áudio de uma novela (por capítulo)](https://developers.googa.com.br/novelaudio/reference/audio-metadata/metadados-de-áudio-de-uma-novela-por-capítulo.md): Espelha as tabelas reais `novel_chapters` (metadado do catálogo: título, duração estimada) e `chapter_audio` (metadado do áudio pré-renderizado: voz usada, duração real, status) do mesmo grafo de narrativa do NovelAI — mesma obra, mesmos finais (ver [NovelAI — catálogo](/novelai/reference/catalog/li…
- [Atualiza a posição de reprodução do assinante em uma novela](https://developers.googa.com.br/novelaudio/reference/playback/atualiza-a-posição-de-reprodução-do-assinante-em-uma-novela.md): Upsert por (assinante, novela) — equivalente ao `onConflict: "user_id,novel_id"` já usado pelo app oficial. Chamar de novo com o mesmo `novel_id` substitui a posição anterior; não acumula histórico — por isso repetir a chamada é seguro, sem precisar de header de idempotência (o mecanismo de `Idempot…
- [Consulta a posição de reprodução do assinante em uma novela](https://developers.googa.com.br/novelaudio/reference/playback/consulta-a-posição-de-reprodução-do-assinante-em-uma-novela.md): **Nota de contrato pendente:** este path usa `subscribers` (plural), enquanto a Platform API usa o singular (`/subscriber-status/{id}`). A escolha do path final é uma decisão em aberto do dono da API antes de qualquer implementação — este endpoint, como o resto deste arquivo, é roadmap. Espelha a ta…
- [Emite uma URL de reprodução assinada para um capítulo liberado](https://developers.googa.com.br/novelaudio/reference/streaming/emite-uma-url-de-reprodução-assinada-para-um-capítulo-liberado.md): Verifica entitlement (plano do assinante inclui áudio + capítulo já liberado pela cadência de 1 capítulo/dia — mesma regra de drip do NovelAI, com acesso antecipado no plano VIP) antes de emitir a URL. Nunca devolve o áudio bruto no corpo da resposta — apenas a URL assinada de curta duração para o p…
- [Lista vozes de narração disponíveis](https://developers.googa.com.br/novelaudio/reference/voices/lista-vozes-de-narração-disponíveis.md): **Roadmap de ponta a ponta — não existe catálogo de vozes hoje.** Duas coisas diferentes existem no projeto e nenhuma delas é isto: 1. O app NovelAudio toca **áudio pré-gravado** (bucket privado `chapter-audio`, servido por URL assinada via a Edge Function `audio-url`) — a voz de cada capítulo é a v…
- [Platform API — visão geral](https://developers.googa.com.br/platform/overview.md): Entitlements, status de assinante, billing e webhooks — a base compartilhada por todo parceiro Googa.
- [Consulta o consumo do período para reconciliação de billing](https://developers.googa.com.br/platform/reference/billing/consulta-o-consumo-do-período-para-reconciliação-de-billing.md): Contagem de exemplares ativos do parceiro no produto, base para a Nota de Débito mensal.
- [Ativa, suspende ou cancela o acesso de um assinante a um produto](https://developers.googa.com.br/platform/reference/entitlements/ativa-suspende-ou-cancela-o-acesso-de-um-assinante-a-um-produto.md): Upsert por (parceiro, assinante, produto): chamar novamente com o mesmo assinante/produto e um status diferente atualiza o entitlement existente — não cria duplicado. Por ser um upsert, repetir a mesma chamada é seguro; não há (nem é necessário) um header `Idempotency-Key` — esse mecanismo chegou a…
- [Chave pública (JWKS) do emissor de tokens de parceiro](https://developers.googa.com.br/platform/reference/keys/chave-pública-jwks-do-emissor-de-tokens-de-parceiro.md): Endpoint público (sem autenticação) com a chave pública ES256 usada para verificar a assinatura do JWT de serviço emitido por `POST /oauth2/token`. É assim que os projetos de produto (Novel, HistorinhAI) validam o token do parceiro sem depender de segredo compartilhado. Respondido com `Cache-Control…
- [Início do login federado do assinante (SSO OIDC) — planejado](https://developers.googa.com.br/platform/reference/oauth2/início-do-login-federado-do-assinante-sso-oidc-—-planejado.md): **Planejado — ainda não implementado.** Não existe hoje nenhum endpoint de SSO em nenhum ambiente, e nenhum IdP de parceiro está configurado. Esta operação documenta o contrato de destino, não algo disponível para chamada.
- [Troca client credentials por um token de acesso de parceiro](https://developers.googa.com.br/platform/reference/oauth2/troca-client-credentials-por-um-token-de-acesso-de-parceiro.md): Implementa o grant `client_credentials` do OAuth 2.0 (RFC 6749 §4.4). O token retornado autentica chamadas de servidor-a-servidor (Entitlements, Subscriber, Billing) — não é um token de usuário final. TTL curto (10 minutos); o cliente deve renovar antes de expirar, não reutilizar tokens vencidos.
- [Consulta o status de um assinante em um produto](https://developers.googa.com.br/platform/reference/subscriber/consulta-o-status-de-um-assinante-em-um-produto.md): Consulta pontual do entitlement de um assinante para **um produto por chamada** — o parâmetro `product` é obrigatório. Agregar todos os produtos numa única resposta fica para uma versão futura, quando um segundo parceiro/produto justificar o fan-out.
- [Subscriberupdated](https://developers.googa.com.br/platform/reference/subscriberupdated.md): Disparado quando o entitlement de um assinante muda do lado da Googa (criação ou atualização de status/plano). Assinado via HMAC-SHA256 do corpo bruto, entregue com os headers `X-Googa-Signature: sha256=<hmac-hex>` e `X-Googa-Event: subscriber.updated` — ver a verificação passo a passo em [Eventos (…
- [Subscriptioncanceled](https://developers.googa.com.br/platform/reference/subscriptioncanceled.md): Disparado quando o status do entitlement transiciona para `canceled`. Mesmo formato de payload e de assinatura do `subscriber.updated` (headers `X-Googa-Signature` e `X-Googa-Event: subscription.canceled`); o payload não inclui campo de motivo do cancelamento — o parceiro é a fonte desse status, ent…
- [Política de Uso da API](https://developers.googa.com.br/security/api-usage-policy.md): Termos que regem o uso das credenciais e dos endpoints da API de parceiro Googa — elegibilidade, uso aceitável, segurança de credenciais, limites, IP e rescisão.
- [Proteção de dados de crianças — LGPD Art. 14 & ECA](https://developers.googa.com.br/security/child-data-eca.md): Consentimento parental, proibição de perfilamento comercial, retenção reforçada e o direito dos pais de excluir os dados do filho — o tratamento específico do HistorinhAI.
- [Mapeamento de fluxo de dados](https://developers.googa.com.br/security/data-processing.md): Onde cada dado entra, em qual projeto Supabase é processado e armazenado, quem tem acesso interno, e como um pedido de exclusão se propaga pelas tabelas.
- [Resposta a incidentes](https://developers.googa.com.br/security/incident-response.md): Classificação de severidade, tempos de resposta e o fluxo de comunicação — incluindo quando um incidente com dados pessoais aciona a ANPD.
- [LGPD — bases legais, direitos e governança de dados](https://developers.googa.com.br/security/lgpd.md): Como a Lei 13.709/2018 se aplica a cada relação de tratamento da Googa — bases legais, papéis (controlador/operador), direitos do titular, retenção, DPO, RIPD e transferência internacional.
- [Segurança da informação — visão geral](https://developers.googa.com.br/security/overview.md): Criptografia, isolamento multi-tenant e defesa em profundidade: o que já está em produção hoje e o que é desenho de destino.
- [Política de Privacidade da API](https://developers.googa.com.br/security/privacy-policy.md): Como a Googa trata dados pessoais especificamente no fluxo de integração via API de parceiro — papéis de controlador/operador, dados trafegados, retenção e direitos do titular.
- [Divulgação responsável de vulnerabilidades](https://developers.googa.com.br/security/vulnerability-disclosure.md): Como reportar uma vulnerabilidade de segurança encontrada em qualquer produto ou API da Googa, e o que esperamos em troca.

## OpenAPI Specs

- [openapi](https://developers.googa.com.br/platform/openapi.yaml)