Feedback API

Almirant stellt eine öffentliche REST-API (kein MCP) für die Aufnahme von Feedback aus eingebetteten Website-Widgets oder Server-zu-Server-Integrationen bereit. Diese API ist vom MCP-Server unabhängig und erfordert keinen Almirant-API-Schlüssel.

Authentifizierung

Die Feedback API verwendet ein auf Public Keys und Widget-Tokens basierendes Authentifizierungssystem:

• Public Key (pk_...): Identifiziert die Feedback-Quelle. Er wird beim Erstellen einer Feedback-Quelle in Almirant abgerufen und kann sicher im Frontend offengelegt werden.
• Widget-Token: Temporär signiertes Token, das über den Endpunkt bootstrap abgerufen wird. Es hat eine begrenzte Gültigkeit und wird zur Validierung von Aufnahme-Anfragen verwendet.

Endpunkte

GET /feedback/widget/bootstrap

Initialisiert das Feedback-Widget. Gibt die Konfiguration der Quelle und ein temporär signiertes Token zurück, das zum Senden von Feedback erforderlich ist.

Query-Parameter:

Name	Typ	Erforderlich	Beschreibung
publicKey	string	Ja	Public Key der Feedback-Quelle (pk_...)

Anfragebeispiel:

curl "https://api.almirant.ai/feedback/widget/bootstrap?publicKey=pk_abc123def456"

Erfolgreiche Antwort (200):

{
  "success": true,
  "data": {
    "source": {
      "publicKey": "pk_abc123def456",
      "type": "widget",
      "name": "Web App Feedback"
    },
    "token": "eyJzb3VyY2VJZCI6Ii4uLiJ9.a1b2c3d4e5f6",
    "expiresAt": 1708531200,
    "config": {
      "requireCaptcha": true
    }
  }
}

Fehler:

Code	Beschreibung
404	Keine Feedback-Quelle für den angegebenen publicKey gefunden
403	Der Ursprung (Domain) der Anfrage befindet sich nicht in der Liste erlaubter Domains

---

POST /feedback/ingest

Sendet ein Feedback-Item. Erfordert das vom Endpunkt bootstrap abgerufene Token.

Header:

Content-Type: application/json

Body:

Name	Typ	Erforderlich	Beschreibung
publicKey	string	Ja	Public Key der Feedback-Quelle
token	string	Ja	Von bootstrap abgerufenes Widget-Token
message	string	Ja	Inhalt des Feedbacks (1-5000 Zeichen)
category	string	Nein	Kategorie: bug, feature_request, improvement, question, praise, other
email	string	Nein	E-Mail-Adresse des Absenders
pageUrl	string	Nein	URL der Seite, auf der das Feedback gesendet wurde
locale	string	Nein	Sprache/Locale des Benutzers
captchaToken	string	Nein	hCaptcha-Token (erforderlich, wenn die Quelle Captcha aktiviert hat)

Anfragebeispiel:

curl -X POST "https://api.almirant.ai/feedback/ingest" \
  -H "Content-Type: application/json" \
  -d '{
    "publicKey": "pk_abc123def456",
    "token": "eyJzb3VyY2VJZCI6Ii4uLiJ9.a1b2c3d4e5f6",
    "message": "El formulario de registro no valida emails correctamente",
    "category": "bug",
    "email": "[email protected]",
    "pageUrl": "https://miapp.com/registro",
    "locale": "es"
  }'

Erfolgreiche Antwort (201):

{
  "success": true,
  "data": {
    "id": "fb-uuid-001",
    "status": "new",
    "createdAt": "2025-02-15T10:30:00.000Z"
  }
}

Fehler:

Code	Beschreibung
400	Ungültiges oder fehlendes Captcha-Token (wenn Captcha erforderlich ist)
401	Ungültiges oder abgelaufenes Widget-Token
403	Der Ursprung (Domain) der Anfrage ist nicht erlaubt
404	Feedback-Quelle nicht gefunden
409	Doppeltes Feedback erkannt (derselbe Inhalt wurde vor Kurzem gesendet)
429	Rate Limit überschritten

Vollständiger Integrationsablauf

1. Das Widget wird auf der Seite des Benutzers geladen
   |
2. GET /feedback/widget/bootstrap?publicKey=pk_...
   |-- Ruft temporäres Token + Konfiguration ab
   |
3. Benutzer schreibt Feedback und sendet es
   |
4. POST /feedback/ingest
   |-- publicKey + token + message + metadata
   |
5. Feedback erscheint als neues Item in Almirant

Schutzmechanismen

Die API umfasst folgende Schutzmechanismen:

• Ursprungsvalidierung: Akzeptiert nur Anfragen von den in der Feedback-Quelle konfigurierten Domains (unterstützt Wildcards wie *.midominio.com)
• Signierte Widget-Tokens: HMAC-SHA256-Tokens mit zeitlich begrenzter Gültigkeit
• Rate Limiting: Begrenzt die Anzahl der Anfragen pro IP und Quelle innerhalb eines Zeitfensters
• Deduplizierung: Erkennt und verwirft kürzlich gesendetes doppeltes Feedback (basierend auf dem SHA-256-Hash des normalisierten Inhalts)
• hCaptcha: Optionale Captcha-Verifizierung pro Quelle (standardmäßig aktiviert)

Feedback-Kategorien

Kategorie	Beschreibung
bug	Fehlerbericht oder Fehlfunktion
feature_request	Anfrage nach neuer Funktionalität
improvement	Verbesserungsvorschlag zu vorhandener Funktionalität
question	Frage oder Informationsanfrage
praise	Positiver Kommentar
other	Standardkategorie, wenn keine angegeben ist

Server-zu-Server-Integration

Bei Backend-Integrationen (ohne Widget) ist der Ablauf derselbe: Rufe zuerst bootstrap auf, um ein Token zu erhalten, und sende das Feedback anschließend an ingest. Der Unterschied besteht darin, dass du sicherstellen musst, dass die Ursprungsdomain in der Liste erlaubter Domains der Feedback-Quelle steht, oder die Quelle ohne Domainbeschränkungen konfigurierst.

Feedback mit Ideen verknüpfen

Eingehendes Feedback kann mit Items im Idea Hub über das MCP-Tool link_feedback_to_idea_item verknüpft werden. Dadurch entsteht Nachvollziehbarkeit zwischen Benutzerfeedback und Produktentscheidungen.