Relatórios de uso · Astorya para Parceiros

Nesta página

Consultar um mês
O que significa cada campo
Comprovação de entrega

Consultar um mês

GET/partner/v1/usage?month=YYYY-MM

O parâmetro month é obrigatório, no formato AAAA-MM (por exemplo, 2026-09). O mês corrente pode ser consultado a qualquer momento e mostra os números parciais.

curl

curl "https://api.astorya.com.br/partner/v1/usage?month=2026-09" \
  -u "$ASTORYA_CLIENT_ID:$ASTORYA_CLIENT_SECRET"

200 OK

{
  "month": "2026-09",
  "totals": {
    "activeUsers": 1284,
    "titlesStarted": 2310,
    "listeningSeconds": 9182340,
    "readingChapters": 4127
  },
  "users": [
    {
      "externalUserId": "usuario-10293",
      "titlesStarted": 3,
      "listeningSeconds": 41760,
      "lastActivityAt": "2026-09-29T07:41:12.000Z"
    },
    {
      "externalUserId": "usuario-20877",
      "titlesStarted": 1,
      "listeningSeconds": 5400,
      "lastActivityAt": "2026-09-14T19:03:55.000Z"
    }
  ]
}

O que significa cada campo

Campo	Significado
`month`	O mês consultado.
`totals.activeUsers`	Membros do seu tenant com alguma atividade (ouvir ou ler) no mês.
`totals.titlesStarted`	Títulos (audiolivros e e-books) que os membros começaram no mês, somando todos os membros.
`totals.listeningSeconds`	Tempo total de áudio ouvido no mês, em segundos. Divida por 3600 para ter horas.
`totals.readingChapters`	Capítulos de e-book lidos no mês.
`users[]`	Uma linha por membro com atividade no mês, identificado pelo seu `externalUserId`: `titlesStarted`, `listeningSeconds` e `lastActivityAt` (último uso no mês).

Como o relatório usa o externalUserId, você cruza os números com o seu cadastro sem que a Astorya precise de dados pessoais além dos que você enviou.

Comprovação de entrega

O relatório mensal registra, para cada membro identificado, que o conteúdo foi disponibilizado e efetivamente consumido — títulos iniciados, tempo de escuta e data do último uso. Por isso ele pode servir como evidência de entrega do benefício aos seus clientes, inclusive quando a sua empresa usa esse benefício em algum enquadramento fiscal.

Valide com a sua contabilidade. A Astorya fornece os dados de uso; se eles bastam como comprovação, e por quanto tempo precisam ser guardados, depende da regra fiscal que a sua empresa aplica. Leve um relatório de exemplo para o seu contador antes de fechar o processo.

Boas práticas de arquivo

Baixe o relatório a partir do dia 2 do mês seguinte, quando o mês já está fechado.
Guarde o JSON original, sem editar, junto com a data do download e um hash (SHA-256) do arquivo.
Mantenha pelo prazo que a sua contabilidade indicar — no Brasil, documentos com efeito fiscal costumam ser guardados por pelo menos 5 anos.
Gere a planilha para o contador a partir do JSON arquivado, não o contrário.

Job mensal (Python)

# Rode todo dia 2: baixa o mês anterior, arquiva o JSON e gera um CSV.
import csv
import datetime as dt
import hashlib
import os

import requests

ASTORYA_API = "https://api.astorya.com.br"
AUTH = (os.environ["ASTORYA_CLIENT_ID"], os.environ["ASTORYA_CLIENT_SECRET"])

first_of_this_month = dt.date.today().replace(day=1)
month = (first_of_this_month - dt.timedelta(days=1)).strftime("%Y-%m")

response = requests.get(
    f"{ASTORYA_API}/partner/v1/usage", params={"month": month}, auth=AUTH, timeout=30
)
response.raise_for_status()
raw = response.content

with open(f"astorya-uso-{month}.json", "wb") as f:
    f.write(raw)
with open(f"astorya-uso-{month}.json.sha256", "w") as f:
    f.write(hashlib.sha256(raw).hexdigest())

report = response.json()
with open(f"astorya-uso-{month}.csv", "w", newline="", encoding="utf-8") as f:
    writer = csv.writer(f)
    writer.writerow(["externalUserId", "titlesStarted", "listeningHours", "lastActivityAt"])
    for user in report["users"]:
        writer.writerow([
            user["externalUserId"],
            user["titlesStarted"],
            round(user["listeningSeconds"] / 3600, 2),
            user["lastActivityAt"],
        ])

print(month, report["totals"])