# Bestellungen an TrueTrust melden

Dein Shop meldet jede bezahlte Bestellung an TrueTrust. TrueTrust lädt den Kunden dann per E-Mail zur Bewertung ein.

## 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

```bash
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": "kunde@example.com",
    "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:

```bash
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": "kunde@example.com",
    "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.