05 · API

Deine Zahlen über die REST-API abrufen

Die Zahlen des Dashboards selbst, als JSON, für eine Website, mit einem Schlüssel, der nur lesen kann.

01Schlüssel

Schlüssel erstellst du auf der Seite Setup der Website, unter API keys. Ein Schlüssel (opa_ und 40 Zeichen) wird einmal angezeigt: Gespeichert werden nur ein Hash davon und seine ersten Zeichen.
Ein Schlüssel liest eine Website: die, auf der er erstellt wurde. Ein Widerruf wirkt sofort.
Ein Schlüssel liest nur, außer beim Erstellen wurde Record payments angehakt: Dann kann er auch Zahlungen senden (Payments API).

Sende den Schlüssel bei jeder Anfrage als Authorization: Bearer opa_…:

Shell

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

02Routen

Alle sind GET, unter https://tallybyoutpost.com/api/v1, und {id} ist die ID der Website. Jede nimmt die Parameter des Dashboards und liefert die Zahlen des Dashboards selbst:

Route	Was sie liefert
`GET /sites`	Die Website des Schlüssels: ihre ID, Name, Domain, Zeitzone und Modus.
`GET /sites/{id}/overview`	Die Zahlen des Dashboards für einen Zeitraum und den davor: Besucher, Seitenaufrufe, Besuche, aktive Zeit und Umsatz.
`GET /sites/{id}/timeseries`	Das Diagramm: Besucher und Seitenaufrufe pro Stunde oder Tag, mit Umsatz, wenn es Zahlungen gibt.
`GET /sites/{id}/breakdown/{dimension}`	Quellen, Kanäle, Seiten, Länder, Geräte und der Rest, mit dem Umsatz jeder Zeile.
`GET /sites/{id}/sales`	Zahlungen, die neuesten zuerst, jede mit der Angabe, wie sie verknüpft wurde.
`GET /sites/{id}/receipts/{payment_id}`	Der Beleg einer Zahlung: die Kette vom ersten Besuch bis zur Zahlung.
`GET /sites/{id}/coverage`	Der Anteil der Verkäufe, die mit einem Besucher verknüpft sind, nach Methode, und die Korrekturen.
`GET /sites/{id}/visitors`	Die Besucherliste, mit den Besuchen jedes Besuchers und dem, was er bezahlt hat.
`GET /sites/{id}/visitors/{visitor}`	Der Weg eines Besuchers.
`GET /sites/{id}/goals`	Jedes erreichte Ziel, mit seinen konvertierenden Besuchern und deren Umsatz, und die Funnels.
`GET /sites/{id}/funnels/{id}`	Ein Funnel, Schritt für Schritt.
`GET /sites/{id}/realtime`	Wer in den letzten fünf Minuten auf der Website war, und die Verkäufe der letzten Stunde.
`GET /sites/{id}/peak-hours`	Besuche, Verkäufe und Umsatz nach Wochentag und Stunde in Ortszeit.
`GET /sites/{id}/pages`	Wie Seiten gelesen werden: Aufrufe, Lesezeit, Scrolltiefe, Einstiege und Ausstiege.
`GET /sites/{id}/path-to-purchase`	Wie Käufer zum Kauf kamen: Zeit und Besuche vor dem Bezahlen, und vom ersten Kontakt zur zugerechneten Quelle.
`GET /sites/{id}/ltv`	Lifetime Value nach der Quelle, die jeden Kunden zuerst gebracht hat.

Quellen nach Umsatz, letzte 30 Tage

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

03Parameter

Parameter	Werte
`period`	`today`, `yesterday`, `7d`, `30d`, `12m`. Jede Route hat einen Standardwert.
`from`, `to`	Ein eigener Zeitraum, `YYYY-MM-DD`, beide angegeben, bis zu 366 Tage. Nicht zusammen mit `period`.
`compare`	`off` (Standard), `previous` oder `year`.
`f.<dim>`	Ein Filter: `f.country=DE`, `f.source=x.com`, `f.page=/pricing`, `f.device=mobile` und die anderen Dimensionen des Dashboards.
`limit`, `cursor`	Zeilen pro Seite und der `next_cursor` der vorherigen Seite.

Ein Parameter, den eine Route nicht kennt, wird mit 400 abgelehnt, damit ein Tippfehler nie als Antwort durchgeht.

04Antworten

JSON, mit Geldbeträgen als ganzzahlige Cent samt Währung: {"cents": 4900, "currency": "USD", "exponent": 2}. Summen sind in US-Dollar; jeder Verkauf trägt außerdem seinen Betrag, wie er berechnet wurde.
Zeiten sind RFC 3339 in UTC; Tagesgrenzen gelten in der Zeitzone der Website, die jede range nennt.
Anteile und Raten liegen zwischen 0 und 1: 0.1234 sind 12,34 %.
Fehler sind {"error": {"code", "message"}}, wobei die Nachricht ein Satz ist, den du unverändert anzeigen kannst: 400 invalid_parameter, 401 unauthorized, 402 payment_required (das Konto hat keinen Tarif), 404 not_found, 429 rate_limited und 503 unavailable.

05Rate-Limits

Jeder Schlüssel darf 120 Anfragen pro Minute stellen, REST und MCP zusammen, laufend wieder aufgefüllt. Jede Antwort trägt X-RateLimit-Limit und X-RateLimit-Remaining; über dem Limit kommt 429 mit Retry-After in Sekunden.

06Prüfen, ob es geklappt hat

Fehlt etwas, oder sieht es bei dir anders aus? Schreib an support@tallybyoutpost.com und nenne die Seite.