Kingsworth Adcon API v1.0

Die Kingsworth Adcon API ermöglicht Auftraggebern die direkte Integration in unsere Auftragsverarbeitung. Aufträge aus Ihren eigenen Systemen können automatisiert übermittelt, abgefragt und statusverfolgt werden.

📧 API-Zugang anfragen: api@kingsworthadcon.com · Sie erhalten innerhalb von 24h Ihre Zugangsdaten und einen dedizierten Sandbox-Bereich.

Was ist möglich?

Aufträge (Strom, Gas, DSL, Glasfaser, PV, Wärmepumpe) programmatisch einreichen
Eigene Tarife und Produkte hochladen und pflegen
Auftragsstatus in Echtzeit verfolgen
Webhook-Benachrichtigungen bei Statusänderungen empfangen
Hardware-Optionen und Optionen per API abrufen

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
Content-Type: application/json
X-AG-ID: ag_123  // Ihre Auftraggeber-ID

⚠️ API-Keys niemals im Frontend-Code oder in öffentlichen Repositories speichern. Nutzen Sie ausschließlich serverseitige Anfragen.

Key-Typen

Typ	Präfix	Verwendung
Live-Key	ka_live_	Produktivbetrieb – echte Aufträge
Sandbox-Key	ka_test_	Testbetrieb – keine echten Aufträge

Versionen & Basis-URL

// Produktiv
https://api.kingsworthadcon.com/v1

// Sandbox
https://sandbox.api.kingsworthadcon.com/v1

Alle Endpunkte sind unter der Basis-URL erreichbar. Aktuell verfügbar: v1.

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

Plan	Anfragen / Minute	Anfragen / Tag
Standard	60	10.000
Premium	300	100.000
Enterprise	Unbegrenzt	Unbegrenzt

Bei Überschreitung wird 429 Too Many Requests zurückgegeben. Der Header X-RateLimit-Reset gibt den Zeitpunkt der Zurücksetzung an.

Aufträge

POST /auftraege Neuen Auftrag einreichen

Reicht einen neuen Auftrag ein. Der Auftrag wird sofort 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 /tarife
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://api.kingsworthadcon.com/v1/auftraege \
  -H "Authorization: Bearer ka_live_xxxx" \
  -H "Content-Type: application/json" \
  -H "X-AG-ID: ag_123" \
  -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 /auftraege/{id} Einzelnen Auftrag abrufen

cURL

curl https://api.kingsworthadcon.com/v1/auftraege/ord_01j9k2mxyz \
  -H "Authorization: Bearer ka_live_xxxx" \
  -H "X-AG-ID: ag_123"

GET /auftraege Aufträge auflisten

Query Parameter

Parameter	Typ	Beschreibung
status	string	neu \| in_bearbeitung \| abgeschlossen \| storniert
kategorie	string	strom \| gas \| dsl \| glasfaser \| pv \| waerme
von	date	Startdatum (ISO 8601)
bis	date	Enddatum (ISO 8601)
limit	integer	Ergebnisse pro Seite (max. 100, default 20)
offset	integer	Pagination-Offset

cURL

curl "https://api.kingsworthadcon.com/v1/auftraege?status=neu&kategorie=strom&limit=50" \
  -H "Authorization: Bearer ka_live_xxxx" \
  -H "X-AG-ID: ag_123"

PUT /auftraege/{id}/status Auftragsstatus aktualisieren

JSON

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

Produkte & Tarife

GET /tarife Ihre aktiven Tarife abrufen

JSON Response

{
  "tarife": [
    {
      "id": "s_nfh_basis_2026",
      "name": "Strom Basis",
      "kategorie": "strom",
      "preis_mt": 89.00,
      "preis_kwh": 0.31,
      "laufzeit_monate": 12,
      "bonus": 50.00,
      "aktiv": true,
      "gueltig_bis": "2026-12-31"
    }
  ],
  "total": 12
}

POST /tarife Tarife hochladen / aktualisieren

Tarife können als JSON-Array oder per CSV-Upload übermittelt werden. Bestehende Tarife mit gleicher ID werden aktualisiert.

cURL – CSV Upload

curl -X POST https://api.kingsworthadcon.com/v1/tarife/upload \
  -H "Authorization: Bearer ka_live_xxxx" \
  -H "X-AG-ID: ag_123" \
  -F "file=@tarife_juni_2026.csv"

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

GET /hardware Hardware-Optionen abrufen

JSON Response

{
  "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

Die Sandbox-Umgebung ist identisch zur Produktivumgebung, jedoch werden keine echten Aufträge verarbeitet.

🧪 Sandbox-Basis-URL: https://sandbox.api.kingsworthadcon.com/v1
Sandbox-Keys beginnen mit ka_test_

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