Alles was Sie brauchen um Aficial in Ihr System zu integrieren
Senden Sie einen gescopten Aficial API-Key als Header mit jedem Request. Keys werden nur einmal angezeigt, danach nur gehasht gespeichert und können widerrufen werden.
x-api-key: afc_live_abcdefghij_your_secret_part_here
Alternativ: Authorization: Bearer afc_live_abcdefghij_your_secret_part_here
Authentifizierte Admins erstellen Keys ueber die API-Key-Verwaltung. Fuer Webhook-Ingest braucht der Key den Scope webhook:write.
curl -X POST https://aficial.ai/api/api-keys \
-H "Content-Type: application/json" \
-H "Cookie: sb-access-token=USER_SESSION" \
-d '{
"name": "Shop webhook",
"scopes": ["webhook:write"],
"rateLimitPerMinute": 120
}'Das OpenAPI-Dokument liegt unter /api/openapi.
/api/webhookDer 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.
curl -X POST https://aficial.ai/api/webhook \
-H "Content-Type: application/json" \
-H "x-api-key: afc_live_abcdefghij_your_secret_part_here" \
-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"
}
}'{ "success": true, "message": "Order data received" }curl -X POST https://aficial.ai/api/webhook \
-H "Content-Type: application/json" \
-H "x-api-key: afc_live_abcdefghij_your_secret_part_here" \
-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"]
}
}'curl -X POST https://aficial.ai/api/webhook \
-H "Content-Type: application/json" \
-H "x-api-key: afc_live_abcdefghij_your_secret_part_here" \
-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"
}
}'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: afc_live_abcdefghij_your_secret_part_here" \
-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.
Jede AI-Antwort bekommt einen eindeutigen CSAT-Token. Kunden können damit bewerten.
GET /api/csat?token=CSAT_TOKEN
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.
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"
}'{
"success": true,
"plan": "starter",
"trialDays": 14,
"trialEnds": "2026-04-06T12:00:00.000Z",
"message": "Aktiviert! Ihr 14-Tage Testzeitraum läuft."
}GET /api/health
{
"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"
}Aficial kann Ihr System benachrichtigen wenn etwas passiert. Konfigurieren Sie Webhook-URLs im Dashboard unter Integrationen.
email.receivedNeue E-Mail eingegangenreply.sentAntwort gesendetemail.escalatedE-Mail an Team eskaliertsla.breachedSLA-Frist überschrittencsat.receivedNeue CSAT-Bewertung{
"event": "reply.sent",
"timestamp": "2026-03-23T14:30:00Z",
"data": {
"emailId": "abc-123",
"replyId": "def-456",
"category": "order_status"
}
}Jeder Webhook wird mit HMAC-SHA256 signiert:
X-Aficial-Signature: sha256=a1b2c3d4e5... X-Aficial-Event: reply.sent
// Node.js Verification
const crypto = require('crypto');
const signature = crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(JSON.stringify(body))
.digest('hex');
const valid = signature === header.split('=')[1];Bei Überschreitung erhalten Sie 429 Too Many Requests mit Retry-After Header.
{
"error": "Token and rating required"
}Offizielle SDKs sind in Planung. Bis dahin funktioniert jeder HTTP-Client. Beispiel für das Webhook-Endpoint:
const res = await fetch('https://aficial.ai/api/webhook', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'afc_live_abcdefghij_your_secret_part_here',
},
body: JSON.stringify({
type: 'order',
order: { order_number: '4521', status: 'shipped' },
}),
});
console.log(await res.json());import requests
res = requests.post(
'https://aficial.ai/api/webhook',
headers={'x-api-key': 'afc_live_abcdefghij_your_secret_part_here'},
json={'type': 'order', 'order': {'order_number': '4521', 'status': 'shipped'}},
)
print(res.json())$ch = curl_init('https://aficial.ai/api/webhook');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'x-api-key: afc_live_abcdefghij_your_secret_part_here',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'type' => 'order',
'order' => ['order_number' => '4521', 'status' => 'shipped'],
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);require 'net/http'
require 'json'
uri = URI('https://aficial.ai/api/webhook')
req = Net::HTTP::Post.new(uri, {
'Content-Type' => 'application/json',
'x-api-key' => 'afc_live_abcdefghij_your_secret_part_here',
})
req.body = { type: 'order', order: { order_number: '4521', status: 'shipped' } }.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body