Kingsworth Adcon API v1.0

Die Kingsworth Adcon API – King Connect – verbindet Ihr System direkt mit unserer Auftragsverarbeitung. So einfach wie eine Schlauchkupplung, mit Wasserstopp: Ihr Zugang sieht ausschließlich Ihre eigenen Daten und ist jederzeit abziehbar.

Schlüssel im Self-Service: Loggen Sie sich in Ihr Partnerportal ein und öffnen Sie King Connect – Schlüssel erzeugen, einsetzen, testen. In unter einer Minute verbunden, kein Antrag, keine Wartezeit.

Was ist möglich?

✓ Live (v1): Eigene Aufträge abrufen & nach Status filtern (/v1/auftraege)
✓ Live (v1): Einzelauftrag per Auftragsnummer abrufen (/v1/auftraege/{nr})
✓ Live (v1): Tarif-/Produktverteilung Ihrer Aufträge (/v1/produkte)
✓ Live (v1): Verbindungstest (/v1/ping)
🔜 In Vorbereitung (v2, Outbound): Aufträge einreichen, Status-Rückmeldung an KING, Webhooks bei Statusänderung

Authentifizierung

Alle API-Anfragen werden per Bearer Token authentifiziert. Ihr API-Key wird im Header jeder Anfrage mitgesendet.

HTTP Header

Authorization: Bearer ka_live_xxxxxxxxxxxxxxxxxxxxxxxx

Mehr braucht es nicht: Die Auftraggeber-Zuordnung steckt im Schlüssel (Wasserstopp) – kein zusätzlicher AG-Header, keine Cross-AG-Sicht möglich. Der Schlüssel wird serverseitig nur als SHA-256-Fingerabdruck gespeichert, nie im Klartext.

API-Keys niemals im Frontend-Code oder in öffentlichen Repositories speichern. Nutzen Sie ausschließlich serverseitige Anfragen. Verloren? In King Connect widerrufen und neu erzeugen.

Key-Typen

Typ	Präfix	Verwendung
Live-Key	ka_live_	Produktivbetrieb (aktuell read-only)
Sandbox-Key	ka_test_	🔜 geplant – Testbetrieb ohne echte Aufträge

Versionen & Basis-URL

Basis-URL (live)

https://zwdwzbkdorqtyatgtjou.supabase.co/functions/v1/api

// Beispiel: eigene Aufträge abrufen
https://zwdwzbkdorqtyatgtjou.supabase.co/functions/v1/api/v1/auftraege

Alle Endpunkte liegen unter /v1/ – diese Version bleibt abwärtskompatibel (nur additive Ergänzungen, nie Breaking Changes). Aktuell verfügbar: v1 (read-only). Ein Vanity-Host api.kingsworthadcon.com kann später ohne Vertragsänderung davorgeschaltet werden.

Maschinenlesbar: OpenAPI-3.1-Spec (für Code-Generatoren / Postman) · Live ausprobieren: Try-it-Konsole in King Connect

Fehlerbehandlung

Fehler werden als JSON-Objekt mit error und message zurückgegeben.

JSON

{
  "error": "VALIDATION_ERROR",
  "message": "IBAN ist ungültig",
  "field": "bank.iban",
  "request_id": "req_01j9k2mxyz"
}

200OK – Anfrage erfolgreich

201Created – Auftrag wurde angelegt

400Bad Request – Fehlende oder ungültige Parameter

401Unauthorized – API-Key fehlt oder ungültig

404Not Found – Ressource nicht gefunden

422Unprocessable – Validierungsfehler (z.B. IBAN)

500Server Error – Interner Fehler, bitte melden

Rate Limits

Jeder Schlüssel hat ein eigenes Limit pro Minute (Standard 120/min, pro Auftraggeber anpassbar). Bei Überschreitung kommt 429 Too Many Requests mit Header Retry-After: 60.

Aufträge

POST /v1/auftraege 🔜 In Vorbereitung (v2)

Noch nicht live. Das Einreichen von Aufträgen (Outbound/Schreiben) kommt mit v2 inkl. Status-Rückkanal. v1 ist read-only (Wasserstopp). Das folgende Schema zeigt den geplanten Request.

Reicht einen neuen Auftrag ein. Der Auftrag wird in der Kingsworth Adcon Auftragsverarbeitung angelegt und erhält eine eindeutige Auftragsnummer.

Request Body

