REST-API-Referenz

Die öffentliche REST-API von The-Y CRM ist für Server-zu-Server-Integrationen gedacht: Kontakte anlegen/lesen/aktualisieren und Ereignisse per Webhook empfangen. Authentifiziert wird mit einem API-Schlüssel.

Basis-URL (gehostet): https://crm.the-y.at/api/ext/v1 · self-host: https://<deine-domain>/api/ext/v1 · Paid-Feature

Authentifizierung

Jede Anfrage braucht deinen API-Schlüssel im Header — entweder als Bearer-Token oder als X-API-Key:

Authorization: Bearer <DEIN_API_SCHLÜSSEL>
# oder
X-API-Key: <DEIN_API_SCHLÜSSEL>

Schlüssel erstellen: In der App unter Einstellungen → 🔌 Integrationen → „API-Schlüssel" → neuer Schlüssel. Der Schlüssel wird nur einmal angezeigt — sicher speichern (in The-Y wird nur ein Hash abgelegt). Der Schlüssel bindet an deinen Mandanten.

Konventionen

• Format: Requests & Responses in application/json (UTF-8).
• Paginierung: Listen akzeptieren ?limit= (Standard/Max serverseitig gedeckelt) und ?offset=; die Antwort enthält hasMore.
• Rate-Limit: Anfragen sind pro Schlüssel/Minute gedeckelt; bei Überschreitung kommt 429 Too Many Requests — mit Backoff erneut versuchen.
• Fehler: als JSON { "error": { "code": "..." } } mit passendem HTTP-Status.

Kontakte

GET/contacts

Kontakte auflisten (paginiert). Optional Suche via ?q=.

# Anfrage
curl "https://crm.the-y.at/api/ext/v1/contacts?limit=20&offset=0" \
  -H "Authorization: Bearer $API_KEY"

# Antwort
{
  "data": [
    { "id": "c_123", "name": "Maria Muster", "email": "maria@example.com", "phone": "+4366012345678", "company": "ACME" }
  ],
  "hasMore": false
}

POST/contacts

Einen Kontakt anlegen. Pflichtfeld ist mindestens ein Name oder eine E-Mail.

curl -X POST "https://crm.the-y.at/api/ext/v1/contacts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Maria Muster", "email": "maria@example.com", "phone": "+4366012345678", "company": "ACME" }'

# 201 Created
{ "data": { "id": "c_123", "name": "Maria Muster", "email": "maria@example.com" } }

GET/contacts/{id}

Einen einzelnen Kontakt lesen.

curl "https://crm.the-y.at/api/ext/v1/contacts/c_123" \
  -H "Authorization: Bearer $API_KEY"

PATCH/contacts/{id}

Einen Kontakt teilweise aktualisieren — nur die gesendeten Felder werden geändert (bestehende bleiben erhalten).

curl -X PATCH "https://crm.the-y.at/api/ext/v1/contacts/c_123" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+4366099999999" }'

Ausgehende Webhooks (Events)

Statt zu pollen, lässt du dir Ereignisse an deine URL schicken. Unter Einstellungen → 🔌 Integrationen → „Webhooks" legst du Ziel-URL, Secret und Ereignisse an (z. B. contact.created, contact.updated).

• The-Y sendet ein POST mit JSON-Payload an deine URL.
• Signatur: Der Header X-Signature enthält einen HMAC-SHA256 über den rohen Body mit deinem Secret. Verifiziere ihn, um die Echtheit zu prüfen.
• Zustellung ist best-effort mit Wiederholungen; dein Endpunkt sollte 2xx zurückgeben.

# Signatur prüfen (Node.js)
const crypto = require("crypto");
const expected = crypto.createHmac("sha256", SECRET).update(rawBody).digest("hex");
if (expected !== req.headers["x-signature"]) return res.status(401).end();

Eingehende Webhooks

Externe Systeme können über eine Token-URL Daten in The-Y anlegen/aktualisieren: POST /api/hooks/<token> (Token in den Integrationen erzeugt). Je Webhook wählst du das Zugriffs-Level: upsert (nur anlegen/aktualisieren, Löschungen ignoriert — Anti-Lock-in) oder full (inkl. Löschen).

Weiter geht's