Kampagnen und API

API für eigene Systeme

Persönliche Bewertungslinks automatisch aus Ticketsystem, CRM oder Shop erzeugen: Anmeldung, Aufrufe, Felder, Fehler.

Mit der API legt Ihr eigenes System, etwa ein Ticketsystem, CRM, Shop oder Event-Tool, persönliche Bewertungslinks automatisch an. Den Link verschickt Ihr System selbst, per Mail oder SMS. Die Bewertungen fragen Sie bei Bedarf wieder ab. Was Kampagnen und persönliche Links sind, steht unter Kampagnen und persönliche Links.

#Beispiel: Umfrage 3 Tage nach dem Ticket

1. Legen Sie einmalig eine Kampagne an, z. B. „Support-Tickets“, in der App oder per API. Ihre ID steht in der Adresse der Kampagne (/kampagnen/{id}).
2. Wird ein Ticket geschlossen, plant Ihr System eine Aufgabe in drei Tagen.
3. Die Aufgabe ruft POST /api/v1/campaigns/{id}/invitations mit der Ticketnummer als reference auf und bekommt den Link zurück.
4. Ihr System schickt den Link an den Kunden. Fertig: Die Bewertung erscheint in emojirate mit der Ticketnummer.

curl -X POST https://app.emojirate.de/api/v1/campaigns/68db3e37-590a-42ac-97fc-aeda1dd724a7/invitations \
  -H "Authorization: Bearer er_…" \
  -H "Content-Type: application/json" \
  -d '{"reference": "TICKET-4711", "expires_in_days": 14, "metadata": {"agent": "Lisa"}}'

{
  "id": "74032aca-998d-45fd-8312-85f485ea924c",
  "campaign_id": "68db3e37-590a-42ac-97fc-aeda1dd724a7",
  "reference": "TICKET-4711",
  "url": "https://feedback.emojirate.de/r/y1vFRqWcKVEcYlAunS4eIr",
  "status": "pending",
  "metadata": {"agent": "Lisa"},
  "created_at": "2026-10-18T13:01:55Z",
  "expires_at": "2026-11-01T13:01:55Z",
  "opened_at": null,
  "completed_at": null,
  "revoked_at": null,
  "rating": null
}

#Anmeldung

Legen Sie unter API-Schlüssel einen Schlüssel an (nur Inhaber). Er beginnt mit er_ und wird genau einmal angezeigt. Schicken Sie ihn bei jeder Anfrage als Header mit:

Authorization: Bearer er_…

Ein Schlüssel gilt für alle Kampagnen Ihrer Organisation. Legen Sie je System einen eigenen Schlüssel an; so können Sie einen zurückziehen, ohne die anderen zu stören. Schlüssel gehören nur auf Server, nie in eine Website oder App, die Kunden laden.

#Grundlagen

• Adresse: https://app.emojirate.de/api/v1. GET /api/v1 testet die Verbindung und nennt Ihre Organisation.
• Format: JSON (Header Content-Type: application/json), Zeichensatz UTF-8. Zeitangaben in UTC nach ISO 8601, z. B. 2026-10-18T13:01:55Z.
• Grenzen: 120 Anfragen pro Minute und Schlüssel. Darüber antwortet die API mit 429 und Retry-After.
• Doppelte Aufrufe: Je Kampagne gibt es zu einer reference genau einen Link. Ruft Ihr System dieselbe Referenz noch einmal auf, kommt der bestehende Link zurück (Status 200 statt 201). Wiederholungen nach Netzwerkfehlern sind damit gefahrlos.

#Kampagnen

Felder:

Rückfragen legen Sie in der App an (Kampagnen›Kampagne öffnen›Rückfragen).

#Persönliche Links

Beim Erzeugen:

status ist einer von pending (offen), opened (geöffnet), completed (bewertet), expired (abgelaufen), revoked (zurückgezogen). Nach der Bewertung enthält rating die Note (score 1–5 und label), den Zeitpunkt, die Antworten auf die Rückfragen und – nur mit Einwilligung des Kunden – contact_email.

Seitenweise abrufen: Listen kommen neueste zuerst. Ist next_cursor nicht null, holen Sie die nächste Seite mit ?cursor=….

GET /api/v1/invitations?status=completed&limit=100
{
  "data": [ { "id": "…", "reference": "TICKET-4711", "status": "completed",
              "rating": { "score": 4, "label": "Gut", "rated_at": "2026-10-18T13:01:55Z",
                          "changed_at": null, "answers": [ { "question": "Wurde Ihr Anliegen gelöst?", "answer": "Ja" } ],
                          "contact_email": null }, … } ],
  "next_cursor": "MjAyNi0xMC0xOCAxMzowMjoxMnw…"
}

#Fehler

Fehler kommen immer im selben Format, bei ungültigen Eingaben mit den betroffenen Feldern:

{"error": {"code": "validation_failed", "message": "Bitte Eingaben prüfen.",
           "fields": {"expires_in_days": "Ganze Zahl von 1 bis 365."}}}