API Dokumentation

Alles was Sie brauchen um Aficial in Ihr System zu integrieren

Authentifizierung

Senden Sie Ihren API-Key als Header mit jedem Request. Den Key finden Sie unter Integrationen im Dashboard.

x-api-key: sk_live_abc123def456

Alternativ: Authorization: Bearer sk_live_abc123def456

Endpoints

POST/api/webhook
POST/api/chat
POST/api/activate
GET/api/csat?token=X
POST/api/csat
GET/api/health

Webhook

Der Webhook-Endpoint nimmt Daten entgegen die der Agent nutzt um Kundenanfragen zu beantworten. Je mehr Daten, desto bessere Antworten.

Der Agent nutzt diese Daten automatisch. Wenn ein Kunde nach Bestellung #4521 fragt und Sie diese Bestellung per Webhook gesendet haben, kann der Agent Tracking-Nummer, Status und Details nennen.

Bestellungen senden

curl -X POST https://aficial.ai/api/webhook \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "type": "order",
    "order": {
      "order_number": "4521",
      "status": "shipped",
      "tracking_number": "DE-2026-4521-89",
      "carrier": "DHL",
      "customer_email": "max@example.com",
      "customer_name": "Max Müller",
      "items": [
        { "name": "Wireless Headphones Pro", "qty": 2, "price": 59.95 },
        { "name": "Ladestation", "qty": 1, "price": 29.99 }
      ],
      "total": 149.89,
      "currency": "EUR",
      "ordered_at": "2026-03-12T10:30:00Z",
      "shipped_at": "2026-03-14T06:42:00Z"
    }
  }'

Response

{ "success": true, "message": "Order data received" }

Kundendaten senden

curl -X POST https://aficial.ai/api/webhook \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "type": "customer",
    "customer": {
      "email": "max@example.com",
      "name": "Max Müller",
      "company": "Müller GmbH",
      "phone": "+49 123 456789",
      "tier": "premium",
      "lifetime_value": 2450.00,
      "orders_count": 18,
      "since": "2024-01-15",
      "tags": ["vip", "enterprise"]
    }
  }'

Produkte senden

curl -X POST https://aficial.ai/api/webhook \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "type": "product",
    "product": {
      "sku": "WHP-001",
      "name": "Wireless Headphones Pro",
      "price": 59.95,
      "currency": "EUR",
      "in_stock": true,
      "category": "Audio",
      "description": "Kabellose Kopfhörer mit Active Noise Cancelling",
      "return_policy": "14 Tage Rückgabe, Originalverpackung nötig"
    }
  }'

Events senden

Beliebige Events die der Agent als Kontext nutzt:

curl -X POST https://aficial.ai/api/webhook \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "type": "event",
    "event": "shipping_delay",
    "data": {
      "region": "EU",
      "delay_days": 2,
      "reason": "Wetterbedingungen",
      "affected_orders": ["4521", "4522", "4530"]
    }
  }'

Max Payload: 100 KB. Format: JSON. Beliebige Struktur, der Agent verarbeitet alles.

Chat API

Senden Sie Chat-Nachrichten direkt an den Agent. Für eigene Integrationen, Slack-Bots oder Custom-Widgets.

curl -X POST https://aficial.ai/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "YOUR_ORG_ID",
    "message": "Wo ist meine Bestellung #4521?"
  }'

Response

{
  "reply": "Ich habe Bestellung #4521 geprüft. Sie wurde heute versandt. Tracking: DE-2026-4521-89. Zustellung: Donnerstag."
}

Chat mit Verlauf

Für mehrstufige Gespräche senden Sie den bisherigen Verlauf mit:

curl -X POST https://aficial.ai/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "YOUR_ORG_ID",
    "message": "Und wann genau kommt es an?",
    "history": [
      { "role": "user", "content": "Wo ist meine Bestellung #4521?" },
      { "role": "assistant", "content": "Sie wurde heute versandt. Tracking: DE-2026-4521-89." }
    ]
  }'

Max History: 8 Nachrichten. Max Message: 2.000 Zeichen. Der Agent erkennt die Sprache automatisch.

Chat Widget einbetten

Zwei Zeilen vor dem </body> Tag:

<script>window.AFICIAL_ORG_ID = "YOUR_ORG_ID";</script>
<script src="https://aficial.ai/widget.js" defer></script>

Widget anpassen

Optionale Konfiguration vor dem Widget-Script:

<script>
  window.AFICIAL_ORG_ID = "YOUR_ORG_ID";
  window.AFICIAL_CONFIG = {
    greeting: "Wie können wir helfen?",
    position: "right",        // "left" oder "right"
    color: "#2d3435",         // Bubble-Farbe
    language: "de"            // "de", "en" oder "auto"
  };