Parameter	Typ	Pflicht	Beschreibung
kategorie	string	✱ Pflicht	strom \| gas \| dsl \| glasfaser \| pv \| waerme
tarif_id	string	✱ Pflicht	ID des gewählten Tarifs aus /produkte
kunde	object	✱ Pflicht	Kundendaten (siehe Objekt „Kunde")
details	object	✱ Pflicht	Produktdetails (abhängig von Kategorie)
bank	object	Optional	Bankdaten für SEPA-Lastschrift (nicht bei Leads)
hardware	array	Optional	Array von Hardware-IDs
externe_id	string	Optional	Ihre eigene Auftragsnummer zur Referenzierung

Beispiel-Request

cURL

curl -X POST https://zwdwzbkdorqtyatgtjou.supabase.co/functions/v1/api/v1/auftraege \
  -H "Authorization: Bearer ka_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "kategorie": "strom",
    "tarif_id": "s_nfh_basis_2026",
    "externe_id": "MEIN-SYS-4711",
    "kunde": {
      "anrede": "Herr",
      "vorname": "Max",
      "nachname": "Mustermann",
      "geburtsdatum": "1985-06-15",
      "email": "max@mustermann.de",
      "telefon": "0170 1234567",
      "adresse": {
        "strasse": "Musterstraße",
        "hausnr": "1",
        "plz": "21337",
        "ort": "Lüneburg"
      }
    },
    "details": {
      "kwh_jahr": 3500,
      "zaehler_nr": "123456789",
      "lieferbeginn": "2026-07-01",
      "vorversorger": "E.ON"
    },
    "bank": {
      "inhaber": "Max Mustermann",
      "iban": "DE89370400440532013000"
    }
  }'

Beispiel-Response

JSON

{
  "id": "ord_01j9k2mxyz",
  "auftrag_nr": "AUF-2026-0523",
  "externe_id": "MEIN-SYS-4711",
  "status": "neu",
  "kategorie": "strom",
  "tarif": {
    "id": "s_nfh_basis_2026",
    "name": "Strom Basis",
    "preis_mt": 89.00
  },
  "created_at": "2026-06-09T10:23:44Z",
  "webhook_sent": true
}

GET /v1/auftraege/{nr} ✓ Live · Einzelauftrag abrufen

cURL

curl https://zwdwzbkdorqtyatgtjou.supabase.co/functions/v1/api/v1/auftraege/AUF-2026-2358 \
  -H "Authorization: Bearer ka_live_xxxx"

GET /v1/auftraege ✓ Live · Aufträge auflisten

Query Parameter

Parameter	Typ	Beschreibung
status	string	Filter auf KING-Status (z.B. akzeptiert, erfasst, abgerechnet)
limit	integer	Ergebnisse pro Seite (max. 200, default 50)
offset	integer	Pagination-Offset

cURL

curl "https://zwdwzbkdorqtyatgtjou.supabase.co/functions/v1/api/v1/auftraege?status=akzeptiert&limit=50" \
  -H "Authorization: Bearer ka_live_xxxx"

JSON Response

{
  "version": "v1",
  "anzahl": 3,
  "limit": 50, "offset": 0,
  "daten": [
    { "auftrag_nr": "AUF-2026-2358", "status": "akzeptiert",
      "tarif": "lünecom 300", "kunde": "Mustermann GmbH",
      "umsatz_stufe": "forecast",
      "erfasst_am": "2026-06-18T10:32:19Z" }
  ]
}

Umsatz-/Beleg-Felder (seit 06/2026): Jeder Auftrag trägt umsatz_stufe = forecast (nur erfasst) · belegt_erwartet (abgerechnet, Liqui-relevant) · fakturiert (Rechnung/Gutschrift liegt vor, GuV). Quelle ist beleg_typ (rechnung|gutschrift|provisionsuebersicht) mit beleg_datum; bezahlt_am = Kontoeingang. Buchhaltung läuft über Lexware Office (Beleg-Sync über die Auftrag-Nr.).

PUT /v1/auftraege/{nr}/status 🔜 In Vorbereitung (v2)

Noch nicht live. Status-Rückmeldung an KING (für die Kundeninfo) kommt mit dem v2-Rückkanal. Geplanter Request:

JSON

{
  "status": "abgeschlossen",
  "notiz": "Freischaltung erfolgt am 01.07.2026"
}

Produkte & Tarife

GET /v1/produkte ✓ Live · Tarif-/Produktverteilung

JSON Response

{
  "version": "v1",
  "anzahl": 2,
  "daten": [
    {
      "tarif": "Strom Basis",
      "anzahl": 7
    },
    {
      "tarif": "Glasfaser 500",
      "anzahl": 3
    }
  ]
}

