API Dokumentation

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 mehrere 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
}