Relatórios para bibliotecas

API somente leitura que expõe, de forma programática, o que o painel de Relatórios da rede de bibliotecas mostra: KPIs agregados, engajamento diário por leitor, cadastro de leitores, acervo, estoque, empréstimos, reservas, acessos e sugestões de compra.

São cinco rotas, organizadas pelo grão do dado:

Acesso

Exemplo:

curl -s \
  -H 'X-Api-Key: <chave>' \
  'https://livros.arvore.com.br/api-arvore/libraries/v1/summary?startDate=2026-08-01&endDate=2026-08-31'

Convenções e tipos

• Tempo lido ou ouvido é sempre em segundos inteiros.
• Campos sem valor vêm como null, nunca omitidos.
• Parâmetros de data usam YYYY-MM-DD; outro formato responde 400.
• startDate e endDate são inclusivos. Quando opcionais e omitidos, valem os últimos 30 dias (de 30 dias atrás até hoje, em Brasília). Se startDate vier depois de endDate, o servidor inverte os dois.
• Parâmetros booleanos (newUsers) recebem a string true ou false.
• Ids de dimensão (libraryId, ageGroupId, publisherId, categoryId, subjectId) são inteiros. O /dimensions devolve esses ids como string; converta antes de enviar.
• Histórico começa em 2026-07-21, data de entrada da BibliON na plataforma. Empréstimos, devoluções, renovações e reservas anteriores não existem na base.

Paginação

page começa em 1 (default 1). pageSize tem default 100 e o máximo depende da rota:

pageSize acima do máximo responde 400. page vai até 100000. O total de linhas vem em meta.page.totalRows.

Janela máxima

/engagements, datasets/logins e datasets/channels aceitam no máximo 31 dias por chamada (400 acima disso). Ingestões maiores fatiam por mês.

Datas são YYYY-MM-DD e precisam existir no calendário: 2026-02-30 ou 2026-01-00 respondem 400.

Cliente HTTP

O host fica atrás de um WAF que barra requisições com o User-Agent padrão do urllib do Python (Python-urllib/3.x), respondendo 403 antes de a chamada chegar à API. Defina um User-Agent próprio na sua integração, por exemplo BibliON-Ingest/1.0. Clientes comuns (requests, axios, HttpClient do Java, Go) passam sem ajuste.

Atualização dos dados

Os dados vêm do lakehouse da Árvore, sincronizados ao longo do dia. Não são tempo real. As respostas são calculadas por hora cheia: meta.updatedAt traz essa hora (ex.: 2026-09-04 18:00:00), e a mesma consulta repetida devolve o mesmo resultado até a hora virar. Não há ganho em repetir a mesma chamada dentro da hora.

Envelope de resposta

Toda rota responde neste formato. data varia por rota; meta é sempre igual.

{
  "meta": {
    "updatedAt": "2026-08-27 09:59:12",
    "period": { "startDate": "2026-07-28", "endDate": "2026-08-27" },
    "page": { "page": 1, "pageSize": 100, "totalRows": 9317 }
  },
  "data": { }
}