</script>
<script src="https://aficial.ai/widget.js" defer></script>

Kundenzufriedenheit (CSAT)

Jede AI-Antwort bekommt einen eindeutigen CSAT-Token. Kunden können damit bewerten.

Status abfragen

GET /api/csat?token=CSAT_TOKEN

Bewertung abgeben

curl -X POST https://aficial.ai/api/csat \
  -H "Content-Type: application/json" \
  -d '{
    "token": "CSAT_TOKEN",
    "rating": 5,
    "comment": "Schnelle und hilfreiche Antwort"
  }'

Rating: 1-5. Comment: optional, max 500 Zeichen. Jeder Token kann nur einmal bewertet werden.

Aktivierungscode einlösen

Authentifizierter Endpoint. Der eingeloggte User löst einen Code für seine Organisation ein.

curl -X POST https://aficial.ai/api/activate \
  -H "Content-Type: application/json" \
  -H "Cookie: sb-access-token=USER_SESSION" \
  -d '{
    "code": "HELLOFRESH"
  }'

Response

{
  "success": true,
  "plan": "starter",
  "trialDays": 14,
  "trialEnds": "2026-04-06T12:00:00.000Z",
  "message": "Aktiviert! Ihr 14-Tage Testzeitraum läuft."
}

Health Check

GET /api/health

Response

{
  "status": "healthy",
  "uptime": 42.5,
  "totalMs": 155,
  "checks": {
    "supabase": { "status": "ok", "ms": 56 },
    "redis": { "status": "ok", "ms": 104 },
    "anthropic": { "status": "ok" }
  },
  "version": "1.0.0"
}

Outgoing Webhooks

Aficial kann Ihr System benachrichtigen wenn etwas passiert. Konfigurieren Sie Webhook-URLs im Dashboard unter Integrationen.

Events

email.receivedNeue E-Mail eingegangen
reply.sentAntwort gesendet
email.escalatedE-Mail an Team eskaliert
sla.breachedSLA-Frist überschritten
csat.receivedNeue CSAT-Bewertung

Payload-Beispiel

{
  "event": "reply.sent",
  "timestamp": "2026-03-23T14:30:00Z",
  "data": {
    "emailId": "abc-123",
    "replyId": "def-456",
    "category": "order_status"
  }
}

Signatur-Verifizierung

Jeder Webhook wird mit HMAC-SHA256 signiert:

X-Aficial-Signature: sha256=a1b2c3d4e5...
X-Aficial-Event: reply.sent
// Node.js Verifizierung
const crypto = require('crypto');
const signature = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(JSON.stringify(body))
  .digest('hex');
const valid = signature === header.split('=')[1];

Rate Limits

Chat API
20 Requests/minpro IP
Webhook
100 Requests/minpro IP
CSAT
30 Requests/minpro IP
Inbox Test
5 Requests/minpro User
AI Processing
60 Requests/minpro Org

Bei Überschreitung erhalten Sie 429 Too Many Requests mit Retry-After Header.

Fehlercodes

200
ErfolgRequest wurde erfolgreich verarbeitet
400
Bad RequestFehlende oder ungültige Parameter
401
UnauthorizedFehlender oder ungültiger API-Key
403
ForbiddenKeine Berechtigung für diese Resource
404
Not FoundResource existiert nicht
413
Payload Too LargeRequest-Body über 100 KB
429
Rate LimitedZu viele Requests, bitte warten
500
Server ErrorInterner Fehler, bitte erneut versuchen

Error Response Format

{
  "error": "Token and rating required"
}

SDKs & Libraries

Offizielle SDKs sind in Planung. Bis dahin funktioniert jeder HTTP-Client:

JavaScript / Node.js

const res = await fetch('https://aficial.ai/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    orgId: 'YOUR_ORG_ID',
    message: 'Wo ist meine Bestellung?'
  })
});
const { reply } = await res.json();
console.log(reply);

Python

import requests

res = requests.post('https://aficial.ai/api/chat', json={
    'orgId': 'YOUR_ORG_ID',
    'message': 'Wo ist meine Bestellung?'
})
print(res.json()['reply'])

PHP

$ch = curl_init('https://aficial.ai/api/chat');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'orgId' => 'YOUR_ORG_ID',
    'message' => 'Wo ist meine Bestellung?'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch));
echo $response->reply;

Ruby

require 'net/http'
require 'json'

uri = URI('https://aficial.ai/api/chat')
res = Net::HTTP.post(uri, {
  orgId: 'YOUR_ORG_ID',
  message: 'Wo ist meine Bestellung?'
}.to_json, 'Content-Type' => 'application/json')
puts JSON.parse(res.body)['reply']