Europace AG
Heidestraße 8, D-10557 Berlin
devsupport@europace2.de

KEX Angebote API

Ermittlung von Schaufensterkonditionen (Top-Konditionen) in Bezug auf eine dedizierte Vertriebseinheit.


Table of Contents

Allgemeines

Die Schnittstelle ermöglicht die Ermittlung von Ratenkredit-Angeboten.

:warning: Diese Schnittstelle wird kontinuierlich weiterentwickelt. Daher erwarten wir von allen Nutzern dieser Schnittstelle, dass sie das "Tolerant Reader Pattern" nutzen, d.h. tolerant gegenüber kompatiblen API-Änderungen beim Lesen und Prozessieren der Daten sind:

  1. unbekannte Felder dürfen keine Fehler verursachen

  2. Strings mit eingeschränktem Wertebereich (Enums) müssen mit neuen, unbekannten Werten umgehen können

  3. sinnvoller Umgang mit HTTP-Statuscodes, die nicht explizit dokumentiert sind

Angebote

Angebote, sowohl das beste Angebot als auch die komplette Angebotsliste, können über unsere GraphQL Schnittstelle via HTTP POST ermittelt werden.
Die URL für das Ermitteln von Angeboten ist:

https://kex-angebote.kreditsmart.api.europace.de/angebote

Beispiele

Query bestesAngebot

POST Request

POST https://kex-angebote.kreditsmart.api.europace.de/angebote
Authorization: Bearer xxxx
Content-Type: application/json

{
  "query": "query bestesAngebot($partnerId: String, $auszahlungsbetrag: Euro!, $laufzeitInMonaten: Int) { 
     bestesAngebot(partnerId: $partnerId, auszahlungsbetrag: $auszahlungsbetrag, laufzeitInMonaten: $laufzeitInMonaten) {
        ratenkredit {
            produktanbieter {
                name
            }
        }
        gesamtkonditionen {
            sollzins
            effektivzins
            gesamtkreditbetrag
        }
     }
  }",
  "variables": {
    "partnerId": "ABC12",
    "auszahlungsbetrag": 10000,
    "laufzeitInMonaten": 72
  }
}

POST Response

{
    "data": {
        "bestesAngebot": {
            "ratenkredit": {
                "produktanbieter": {
                    "name": "Testbank AG"
                }
            },
            "gesamtkonditionen": {
                "sollzins": 2.95,
                "effektivzins": 2.99,
                "gesamtbetrag": 10916.88
            }
        }
    }
}

Query angebote

POST Request

POST https://kex-angebote.kreditsmart.api.europace.de/angebote
Authorization: Bearer xxxx
Content-Type: application/json

{
  "query": "query angebote($partnerId: String, $auszahlungsbetrag: Euro!, $laufzeitInMonaten: Int) { 
     angebote(partnerId: $partnerId, auszahlungsbetrag: $auszahlungsbetrag, laufzeitInMonaten: $laufzeitInMonaten) {
        ratenkredit {
            produktanbieter {
                name
            }
        }
        gesamtkonditionen {
            sollzins
            effektivzins
            gesamtkreditbetrag
        }
     }
  }",
  "variables": {
    "partnerId": "ABC12",
    "auszahlungsbetrag": 10000,
    "laufzeitInMonaten": 72
  }
}

POST Response

{
    "data": {
        "angebote": [
            {
                "ratenkredit": {
                    "produktanbieter": {
                        "name": "Testbank1 AG"
                    }
                },
                "gesamtkonditionen": {
                    "sollzins": 3.95,
                    "effektivzins": 3.99,
                    "gesamtbetrag": 10916.88
                }
            },
            {
                "ratenkredit": {
                    "produktanbieter": {
                        "name": "Testbank2 AG"
                    }
                },
                "gesamtkonditionen": {
                    "sollzins": 2.95,
                    "effektivzins": 2.99,
                    "gesamtbetrag": 10916.88
                }
            }
        ]
    }
}

Request

Die Angaben werden als JSON mit UTF-8 Encoding im Body des Requests gesendet.
Die Attribute innerhalb eines Blocks können in beliebiger Reihenfolge angegeben werden.

Authentifizierung

Für jeden Request ist eine Authentifizierung erforderlich. Die Authentifizierung erfolgt über den OAuth 2.0 Client-Credentials Flow.

Request Header Name Beschreibung
Authorization OAuth 2.0 Bearer Token

Das Bearer Token kann über die Authorization-API angefordert werden. Dazu wird ein Client benötigt der vorher von einer berechtigten Person über das Partnermanagement angelegt wurde, eine Anleitung dafür befindet sich im Help Center.

Damit der Client für diese API genutzt werden kann, muss im Partnermanagement die Berechtigung Kreditsmartangebote ermitteln aktiviert sein.

Schlägt die Authentifizierung fehl, erhält der Aufrufer eine HTTP Response mit Statuscode 401 UNAUTHORIZED.

Hat der Client nicht die benötigte Berechtigung um die Resource abzurufen, erhält der Aufrufer eine HTTP Response mit Statuscode 403 FORBIDDEN.

Nachverfolgbarkeit von Requests

