Skip to main content
Hoje só o app oficial (Web/PWA — não há apps nativos) consome o HistorinhAI, autenticando diretamente contra o projeto Supabase do produto. Esta página descreve o contrato para um parceiro (ex: uma operadora) integrar sem acesso direto ao banco de dados de crianças.

​
Por que esta API é bem menor que NovelAI/NovelAudio

Isso não é um contrato incompleto — é o tamanho correto para o problema. O HistorinhAI trata dados de crianças, e a proposta técnica original à Algar já assume essa restrição explicitamente na seção de segurança: “dados da criança sob responsabilidade dos pais, sem perfilamento comercial de menores” (Proteção infantil — ECA). Levamos essa frase a sério como regra de arquitetura, não como intenção de marketing: o desenho abaixo assume, desde o primeiro endpoint, que nenhum parceiro externo — mesmo um parceiro contratual como a Algar, mesmo com consentimento parental válido para o app funcionar — recebe dado identificável de uma criança individual. Repassar isso a um terceiro é uma superfície de risco de LGPD (Lei 13.709/2018) e do Estatuto da Criança e do Adolescente (Lei 8.069/1990) que nenhum ganho comercial de integração justifica. Consequência prática: a integração de parceiro no HistorinhAI resolve apenas dois problemas — “o assinante tem direito de acesso?” (Entitlements, já coberto pela Platform API e não repetido aqui) e “como está o engajamento agregado da minha base neste produto?” (um único endpoint de métrica, sem granularidade de criança, ainda planejado — ver abaixo). Não há endpoint de catálogo, de perfil de criança, de progresso individual, de relatório ou de conteúdo. Se uma futura necessidade comercial exigir mais do que isso, o desenho correto é resolvê-la dentro do app oficial (onde o responsável está autenticado e no controle), não abrir uma nova rota nesta API — ver O que esta API deliberadamente não expõe.

​
Isolamento de dados e infraestrutura

api.historinhai.com.br aponta para um projeto Supabase próprio, isolado do projeto que atende NovelAI e NovelAudio — decisão deliberada, não uma consequência acidental de como o produto foi construído. Ver Modelo de autenticação sobre Supabase para o desenho completo de domínios; o ponto relevante aqui é que esse isolamento é a primeira camada de defesa por trás de tudo nesta página — mesmo que a credencial de parceiro de outro produto Googa fosse comprometida, ela não teria como alcançar o banco de dados do HistorinhAI, porque é fisicamente outro projeto, com outra base de dados e outro conjunto de chaves. Hoje a credencial de parceiro que o HistorinhAI reconhece é a emitida centralmente pela Platform API; um emissor próprio, sob este domínio e com par de chaves independente, é planejado — ainda não implementado — ver Autenticação abaixo.

​
O que esta API oferece

Credencial de parceiro

