Voraussetzungen
Datenformat
Die API nutzt HTTP und JSON um Daten abzurufen und zu liefern.
State Management
Die Neocom-API verfügt bereits über ein integriertes State Management. Daher müssen nur die Antwort(en) auf die aktuelle Frage zusammen mit einem Session-Token an die API gesendet werden. Der Session-Token identifiziert eine Berater-Session und kann nur einmal verwendet werden.
Bei jeder Anfrage an die API muss der Session-Token mit Ausnahme der ersten Anfrage mitgesendet werden. Wenn der Session-Token nicht existiert, wird eine neue Session erstellt und der neue Session-Token zurückgespielt.
Der Session-Token muss als separater HTTP-Header gesendet werden: Neocom-Session-Token.
Authentifizierung
Um die API zu nutzen, wird ein API-Key benötigt. Dieser API-Key muss mit jedem Request als separater HTTP-Header gesendet werden: Neocom-API-Key
Berater
Die API unterstützt mehrer Berater pro Klient. Daher muss die ID des entsprechenden Beraters bei jedem Request im HTTP-Header übermittelt werden: Neocom-Advisor-ID.
Die Advisor-ID finden Sie im Neocom Admin Portal.
Dateneinheiten
Frage
Stellt eine Frage mit Antworten dar, wie im Neocom Admin Portal definiert. Eine Frage wird in der API über die Question-ID identifiziert, die auch verwendet wird, wenn die Antwort auf die aktuelle Frage an die API gesendet wird.
Es gibt drei Fragetypen:
- SINGLE: Nur eine Antwort kann ausgewählt werden
- MULTIPLE: Mehrere Antworten können ausgewählt werden
- RANGE: ein numerischer Bereich zugelassener Werte kann gewählt werden
Single & Multiple Fragen
{
"question_id": "some-question-id",
"title": "some question title",
"description": "some question description" || null,
"image": "link to a question image" || null,
"question_type": "SINGLE" || "MULTIPLE",
"skip_text": "Skip question" || null,
"answers": [<Answer Object>]
}
Range Fragen
"question_id": "some-question-id",
"title": "some question title",
"description": "some question description" || null,
"image": "link to a question image" || null,
"question_type": "RANGE",
"skip_text": "Skip question" || null,
"range_from": 500,
"range_to": 5000,
"range_step": 500,
"range_label": "€",
"range_groupings": [
{
"title": "Bis zu 1.500€",
"position": 0,
"range_from": 500,
"range_to": 1500
}
],
"answers": [
{
"answer_id": "500.0-1500.0",
"range_from": 500,
"range_to": 1500
}
]
}
Antwort
Stellt die Antwort zu einer Frage dar. Eine Antwort wird in der API über die Answer-ID identifiziert, die auch verwendet wird, wenn die Antwort auf die aktuelle Frage an die API gesendet wird.
Für Farbfragen wird background_color genutzt.
{
"answer_id": "some-answer-id",
"title": "some answer title",
"description": "some answer description" || null,
"image": "link to an answer image" || null,
"background_color": "#ff0044" || null
}
Ergebniselement
Ein Ergebniselement stellt ein von Neocom empfohlenes Produkt dar.
{
"sku": "some-sku",
"image": "link to product image",
"link": "link to the product",
"title": "some product title",
"description": "some product description" || null,
"price": "99.99"
}
Die erste Frage abrufen
Um die erste Frage abzurufen und gleichzeitig eine neue Session zu erstellen, senden Sie einen POST Request mit den erforderlichen HTTP-Headern zum next Endpoint.
Request
curl -X POST https://public.api.neocomapp.com/api/v7/next/
-H 'Content-Type: application/json' \
-H 'Neocom-API-Key: some-api-key' \
-H 'Neocom-Advisor-ID: some-advisor-id'
Response
{
"session_token": "some-session-token",
"question": <Question Object>,
"results": null
}
Die zweite (und weitere) Frage abrufen
Alle weiteren Requests, um die nächste Frage abzurufen folgen dem gleichen Schema und Endpoint wie der erste Request. Um den Request mit einer Session zu verknüpfen, muss der Session-Token in den HTTP-Headern übermittelt werden.
Ist der Question-Key null, ist das Ende der Beratung erreicht und es gibt keine weitere Frage mehr.
Sobald der Ergebnis-Key nicht null ist und eine Anzahl von Ergebniselementen enthält, können bereits Ergebnisse angezeigt werden.
Bis alle Fragen gestellt wurden (was bedeutet, dass der Question-Key null ist), entsprechen diese Ergebnisse möglicherweise noch nicht allen angegebenen Präferenzen. Ergebnisse werden übermittelt sobald alle Filtering-Fragen beantwortet wurden, was üblicherweise ungefähr 25% der Beratung entspricht (dies kann im Neocom Admin Portal verwaltet werden). Ob Sie Ergebnisse erst am Ende der Beratung oder bereits früher als kleine Sneak-Peek zeigen möchten ist ganz Ihnen überlassen.
Das Überspringen einer Frage wird durch das Senden einer leeren Liste von Antworten übermittelt.
Request
curl -X POST https://public.api.neocomapp.com/api/v7/next/
-H 'Content-Type: application/json' \
-H 'Neocom-API-Key: some-api-key' \
-H 'Neocom-Advisor-ID: some-advisor-id' \
-H 'Neocom-Session-Token: some-session-token' \
-d '{ "question_id": "some-question-id", "answers": ["some-answer-id"]}'
Response
{
"session_token": "some-session-token",
"question": <Question Object> || null,
"results": [<Result Object>] || null
}