Custom API

Wofür die Custom API?

Die meisten Händler kommen ganz ohne Code aus: Widget einbinden, Domain crawlen lassen, Inbox im Dashboard bedienen. Die Custom API ist für die Fälle gedacht, in denen du Alpheris in eigene Software integrieren willst:

• Konversationen und Tickets in dein bestehendes CRM oder Helpdesk spiegeln.
• Aus einem eigenen Backend heraus auf einen Thread antworten.
• Erfasste Leads automatisiert in deine Vertriebs-Pipeline schreiben.
• Den Shop-/Plan-Kontext eines Workspaces serverseitig prüfen.

Die API spricht JSON, läuft über deine reguläre Alpheris-Domain und nutzt denselben Datenbestand wie das Dashboard.

Grundlagen

Jeder Key ist fest an genau einen Workspace (Shop) gebunden. Es gibt keine kontoübergreifenden Keys — ein Request sieht ausschließlich die Daten des Workspaces, zu dem der Key gehört.

API-Key erstellen

API-Keys verwaltest du im Dashboard. Eine ausführliche Anleitung inklusive aller Endpunkte und Fehlercodes findest du in der API-Referenz.

# Key serverseitig als ENV-Variable ablegen
export ALPHERIS_API_KEY="sb_live_xxxxxxxxxxxxxxxxxxxxxxxx"
export ALPHERIS_BASE_URL="https://console.alpheris.com"

Authentifizierung testen

Prüfe zuerst mit GET /api/me, ob Key, Workspace und Plan korrekt sind. Erst danach solltest du fachliche Endpunkte aufrufen.

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

import os, requests

base_url = os.environ["ALPHERIS_BASE_URL"]
api_key  = os.environ["ALPHERIS_API_KEY"]

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

Wichtige Endpunkte

Die Inbox-Endpunkte akzeptieren sowohl die Dashboard-Session als auch einen API-Key — ideal für eigene CRM- und Ops-Flows. Die vollständige Liste mit allen Parametern steht in der API-Referenz.

Beispiel: Antwort in einen Thread senden

Schicke beim Senden immer eine eindeutige client_msg_id mit. So erkennt Alpheris Wiederholungen (etwa nach einem Timeout) als denselben Vorgang und erzeugt keine doppelte Nachricht.

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"
  }'

Optionale Steuer-Endpunkte

Über die API lassen sich auch einzelne Chatbot- und Shopify-Funktionen serverseitig steuern. Diese Endpunkte akzeptieren ebenfalls API-Key oder Session:

curl -sS -X POST "$ALPHERIS_BASE_URL/api/chatbot/settings" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shopify_store_enabled": true,
    "shopify_chat_order_tracking_enabled": true,
    "shopify_chat_refund_mode": "ticket",
    "shopify_chat_refund_max_amount": "50.00",
    "shopify_chat_refund_max_days": 30,
    "shopify_chat_refund_unshipped_only": true,
    "shopify_chat_return_mode": "auto",
    "shopify_chat_return_portal_url": "https://shop.example/retoure",
    "shopify_chat_return_window_days": 14
  }'

Erstattung kennt drei Stufen: off (nicht anbieten), ticket (Vorgang für einen Mitarbeiter — Voreinstellung) und auto. auto gilt nur innerhalb der Grenzen: ohne shopify_chat_refund_max_amount fällt sie auf ticket zurück, und über der systemweiten Obergrenze wird immer ein Vorgang angelegt statt einer Absage.

Retoure kennt eine Stufe mehr: off, ticket, auto und anlegen. Bei auto verweist der Chatbot sofort auf shopify_chat_return_portal_url (nur https); ohne hinterlegtes Portal fällt die Stufe auf ticket zurück. Bei anlegen erzeugt der Chatbot die Rücksendung in Shopify — als returnRequest, also im Zustand REQUESTED. Freigeben oder ablehnen kann sie ausschließlich ein Mensch in der Inbox; dafür gibt es bewusst keinen API-Weg. Voraussetzung sind die Shopify-Rechte read_returns und write_returns: fehlen sie, legt der Chatbot einen Vorgang an statt die Anfrage. Vor der Artikelauswahl bestätigt der Kunde einen 6-stelligen Code an die E-Mail der Bestellung — ohne diesen Code gibt die API keine Bestellpositionen heraus.

Fehlercodes

Best Practices

• Keys nur serverseitig verwenden, niemals im Frontend oder in öffentlichem Code.
• Pro Integration ein eigener Key mit sprechendem Namen — so kannst du gezielt einzelne Keys rotieren oder widerrufen.
• Key-Rotation regelmäßig einplanen und ungenutzte Keys im Dashboard widerrufen.
• Idempotenz: bei jedem Send-Request eine eindeutige client_msg_id mitschicken.
• Erst /api/me, dann der Rest: so trennst du Auth-/Plan-Probleme sauber von fachlichen Fehlern.