Démarrer avec l'API

Crée une clé d'API, fais ton premier appel et lis la réponse. L'API TrueRoyalties permet à un tableur, un script ou une automatisation de lire tes chiffres.

L'API TrueRoyalties permet à tes propres outils — un tableur, un script, une automatisation — de lire les chiffres que tu vois dans l'app : royalties, dépenses pub et bénéfice net, par livre et par marketplace, ainsi que les pages lues Kindle Unlimited, les téléchargements gratuits et la lecture des séries.

Elle est en lecture seule. Une clé lit tout ton compte et ne modifie rien : aucune synchro, aucun réglage, aucun livre. L'API est incluse dans toutes les formules et pendant l'essai gratuit.

Pour interroger claude.ai ou ChatGPT sur tes chiffres, pas besoin de clé : voir Connecter un assistant IA.

1. Crée une clé

Réglages → API → Créer une clé. Donne-lui le nom de l'outil qui va l'utiliser, par exemple « Google Sheets », puis copie la clé. Elle commence par tr_live_ et n'est affichée qu'une seule fois.

L'onglet API des paramètres, avec une clé nommée Google Sheets, le début de la clé, sa date de création et « Jamais » comme dernière utilisation

Combien de clés tu peux avoir et comment en révoquer une : Authentification et clés d'API.

2. Fais ton premier appel

Chaque requête part vers https://author.trueroyalties.com/api/v1 et porte ta clé dans l'en-tête Authorization :

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

/account est un bon premier appel : il prouve que la clé marche et te dit à quel point tes données sont fraîches.

{
  "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. Demande tes chiffres

/summary renvoie les totaux d'une période, les mêmes chiffres que les cartes de ton tableau de bord :

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

Trois champs à lire dans chaque rapport :

Champ	Ce qu'il te dit
`period`	Les jours exacts couverts, et le fuseau horaire qui décide quel jour est « aujourd'hui ».
`currency`	La devise de chaque montant. Par défaut ta devise de rapport ; ajoute `currency=EUR` pour la changer.
`meta.truncated`	`true` quand certaines lignes n'ont pas pu être lues : les chiffres peuvent être incomplets. Demande une période plus courte.

Les périodes, les devises et les arrondis sont expliqués dans Limites et erreurs.

Ce que tu peux lire

Endpoint	Renvoie
`GET /api/v1/account`	Devise de rapport, abonnement, plateformes connectées et leur dernière synchro
`GET /api/v1/summary`	Les totaux d'une période
`GET /api/v1/timeline`	Les mêmes chiffres, jour par jour ou mois par mois
`GET /api/v1/reports/books`	Une ligne par livre
`GET /api/v1/reports/marketplaces`	Une ligne par marketplace
`GET /api/v1/books`	Ton catalogue
`GET /api/v1/series`	Tes séries, avec leurs livres dans l'ordre
`GET /api/v1/kenp`	Les pages lues Kindle Unlimited
`GET /api/v1/kenp/books`	Les pages lues, livre par livre
`GET /api/v1/free-units`	Les téléchargements gratuits, jamais comptés comme royalties
`GET /api/v1/series/{series_id}/read-through`	La lecture d'une série, livre par livre

Chaque paramètre et chaque champ figurent dans la référence de l'API (en anglais). Son bouton Try it est prérempli avec une clé de démo publique : tu peux tester chaque endpoint sans compte, les réponses viennent alors des chiffres fictifs du compte démo.

Paramètres Authentification et clés d'API