Hoje: o token vem do emissor central da Platform API (POST https://api.googa.com.br/v1/oauth2/token). Um POST /oauth2/token próprio deste domínio, escopado a historinhai:engagement:read, é planejado — ainda não implementado.

Engajamento agregado (planejado)

GET /engagement/summary — planejado, ainda não implementado: contas ativas, histórias concluídas e minutos médios por conta ativa (avg_minutes_per_active_account) no período, agregado sobre toda a base do parceiro. Sem lista, sem linha por conta, sem linha por criança. Ver Referência para o contrato completo.
Isso é tudo. Qualquer outra necessidade de integração do parceiro com o HistorinhAI — ativar acesso, verificar status de assinante, reportar uso para billing, autenticar o assinante via SSO — já está coberta pela Platform API, que é a mesma para os três produtos e não trata dado de criança em nenhum momento (o subscriber_id ali é o identificador do responsável, no sistema do parceiro).

​
O que esta API deliberadamente não expõe

Esta seção é tão importante quanto a anterior. Cada item abaixo foi considerado e excluído por uma razão específica — não por falta de tempo de desenho.
O app mantém, por criança, nome, data de nascimento e um avatar escolhido pelos pais (perfil gerido dentro de uma conta-família, com até 6 crianças). Nenhum desses campos tem contrapartida em qualquer endpoint desta API. Um parceiro nunca tem motivo de negócio legítimo para saber o nome ou a idade exata de uma criança específica — só se ela tem, na agregada, uma conta com acesso ativo, o que já é resolvido pelo Entitlements da Platform API no nível do responsável.
Texto literal de histórias, respostas do mini-desafio lúdico (quiz/conversa guiada) e qualquer transcrição de interação da criança com o app não têm — e não terão — um endpoint de leitura para parceiro. Isso é conteúdo de uma interação privada entre a criança, o responsável e o app; expor isso a um terceiro comercial não passa o teste de finalidade da LGPD (a finalidade da coleta é a experiência de leitura em si, não telemetria de terceiro).
Sequência de leitura, pontos, minutos lidos e o relatório de desenvolvimento que o app entrega aos pais (histórias lidas, tempo compartilhado, competências percebidas) existem para o responsável dentro do próprio app — nunca como resposta de API para um parceiro. Isso vale mesmo agregado por criança ao longo do tempo: um parceiro que conseguisse reconstruir a trajetória de leitura de uma criança específica teria, na prática, um perfil comportamental de um menor — exatamente o que a cláusula de “sem perfilamento comercial de menores” da proposta técnica existe para impedir.
O app registra quem participou de cada sessão de leitura (a própria criança, um responsável, outro membro da família) para alimentar estatísticas de uso compartilhado dentro do app. Esse detalhe por sessão nunca é individualmente endereçável via API de parceiro — só entra, sem identificação de sessão ou de criança, no agregado de stories_completed do endpoint de engajamento.
Quantos adultos compõem uma conta-família, quem é o responsável principal e convites pendentes são informação de gestão de conta dentro do app — não fazem parte de nenhum contrato de parceiro. Do ponto de vista do parceiro, uma conta-família é só uma unidade anônima que conta para active_accounts.
Deliberadamente sem endpoint de catálogo — diferente de NovelAI/NovelAudio, onde listar o catálogo para o parceiro tem uma razão de negócio clara (o parceiro pode querer promover títulos). No HistorinhAI não identificamos uma razão de negócio equivalente: a curadoria por faixa etária e por desafio do mês é parte do valor do produto e permanece uma decisão editorial interna, exercida dentro do app, sob supervisão dos pais. Expor externamente o mapeamento entre título e faixa etária também aumentaria, ainda que marginalmente, o risco de combinação com dados de uso agregados para inferir características de uma criança — risco que não compensa o ganho de expor um catálogo que o parceiro não tem como comercializar por conta própria.
GET /engagement/summary aceita apenas uma janela de tempo como parâmetro. Não existe, e não está desenhada, uma versão com subscriber_id, family_id ou child_id como filtro — isso transformaria um agregado seguro em uma consulta pontual sobre uma família específica. O piso mínimo de amostra (min_sample_threshold, 30 contas ativas no desenho) documentado na Referência de GET /engagement/summary existe pelo mesmo motivo: impedir que um corte de período pequeno demais funcione como um jeito indireto de isolar uma conta.

​
Autenticação

Toda chamada usa OAuth2 client credentials, o mesmo grant da Platform API. Hoje, a credencial vem do emissor central da Platform (POST https://api.googa.com.br/v1/oauth2/token) — o HistorinhAI valida o token recebido contra a chave pública do projeto Platform, e é assim que o endpoint interno de entitlements (roteado pela Platform) funciona no código. Um emissor próprio deste domínio (POST /oauth2/token em api.historinhai.com.br, com par de chaves independente e escopo único historinhai:engagement:read) é planejado — ainda não implementado: foi deliberadamente adiado para uma revisão dedicada, por ser o produto que trata dado de criança. Ver Modelo de autenticação sobre Supabase para o racional de defesa em profundidade por trás desse desenho.

​
Proteção de dados de crianças

O raciocínio de compliance por trás de cada exclusão listada acima — a base legal na LGPD e no ECA, como o consentimento parental é obtido e mantido dentro do app, e como isso se relaciona com as práticas de segurança da informação da Googa — está documentado em Proteção de dados de menores (ECA). Esta página descreve o quê a API não expõe; aquela descreve o porquê legal e operacional com mais profundidade.