Liefert die aggregierte Tarif-Verteilung (Tarifname + Anzahl Aufträge), gescopt auf den eigenen Auftraggeber. anzahl = Zahl der unterschiedlichen Tarife. Ein vollständiger Tarif-Katalog (Felder wie preis_mt, laufzeit_monate, bonus, gueltig_bis) ist erst mit v2 geplant.

POST /v1/produkte/upload 🔜 In Vorbereitung (v2)

Noch nicht live. Tarif-Upload (Schreiben) kommt mit v2. Geplant: JSON-Array oder CSV, Upsert per ID.

cURL – CSV Upload (geplant)

curl -X POST https://zwdwzbkdorqtyatgtjou.supabase.co/functions/v1/api/v1/produkte/upload \
  -H "Authorization: Bearer ka_live_xxxx" \
  -F "file=@produkte_juni_2026.csv"

CSV-Vorlage herunterladen: produkte_vorlage.csv · Spalten: id, name, kategorie, preis_mt, preis_kwh, laufzeit, bonus, gueltig_bis

GET /v1/hardware 🔜 In Vorbereitung

Noch nicht live. Hardware-Katalog folgt. Geplante Antwort:

JSON Response (geplant)

{
  "hardware": [
    {
      "id": "hw_7590ax",
      "name": "Fritz!Box 7590 AX",
      "preis_einmalig": 0,
      "inkludiert": true,
      "kategorien": ["dsl", "glasfaser"]
    }
  ]
}

Webhooks

Webhooks benachrichtigen Ihr System automatisch bei Statusänderungen. Sie hinterlegen eine HTTPS-URL in Ihren API-Einstellungen.

Webhook Payload

{
  "event": "auftrag.status_geaendert",
  "auftrag_nr": "AUF-2026-0523",
  "externe_id": "MEIN-SYS-4711",
  "status_alt": "neu",
  "status_neu": "abgeschlossen",
  "timestamp": "2026-06-09T14:22:11Z",
  "ag_id": "ag_123"
}

Event-Typen

Event	Auslöser
auftrag.erstellt	Neuer Auftrag eingegangen
auftrag.status_geaendert	Auftragsstatus wurde aktualisiert
auftrag.abgeschlossen	Auftrag vollständig abgewickelt
auftrag.storniert	Auftrag wurde storniert
provision.freigegeben	Provisionsanzeige freigegeben

Signatur prüfen

Jeder Webhook enthält den Header X-KA-Signature – ein HMAC-SHA256 des Request-Body mit Ihrem Webhook-Secret.

Node.js

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from('sha256=' + expected)
  );
}

Datenobjekte

Kunde

Feld	Typ	Pflicht	Beschreibung
anrede	string	Optional	Herr \| Frau \| Divers \| Firma
vorname	string	✱	Vorname
nachname	string	✱	Nachname
geburtsdatum	date	✱	ISO 8601 (YYYY-MM-DD)
email	string	✱	Gültige E-Mail-Adresse
telefon	string	✱	Mobilnummer inkl. Vorwahl
adresse	object	✱	strasse, hausnr, plz, ort

Details (Strom / Gas)

Feld	Typ	Pflicht	Beschreibung
kwh_jahr	integer	✱	Jahresverbrauch in kWh
zaehler_nr	string	✱	Zählernummer
lieferbeginn	date	✱	Gewünschter Lieferbeginn
vorversorger	string	Optional	Name des bisherigen Versorgers
zaehlerstand	integer	Optional	Aktueller Zählerstand in kWh

Enumerationen

Status-Werte

Wert	Bedeutung
neu	Auftrag eingegangen, noch nicht bearbeitet
in_bearbeitung	Wird aktuell verarbeitet
abgeschlossen	Auftrag vollständig abgewickelt
storniert	Auftrag wurde widerrufen oder storniert
fehler	Fehler bei der Verarbeitung

Sandbox & Testing

Für den Live-Test von v1 (read-only) genügt der /v1/ping-Endpunkt – in King Connect ist dafür ein Test-Knopf eingebaut („verbunden ✓"). Eine separate Sandbox mit ka_test_-Keys folgt mit dem schreibenden v2 (dann werden keine echten Aufträge verarbeitet).

🧪 Verbindungstest: GET /v1/ping mit Ihrem ka_live_-Schlüssel → 200 {"ok":true,…}

Test-IBANs

IBAN	Verhalten
DE89370400440532013000	Immer gültig
DE00000000000000000000	Löst 422 Validierungsfehler aus

Test-Tarif-IDs

ID	Kategorie
test_strom_basis	Strom
test_gas_komfort	Gas
test_glasfaser_1000	Glasfaser