API-Referenz

Voraussetzungen

• Plan: Business oder Enterprise. Andere Pläne erhalten bei API-Key-Aufrufen 402 plan required.
• Shop-Status: Dein Shop muss active sein. Inaktive Shops erhalten 403 shop_inactive.
• API-Key: Wird im Dashboard erzeugt (siehe unten). Der vollständige Key ist nur einmal – direkt beim Erstellen – sichtbar.
• Feature-Gates: Einzelne Endpunkte benötigen zusätzlich ein Feature deines Plans (z. B. inbox, tickets, contacts_basic). Fehlt das Feature, antwortet der Server mit 402.

API in 4 Schritten anbinden

1. Key erstellen: im Dashboard unter /dashboard/api-keys.
2. Key serverseitig speichern: z. B. als Umgebungsvariable – niemals im Browser-Frontend.
3. Request authentifizieren: per Authorization: Bearer <key> (empfohlen) oder X-API-Key: <key>.
4. Mit Test-Call prüfen: zuerst GET /api/me, danach die fachlichen Endpunkte.

Authentifizierung

Jeder API-Aufruf wird über einen Shop-API-Key authentifiziert. Der Server liest den Key aus einem von zwei Headern – zuerst wird der Authorization-Header geprüft, danach X-API-Key:

• Authorization: Bearer <key>  (empfohlen)
• X-API-Key: <key>

API-Keys haben das Präfix sb_live_. Die Basis-URL deiner Integration ist https://docs.alpheris.com. Alternativ kann derselbe Endpunkt auch über eine angemeldete Dashboard-Session aufgerufen werden (Cookie statt Key) – für externe Integrationen ist jedoch ausschließlich der API-Key vorgesehen.

# Key serverseitig als Umgebungsvariable ablegen
export ALPHERIS_API_KEY="sb_live_xxxxxxxxxxxxxxxxxxxxxxxx"
export ALPHERIS_BASE_URL="https://docs.alpheris.com"

# Authentifizierter Test-Call (empfohlener Header)
curl -sS "$ALPHERIS_BASE_URL/api/me" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

# Alternativ mit X-API-Key
curl -sS "$ALPHERIS_BASE_URL/api/me" \
  -H "X-API-Key: $ALPHERIS_API_KEY"

import os, requests

base_url = "https://docs.alpheris.com"
api_key = os.environ["ALPHERIS_API_KEY"]  # sb_live_...

r = requests.get(
    f"{base_url}/api/me",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=20,
)
print(r.status_code, r.json())

Beispiel-Antwort: GET /api/me

Bestätigt Authentifizierung, Shop, Plan und den genutzten Auth-Modus (api_key oder session).

{
  "user_id": 0,
  "email": "api@integration",
  "shop_id": 42,
  "shop_name": "Mein Shop",
  "plan": "business",
  "role": "integration",
  "auth_mode": "api_key",
  "acl": { }
}

API-Keys verwalten

API-Keys werden im Dashboard unter Dashboard → API Keys (/dashboard/api-keys) verwaltet. Die Verwaltung selbst ist nur über eine angemeldete Dashboard-Session und mit Manager-/Owner-Rolle möglich – nicht über einen API-Key. Voraussetzung ist ein aktiver Shop im Business- oder Enterprise-Plan.

Hinweis: Die obigen Verwaltungs-Endpunkte erwarten eine Dashboard-Session (Cookie) und sind nicht per API-Key aufrufbar. In der Praxis genügt die Verwaltung über die Dashboard-Seite /dashboard/api-keys.

Chat-API (KI-Antworten)

Mit der Chat-API bindest du den Alpheris-Chatbot direkt in deine eigene Website, App oder dein Backend ein – ohne unser JS-Widget. Du sendest eine Nachricht, Alpheris antwortet mit einer auf deine echten Shop-Daten gegroundeten Antwort (kein Halluzinieren) plus den verwendeten Quellen. Basis-URL: $ALPHERIS_BASE_URL/v1/…. Verfügbar in Enterprise oder in Business mit dem Branding-Add-on – sonst antwortet die Chat-API mit 402 plan_required. Der Export unten geht ab Business.

POST /v1/chat

Eine Nachricht rein – eine vollständige Antwort raus. Der Shop-Bezug kommt aus dem Key (keine shop_id mitsenden). conversation_id weglassen startet eine neue Konversation; denselben Wert erneut senden führt den Gesprächsfaden fort.

curl -sS -X POST "$ALPHERIS_BASE_URL/v1/chat" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Wie lange dauert der Versand nach Österreich?" }'

{
  "reply": "Der Versand nach Österreich dauert in der Regel 2-4 Werktage.",
  "conversation_id": "conv_ab12...",
  "message_id": "msg_00987",
  "sources": [
    { "url": "https://deinshop.de/faq/versand", "title": "Versand & Lieferzeiten", "snippet": "Lieferung nach AT: 2-4 Werktage ...", "type": "faq" }
  ],
  "confidence": 0.82,
  "plan": "business"
}

