> ## Documentation Index > Fetch the complete documentation index at: https://developers.googa.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Métrica de engajamento agregada do período, sem granularidade de criança — planejado > **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. Retorna contagens agregadas no nível de **conta do parceiro como um todo** — nunca por criança, nunca por família individual, nunca com nome. Pensado para alimentar o painel de KPIs do parceiro (contas ativas, histórias concluídas no período) sem que nenhum dado identificável de menor deixe o perímetro do HistorinhAI. Ver [O que esta API deliberadamente não expõe](/historinhai/overview#o-que-esta-api-deliberadamente-não-expõe) para a justificativa completa de design. **Piso mínimo de amostra (k-anonimato).** Para evitar que um corte pequeno vire uma forma indireta de identificar uma família específica, a resposta suprime os campos numéricos (retorna `null`) sempre que `active_accounts` no período consultado fica abaixo de `min_sample_threshold` (hoje 30). Isso é deliberado mesmo sabendo que reduz a utilidade do endpoint em pilotos pequenos — um piloto de dezenas de milhares de usuários deve operar bem acima desse piso na maior parte dos recortes de período. Não aceita filtro por `subscriber_id`, por `child_id`, nem por qualquer outro identificador individual — o único parâmetro de recorte é a janela de tempo. ## OpenAPI ````yaml /historinhai/openapi.yaml get /engagement/summary openapi: 3.1.0 info: title: Googa HistorinhAI API — Parceiro version: 1.0.0 summary: >- Superfície de API específica do HistorinhAI para um parceiro de distribuição (ex: uma operadora). Deliberadamente pequena: por desenho de arquitetura, nenhum dado identificável de criança atravessa esta API. Entitlements, status de assinante e billing são resolvidos pela Googa Platform API (`api.googa.com.br`) — não repetidos aqui. description: >- Hoje só o app oficial (Web/PWA — não há apps nativos) consome o HistorinhAI, autenticando diretamente contra o Supabase do produto. Esta API é o contrato para um parceiro integrar sem acesso direto ao banco de dados de crianças. **Status:** nenhuma das duas operações deste arquivo está implementada. Hoje, a credencial de parceiro que o HistorinhAI aceita (no endpoint interno de entitlements, roteado pela Platform) é o token emitido **pela Platform API** (`https://api.googa.com.br`), verificado aqui com a chave pública do projeto Platform. O emissor próprio descrito abaixo e o `GET /engagement/summary` são **planejados — ainda não implementados**, e estão marcados como tal em cada operação. Leia [Visão geral do HistorinhAI](/historinhai/overview) antes de implementar contra este contrato — em especial a seção "O que esta API deliberadamente não expõe", que documenta a regra de arquitetura por trás do tamanho reduzido desta especificação: o HistorinhAI trata dados de crianças (LGPD + ECA) e roda em um projeto Supabase isolado dos demais produtos Googa (ver [Modelo de autenticação sobre Supabase](/architecture/supabase-auth-model)). contact: name: Googa — Suporte a parceiros email: developers@googa.com.br license: name: Uso restrito — ver Política de Uso da API url: https://developers.googa.com.br/security/api-usage-policy servers: - url: https://api.historinhai.com.br/v1 description: Produção (proposto) - url: https://sandbox.historinhai.com.br/v1 description: Sandbox (proposto) — dados fictícios, sem impacto em billing real security: - partnerOAuth2: [] tags: - name: OAuth2 description: Emissão de credencial de parceiro escopada ao HistorinhAI. - name: Engagement description: >- Métrica de engajamento agregada e anonimizada — sem granularidade de criança. paths: /engagement/summary: get: tags: - Engagement summary: >- Métrica de engajamento agregada do período, sem granularidade de criança — planejado description: >- **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. Retorna contagens agregadas no nível de **conta do parceiro como um todo** — nunca por criança, nunca por família individual, nunca com nome. Pensado para alimentar o painel de KPIs do parceiro (contas ativas, histórias concluídas no período) sem que nenhum dado identificável de menor deixe o perímetro do HistorinhAI. Ver [O que esta API deliberadamente não expõe](/historinhai/overview#o-que-esta-api-deliberadamente-não-expõe) para a justificativa completa de design. **Piso mínimo de amostra (k-anonimato).** Para evitar que um corte pequeno vire uma forma indireta de identificar uma família específica, a resposta suprime os campos numéricos (retorna `null`) sempre que `active_accounts` no período consultado fica abaixo de `min_sample_threshold` (hoje 30). Isso é deliberado mesmo sabendo que reduz a utilidade do endpoint em pilotos pequenos — um piloto de dezenas de milhares de usuários deve operar bem acima desse piso na maior parte dos recortes de período. Não aceita filtro por `subscriber_id`, por `child_id`, nem por qualquer outro identificador individual — o único parâmetro de recorte é a janela de tempo. operationId: getEngagementSummary parameters: - name: period_start in: query required: true schema: type: string format: date - name: period_end in: query required: true schema: type: string format: date description: >- Janela máxima suportada: 366 dias. Recomendamos alinhar ao ciclo mensal da Nota de Débito da Platform API para facilitar a correlação com billing. responses: '200': description: Resumo do período (possivelmente suprimido pelo piso de amostra). content: application/json: schema: $ref: '#/components/schemas/EngagementSummary' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': description: Token válido, mas sem o escopo `historinhai:engagement:read`. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: EngagementSummary: type: object description: >- Todo campo numérico é um agregado sobre a base completa de contas do parceiro no período — nunca uma lista, nunca uma linha por conta ou por criança. properties: period_start: type: string format: date period_end: type: string format: date active_accounts: type: integer nullable: true description: >- Contas do parceiro com ao menos um entitlement HistorinhAI ativo em algum momento do período. `null` se abaixo do piso de amostra. stories_completed: type: integer nullable: true description: >- Total de histórias concluídas por qualquer criança de qualquer conta do parceiro no período, somado sem distinção de conta ou criança. `null` se abaixo do piso de amostra. avg_minutes_per_active_account: type: number nullable: true description: >- Minutos lidos no período, somados por conta e depois em média entre contas. min_sample_threshold: type: integer example: 30 description: >- Piso mínimo de `active_accounts` exigido para retornar os campos acima. suppressed: type: boolean description: >- `true` quando os campos numéricos foram omitidos por estarem abaixo do piso de amostra. generated_at: type: string format: date-time Error: type: object description: >- Mesmo formato de erro (estilo OAuth2, RFC 6749 §5.2) usado pela Platform API. properties: error: type: string example: invalid_request error_description: type: string example: Janela de período inválida responses: BadRequest: description: >- Requisição inválida — inclui tentativas de filtrar por identificador individual (assinante, família ou criança), que este endpoint não aceita por desenho. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Credenciais ausentes, inválidas ou expiradas. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: partnerOAuth2: type: oauth2 description: >- Client credentials, escopado ao HistorinhAI — ver `/oauth2/token` acima (**planejado**: hoje o emissor que existe é o da Platform API, em `https://api.googa.com.br/v1/oauth2/token`). flows: clientCredentials: tokenUrl: https://api.historinhai.com.br/v1/oauth2/token scopes: historinhai:engagement:read: Consultar métrica de engajamento agregada do período ````