Für jeden Request soll eine eindeutige ID generiert werden, die den Request im EUROPACE System nachverfolgbar macht und so bei etwaigen Problemen oder Fehlern die systemübergreifende Analyse erleichtert.
Die Übermittlung der X-TraceId erfolgt über einen HTTP-Header. Dieser Header ist optional. Wenn er nicht gesetzt ist, wird eine ID vom System generiert. Hilfreich für die Analyse ist es, wenn die TraceId mit einem System-Kürzel beginnt (im Beispiel unten 'sys').

Request Header Name Beschreibung Beispiel
X-TraceId eindeutige Id für jeden Request sys12345678

Format

Die Schnittstelle unterstützt alle gängigen GraphQL Formate. Ein Beispiel ist das folgende Format (siehe auch den Beispiel Requests):

<angebote/bestesAngebot>(partnerId: <partnerId>, auszahlungsbetrag: <auszahlungsbetrag>, laufzeitInMonaten: <laufzeitInMonaten>, finanzierungszweck: <finanzierungszweck>, datenkontext: <datenkontext>){
    <gewünschte Felder>
}

Request Parameter

Bestes Angebot

Parametername Typ Default
partnerId Partner-ID Die Partner-ID aus dem API-Client
auszahlungsbetrag Euro! Pflichtfeld
laufzeitInMonaten Int -
finanzierungszweck Finanzierungszweck Alle Finanzierungszwecke
datenkontext Datenkontext TESTUMGEBUNG

Angebotsliste

Parametername Typ Default
partnerId Partner-ID Die Partner-ID aus dem API-Client
auszahlungsbetrag Euro! Pflichtfeld
laufzeitInMonaten Int -
finanzierungszweck Finanzierungszweck FREIE_VERWENDUNG
datenkontext Datenkontext TESTUMGEBUNG

Partner-ID

Dieser Typ ist ein 5-stelliger String und identifiziert eine Plakette aus dem Europace-Partnermanagement.
Die angegebene Partner-ID muss unterhalb der Partner-ID des API-Clients liegen oder mit ihr identisch sein.

Datenkontext

Dieser Typ ist ein String, der aktuell folgende Werte annehmen kann

  • TESTUMGEBUNG
  • ECHTGESCHAEFT

Finanzierungszweck

Dieser Typ ist ein String, der aktuell folgende Werte annehmen kann

  • UMSCHULDUNG
  • FREIE_VERWENDUNG
  • FAHRZEUGKAUF
  • MODERNISIEREN

Anfragbare Felder

Für eine bessere Lesbarkeit wird das Gesamtformat in Typen aufgebrochen, die an anderer Stelle definiert sind, aber an verwendeter Stelle eingesetzt werden müssen.
Es gibt die Scalare Euro und Prozent, die jeweils Wrapper für BigDecimal sind.

Angebot

{
    gesamtkonditionen: Gesamtkonditionen
    ratenkredit: Ratenkredit
}

Gesamtkonditionen

{
    effektivzins: Prozent,
    gesamtkreditbetrag: Euro,
    laufzeitInMonaten: Int,
    nettokreditbetrag: Euro,
    rateMonatlich: Euro,
    sollzins: Prozent,
    zinsgrenzen: Zinsgrenzen
}
Zinsgrenzen
{
    maximalerEffektivzins: Prozent,
    maximalerSollzins: Prozent,
    minimalerEffektivzins: Prozent,
    minimalerSollzins: Prozent
}

Ratenkredit

{
    produktanbieter: Produktanbieter,
    produktbezeichnung: String,
    schlussrate: Euro
}
Produktanbieter
{
    name: String
    anschrift: Anschrift
    logo: Logo
}
Anschrift
{
    strasse: String
    hausnummer: String
    plz: String
    ort: String
}
Logo
{
    svg: String
}    

Das Property svg enthält die URL auf das SVG.

Fehlercodes

Die Besonderheit in GraphQL ist u.a., dass die meisten Fehler nicht über HTTP-Fehlercodes wiedergegeben werden. In vielen Fällen bekommt man einen Status 200 zurück, obwohl ein Fehler aufgetreten ist. Dafür gibt es das Attribut errors in der Response.

HTTP-Status Errors

Fehlercode Nachricht Erklärung
400 Bad Request Request Format ist ungültig, z.B. Pflichtfelder fehlen, Parameternamen, -typen oder -werte sind falsch, ...
401 Unauthorized Authentifizierung ist fehlgeschlagen
403 Forbidden Der API-Client besitzt nicht den richtigen Scope
415 Unsupported MediaType Es wurde ein anderer content-type angegeben

Weitere Fehler

Wenn der Request nicht erfolgreich verarbeitet werden konnte, liefert die Schnittstelle eine 200, aber in dem Attribut errors sind Fehlerdetails zu finden

{
  "data": {},
  "errors": [
    {
      "message": MESSAGE,
      "status": STATUS_CODE
    }
  ]
}

Tools

Das GraphQL-Schema kann man z.B. mit dem Tool GraphiQL analysieren und sich per Autocomplete bequem die Query zusammenbauen.

Nutzungsbedingungen

Die APIs werden unter folgenden Nutzungsbedingungen zur Verfügung gestellt

Wir sind für Dich da! Wir beantworten gerne alle Fragen