Base URL: https://api.ckonto.de

Version: v1  (alle Endpunkte beginnen mit /v1/)

Format: JSON (Content-Type: application/json)

Discovery: /service  |  OpenAPI 3.0 Schema

Alle Endpunkte (außer /service, /service/openapi.json sowie /v1/ping und /v1/test) erfordern einen gültigen API-Schlüssel als Bearer-Token:

Authorization: Bearer API_KEY

Alternativ via Header X-API-Key: API_KEY. Der Schlüssel wird ausschließlich per Header übergeben - nicht als Query-Parameter und nicht im Request-Body. So landet er weder in Server-Logs noch in Browser-Verläufen oder Referer-Headern.

/v1/ping und /v1/test sind bewusst ohne Authentifizierung erreichbar (gedacht für Healthchecks/Monitoring). Ein trotzdem mitgeschickter Token wird dort ignoriert und nicht geprüft.

API-Schlüssel erhalten Sie über ckonto.de/bestellung.htm.

Prüft eine deutsche Kontonummer und Bankleitzahl. Optional mit IBAN-Generierung (sepa=1).

Beispiel GET

curl -H "Authorization: Bearer API_KEY" \
  "https://api.ckonto.de/v1/kto/0532013000/37040044"

Beispiel POST

curl -H "Authorization: Bearer API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"kontonummer":"0532013000","bankleitzahl":"37040044"}' \
  "https://api.ckonto.de/v1/kto"

Antwort

{
  "status": 1,
  "message": "The bank account details are valid",
  "data": {
    "iban": null,
    "bic": null,
    "kto": "0532013000",
    "blz": "37040044",
    "bank": "Commerzbank",
    "zip": "50447",
    "location": "Köln",
    "country": "DE"
  }
}

Mit sepa=1 (GET: Query-Parameter, POST: im JSON-Body) werden iban und bic zusätzlich zurückgegeben. Zulässig sind ausschließlich 0 und 1; andere Werte liefern HTTP 400 mit Code invalid_sepa. Fehlt der Parameter, gilt der Default 0.

country enthält immer den ISO-3166-1-alpha-2-Ländercode der Bank (z. B. DE), nicht den ausgeschriebenen Ländernamen. Ist kein Code ermittelbar, ist das Feld ein leerer String.

ccd (optional, GET: Query-Parameter, POST: im JSON-Body): 2-stelliger Ländercode, steuert die IBAN-Generierung aus Kontonummer/BLZ für Länder außerhalb Deutschlands. Unterstützt: DE, AT, CH, BE, CZ, SK, ES (Groß-/Kleinschreibung wird toleriert, andere Werte werden ignoriert). Wirkt unabhängig von sepa auch auf das Feld country der Antwort.

Wichtig: kontonummer und bankleitzahl müssen im länderspezifischen Format vorliegen – nicht zwingend 8-stellig wie bei einer deutschen BLZ. ccd allein liefert nur country – für die generierte iban/bic zusätzlich sepa=1 setzen. Beispiel Slowakei:

curl -H "Authorization: Bearer API_KEY" \
  "https://api.ckonto.de/v1/kto/5207004203041425/8360?ccd=SK&sepa=1"

{
  "status": 1,
  "message": "The bank account details are valid",
  "data": {
    "iban": "SK4283605207004203041425",
    "bic": "BREXSKBXXXX",
    "kto": "5207004203041425",
    "blz": "8360",
    "bank": "mBank S.A., pobočka zahraničnej banky",
    "zip": "SK-81109",
    "location": "Bratislava",
    "country": "SK"
  }
}

Prüft eine IBAN (international, Schwerpunkt DE/AT/CH/EU). Optional mit BIC-Validierung. Per POST auch als Batch bis 500 IBANs.

iban und bic werden bei diesem Endpunkt immer zurückgegeben – ein sepa-Parameter wird hier syntaktisch akzeptiert, hat aber keine Wirkung (anders als bei der Kontonummer/BLZ-Prüfung, wo erst sepa=1 sie freischaltet).

Beispiel GET

curl -H "Authorization: Bearer API_KEY" \
  "https://api.ckonto.de/v1/iban/DE89370400440532013000"

Antwort (Einzelprüfung)

{
  "status": 1,
  "message": "The IBAN is valid",
  "data": {
    "iban": "DE89370400440532013000",
    "bic": "COBADEFFXXX",
    "kto": "0532013000",
    "blz": "37040044",
    "bank": "Commerzbank",
    "zip": "DE-50447",
    "location": "Köln",
    "country": "DE",
    "sepa_methods": {
      "sct": 1,
      "sdd": 1,
      "b2b": 1,
      "scc": 1
    }
  }
}