const res = await fetch(`${process.env.ALPHERIS_BASE_URL}/v1/chat`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ALPHERIS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ message: "Habt ihr das in Größe M?" }),
});
const data = await res.json();
console.log(data.reply, data.sources);

POST /v1/chat/stream

Wie /v1/chat, aber als Server-Sent-Events (SSE): die Antwort kommt Token für Token für ein Live-Tipp-Gefühl. Jede Zeile ist ein data: {…}-Frame – Token-Frames tragen {"t":"…"}, der Abschluss-Frame {"done":true, …} enthält die volle Antwort inkl. Quellen.

curl -sS -N -X POST "$ALPHERIS_BASE_URL/v1/chat/stream" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Seid ihr gerade erreichbar?" }'

# data: {"t": "Hey! Ja, "}
# data: {"t": "wir sind hier ..."}
# data: {"done": true, "reply": "...", "conversation_id": "...", "sources": [...]}

Daten-Export (auf ein anderes System übertragen)

Zieh deine Daten programmatisch aus Alpheris – für eine einmalige Migration oder laufenden Sync in dein CRM/Helpdesk. Blätterbar per Cursor (keine 500er-Grenze), sodass auch die komplette Historie erreichbar ist. Business/Enterprise.

GET /v1/export/{entity}

{entity} ist eines von contacts, tickets, conversations, messages, leads. Query-Parameter: limit (1–1000, Standard 200), cursor (die next_cursor der vorigen Seite), bei messages zusätzlich optional thread_id.

curl -sS "$ALPHERIS_BASE_URL/v1/export/contacts?limit=200" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

{
  "entity": "contacts",
  "data": [
    { "id": 51, "name": "Erika Musterfrau", "email": "[email protected]", "phone": "", "company": "", "tags": [], "created_at": 1718700000 }
  ],
  "count": 1,
  "next_cursor": 51,
  "has_more": false
}

Paginierung: Solange has_more: true ist, den nächsten Aufruf mit ?cursor=<next_cursor> wiederholen, bis next_cursor: null zurückkommt.

// Alle Kontakte seitenweise abrufen
let cursor = 0, all = [];
while (true) {
  const r = await fetch(`${process.env.ALPHERIS_BASE_URL}/v1/export/contacts?limit=500&cursor=${cursor}`, {
    headers: { "Authorization": `Bearer ${process.env.ALPHERIS_API_KEY}` },
  });
  const page = await r.json();
  all.push(...page.data);
  if (!page.has_more) break;
  cursor = page.next_cursor;
}

Endpunkt-Referenz

Die folgenden Endpunkte sind per API-Key erreichbar. Alle erwarten den Authentifizierungs-Header (Authorization: Bearer oder X-API-Key); POST-Endpunkte mit Body erwarten zusätzlich Content-Type: application/json. Der Shop-Bezug ergibt sich automatisch aus dem Key – eine shop_id musst du nicht mitsenden.

GET /api/me

Prüft Authentifizierung und liefert Shop-, Plan- und Rollen-Kontext. Idealer erster Test-Call.

curl -sS "$ALPHERIS_BASE_URL/api/me" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

GET /api/inbox/tickets

Lädt die Tickets des Shops (bis zu 500, neueste zuerst). Benötigt das Feature tickets. Optionaler Query-Parameter status (z. B. open, closed, all); ein unbekannter Wert führt zu 400 invalid_status_filter.

curl -sS "$ALPHERIS_BASE_URL/api/inbox/tickets?status=open" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

GET /api/inbox/threads

Listet die Konversations-Threads des Shops auf (E-Mail, Chat, Social) – die zentrale Inbox-Sicht. Benötigt das Feature inbox. Threads werden mandantengetrennt nur für den eigenen Shop geliefert. Nützliche Query-Parameter: source (z. B. all, email, chat, instagram), thread_limit (10–300), message_limit (1–120) sowie fast=1 bzw. minimal=1 für schlankere Antworten.

curl -sS "$ALPHERIS_BASE_URL/api/inbox/threads?source=all&thread_limit=50" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

{
  "ok": true,
  "threads": [
    {
      "id": "abc123",
      "subject": "Frage zur Bestellung #1234",
      "channel": "email",
      "status": "open",
      "customer_name": "Erika Musterfrau",
      "customer_email": "[email protected]",
      "last_message": "Wann wird meine Bestellung versandt?",
      "unread_count": 1,
      "updated_at": 1718700000
    }
  ]
}

POST /api/inbox/tickets

Erstellt ein neues Ticket. Benötigt das Feature tickets. Pflichtfeld ist subject (mindestens 3 Zeichen).

