Primeiros passos com a API
Crie uma chave de API, faça sua primeira chamada e leia a resposta. A API do TrueRoyalties permite que uma planilha, um script ou uma automação leiam seus números.
A API do TrueRoyalties permite que suas próprias ferramentas — uma planilha, um script, uma automação — leiam os números que você vê no app: royalties, gastos com anúncios e lucro líquido, por livro e por marketplace, além das páginas lidas no Kindle Unlimited, dos downloads gratuitos e da leitura das séries.
Ela é somente leitura. Uma chave lê toda a sua conta e não altera nada: nenhuma sincronização, nenhuma configuração, nenhum livro. A API está incluída em todos os planos e durante o teste gratuito.
Para perguntar ao claude.ai ou ao ChatGPT sobre seus números, você não precisa de chave: veja Conectar um assistente de IA.
1. Crie uma chave
Configurações → API → Criar uma chave. Dê a ela o nome da ferramenta que vai
usá-la, por exemplo "Google Sheets", e copie a chave. Ela começa com tr_live_ e é
mostrada uma única vez.
Quantas chaves você pode ter e como revogar uma: Autenticação e chaves de API.
2. Faça sua primeira chamada
Cada requisição vai para https://author.trueroyalties.com/api/v1 e leva sua chave
no cabeçalho Authorization:
curl https://author.trueroyalties.com/api/v1/account \
-H "Authorization: Bearer YOUR_API_KEY"/account é uma boa primeira chamada: prova que a chave funciona e mostra o quão
atualizados estão seus dados.
{
"reporting_currency": "USD",
"is_demo": false,
"subscription": { "status": "active" },
"platforms": [
{
"platform_id": "amazon-kdp",
"name": "Amazon KDP",
"connected": true,
"last_sync_at": "2026-09-15T08:02:11.000Z",
"sync_status": "success",
"covered_through": "2026-09-14"
}
],
"api_key": {
"name": "Google Sheets",
"start": "tr_live_ab12",
"scopes": ["read"],
"created_at": "2026-09-15T07:55:00.000Z",
"last_used_at": null
},
"connected_app": null
}3. Peça seus números
/summary devolve os totais de um período, os mesmos números dos cartões do seu
painel:
curl "https://author.trueroyalties.com/api/v1/summary?range=last_30_days" \
-H "Authorization: Bearer YOUR_API_KEY"Três campos para ler em todo relatório:
| Campo | O que ele diz |
|---|---|
period | Os dias exatos cobertos, e o fuso horário que decide qual dia é "hoje". |
currency | A moeda de cada valor. Por padrão, sua moeda de relatório; adicione currency=EUR para mudá-la. |
meta.truncated | true quando algumas linhas não puderam ser lidas, então os números podem estar incompletos. Peça um período menor. |
Períodos, moedas e arredondamento são explicados em Limites e erros.
O que você pode ler
| Endpoint | Devolve |
|---|---|
GET /api/v1/account | Moeda de relatório, assinatura, plataformas conectadas e a última sincronização |
GET /api/v1/summary | Os totais de um período |
GET /api/v1/timeline | Os mesmos números, dia a dia ou mês a mês |
GET /api/v1/reports/books | Uma linha por livro |
GET /api/v1/reports/marketplaces | Uma linha por marketplace |
GET /api/v1/books | Seu catálogo |
GET /api/v1/series | Suas séries, com os livros em ordem |
GET /api/v1/kenp | Páginas lidas no Kindle Unlimited |
GET /api/v1/kenp/books | Páginas lidas, livro por livro |
GET /api/v1/free-units | Downloads gratuitos, nunca contados como royalties |
GET /api/v1/series/{series_id}/read-through | A leitura de uma série, livro por livro |
Cada parâmetro e cada campo estão na referência da API (em inglês). O botão Try it vem preenchido com uma chave de demonstração pública: você pode testar cada endpoint sem conta, e as respostas vêm então dos números fictícios da conta de demonstração.