Iniziare con l'API

Crea una chiave API, fai la tua prima chiamata e leggi la risposta. L'API di TrueRoyalties permette a un foglio di calcolo, uno script o un'automazione di leggere i tuoi numeri.

L'API di TrueRoyalties permette ai tuoi strumenti — un foglio di calcolo, uno script, un'automazione — di leggere i numeri che vedi nell'app: royalty, spesa pubblicitaria e profitto netto, per libro e per marketplace, più le pagine lette su Kindle Unlimited, i download gratuiti e la lettura delle serie.

È in sola lettura. Una chiave legge tutto il tuo account e non modifica nulla: nessuna sincronizzazione, nessuna impostazione, nessun libro. L'API è inclusa in tutti i piani e durante la prova gratuita.

Per chiedere a claude.ai o ChatGPT dei tuoi numeri non serve una chiave: vedi Collega un assistente IA.

1. Crea una chiave

Impostazioni → API → Crea una chiave. Dalle il nome dello strumento che la userà, per esempio «Google Sheets», poi copia la chiave. Inizia con tr_live_ e viene mostrata una sola volta.

La scheda API delle Impostazioni, con una chiave chiamata Google Sheets, l'inizio della chiave, la data di creazione e «Mai» come ultimo utilizzo

Quante chiavi puoi avere e come revocarne una: Autenticazione e chiavi API.

2. Fai la tua prima chiamata

Ogni richiesta va a https://author.trueroyalties.com/api/v1 e porta la tua chiave nell'intestazione Authorization:

curl https://author.trueroyalties.com/api/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

/account è una buona prima chiamata: dimostra che la chiave funziona e ti dice quanto sono aggiornati i tuoi dati.

{
  "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. Chiedi i tuoi numeri

/summary restituisce i totali di un periodo, gli stessi numeri delle schede della tua dashboard:

curl "https://author.trueroyalties.com/api/v1/summary?range=last_30_days" \
  -H "Authorization: Bearer YOUR_API_KEY"

Tre campi da leggere in ogni report:

Campo	Cosa ti dice
`period`	I giorni esatti coperti, e il fuso orario che decide quale giorno è «oggi».
`currency`	La valuta di ogni importo. Di default la tua valuta di report; aggiungi `currency=EUR` per cambiarla.
`meta.truncated`	`true` quando alcune righe non sono state lette, quindi i numeri possono essere incompleti. Chiedi un periodo più breve.

Periodi, valute e arrotondamenti sono spiegati in Limiti ed errori.

Cosa puoi leggere

Endpoint	Restituisce
`GET /api/v1/account`	Valuta di report, abbonamento, piattaforme collegate e la loro ultima sincronizzazione
`GET /api/v1/summary`	I totali di un periodo
`GET /api/v1/timeline`	Gli stessi numeri, giorno per giorno o mese per mese
`GET /api/v1/reports/books`	Una riga per libro
`GET /api/v1/reports/marketplaces`	Una riga per marketplace
`GET /api/v1/books`	Il tuo catalogo
`GET /api/v1/series`	Le tue serie, con i loro libri in ordine
`GET /api/v1/kenp`	Pagine lette su Kindle Unlimited
`GET /api/v1/kenp/books`	Pagine lette, libro per libro
`GET /api/v1/free-units`	Download gratuiti, mai contati come royalty
`GET /api/v1/series/{series_id}/read-through`	La lettura di una serie, libro per libro

Ogni parametro e ogni campo sono nel riferimento dell'API (in inglese). Il suo pulsante Try it è precompilato con una chiave demo pubblica: puoi provare ogni endpoint senza account, e le risposte arrivano allora dai numeri fittizi dell'account demo.

Impostazioni Autenticazione e chiavi API