curl -sS -X POST "$ALPHERIS_BASE_URL/api/inbox/tickets" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Lieferung verspätet",
    "description": "Bestellung #1234 ist noch nicht angekommen.",
    "customer_email": "[email protected]",
    "priority": "high",
    "tags": ["versand", "reklamation"]
  }'

GET /api/inbox/leads

Lädt erfasste Leads. Benötigt das Feature inbox. Optionaler Query-Parameter limit (1–500, Standard 120).

curl -sS "$ALPHERIS_BASE_URL/api/inbox/leads?limit=50" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

POST /api/inbox/leads

Legt einen neuen Lead an. Benötigt das Feature inbox. Wird kein source mitgegeben, setzt der Server lead_form_manual.

curl -sS -X POST "$ALPHERIS_BASE_URL/api/inbox/leads" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Erika Musterfrau",
    "email": "[email protected]",
    "source": "website_kontaktformular"
  }'

Weitere Lead-Aktionen (ebenfalls Feature inbox): POST /api/inbox/leads/{lead_id}/close, POST /api/inbox/leads/{lead_id}/reopen und POST /api/inbox/leads/{lead_id}/delete.

GET /api/inbox/customers

Lädt die Kontakte/Kunden des Shops. Benötigt das Feature contacts_basic.

curl -sS "$ALPHERIS_BASE_URL/api/inbox/customers" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

{
  "ok": true,
  "customers": [
    {
      "name": "Erika Musterfrau",
      "email": "[email protected]"
    }
  ]
}

POST /api/inbox/customers

Legt einen Kontakt an. Benötigt das Feature contacts_basic. Pflichtfeld ist eine gültige email; fehlt sie, antwortet der Server mit 400 email_required.

curl -sS -X POST "$ALPHERIS_BASE_URL/api/inbox/customers" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Max Mustermann",
    "company": "Muster GmbH",
    "tags": ["b2b", "newsletter"]
  }'

POST /api/inbox/threads/{conversation_id}/reply

Sendet eine Antwort in einen bestehenden Konversations-Thread (z. B. eine E-Mail-Konversation). Für idempotentes Senden immer eine eindeutige client_msg_id mitschicken – so erzeugen Wiederholungen bei Timeouts keine Duplikate (Server-Dedup beim Re-Sync).

curl -sS -X POST "$ALPHERIS_BASE_URL/api/inbox/threads/abc123/reply" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hallo, wir melden uns direkt bei dir.",
    "client_msg_id": "reply-2026-06-18-001"
  }'

{
  "ok": true,
  "provider": "outlook",
  "conversation_id": "abc123",
  "message": {
    "id": "sent:outlook:reply-2026-06-18-001",
    "sender": "agent",
    "type": "outgoing",
    "text": "Hallo, wir melden uns direkt bei dir.",
    "client_msg_id": "reply-2026-06-18-001"
  }
}

Weitere Thread-Aktionen über API-Key: POST /api/inbox/email/new (neue E-Mail starten), POST /api/inbox/threads/{conversation_id}/assign (Thread zuweisen), POST /api/inbox/threads/{conversation_id}/reopen (geschlossenen Thread wieder öffnen) sowie Ticket-Statuswechsel: POST /api/inbox/tickets/{ticket_id}/close, .../reopen und .../reroute.

POST /api/inbox/threads/{conversation_id}/close

Schließt einen Konversations-Thread. Benötigt das Feature inbox. Über .../reopen wird er wieder geöffnet, über .../delete dauerhaft gelöscht. Alle drei Aktionen sind mandantengetrennt auf den eigenen Shop beschränkt.

# Schließen
curl -sS -X POST "$ALPHERIS_BASE_URL/api/inbox/threads/abc123/close" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

# Wieder öffnen
curl -sS -X POST "$ALPHERIS_BASE_URL/api/inbox/threads/abc123/reopen" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

# Dauerhaft löschen
curl -sS -X POST "$ALPHERIS_BASE_URL/api/inbox/threads/abc123/delete" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

POST /api/inbox/tickets/{ticket_id}/delete

Löscht ein Ticket samt zugehöriger Nachrichten dauerhaft. Benötigt das Feature tickets. Ist das Ticket nicht im eigenen Shop vorhanden, antwortet der Server mit 404 ticket_not_found.

curl -sS -X POST "$ALPHERIS_BASE_URL/api/inbox/tickets/42/delete" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

DELETE /api/inbox/customers/{customer_id}

Löscht einen Kontakt/Kunden dauerhaft. Benötigt das Feature contacts_basic. Existiert der Kontakt nicht im eigenen Shop, antwortet der Server mit 404 customer_not_found.

curl -sS -X DELETE "$ALPHERIS_BASE_URL/api/inbox/customers/7" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

Fehlercodes

Authentifizierung und Plan-Gating folgen einem festen Schema. Fachliche Fehler werden zusätzlich mit 4xx und einem error-Feld im JSON-Body zurückgegeben.