⚠️ You'll find German domain-specific terms in the documentation, for translations and further explanations please refer to our glossary
These APIs allow the calculation of Schaufensterkonditionen as well as calculating and accepting Angebote based on a Vorgang. All APIs documented here are GraphQL-APIs.
This API may contain advanced beta features that are still in development. Beta features may undergo modifications or be removed at a later release.
⚠️ This API is continuously developed. Therefore we expect all users to align with the "Tolerant Reader Pattern", which requires clients to be tolerant towards compatible API changes when reading and processing the data. This means:
unknown properties must not result in errors
Strings with a restricted set of values (Enums) must support new unknown values
sensible usage of HTTP status codes, even if they are not explicitly documented
These APIs are secured by the OAuth 2.0 client credentials flow using the Authorization-API. To use these APIs your OAuth2-Client needs the following scopes:
| Scope | Label in Partnermanagement | Description |
|---|---|---|
| privatkredit:angebot:ermitteln | KreditSmart-Angebote ermitteln | Scope for calculating Schaufensterkonditionen and Angebote |
| privatkredit:antrag:schreiben | KreditSmart-Anträge anlegen/verändern | Scope for accepting an Angebot (creating an Antrag) |
These APIs accept data with the content-type application/json with UTF-8 encoding. The fields inside a block can be sent in any order.
The APIs support all common GraphQL formats. More information can be found at https://graphql.org/learn/queries/.
The body of a GraphQL request contains the field query, which includes the GraphQL query as a String. Parameters can be set directly in the query or defined as variables.
The variables can be sent in the variables field of the body as a key-value map. All our examples use variables.
{
"query": "...",
"variables": { ... }
}
One of the special features in GraphQL is that most errors are not reflected via HTTP error codes.
In many cases you receive a status code 200, even though an error has occurred. These GraphQL errors can be found in the errors field of the response body.
More information about error codes can be found here.
| Error Code | Message | Description |
|---|---|---|
| 401 | Unauthorized | Authentication failed |
| 403 | Forbidden | The API client misses a scope |
| 415 | Unsupported MediaType | The wrong content type was used |
| Error Code | Message | Description |
|---|---|---|
| 400 | Bad Request | Request format is invalid (mandatory fields are missing, wrong parameter names or values, ...) |
| 403 | Forbidden | The authenticated user does not have sufficient rights |
| 409 | Conflict | The Vorgang was updated after the offer was calculated and before the offer was accepted |
Schaufensterkonditionen, both the top Schaufensterkondition and a complete list, can be retrieved via our GraphQL API using HTTP POST.
The URL for the Schaufensterkonditionen is:
https://kex-angebote.ratenkredit.api.europace.de/schaufenster
- The calculation of Top-Schaufensterkondition requires a valid
auszahlungsbetragandlaufzeitInMonaten. If the provided values are not valid, an GraphQL-Error with the status code400is returned.
The GraphQL-Query is called topSchaufensterkondition and contains the following parameter:
| Parameter Name | Type | Default Value | Details |
|---|---|---|---|
| partnerId | Partner-ID | The Partner-ID of the API Client | |
| auszahlungsbetrag | Euro! | - (mandatory field) | Value must be greater than 0 |
| laufzeitInMonaten | Int | - (mandatory field) | Value must be greater than 0 |
| finanzierungszweck | Finanzierungszweck | Calculation over all values of Finanzierungszweck | |
| datenkontext | Datenkontext | TESTUMGEBUNG |
The Query returns a Schaufensterkondition.
POST https://kex-angebote.ratenkredit.api.europace.de/schaufenster
Authorization: Bearer xxxx
Content-Type: application/json
{
"query": "query topSchaufensterkondition($partnerId: String, $auszahlungsbetrag: Euro!, $laufzeitInMonaten: Int, $finanzierungszweck: Finanzierungszweck) {
topSchaufensterkondition(partnerId: $partnerId, auszahlungsbetrag: $auszahlungsbetrag, laufzeitInMonaten: $laufzeitInMonaten, finanzierungszweck: $finanzierungszweck) {
ratenkredit {
produktanbieter {
name
}
}
gesamtkonditionen {
sollzins
effektivzins
gesamtkreditbetrag
}
}
}",
"variables": {
"partnerId": "ABC12",
"auszahlungsbetrag": 10000,
"laufzeitInMonaten": 72,
"finanzierungszweck": "UMSCHULDUNG"
}
}
{
"data": {
"topSchaufensterkondition": {
"ratenkredit": {
"produktanbieter": {
"name": "Testbank AG"
}
},
"gesamtkonditionen": {
"sollzins": 2.95,
"effektivzins": 2.99,
"gesamtbetrag": 10916.88
}
}
}
}
- The calculation of Schaufensterkondition requires a valid
auszahlungsbetragandlaufzeitInMonaten. If the provided values are not valid, an GraphQL-Error with the status code400is returned.
The GraphQL-Query is called schaufensterkonditionen and has the following parameter:
| Parameter Name | Type | Default Value | Details |
|---|---|---|---|
| partnerId | Partner-ID | The Partner-ID of the API Client | |
| auszahlungsbetrag | Euro! | - (mandatory field) | Value must be greater than 0 |
| laufzeitInMonaten | Int | - (mandatory field) | Value must begreater than 0 |
| finanzierungszweck | Finanzierungszweck | FREIE_VERWENDUNG |
|
| datenkontext | Datenkontext | TESTUMGEBUNG |
The Query returns a list of Schaufensterkonditionen.
POST https://kex-angebote.ratenkredit.api.europace.de/schaufenster
Authorization: Bearer xxxx
Content-Type: application/json
{
"query": "query schaufensterkonditionen($partnerId: String, $auszahlungsbetrag: Euro!, $laufzeitInMonaten: Int, $finanzierungszweck: Finanzierungszweck) {
schaufensterkonditionen(partnerId: $partnerId, auszahlungsbetrag: $auszahlungsbetrag, laufzeitInMonaten: $laufzeitInMonaten, finanzierungszweck: $finanzierungszweck) {
ratenkredit {
produktanbieter {
name
}
}
gesamtkonditionen {
sollzins
effektivzins
gesamtkreditbetrag
}
}
}",
"variables": {
"partnerId": "ABC12",
"auszahlungsbetrag": 10000,
"laufzeitInMonaten": 72,
"finanzierungszweck": "UMSCHULDUNG"
}
}
{
"data": {
"schaufensterkonditionen": [
{
"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
}
}
]
}
}
You can calculate a list of machbare and vollständige Angebote using data of a Vorgang via our GraphQL-API using HTTP POST. Using the id of the corresponding Angebot you can accept it.
The URL for calculating and accepting Angebote is:
https://kex-angebote.ratenkredit.api.europace.de/angebote
- The calculation of Angebote is only possible if the corresponding Vorgang includes a valid Kreditbetrag and Laufzeit or Rate. Should that not be the case the API user receives
a GraphQL-Error with the status code
400. The Vorgang has to be corrected before you can continue. - Please provide the correct value for the vertriebskanal. That is important in order to deliver e.g. the correct documents for B2B and B2B2C and to generate appropriate and valuable reporting.
- To empower API users with insightful predictions and enhance API capabilities, a feasibility prediction score was added. Based on a prediction model, this score is a beta feature that aims at predicting the likelihood for a Vorgang to secure reliable machbare Angebote. The score is in percent. The higher the score value, the more likely the Vorgang will lead to machbare Angebote. In case of an error while calculating the feasibility score, the Angebot will be returned with an empty score field.
The GraphQL-Query is called angebote and has the following parameters.
If only the vorgangsnummer is provided, only complete offers will be returned.
| Parameter Name | Type | Default Value |
|---|---|---|
| vorgangsnummer | String! | - (mandatory field) |
| options | AngebotOptions | { includeVollstaendigkeitsstatus: [VOLLSTAENDIG], includeMachbarkeitsstatus: [MACHBAR], vertriebskanal: B2B2C } |
The Query returns a list of Angebote.
POST https://kex-angebote.ratenkredit.api.europace.de/angebote
Authorization: Bearer xxxx
Content-Type: application/json
{
"query": "query angebote($vorgangsnummer: String!) {
angebote(vorgangsnummer: $vorgangsnummer) {
ratenkredit {
produktanbieter {
name
}
}
gesamtkonditionen {
sollzins
effektivzins
gesamtkreditbetrag
}
}
}",
"variables": {
"vorgangsnummer": "ABC123"
}
}
{
"data": {
"angebote": [
{
"gesamtkonditionen": {
"effektivzins": 2.99,
"gesamtbetrag": 10916.88,
"sollzins": 2.95
},
"ratenkredit": {
"produktanbieter": {
"name": "Testbank AG"
}
}
}
]
}
}
- Currently the API only supports Fernabsatzgeschäft.
- The vertriebskanal that was used to query the offers will be used when an offer is accepted, if no vertriebskanal was provided the default value B2B2C is used. That is important in order to deliver e.g. the correct documents for B2B and B2B2C and to generate appropriate and valuable reporting.
- When accepting an offer the authenticated user needs to have a Handelsbeziehung for the corresponding bank, which allows the acceptance. Otherwise the user receives
a GraphQL-Error with the status code
403. - Accepting an offer is only possible if the Vorgang did not change in the meantime. Should there be updates between the calculation of offers and accepting an offer the user receives
a GraphQL-Error with the status code
409. In this case the calculation of the offers needs to be done again. - To optimize the process we might calculate alternative offers.
- The Kundenbetreuer of a Vorgang is important for accepting an offer as the name and contact details will be sent to the bank.
The GraphQL-Mutation is called angebotAnnehmenand has the following parameter:
| Parameter Name | Type | Default Value | Comment |
|---|---|---|---|
| vorgangsnummer | String! | - (mandatory field) | |
| angebotId | String! | - (mandatory field) | The ID of the calculated offer that is to be accepted |
This Mutation returns a jobId.
POST https://kex-angebote.ratenkredit.api.europace.de/angebote
Authorization: Bearer xxxx
Content-Type: application/json
{
"query": "mutation annehmen($vorgangsnummer: String!, $angebotId: String!) {
angebotAnnehmen(angebotId: $angebotId, vorgangsnummer: $vorgangsnummer ){
jobId
}
}
}",
"variables": {
"vorgangsnummer": "ABC123"
"angebotId": "angebotId"
}
}
{
"data": {
"angebotAnnehmen": {
"jobId": "AB12345678"
}
},
"errors": []
}
- If the offer cannot be accepted from the bank, the response will contain
status=SUCCESSbut not contain any Antrag. - A partner can only query jobs that were created by this partner otherwise a 403 FORBIDDEN is returned.
- Only complete offers can be accepted, if an incomplete offer is requested, it will result in a 400 BAD REQUEST
The GraphQL-Query is called annahmeJob and has the following parameter:
| Parameter Name | Type | Default Value | Comment |
|---|---|---|---|
| jobId | String! | - (mandatory field) | The ID of the job, which was returned when initiating the acceptance process |
| jobOptions | JobOptions | { includeMachbarkeitsstatus: [MACHBAR] |
This Query returns an AnnahmeJob. It contains the Status of the acceptance process and the Antrag if the process was successful.
POST https://kex-angebote.ratenkredit.api.europace.de/angebote
Authorization: Bearer xxxx
Content-Type: application/json
{
"query": "query annahmeJob($jobId: String!) {
annahmeJob(jobId: $jobId) {
status
antrag {
antragsnummer
gesamtkonditionen {
sollzins
effektivzins
laufzeitInMonaten
gesamtkreditbetrag
nettokreditbetrag
rateMonatlich
}
}
}
}",
"variables": {
"jobId": "$jobId"
}
}
{
"data": {
"angebotAnnehmen": {
"status": "SUCCESS",
"antrag": {
"antragsnummer": "ABC123/1/1",
"gesamtkonditionen": {
"sollzins": 2.95,
"effektivzins": 2.99,
"laufzeitInMonaten": 60,
"gesamtkreditbetrag": 10762.19,
"nettokreditbetrag": 10000,
"rateMonatlich": 179.47
}
}
}
},
"errors": []
}
{
includeMachbarkeitsstatus: [MachbarkeitStatus]
includeVollstaendigkeitsstatus: [VollstaendigkeitStatus],
vertriebskanal: Vertriebskanal
}
For possible value for MachbarkeitStatus see here.
For possible value for VollstaendigkeitStatus see here.
{
B2B2C
B2B
}
This type is a String which can currently have one of the following values
{
TESTUMGEBUNG
ECHTGESCHAEFT
}
This type is a String which can currently have one of the following values
{
UMSCHULDUNG
FREIE_VERWENDUNG
FAHRZEUGKAUF
MODERNISIEREN
}
{
includeMachbarkeitsstatus: [MachbarkeitStatus]
}
For possible value for MachbarkeitStatus see here.
This type is a 5-digit String and identifies a Plakette of the Europace-Partnermanagement.
The Partner-ID has to be underneath or identical to the Partner-ID of the API-Client.
For better readability, the overall format is broken down into types that are defined separately but should be used at the corresponding positions.
The attributes within a block can be specified in any order. There are the scalars Euro and Prozent, which are wrappers for BigDecimal.
{
gesamtkonditionen: Gesamtkonditionen
ratenkredit: Ratenkredit
}
{
anpassungen: Anpassungen
gesamtkonditionen: AngebotGesamtkonditionen
id: String!
machbarkeit: Machbarkeit
ratenkredit: AngebotRatenkredit
ratenschutz: Ratenschutz
sofortkredit: Boolean
vollstaendigkeit: Vollstaendigkeit
vorhersage: Vorhersage
bonitaetsrechnung: Bonitaetsrechnung
}
{
effektivzins: Prozent,
gesamtkreditbetrag: Euro
konditionsspanne: Konditionsspanne
laufzeitInMonaten: Int
nettokreditbetrag: Euro
auszahlungsbetrag: Euro
rateMonatlich: Euro
sollzins: Prozent
}
{
maximum: Konditionsgrenze
minimum: Konditionsgrenze
}
{
effektivzins: Prozent
gesamtkreditbetrag: Euro
rateMonatlich: Euro
sollzins: Prozent
}
{
produktanbieter: Produktanbieter
produktbezeichnung: String
schlussrate: Euro
}
{
angepasst: Boolean
}
{
messages: [VollstaendigkeitMessage]
status: VollstaendigkeitStatus
}
{
category: VollstaendigkeitCategory
identifier: VollstaendigkeitIdentifier
property: String
reason: VollstaendigkeitReason
text: String
}
{
AUSGABEN
BESCHAEFTIGUNG
EINNAHMEN
FINANZBEDARF
HERKUNFT
IMMOBILIEN
KINDER
PERSONENDATEN
SOFORTKREDIT
VERBINDLICHKEITEN
VERMITTLER
VORGANG
WOHNSITUATION
}
{
ids: [String!]!
type: VollstaendigkeitIdentifierType!
}
{
ANTRAGSTELLER
VERMITTLER
}
{
VALUE_IS_EMPTY
VALUE_IS_INVALID
VALUE_OUT_OF_RANGE
}
{
UNVOLLSTAENDIG
VOLLSTAENDIG
}
{
machbarkeit: Machbarkeitsvorhersage
}
{
score: Prozent
}
{
status: JobStatus!
antrag: Antrag
}
"FAILURE" | "PENDING" | "SUCCESS"
{
antragsnummer: String!
produktanbieterantragsnummer: String
gesamtkonditionen: AntragGesamtkonditionen
ratenkredit: AntragRatenkredit
ratenschutz: Ratenschutz
dokumente: [Dokument!]
identifikationAntragsteller1: Identifikation
identifikationAntragsteller2: Identifikation
machbarkeit: Machbarkeit
bonitaetsrechnung: Bonitaetsrechnung
}
{
effektivzins: Prozent
gesamtkreditbetrag: Euro
laufzeitInMonaten: Int
nettokreditbetrag: Euro
auszahlungsbetrag: Euro
rateMonatlich: Euro
sollzins: Prozent
}
{
produktanbieter: Produktanbieter
schlussrate: Euro
}
{
url: String
}
{
antragstellername: String
qesUrl: String
referenznummer: String
videolegitimationUrl: String
}
{
einnahmen: BonitaetsrechnungGroup
ausgaben: BonitaetsrechnungGroup
total: String
}
{
positions: [BonitaetsrechnungPosition]
total: String
}
{
label: String
value: String
}
{
messages: [MachbarkeitMessage]
status: MachbarkeitStatus!
}
{
text: String
}
{
MACHBAR
NICHT_MACHBAR
}
{
anschrift: Anschrift
logo: Logo
name: String
}
{
hausnummer: String
strasse: String
ort: String
plz: String
}
{
svg: String
}
The field svg contains the URL of the svg and not the content.
{
praemieMonatlich: Euro
praemieBrutto: Euro
praemieNetto: Euro
produktanbieter: [Produktanbieter]
versicherungssumme: Euro
versicherteRate: Euro
versicherteRisikenAntragsteller1: [VersichertesRisiko!]!
versicherteRisikenAntragsteller2: [VersichertesRisiko!]!
}
{
ARBEITSLOSIGKEIT
ARBEITSUNFAEHIGKEIT
LEBEN
}
The field antragstellername contains the name in the format "<first name> <last name>".
The APIs are made available under the following Terms of Use.