sepa_methods zeigt, welche SEPA-Zahlungsverfahren die Bank unterstützt: sct (Überweisung), sdd (Lastschrift), b2b (Firmenlastschrift), scc (Cards Clearing). Wert 1 = unterstützt, 0 = nicht unterstützt, 9 = nicht ermittelbar (unvollständige Bankstammdaten für dieses Land, kommt vor allem außerhalb DE/AT/CH vor).

country enthält immer den ISO-3166-1-alpha-2-Ländercode der Bank (z. B. DE, AT, CH), nicht den ausgeschriebenen Ländernamen. Ist kein Code ermittelbar, ist das Feld ein leerer String.

Beispiel POST – Einzelprüfung mit BIC

curl -H "Authorization: Bearer API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"iban":"DE89370400440532013000","bic":"COBADEFFXXX"}' \
  "https://api.ckonto.de/v1/iban"

Negativbeispiele (jeweils ein anderer Status/Fehler)

Die ersten beiden Fälle sind keine Fehler im HTTP-Sinn (HTTP 200) – die Anfrage war syntaktisch korrekt, das fachliche Prüfergebnis ist „ungültig" bzw. „BLZ unbekannt". Nur der dritte Fall ist ein echter Request-Fehler (HTTP 400), weil die IBAN nicht einmal dem Grundformat entspricht.

Beispiel POST – Batch (bis 500 IBANs)

curl -H "Authorization: Bearer API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"ibans":["DE89370400440532013000","AT001234512345678901"]}' \
  "https://api.ckonto.de/v1/iban"

Batch-Antwort

Zählung: Jede IBAN in einem Batch zählt als eine Abfrage - auch Einträge, die bereits an der Formatprüfung scheitern.

Jedes Element in batch.results enthält immer iban, valid, status und data – auch wenn die IBAN fachlich ungültig ist (z. B. status: 7, „BLZ existiert nicht"). Das ist kein Fehler und trägt kein error-Objekt. Ein error-Objekt erscheint ausschließlich, wenn dieses Item gar nicht geprüft werden konnte (Formatfehler oder Backend-Fehler); es ist flach aufgebaut und nutzt wie die übrigen Fehlerobjekte das Feld code (nicht error_code).

{
  "status": 1,
  "message": "Batch processing completed",
  "batch": {
    "total": 3,
    "results": [
      { "status": 1, "iban": "DE89370400440532013000", "valid": true,  "data": { "country": "DE", "sepa_methods": { "sct": 1, "sdd": 1, "b2b": 1, "scc": 1 }, ... } },
      { "status": 7, "iban": "DE93999999990000000001", "valid": false, "data": { "country": "DE", ... } },
      { "status": 0, "iban": "XX",                     "valid": false, "data": { "country": "", ... },
        "error": { "code": "invalid_iban", "message": "The IBAN is invalid or has an incorrect format", "field": "iban" } }
    ]
  }
}

Sucht Banken nach Name, Ort, PLZ oder BLZ. Mindestens eines der Felder name, location, zip oder bankleitzahl muss belegt sein – ohne jedes Suchkriterium liefert die API HTTP 400 mit Code missing_search_criteria. Maximal 50 Treffer.

max begrenzt die Anzahl der Treffer (1–50). Fehlt max, gilt der Default 10. Werte außerhalb 1–50 oder nicht-numerische Werte liefern HTTP 400 mit Code invalid_max.

Beispiel GET

curl -H "Authorization: Bearer API_KEY" \
  "https://api.ckonto.de/v1/search?name=Sparkasse&location=Berlin&max=5"

Antwort

{
  "status": 1,
  "message": "The search was successful",
  "results": {
    "count": 4,
    "items": [
      { "bic": "BELADEBEXXX", "blz": "10050000", "bank": "BSK 1818 - Berliner Sparkasse", "zip": "10889", "location": "Berlin" },
      ...
    ]
  }
}

status ist hier wie überall ein numerischer Wert (kein String).

Prüft ob der Service erreichbar ist. /v1/test zeigt zusätzlich Testmode an. Kein Bearer-Token erforderlich – beide Endpunkte sind bewusst ohne Authentifizierung erreichbar (Healthcheck/Monitoring). Ein trotzdem mitgeschickter Token wird ignoriert.

{ "status": 1, "message": "Pong" }

Fehler werden immer als JSON-Objekt mit dem Schlüssel error zurückgegeben. Eine vollständige Liste aller Fehlercodes mit Beschreibungen und Beispielen findet sich unter /api/docs/errors.

{
  "error": {
    "http_status": 401,
    "code": "invalid_key",
    "message": "The API key is not valid"
  }
}

Das Feld status in der Erfolgs-Antwort enthält den fachlichen Prüfstatus von cKonto: