05 · API

Lire vos chiffres via l’API REST

Les chiffres du tableau de bord lui-même, en JSON, pour un site, avec une clé qui ne peut que lire.

01Clés

Créez les clés sur la page Setup du site, sous API keys. Une clé (opa_ suivi de 40 caractères) ne s’affiche qu’une fois : seuls son hachage et ses premiers caractères sont conservés.
Une clé lit un seul site, celui sur lequel elle a été créée. Sa révocation prend effet immédiatement.
Une clé ne fait que lire, sauf si Record payments a été coché à sa création : elle peut alors aussi envoyer des paiements (Payments API).

Envoyez la clé à chaque requête sous la forme Authorization: Bearer opa_… :

Shell

export TALLY_API_KEY=opa_…
curl -s -H "Authorization: Bearer $TALLY_API_KEY" "https://tallybyoutpost.com/api/v1/sites"

02Routes

Toutes sont en GET, sous https://tallybyoutpost.com/api/v1, et {id} est l’identifiant du site. Chacune accepte les paramètres du tableau de bord et renvoie les chiffres du tableau de bord lui-même :

Route	Ce qu’elle renvoie
`GET /sites`	Le site de la clé : son identifiant, son nom, son domaine, son fuseau horaire et son mode.
`GET /sites/{id}/overview`	Les chiffres du tableau de bord pour une période et la précédente : visiteurs, pages vues, visites, temps actif et revenus.
`GET /sites/{id}/timeseries`	Le graphique : visiteurs et pages vues par heure ou par jour, avec les revenus quand il y a des paiements.
`GET /sites/{id}/breakdown/{dimension}`	Sources, canaux, pages, pays, appareils et le reste, avec les revenus de chaque ligne.
`GET /sites/{id}/sales`	Les paiements, du plus récent au plus ancien, chacun avec la façon dont il a été lié.
`GET /sites/{id}/receipts/{payment_id}`	Le justificatif d’un paiement : la chaîne qui va de la première visite au paiement.
`GET /sites/{id}/coverage`	La part des ventes liées à un visiteur, par méthode, et les correctifs.
`GET /sites/{id}/visitors`	La liste des visiteurs, avec les visites de chacun et ce qu’il a payé.
`GET /sites/{id}/visitors/{visitor}`	Le parcours d’un visiteur.
`GET /sites/{id}/goals`	Chaque objectif atteint, avec ses visiteurs convertis et leurs revenus, et les entonnoirs.
`GET /sites/{id}/funnels/{id}`	Un entonnoir, étape par étape.
`GET /sites/{id}/realtime`	Qui est sur le site au cours des cinq dernières minutes, et les ventes de la dernière heure.
`GET /sites/{id}/peak-hours`	Visites, ventes et revenus par jour de la semaine et par heure locale.
`GET /sites/{id}/pages`	Comment les pages sont lues : vues, temps de lecture, profondeur de défilement, entrées et sorties.
`GET /sites/{id}/path-to-purchase`	Comment les acheteurs sont arrivés : temps et visites avant de payer, et de la source du premier contact à la source attribuée.
`GET /sites/{id}/ltv`	La valeur vie client selon la source qui a amené chaque client la première fois.

Sources par revenus, 30 derniers jours

curl -s -H "Authorization: Bearer $TALLY_API_KEY" \
  "https://tallybyoutpost.com/api/v1/sites/k3xq2mfa7twp/breakdown/source?period=30d&sort=revenue"

03Paramètres

Paramètre	Valeurs
`period`	`today`, `yesterday`, `7d`, `30d`, `12m`. Chaque route a une valeur par défaut.
`from`, `to`	Une plage personnalisée, `YYYY-MM-DD`, les deux bornes renseignées, jusqu’à 366 jours. Incompatible avec `period`.
`compare`	`off` (par défaut), `previous` ou `year`.
`f.<dim>`	Un filtre : `f.country=DE`, `f.source=x.com`, `f.page=/pricing`, `f.device=mobile`, et les autres dimensions du tableau de bord.
`limit`, `cursor`	Le nombre de lignes par page, et le `next_cursor` de la page précédente.

Un paramètre qu’une route n’accepte pas est refusé avec 400 : une faute de frappe ne passe jamais pour une réponse.

04Réponses

JSON, avec les montants en centimes entiers et leur devise : {"cents": 4900, "currency": "USD", "exponent": 2}. Les totaux sont en dollars US ; chaque vente porte aussi son montant tel qu’il a été facturé.
Les dates et heures sont au format RFC 3339 en UTC ; les jours sont découpés dans le fuseau horaire du site, que nomme chaque range.
Les parts et les taux vont de 0 à 1 : 0.1234 correspond à 12,34 %.
Les erreurs prennent la forme {"error": {"code", "message"}}, où le message est une phrase que vous pouvez afficher telle quelle : 400 invalid_parameter, 401 unauthorized, 402 payment_required (le compte n’a pas d’offre), 404 not_found, 429 rate_limited et 503 unavailable.

05Limites de débit

Chaque clé peut faire 120 requêtes par minute, REST et MCP confondus, avec un quota qui se recharge au fur et à mesure. Chaque réponse porte X-RateLimit-Limit et X-RateLimit-Remaining ; au-delà de la limite, c’est 429 avec Retry-After en secondes.

06Vérifier que ça marche

Il manque quelque chose, ou ce n’est pas ce que vous voyez ? Écrivez à support@tallybyoutpost.com en précisant la page.