Bestellungen an TrueTrust melden

Voraussetzung

Deine Kunden bestellen und bezahlen online, etwa im Shop, im Buchungssystem oder im Kundenportal. Pro Bestellung braucht TrueTrust die Bestellnummer und die E-Mail-Adresse des Kunden.

Endpunkt und API-Key

POST https://truetrust.io/api/v1/webhooks/order
X-API-Key: DEIN_API_KEY
Content-Type: application/json

Den API-Key findest du im Dashboard unter Widgets > API-Integration. Rufe den Endpunkt serverseitig auf, damit der Key geheim bleibt.

Felder

Feld	Bedeutung
`order_id`	Pflicht, String, bis 255 Zeichen. Deine Bestellnummer. Pro Bestellnummer verschickt TrueTrust höchstens eine Einladung.
`customer_email`	Pflicht, String. E-Mail-Adresse des Kunden. An sie geht die Einladung.
`order_date`	Optional, Datum im ISO-8601-Format. Bestelldatum, höchstens ein Jahr alt und nicht in der Zukunft. Fehlt es, zählt der Zeitpunkt des Aufrufs.
`test`	Optional, Boolean. Mit `true` prüfst du die Verbindung. TrueTrust speichert dann nichts und verschickt nichts.

Schritt 1: Verbindung testen

curl -X POST https://truetrust.io/api/v1/webhooks/order \
  -H "X-API-Key: DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "10042",
    "customer_email": "[email protected]",
    "order_date": "2026-10-02",
    "test": true
  }'

Kommt {"status": "test_ok", "order_id": "10042", "test": true} zurück, stimmen API-Key, Adresse und Felder.

Schritt 2: Echte Bestellungen melden

Ohne test meldet derselbe Aufruf eine echte Bestellung:

curl -X POST https://truetrust.io/api/v1/webhooks/order \
  -H "X-API-Key: DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "10042",
    "customer_email": "[email protected]",
    "order_date": "2026-10-02"
  }'

Die Antwort {"status": "accepted", ...} heißt: Die Einladung ist geplant.

Wann dein Shop den Aufruf sendet

Sende den Aufruf, sobald dein System die Zahlung verbucht.

Stripe Checkout: im Webhook-Handler für checkout.session.completed, aber nur bei session.payment_status === 'paid'. Bei Zahlarten, die Stripe erst später bestätigt, etwa SEPA-Lastschrift, kommt die Zahlung mit checkout.session.async_payment_succeeded. Melde die Bestellung dann dort. Die E-Mail-Adresse liefert Stripe in customer_details.email.
Stripe mit eigener Bezahlseite: im Handler für payment_intent.succeeded, mit der E-Mail-Adresse aus deiner Bestellung.
Andere Shops und Buchungssysteme: dort, wo die Bestellung auf „bezahlt“ wechselt, zum Beispiel in einem Order-Hook oder nach der Zahlungsbestätigung deines Zahlungsanbieters.

Sende den Aufruf asynchron, damit dein Checkout nicht auf die Antwort wartet.

Antworten

Bei gültigen Aufrufen antwortet TrueTrust mit HTTP 200 und JSON. Das Feld status sagt, was passiert ist:

`status`	Bedeutung
`accepted`	Die Einladung ist geplant. `token_id` ist ihre ID.
`duplicate`	TrueTrust kennt diese `order_id` schon. Es bleibt bei der ersten Einladung.
`skipped`	Für diese Bestellung verschickt TrueTrust keine Einladung. Den Grund nennt das Feld `reason`.
`test_ok`	Der Testaufruf war gültig. TrueTrust hat nichts gespeichert.

Mögliche Werte für reason:

`reason`	Bedeutung
`cooldown`	Der Kunde hat kürzlich schon eine Einladung bekommen. Den Abstand legst du unter Einstellungen > Einladungsregeln fest.
`already_reviewed`	Der Kunde hat dich schon bewertet.
`reviewed_recently`	Du lädst Kunden erneut ein. Die letzte Bewertung dieses Kunden liegt aber weniger Tage zurück, als du unter „Mindesttage seit letzter Bewertung“ eingestellt hast.
`satisfied_customer`	Du lädst Kunden erneut ein. Die letzte Bewertung dieses Kunden hat aber mehr Sterne als deine eingestellte Grenze.
`free_monthly_limit`	Im Free-Tarif sind die 10 Einladungen dieses Monats verbraucht.

Fehler kommen mit diesen HTTP-Codes und dem Body {"message": "..."}:

Code	Bedeutung
`400`	Ein Feld ist ungültig. Die Fehlermeldung nennt es.
`401`	Der API-Key fehlt oder ist falsch, oder das Konto ist deaktiviert.
`429`	Mehr als 100 Aufrufe pro Minute mit demselben Key. Die Fehlermeldung nennt die Wartezeit in Sekunden.

Zeitpunkt der Einladung

Standardmäßig verschickt TrueTrust die Einladung 7 Tage nach dem Bestelldatum. Ändern kannst du das unter Einstellungen > E-Mail-Zeitplanung.

Neue Konten prüfen wir vor dem ersten Versand. Bis dahin gemeldete Bestellungen bleiben gespeichert. Die Einladungen dazu verschicken wir nach der Freischaltung.

Wiederholen ist sicher

Pro order_id verschickt TrueTrust höchstens eine Einladung. Ist ein Aufruf fehlgeschlagen oder weißt du nicht, ob er angekommen ist, sende ihn noch einmal. Hat der erste Aufruf eine Einladung geplant, lautet die Antwort duplicate, und der Kunde bekommt keine zweite E-Mail. Kam er nicht an, behandelt TrueTrust ihn wie einen ersten Aufruf.