TrustFinder API

Integriere Bewertungen in dein System, empfange Echtzeit-Webhooks und bette Trust-Widgets in jede Website ein — mit einer einfachen REST-API.

REST · JSON API-Key Auth HMAC-Webhooks

Schnellstart

In 3 Schritten zur ersten Bewertung per API:

1. API-Key erstellen

Im Dashboard unter API-Keys einen neuen Schlüssel anlegen. Der Klartext-Key wird einmalig angezeigt — sicher aufbewahren.

2. Bewertung einreichen

curl

curl -X POST https://api.trustfinder.de/api/v1/public/reviews \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: tf_YOUR_API_KEY" \
  -d '{"author_name": "Max Mustermann",
    "rating": 5,
    "text": "Hervorragender Service, sehr empfehlenswert!",
    "external_ref": "order-12345"
  }'

3. Antwort

json

{
  "data": {
    "id": "0194abc1-...",
    "status": "pending",
    "message": "Bewertung eingegangen und wartet auf Moderation."
  },
  "meta": { "version": 1 }
}

ℹ️ Neue Bewertungen landen standardmäßig im Status pending und erscheinen erst nach der Moderation im öffentlichen Profil.

Authentifizierung

Die API kennt zwei Authentifizierungsmodelle:

API-Key (öffentliche Endpunkte)

Für maschinelle Review-Einreichungen. Den Key im Header übergeben:

http

X-Api-Key: tf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

JWT Bearer (Dashboard-Endpunkte)

Für Unternehmens-Aktionen (Profil, Quellen, Moderation …). Token via POST /api/v1/auth/login beziehen:

http

Authorization: Bearer eyJhbGciOiJSUzI1Ni...

⚠️ API-Keys niemals clientseitig (Browser, App) exponieren. Ausschließlich serverseitig verwenden.

Bewertungen einreichen

POST /api/v1/public/reviews API-Key

Reicht eine neue Bewertung für das mit dem API-Key verknüpfte Unternehmen ein.

Request Body

Feld	Typ	Pflicht	Beschreibung
author_name	string	✓	Vollständiger Name des Bewerters (max. 120 Zeichen)
rating	integer	✓	Bewertung von 1 (schlecht) bis 5 (sehr gut)
text	string	–	Freitext-Bewertung (max. 5 000 Zeichen)
external_ref	string	–	Deine interne ID (z. B. Bestell-Nr.) zur Deduplizierung (max. 120 Zeichen)
customer_email	string	–	E-Mail-Adresse des Kunden (wird nicht veröffentlicht)

Beispiel (JavaScript)

const res = await fetch('https://api.trustfinder.de/api/v1/public/reviews', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'tf_YOUR_KEY',
  },
  body: JSON.stringify({
    author_name:  'Anna Schmidt',
    rating:       4,
    text:         'Schnelle Lieferung, gerne wieder.',
    external_ref: 'order-9876',
  }),
});
const json = await res.json();
console.log(json.data.status); // "pending"

Beispiel (PHP)

php

$response = $httpClient->request('POST', 'https://api.trustfinder.de/api/v1/public/reviews', [
    'headers' => [
        'X-Api-Key'    => 'tf_YOUR_KEY',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'author_name'  => 'Lukas Bauer',
        'rating'       => 5,
        'text'         => 'Perfekte Erfahrung!',
        'external_ref' => 'INV-00123',
    ],
]);

GET /api/v1/widget/{slug}/reviews Öffentlich

Liefert paginierte, genehmigte Bewertungen eines Unternehmensprofils — für eigene Widget-Implementierungen.

Parameter	Typ	Default	Beschreibung
limit	integer	10	Anzahl Bewertungen (max. 50)
offset	integer	0	Versatz für Paginierung
min_rating	integer	1	Mindest-Sternwertung (1–5)
platform	string	–	Filter: `google`, `trustpilot`, `trustfinder` …

Widget & Badge

Einbettbares Widget (JS)

Füge das folgende Snippet in deine Website ein — das Widget lädt sich automatisch per Shadow DOM:

html