meta.period aparece nas rotas que aceitam período (/summary, /engagements, /datasets/*). meta.page aparece nas respostas paginadas; no /summary só quando há groupBy. /dimensions traz apenas meta.updatedAt.

GET /libraries/v1/summary

Todos os agregados do painel numa chamada. Com groupBy, devolve também a quebra por dimensão.

Parâmetros

Escopo dos filtros: libraryId, state, city, ageGroupId, gender e newUsers recortam apenas os blocos general e breakdown. Os demais blocos (consumption, channels, formats, reservationsByStatus, stock, deletedUsers, catalogProfile, monthly) são sempre da base inteira no período.

data.general

data.consumption

data.channels

Sessões por canal de acesso, medidas pela ferramenta de analytics (PostHog).

data.formats

data.reservationsByStatus

data.stock

data.deletedUsers

Cadastros desativados ou excluídos desde 2026-07-21.

data.catalogProfile

data.monthly[]

data.breakdown[] (com groupBy)

Grupos sem valor no cadastro do leitor aparecem com label Não informado.

GET /libraries/v1/engagements

Engajamento diário no grão dia × leitor, esparso: uma linha por leitor por dia, somente quando houve atividade. Leitor sem métrica no dia não gera linha. Ordenação fixa date ASC, userId ASC, estável para ingestão incremental.

Somando as linhas de um dia, logins, loans, returns, readings10, readings50, previews, readingSeconds, renewals e reservations batem com o data.general do /summary para o mesmo dia. distinctBooks não soma: é distinto por leitor, e no /summary é distinto na base inteira.

Parâmetros

data.rows[]

GET /libraries/v1/users

Cadastro dos leitores. É o único lugar da API com dado nominal; as demais rotas referenciam o leitor por userId. Inclui ativos, desativados e excluídos. Ordenação fixa userId ASC.

Parâmetros

data.rows[]

A tela de cadastros excluídos do painel (e o bloco deletedUsers do /summary) soma deactivated e deleted com deletedAt a partir de 2026-07-21. status=deleted sozinho devolve só quem se excluiu, que é uma fração pequena desse total.

Sincronizar leitores com um CRM

Receita para manter uma base externa (HubSpot, RD Station, planilha) espelhando o cadastro, sem varrer tudo a cada rodada:

1. Carga inicial: percorra GET /libraries/v1/users?pageSize=1000&page=N em sequência, uma página por vez, até meta.page.totalRows. A rota passa pela fila de consultas pesadas, então páginas em paralelo podem responder 503; em sequência não. Ordem de referência: uma página de 1000 leva cerca de 2 segundos, e a base inteira (~636 mil leitores) sai em torno de 20 minutos. A ordenação é fixa por userId e cadastros excluídos continuam na lista (com status deleted), então paginar por page não perde nem repete linha enquanto a base cresce.
2. Rodada diária: chame GET /libraries/v1/users?updatedSince=<ontem> e aplique linha a linha: status diz se o contato segue ativo, foi bloqueado pela biblioteca (deactivated) ou se excluiu (deleted); updatedAt desempata quando a mesma pessoa aparece em duas rodadas. updatedSince tem grão de dia, então repita o dia anterior inteiro e deixe o userId ser a chave de deduplicação.
3. Chave do contato: use userId, nunca o e-mail. O e-mail pode mudar e, em cadastro excluído, é apagado na origem.
4. Frequência: os dados atualizam a cada hora cheia (meta.updatedAt); chamar mais de uma vez por hora devolve o mesmo resultado. Uma rodada por dia costuma bastar.

Não há webhook, evento push nem ambiente de homologação. A API é somente leitura e não altera nada na plataforma, então o próprio ambiente de produção é onde se integra: use uma janela curta (pageSize pequeno, ou updatedSince de ontem) para conferir o formato antes de rodar a carga inteira. A única forma de saber que um cadastro mudou é a rodada com updatedSince. Também não há telefone, endereço ou documento no payload; a API entrega o mínimo necessário para identificar e segmentar o contato (library, ageGroup, city, state, gender). Cadastros de menores de idade estão na base e aparecem com ageGroup correspondente: quem sincroniza para um CRM responde pelo tratamento desse dado no destino.

GET /libraries/v1/datasets/{name}

Dados linha a linha, paginados (máximo por página na tabela de paginação acima), com o envelope padrão. Linhas referenciam o leitor por userId e o título por bookId. Dataset desconhecido responde 404.

Parâmetro do vocabulário desta rota que não se aplica ao dataset é ignorado (ex.: status em books). Nome de parâmetro fora do vocabulário responde 400 com property <nome> should not exist, e isso inclui o antigo method de logins, que não existe mais. orderBy fora da lista do dataset, status fora do conjunto do dataset ou collection fora do vocabulário do dataset respondem 400.

datasets/books

Parâmetros: startDate/endDate (janela das métricas de uso), search (título ou ISBN), author, publisherId, categoryId, subjectId, collection (all | platform | additional | odilo | manual), format (ebook | audiobook), bookId, publicationYear, orderBy (title | loans | returns | readings10 | readings50 | readingSeconds | renewals | reservations | activeReservations | convertedReservations, default loans), orderDir (asc | desc, default desc), page/pageSize. Desempate por título e bookId, então a ordem é total e a paginação não repete linha.

datasets/stock

Sem período: é a foto atual do estoque. Parâmetros: purchasedFrom/purchasedTo (data da compra), consumptionBand (faixa do histograma, ex. 1-10), search, publisherId, categoryId, subjectId, collection (additional | odilo | manual; stock não aceita all nem platform, que não têm estoque próprio), bookId, publicationYear, orderBy (title | activeLoans | readings | possibleReadings | percentage | activeReservations, default percentage), orderDir (default desc), page/pageSize. Desempate por título e bookId.

datasets/loans

Parâmetros: startDate/endDate (sobre a data do empréstimo), userId, bookId, status (active | returned | expired), page/pageSize. Ordenação fixa: data do empréstimo e loanId, ascendentes.

A fonte não registra leitura por empréstimo individual nem o formato (ebook ou audiobook) escolhido no empréstimo. readingSeconds e progress são do par leitor × título; quem emprestou o mesmo livro duas vezes vê o mesmo valor nas duas linhas.

datasets/reservations

Ciclo completo da reserva, não só a fila ativa. Parâmetros: startDate/endDate (sobre reservedAt), status, userId, bookId, page/pageSize. Ordenação fixa: reservedAt e reservationId, ascendentes.

datasets/logins

Uma linha por leitor por dia em que ele teve qualquer atividade na plataforma (abrir a BibliON, navegar, ler, emprestar). É a mesma régua do logins do /summary e do /engagements: somando as linhas de um dia, bate com o data.general.logins desse dia. Parâmetros: startDate/endDate (default últimos 30 dias, máximo 31 dias), userId, page/pageSize. Ordenação fixa: date e userId, ascendentes. (date, userId) é chave única.

A plataforma não registra o login como evento próprio (a BibliON entra por link e SSO), por isso o grão é o dia com atividade e não a autenticação. A fonte também não registra o aparelho por leitor; a visão de aparelhos é a do dataset channels.

datasets/channels

Sessões por dia e aparelho, medidas pela ferramenta de analytics. Parâmetros: startDate/endDate (máximo 31 dias), channel. Não é paginado: vem a série inteira do período (page e pageSize são ignorados). Se o analytics não responder, a rota responde 503 e nada fica em cache; basta repetir a chamada depois.

datasets/suggestions

Sugestões de compra agregadas por título. Parâmetros: startDate/endDate, search, page/pageSize.

datasets/suggestion-requests

Cada solicitação individual. Parâmetros: startDate/endDate, title e author (comparação exata, ignorando maiúsculas e espaços nas pontas), userId, page/pageSize. Ordenação fixa: data e hora do pedido ascendentes, com desempate pelo id interno do pedido, então a paginação é estável durante a ingestão.

GET /libraries/v1/dimensions

Vocabulários válidos para os filtros das demais rotas. Sem parâmetros.

Erros

Corpo de erro padrão: { "statusCode": int, "error": string, "message": string | string[] }. Em erros de validação (400), message é uma lista com uma mensagem por parâmetro inválido.

Ingestão incremental (sugestão)

• Leitores: uma carga inicial paginada de /users e depois /users?updatedSince=<ontem> por dia. A alteração de status (desativação, exclusão) atualiza o registro e entra no recorte.
• Engajamento: /engagements?startDate=<dia>&endDate=<dia> por dia, paginando até totalRows. A chave natural é (date, userId).
• Empréstimos e reservas: datasets/loans e datasets/reservations pelo período de criação; a chave é loanId / reservationId. Como o status muda depois da criação, reprocessar os últimos 60 dias cobre devoluções, expirações e conversões.
• Agregados: /summary uma vez por dia com o período desejado, para conferência dos totais.

Fora do escopo

A aba Radar do painel (detectores, mapa de demanda, ações) não é exposta pela API. Aparelho amarrado a login individual não faz parte da v1; a visão de aparelhos é agregada, via dataset channels.