<!-- Widget-Script einmalig einbinden -->
<script src="https://trustfinder.de/widget/trustfinder-widget.js"
        async defer></script>

<!-- Platzhalter: Standard-Karte -->
<div data-trustfinder-widget
     data-slug="mein-unternehmen"
     data-mode="card"
     data-limit="5"></div>

<!-- Platzhalter: Liste (panel) mit Filtern -->
<div data-trustfinder-widget
     data-slug="mein-unternehmen"
     data-mode="panel"
     data-cols="2"></div>

Widget-Attribute

Attribut	Werte	Beschreibung
data-slug	string	Unternehmens-Slug (aus Dashboard)
data-mode	`card` · `list` · `panel`	Darstellungsvariante
data-limit	1–50	Anzahl anzuzeigender Bewertungen
data-color	Hex-Farbe	Akzentfarbe (Standard: `#1B6B4A`)
data-cols	1–4	Spalten im Panel-Modus

Trust-Badge (SVG)

Dynamisches SVG-Bild mit aktuellem Trust Score — als <img>-Tag einbinden:

html

<a href="https://trustfinder.de/bewertungen/mein-unternehmen"
   target="_blank" rel="noopener">
  <img src="https://trustfinder.de/badge/mein-unternehmen.svg?style=horizontal"
       width="260" height="68"
       alt="TrustFinder Bewertungs-Badge" />
</a>

Verfügbare Stile: horizontal (Standard) · compact · dark

Webhooks

TrustFinder sendet signierte POST-Requests an konfigurierte URLs, wenn bestimmte Events eintreten.

Events

Event	Auslöser
review.new	Neue genehmigte Bewertung nach Sync
review.approved	Moderierte Bewertung genehmigt
review.fake_flagged	Bewertung als verdächtig markiert
sync.completed	Bewertungsquelle erfolgreich synchronisiert

Signatur prüfen

Jede Anfrage enthält drei Headers:

http

X-TrustFinder-Event:    review.approved
X-TrustFinder-Delivery: 0194abc1-...  # eindeutige Delivery-ID
X-TrustFinder-Signature: sha256=abc123...

Die Signatur ist ein HMAC-SHA256 des Request-Bodys mit dem Webhook-Secret:

php

$payload   = file_get_contents('php://input');
$secret    = 'dein-webhook-secret';
$expected  = 'sha256=' . hash_hmac('sha256', $payload, $secret);
$received  = $_SERVER['HTTP_X_TRUSTFINDER_SIGNATURE'];

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

js (node)

import crypto from 'crypto';

function verifySignature(payload, secret, signature) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret)
          .update(payload)
          .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature),
  );
}

Payload-Beispiel

json

{
  "event":      "review.approved",
  "company_slug": "mein-unternehmen",
  "timestamp":  "2026-04-11T12:00:00+00:00",
  "data": {
    "review_id":   "0194abc1-...",
    "author_name": "Max Mustermann",
    "rating":      5,
    "platform":    "trustfinder",
    "text_excerpt": "Hervorragend!"
  }
}

Fehler & Rate Limits

Fehlerformat

json

{
  "error": {
    "code":    "validation_failed",
    "message": "rating muss zwischen 1 und 5 liegen."
  }
}

HTTP-Statuscodes

Code	Bedeutung
200 / 201	Erfolg
400	Ungültige Anfrage (fehlende/fehlerhafte Felder)
401	Fehlende oder ungültige Authentifizierung
403	Keine Berechtigung (falsches Unternehmen)
404	Ressource nicht gefunden
409	Konflikt (z. B. external_ref bereits verwendet)
422	Validierungsfehler
429	Rate Limit erreicht (Duplicate-Schutz)
500	Interner Serverfehler

Rate Limits

Öffentliche API: 60 Requests/Minute pro API-Key
Bulk-Einladungen: max. 100 Adressen pro Request
Webhooks: nach 10 aufeinanderfolgenden Fehlern wird der Webhook automatisch deaktiviert

ℹ️ Bei Fragen zur Integration: im Dashboard unter Support oder via api@trustfinder.de.