Choicera
Referenz: Choicera-MCP für Firmen
Hier steht alles zum Nachschlagen: Verbinden im Einzelnen, alle Werkzeuge mit ihren Feldern, der Ablauf einer Beratung, Fehler, Grenzen, Daten und Beispiele. Zum Einbinden reicht die Anleitung für Firmen; dein Agent bekommt Werkzeuge und Felder außerdem über tools/list selbst. Was neu ist, steht im Änderungsprotokoll.
Werte in den Beispielen (Kennungen, Preise, Texte) sind Beispiele, wo nicht „Antwort des Servers“ dabeisteht. Feldnamen und Aufbau entsprechen den Schemas des Servers.
Verbinden
Adresse und Transport
| Punkt | Wert |
|---|---|
| MCP-Endpunkt | https://choicera.com/agent/mcp |
| Transport | MCP Streamable HTTP, zustandslos, Antworten immer als application/json |
| Methode | nur POST; GET liefert 405 (kein Ereignisstrom, keine Benachrichtigungen) |
| Sitzung | keine; es gibt keine Mcp-Session-Id, jede Anfrage steht für sich |
| Pflicht-Kopfzeilen | Content-Type: application/json und Accept: application/json, text/event-stream (beide Typen; nur application/json ergibt 406) |
| Protokollversionen | 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07; Mcp-Protocol-Version ist optional, ein nicht unterstützter Wert ergibt 400 (außer bei initialize) |
| Anmeldung | keine für die Katalogwerkzeuge; OAuth 2.1 je Mitglied für alles Persönliche |
| Größe einer Anfrage | höchstens 256 KB, sonst 413 |
| Stapelanfragen | nicht erlaubt; ein JSON-Array ergibt 400 |
| Benachrichtigungen des Clients | etwa notifications/initialized: Antwort 202 ohne Inhalt |
| Gesundheitsprüfung | GET https://choicera.com/agent/mcp/health, Antwort {"ok":true} |
| Server-Karte | GET https://choicera.com/agent/mcp/server-card |
| Themenliste | GET https://choicera.com/agent/mcp/topics |
| Partner-Kennung | ?partner=<Kennung> an der Adresse oder Kopfzeile X-Choicera-Partner, siehe Zuordnung zum Partner |
Rufe den Endpunkt von deinem Server aus auf. Anfragen mit einer fremden Origin-Kopfzeile, etwa aus einem Browser, beantwortet der Server mit 403 forbidden_origin.
Ein vorheriges initialize ist wegen der Zustandslosigkeit nicht nötig. MCP-Clients senden es trotzdem, das schadet nicht.
initialize
Antwort des Servers (Auszug aus result):
{
"protocolVersion": "2025-11-25",
"capabilities": { "tools": { "listChanged": false } },
"serverInfo": { "name": "choicera", "title": "Choicera", "version": "6b603ce", "websiteUrl": "https://choicera.com" },
"instructions": "Choicera is a supplement consultation. ..."
}serverInfo.versionist die Kennung des aktuellen Baus und wechselt mit jedem Update. Sie ist keine Versionsnummer: Du kannst damit keine Fassungen vergleichen oder sortieren. Die Server-Karte trägt die feste Fassung1.0.0.instructionsist ein englischer Text mit Hinweisen für das Sprachmodell deines Agenten. Er beschreibt, wie die Werkzeuge zusammenspielen, und gibt keine Befehle: Katalogfragen über die fünf Katalogwerkzeuge, Provisionen ändern nichts an der Auswahl; persönliche Beratung überstart_consultation, die Beratung führt und fragt selbst, was sie braucht; Optionen sind ein Angebot, die Wahl trifft das Mitglied;send_messagenimmt die Antwort sofort; Formulare mit ihren Feldern undanswer_intake; beiready_to_generateerzeugtget_planden Plan; die Felderrole,descriptionundfitText; Produkte, Warenkorb und Link; wo die Pflichttexte stehen. Gib den Text deinem Modell mit, wenn dein Client das kann.capabilities.tools.listChangedistfalse: Der Server meldet Änderungen an der Werkzeugliste nicht, weil es keinen Ereignisstrom gibt. Holetools/listneu, nachdem sich das Token eines Mitglieds geändert hat (neue Verbindung, Erneuerung mit anderen Berechtigungen).
Anmeldung: OAuth 2.1 mit dynamischer Client-Registrierung und PKCE
Alles Persönliche läuft über ein Zugriffstoken, das ein Mitglied für dein Produkt freigibt. Choicera ist dabei der Autorisierungsserver.
Discovery
| Adresse | Inhalt |
|---|---|
https://choicera.com/.well-known/oauth-protected-resource/agent/mcp | Metadaten der geschützten Ressource: resource, authorization_servers, bearer_methods_supported, scopes_supported mit den fünf Choicera-Berechtigungen |
https://choicera.com/.well-known/oauth-authorization-server (gleich: /.well-known/openid-configuration) | Metadaten des Autorisierungsservers |
https://choicera.com/api/auth/oauth2/register | dynamische Client-Registrierung (RFC 7591) |
https://choicera.com/api/auth/oauth2/authorize | Autorisierung |
https://choicera.com/api/auth/oauth2/token | Token-Tausch und Erneuerung |
Die Metadaten des Autorisierungsservers nennen unter scopes_supported nur openid, profile, email und offline_access. Die Choicera-Berechtigungen stehen in den Metadaten der Ressource; gib sie bei der Autorisierung ausdrücklich an. Ein Aufruf ohne Authorization-Kopfzeile bekommt keine 401-Aufforderung, sondern die Katalogwerkzeuge; dein Client startet die Anmeldung also selbst.
Ablauf
1. Client registrieren. redirect_uris müssen absolute https-Adressen sein, ohne Platzhalter * und ohne #-Teil. http://localhost und eigene App-Schemata werden abgewiesen; auch eine App leitet also auf eine https-Adresse deines Servers zurück. Mit token_endpoint_auth_method: "none" entsteht ein öffentlicher Client ohne Geheimnis; vertrauliche Clients (client_secret_basic, client_secret_post) sind ebenfalls möglich.
POST https://choicera.com/api/auth/oauth2/register
{
"client_name": "Studio Coach",
"redirect_uris": ["https://coach.example.com/oauth/choicera/callback"],
"token_endpoint_auth_method": "none",
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"]
}2. Mitglied zur Autorisierung schicken, mit PKCE S256 (Pflicht; plain wird abgewiesen) und state:
https://choicera.com/api/auth/oauth2/authorize?response_type=code&client_id=<client_id>&redirect_uri=https%3A%2F%2Fcoach.example.com%2Foauth%2Fchoicera%2Fcallback&scope=advisor%20checkout%3Apersonalized%20offline_access&state=<state>&code_challenge=<challenge>&code_challenge_method=S2563. Das Mitglied meldet sich in einem Browserfenster von Choicera an (E-Mail-Code, Passkey oder Google; ohne Konto wird eines angelegt) und sieht danach den Einwilligungsbildschirm. Kommt das Mitglied über einen Messenger oder per E-Mail zu dir, schickst du ihm diesen Link.
4. Choicera leitet zurück an redirect_uri mit code, state und iss (https://choicera.com). Prüfe state und iss. Der Code gilt zehn Minuten.
5. Code tauschen:
POST https://choicera.com/api/auth/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=<code>&redirect_uri=<redirect_uri>&client_id=<client_id>&code_verifier=<verifier>{
"access_token": "<zufällige Zeichenfolge>",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "<zufällige Zeichenfolge>",
"scope": "advisor checkout:personalized offline_access"
}6. Lies scope in der Token-Antwort. Das Mitglied kann einzelne Berechtigungen abwählen; das Token trägt nur, was es erteilt hat.
7. Jede MCP-Anfrage für dieses Mitglied trägt Authorization: Bearer <access_token>. Das Zugriffstoken ist eine undurchsichtige Zeichenfolge, kein JWT; prüfe es nicht selbst.
Berechtigungen (scopes)
| Berechtigung | Schaltet frei | Auf dem Einwilligungsbildschirm |
|---|---|---|
advisor | Beratung und Plan, siehe Werkzeuge | Häkchen „Beratung“ |
advisor:medication | keine eigenen Werkzeuge; die Beratung darf nach Medikamenten fragen, answer_intake nimmt das Medikamenten-Formular an, Produkte tragen Hinweise zu Medikamenten | Häkchen „Medikamente“, setzt „Beratung“ voraus |
advisor:maternal | keine eigenen Werkzeuge; die Beratung darf nach Schwangerschaft und Stillzeit fragen, Produkte tragen passende Hinweise | Häkchen „Schwangerschaft / Stillzeit“, setzt „Beratung“ voraus |
checkout:personalized | Produkte und Warenkorb des Plans, Link zur Planseite | Teil von „Beratung“, dazu Hinweis zu Kauflinks |
checkout:catalog | Link zu einem einzelnen Katalogprodukt (get_checkout_link mit productId) | Hinweis zu Kauflinks, nur Nutzungsbedingungen nötig |
offline_access | Erneuerungstoken | kein eigenes Häkchen |
openid, profile, email | Standard-Berechtigungen des Autorisierungsservers; für die Beratung nicht nötig, frag sie nicht an | kein eigenes Häkchen |
Für einen Agenten mit Beratung, Plan und Kauf fragst du advisor checkout:personalized offline_access an. Als Partner fragst du advisor:medication und advisor:maternal nicht an. Was ohne diese beiden Freigaben gilt, steht unter Gesundheitsdaten.
Was das Mitglied auf dem Einwilligungsbildschirm sieht
- Überschrift „Choicera mit deinem KI-Assistenten verbinden“ und „Anfragende Anwendung: <dein
client_name> (nicht von Choicera verifiziert)“. Den Zusatz „nicht von Choicera verifiziert“ zeigt der Bildschirm heute bei jeder Anwendung, auch bei Partnern, weil sich jede Anwendung selbst registriert. - Einen Hinweis, dass Choicera gesundheitsbezogene Angaben verarbeitet und dass Eingaben und Beratungsergebnisse auch die Systeme des Anbieters des Assistenten erreichen, gegebenenfalls außerhalb der EU.
- Nur die Häkchen, die zu deinen angefragten Berechtigungen passen: „Beratung“, „Medikamente“, „Schwangerschaft / Stillzeit“, alle freiwillig und einzeln. Hat das Mitglied sie deinem Client früher schon erteilt, sind sie vorbelegt.
- Das Pflicht-Häkchen „Nutzungsbedingungen“ mit der Bestätigung, mindestens 18 Jahre alt zu sein. Ohne dieses Häkchen bleibt „Verbinden“ gesperrt.
- Bei
checkout:*den Hinweis, dass Kauflinks eine Provisions-Kennung tragen können. - Hinweise zu Freiwilligkeit und Widerruf. Es gibt nur den Knopf „Verbinden“; wer nicht verbinden will, schließt das Fenster.
Laufzeiten und erneutes Verbinden
| Was | Laufzeit |
|---|---|
| Autorisierungscode | 10 Minuten |
| Zugriffstoken | 1 Stunde (expires_in: 3600) |
| Erneuerungstoken | 7 Tage ab Ausgabe; nur mit offline_access |
- Erneuern:
grant_type=refresh_token&refresh_token=<token>&client_id=<client_id>an den Token-Endpunkt (vertrauliche Clients zusätzlich mit Geheimnis). Jede Erneuerung liefert ein neues Zugriffstoken und ein neues Erneuerungstoken mit wieder 7 Tagen Laufzeit. Speichere immer das zuletzt erhaltene. Wer mindestens einmal in 7 Tagen erneuert, bleibt verbunden; ein Mitglied, das länger nicht aktiv ist, muss neu verbinden, wenn dein Server nicht selbst rechtzeitig erneuert. - Ein Mitglied muss neu verbinden, wenn das Erneuerungstoken abgelaufen ist (
invalid_grant), wenn es den Zugriff in seinen Choicera-Einstellungen unter „Verbundene Agenten“ widerrufen hat, und nach einer neuen Fassung der Nutzungsbedingungen von Choicera: Dann endet der Zugriff beim nächsten Aufruf. Lass das Mitglied neu verbinden; dabei bestätigt es die neue Fassung einmal. - Beim erneuten Verbinden entfällt der Einwilligungsbildschirm, wenn die Einwilligung für alle angefragten Berechtigungen noch besteht. Fragst du eine Berechtigung an, die das Mitglied abgewählt hatte, erscheint der Bildschirm bei jeder Verbindung wieder.
- Trennt ein Mitglied die Verbindung bei dir, lösche seine Tokens; einen Endpunkt zum Widerrufen nennt die Discovery nicht. Das Mitglied kann den Zugriff zusätzlich in seinen Choicera-Einstellungen unter „Verbundene Agenten“ widerrufen.
Werkzeuge
tools/list zeigt je nach Token verschiedene Werkzeuge: ohne Token nur die Katalogwerkzeuge, mit Token zusätzlich die Werkzeuge der erteilten Berechtigungen. Ein Werkzeug ohne passende Berechtigung fehlt in der Liste. Rufst du es trotzdem auf, kommt derselbe Fehler wie für ein Werkzeug, das es nicht gibt: MCP error -32602: Tool start_consultation not found (siehe Fehler). Prüfe deshalb vor einem Aufruf, ob das Werkzeug in der Liste für genau dieses Token steht.
Jedes Werkzeug bringt inputSchema, outputSchema und die Hinweise readOnlyHint, destructiveHint und openWorldHint mit. tools/list ist die maßgebliche Liste; lies die Schemas zur Laufzeit.
Werkzeuge heute
Erzeugt aus tools/list des Servers. Mit allen Berechtigungen zeigt tools/list heute 28 Werkzeuge, davon 5 ohne Konto. Die Felder jedes Werkzeugs stehen in der Feldreferenz.
| Werkzeug | Berechtigung | Art | Zweck |
|---|---|---|---|
list_brands | keine | liest | die aktiven Marken |
list_topics | keine | liest | die laufenden Themen |
search_products | keine | liest | Katalog nach Suchwort, Ziel, Thema oder Marke |
get_product | keine | liest | ein Produkt mit Varianten |
get_goals | keine | liest | die festen Ziel-Kennungen |
start_consultation | advisor | schreibt | Beratung beginnen |
send_message | advisor | schreibt | Antwort des Mitglieds senden |
answer_intake | advisor | ersetzt | Formular der Beratung beantworten |
undo_last_answer | advisor | ersetzt | letzte Antwort zurücknehmen |
get_plan | advisor | ersetzt | Plan erzeugen, abfragen, Entwurf beantworten |
search_substances | advisor oder checkout:personalized | liest | Wirkstoffe zum Hinzufügen finden, für den Entwurf oder den fertigen Plan |
get_plan_products | checkout:personalized | liest | Produkte zum fertigen Plan |
add_to_cart | checkout:personalized | schreibt | gewählte Produkte in den Warenkorb des Plans |
get_checkout_link | checkout:catalog oder checkout:personalized | schreibt | Link zum Bestellen: mit planId der Warenkorb mit Verkäufern, Versand und Gesamtpreis und der Link in die Kasse oder zur Planseite (braucht checkout:personalized), mit productId in den Shop der Marke (braucht checkout:catalog) |
fill_cart_with_set | checkout:personalized | ersetzt | ein Set der Planseite in den Warenkorb; ersetzt, was darin lag |
update_cart_line | checkout:personalized | ersetzt | Menge einer Zeile im Warenkorb ändern oder die Zeile entfernen |
add_substance | checkout:personalized | schreibt | Wirkstoff zum fertigen Plan hinzufügen |
set_brand_scope | checkout:personalized | ersetzt | Marken des Plans abwählen oder wieder wählen |
remove_substance | checkout:personalized | ersetzt | selbst hinzugefügten Wirkstoff wieder aus dem Plan nehmen |
set_shipping_country | checkout:personalized | ersetzt | Versandland des Plans setzen, DE oder AT |
get_position_products | checkout:personalized | liest | alle Produkte eines Planpunkts, sortiert und gefiltert wie auf der Planseite |
rate_plan | advisor oder checkout:personalized | ersetzt | Bewertung des fertigen Plans durch das Mitglied übermitteln, wie die Sterne unter dem Plan in der App |
rate_message | advisor | ersetzt | Daumen des Mitglieds zu einer Antwort der Beratung übermitteln, wie in der App |
list_consultations | advisor | liest | eigene Beratungen finden, neueste zuerst, mit dem Hinweis, ob sie hier weitergehen |
get_consultation | advisor | liest | eine Beratung mit ihrer offenen Frage öffnen, um sie fortzusetzen |
get_profile | advisor | liest | gespeicherte Angaben lesen, mit dem Stand der letzten Bestätigung |
confirm_profile | advisor | schreibt | gespeicherte Angaben als bestätigt markieren, wie „Ja, stimmt“ in der App |
get_orders | checkout:personalized | liest | eigene Bestellungen an der Kasse mit Zahlstand und Versandstand, neueste zuerst, oder eine per Bestellnummer |
„liest“ heißt readOnlyHint: true; „schreibt“ heißt readOnlyHint: false und destructiveHint: false; „ersetzt“ heißt destructiveHint: true. Alle Werkzeuge tragen openWorldHint: true.
Katalogsuche heute
So sucht search_products heute:
- Die Treffer sind nach Passung sortiert. Produkte für Kinder stehen nur vorn, wenn das Suchwort nach Kindern fragt.
queryversteht mehrere Wörter auf Deutsch und Englisch und erkennt darin Marke, Wirkstoff, Ernährungsform und Ziel:kreatin,creatineundcreatine monohydratefinden dieselben Produkte,omega-3 veganfindet vegane Omega-3-Produkte.- Ein Treffer passt zu allen Suchwörtern;
matchModeist dannall. Gibt es dafür keinen Treffer, sucht die Suche nach einzelnen Wörtern und meldetany. - Jeder Treffer nennt in
matchReasonsbis zu zwei Gründe, warum er passt. Ein Wort kann auch überprimaryIngredientstreffen, und dort stehen auch Hilfsstoffe; prüfe solche Treffer selbst. - Die Trefferliste ist schlank: Varianten, Zutatenliste, Warnhinweise und Gutschein liefert
get_product. - Die Texte kommen in der Sprache aus
language, ohne Angabe in der Sprache des verknüpften Kontos, ohne Konto auf Deutsch. goalundtopicschließen sich aus;brandlässt sich mit beiden verbinden.
Ablauf einer Beratung
Der Grundsatz: Choicera führt die Beratung, dein Agent ist der Bote. Reiche jede Frage der Beratung an das Mitglied weiter und frage nicht selbst, was die Beratung gleich fragen wird. Wähle nie für das Mitglied.
Die Beratung antwortet in der Sprache des Choicera-Kontos (Deutsch oder Englisch), ihre Pflichttexte ebenso. Die Katalogwerkzeuge nehmen dafür language.
1. Beratung beginnen
start_consultation beginnt mit goalSlugs (Kennungen aus get_goals), mit topic (eine Kennung aus list_topics, optional mit eventDate) oder nur mit message, nie mit goalSlugs und topic zugleich. Angaben, die das Mitglied schon gemacht hat, gehen in statedProfile mit (siehe Angaben beim Start). message ist das Anliegen in den Worten des Mitglieds, ohne Medikamente, Diagnosen oder andere Gesundheitsdaten. Ohne Ziel und Thema reicht message allein: Die Beratung fragt dann selbst nach, so wie in der App. list_topics kann leer sein; dann geht der Start über goalSlugs oder message.
Starte keine zweite Beratung, solange eine offen ist; finde sie mit list_consultations und setze sie fort (siehe Beratung fortsetzen). Gibt es zu einem topic schon eine Beratung, beginnt start_consultation keine neue: Geht sie hier weiter, kommt ihre offene Frage als Antwort zurück, sonst der Fehler consultation_open_in_app.
2. Angaben beim Start
Hat das Mitglied deinem Agenten schon Angaben gemacht, etwa Körperwerte oder wie es schläft, gibt start_consultation sie in statedProfile mit. Das sind feste Werte, kein Freitext außer Namen; Medikamente gehören nie dazu. Choicera übernimmt sie erst, wenn das Mitglied sie bestätigt hat, und die Beratung fragt danach nur, was noch fehlt.
- Die Antwort ist dann die Karte
handover_confirm, bevor die Beratung beginnt, mit eigenerconversationId(sie beginnt mithandover:).reply.formder Arthandoverhat je Angabe ein Feld mit dem übergebenen Wert inpreset; die vier Körperwerte stehen immer darauf, auch schon gespeicherte.storednennt den gespeicherten Wert,differseine Abweichung, die die Angabe ersetzt,needsRevieweine Angabe, die lautobservedAtälter als 300 Tage ist oder deren Körperwerte zu lange nicht bestätigt wurden;noteist der Hinweis der Karte, etwa „bisher 80 kg“. - Zeig die Karte mit ihren
options„Stimmt so“, „Ändern“ und „Nicht übernehmen“. Bestätigt das Mitglied, sendeanswer_intakemitkind: "handover"undhandover: {"confirmed": true}; Korrekturen gehen inchanges, benannt wiestatedProfile, Angaben, die das Mitglied nicht übernehmen will, als Feld-idinrejectedFields.declined: trueübernimmt nichts.send_messagemit dem Wert einer Option zählt ebenso, „Ändern“ liefert die Karte noch einmal; jeder andere Text beginnt die Beratung ohne die Angaben, mit diesem Text als erster Nachricht. - Danach beginnt die Beratung, und die Antwort trägt ihre
conversationId; nimm immer dieconversationIdder letzten Antwort. Aufrufe mit der Kennung der Karte gehen eine Stunde lang auf diese Beratung, eine wiederholte Bestätigung liefert dieselbe Antwort.adoptednennt die übernommenen Werte samt Korrekturen,ignoreddie nicht übernommenen mit Grund. Die erste Antwort der Beratung beginnt mit einem Satz, was übernommen wurde. - Körperwerte, Ernährung, Darreichungsform und Sport-Vorlieben stehen danach im Konto des Mitglieds, Präparate und Allergien kommen zu den gespeicherten dazu. Als Herkunft steht dort der Assistent, bei Korrekturen das Mitglied. Was das Mitglied in der App selbst eingetragen hat, ändert sich nur, wenn die Karte die Abweichung gezeigt hat. Schlaf, Stress und Schichtarbeit gehen als Satz des Mitglieds vor seine erste Nachricht; so kennt die Beratung sie von der ersten Frage an. Die Formulare zu Körperwerten und Sport entfallen, wenn ihre Werte bekannt sind.
- Allergien übernimmt Choicera nur mit der Einwilligung des Mitglieds für Allergien,
lifeStageundtrimesternur mitadvisor:maternalund der Einwilligung dafür; ein Präparat, das nach einem Medikament klingt, bleibt draußen. Solche Felder stehen inignored. Bleibt nichts übrig, beginnt die Beratung ohne Karte. - Ohne Antwort verfällt die Karte nach einer Stunde: Aufrufe mit ihrer Kennung antworten
handover_expired, dann beginne neu. Während eine Bestätigung läuft, antwortet ein zweiter Aufrufhandover_in_progressmitretryAfterSeconds. Solange die Karte offen ist, liefernget_consultation,undo_last_answerundget_plan(Standintake_open) sie erneut;list_consultationszeigt sie nicht. - Als Partner übergibst du nur Körperwerte, Ernährung, Sport-Vorlieben, Schlaf, Stress und Schichtarbeit. Allergien nur nach einer eigenen, ausdrücklichen Zustimmung des Mitglieds beim Start, die du vorher mit uns abstimmst; nie Lebensphase, Präparate oder die Darreichungsform.
3. Antworttypen
Jeder Beratungszug liefert reply. reply.type sagt, was offen ist:
reply.type | Bedeutung | Was dein Agent tut |
|---|---|---|
question | Die Beratung fragt etwas | reply.text als Frage zeigen, options als Auswahl anbieten, Antwort mit send_message senden |
message | Text mit einer Frage, die das Mitglied frei beantwortet | zeigen, freie Antwort mit send_message senden |
statement | nichts offen (Abschied, Information, Bestätigung); auch ein Thema, zu dem die Beratung nichts empfiehlt, dann mit den nächsten Schritten der App als Liste im Text | zeigen, nicht im Namen der Beratung nachfragen |
demographic_intake, medication_intake, sport_preferences | Formular, die Antwort trägt reply.form | Felder einzeln abfragen, dann answer_intake |
handover_confirm | Karte mit den Angaben aus statedProfile, vor der Beratung; trägt reply.form der Art handover und options | zeigen, bestätigen oder korrigieren lassen, dann answer_intake (siehe Angaben beim Start) |
ready_to_generate | die Beratung hat alles; identifiedGoals nennt die Ziele des Plans | get_plan aufrufen |
Behandle einen unbekannten Typ wie message.
Optionen: options sind ein Angebot, keine Grenze. Zeige sie als Auswahl, wo dein Kanal das kann. Bei freeText: true darf das Mitglied frei antworten. Sende den value der gewählten Option; bei multiSelect: true mehrere Werte, durch Kommas getrennt, in einer Nachricht. Sende die Antwort sofort, damit das Mitglied sie nicht noch einmal eingeben muss.
4. Formulare und answer_intake
- Frage die Felder aus
reply.form.fieldseinzeln in ihrer Reihenfolge ab und biete ihreoptionsals Auswahl an. - Ein Feld mit
showIffragst du nur, wenn das Mitglied im FeldshowIf.fielddie OptionshowIf.optionIdgewählt hat. presetist, was Choicera aus früheren Angaben desselben Kontos schon weiß. Zeige es vorausgewählt; das Mitglied darf es behalten oder ändern. Sind alle Körperwerte im Konto bekannt, kann das Formular ganz entfallen.- Die Antworten sind die des Mitglieds. Hat das Mitglied eine Antwort in diesem Chat schon gegeben, darf seine eigene KI sie weitergeben und setzt dazu
onBehalf: true, ebenso beisend_message; Choicera nennt dem Mitglied am Anfang der nächsten Antwort, was übermittelt wurde. Nicht für die Kartehandover_confirmund nicht für das Medikamenten-Formular: Medikamente fragt Choicera immer selbst. Ein Wert, den das Mitglied in der App selbst eingetragen hat, bleibt stehen (ignoredmituser_edit_kept). Als Partner setzt duonBehalfnie; die Antworten kommen dann immer direkt vom Mitglied. - Sende alle Antworten in einem Aufruf:
kindausreply.form.kindund der Antwortblock gleichen Namens, mit den Options-ids. Optionale Felder, die das Mitglied auslässt, lässt du weg. declined: truesendest du nur, wenn das Mitglied den Knopf ausreply.form.skipwählt; dann ohne Antwortblock.- Antwortet das Mitglied in eigenen Worten statt im Formular, sende das mit
send_message; das Formular bleibt dann unbeantwortet.
kind | Antwortblock und Werte | Hinweis |
|---|---|---|
demographics | demographics: gender (female, male, diverse, prefer_not_to_say), ageBracket (under_18, 18_29, 30_44, 45_59, 60_plus), weightBracket (under_60, 60_75, 75_90, 90_plus), heightBracket (under_160, 160_175, 175_190, 190_plus) | alle Felder optional; die Beratung fragt Spannen, keine genauen Werte |
sport_preferences | sport_preferences: protein (any, lactose_free, plant_only), texture (any, creamy, clear), sweetness (any, no_artificial, unsweetened), form (powder_ok, capsule_tablet), caffeine (without, with) | alle Felder optional |
medication | medication: choice (none oder meds), drugClasses (Liste aus pill_contraceptive, blood_thinner, thyroid_medication, antidepressant_ssri, antibiotic, other), freetext (bis 200 Zeichen) | nur mit advisor:medication; bei meds mindestens eine Klasse oder ein Freitext; ersetzt die frühere Antwort ganz |
handover | handover: confirmed (true), changes (benannt wie statedProfile), rejectedFields (Feld-ids der Karte) | nur auf der Karte handover_confirm, siehe Angaben beim Start |
Die Medikamenten-Antwort lässt sich später ändern, auch nach dem Plan: answer_intake mit kind: "medication" und amend: true. Ohne Antwortblock kommt das Formular mit der bisherigen Antwort vorbelegt zurück. Nach dem Plan baut eine geänderte Antwort den Plan neu; rufe dann get_plan, bis der Stand completed ist.
5. Antwort zurücknehmen
undo_last_answer mit conversationId nimmt die letzte Antwort zurück, wie „Antwort ändern“ in der App, und liefert die Frage, zu der sie gehörte. Danach die neue Antwort mit send_message oder answer_intake senden.
6. Plan erzeugen mit get_plan
Bei ready_to_generate rufst du get_plan mit der conversationId. Der Server wartet einige Sekunden auf den Plan und antwortet sonst mit pending. status sagt, wie es weitergeht:
status | Bedeutung | Was dein Agent tut |
|---|---|---|
pending | läuft noch; die Antwort trägt jobId, retryAfterSeconds (derzeit 5) und reason (still_pending oder upstream_unavailable) | retryAfterSeconds warten, dann get_plan mit derselben conversationId und der jobId |
intake_open | ein Formular ist noch offen; reply trägt es | erst answer_intake |
draft_review | Entwurf liegt vor: plan und draft | Entwurf zeigen und Zeile für Zeile beantworten lassen (unten) |
refining_intake | nach dem Entwurf hat die Beratung Rückfragen; plan und reply | Entwurf zeigen, reply wie bei send_message behandeln, bis ready_to_generate, dann wieder get_plan |
plan_generated | nur der Entwurf liegt vor | get_plan noch einmal aufrufen |
regenerating | der Plan wird neu gebaut | kurz warten, get_plan noch einmal |
completed | fertiger Plan in plan, dazu disclosure | Plan mit disclosure zeigen, Produkte anbieten |
failed | Erzeugung gescheitert, Grund in reason (etwa plan_job_failed) | dem Mitglied sagen, später erneut versuchen |
no_plan | kein Plan vorhanden | Beratung fortsetzen |
Jeder Aufruf von get_plan zählt zum Kontingent der Beratungsaufrufe. Rufst du get_plan für eine fertige Beratung erneut auf, kommt der bestehende Plan zurück.
Entwurf beantworten: Frage je Zeile in draft.rows, ob das Mitglied den Wirkstoff schon nimmt (already_taking), eine Darreichungsform bevorzugt (preferred_form mit form aus draft.forms) oder ihn nicht nehmen will (do_not_want); not_taking hebt ein vorbelegtes already_taking auf. Frage nie nach dem Grund. Das Mitglied darf Wirkstoffe hinzufügen: finde sie mit search_substances (conversationId, query, leer für Vorschläge) und sende ihre keys als draftAdded, höchstens draft.addLimit. Wenn das Mitglied alle Zeilen durchgegangen ist, rufe get_plan einmal mit draftFeedback (leere Liste, wenn sich nichts ändert) und draftAdded. Das bestätigt den ganzen Entwurf. Bestätige den Entwurf nie für das Mitglied. Solange der Stand refining_intake ist, öffnet reopenDraft: true den Entwurf noch einmal mit den bisherigen Antworten.
priority: true an einer Entwurfszeile markiert die drei wichtigsten Wirkstoffe (der Stern in der App). Der fertige Plan trägt dieselben Angaben je Punkt, dazu die Rolle im Plan und in consultNotice den Pflichttext F11.
7. Produkte, Warenkorb, Kauflink
get_plan_productsmitplanIdliefert je Planpunkt die passenden Produkte zuerst, dann die weniger passenden (lessFitting: true), bis zu acht je Punkt. Ausverkaufte Produkte und Varianten fehlen. Für einen Entwurf kommtstatus: "plan_not_final"mit leererpositions-Liste; gib dem Mitglied dann den Link zur Planseite.- Zeige die
warningszusammen mit dem Produkt. Ein Produkt mitneedsConfirmation: truedarf nur in den Warenkorb, wenn das Mitglied den Warnhinweis im Chat ausdrücklich bestätigt hat; dannconfirmWarning: truean dieser Zeile. - Zeige den Grundpreis (
basePrice) im selben Satz wie den Preis, etwa „19,90 € (165,83 €/kg)“. Fehlt er, schätze keinen. add_to_cartlegt die gewählten Produkte in den Warenkorb des Plans. NimmpositionId,productIdundvariantIdausget_plan_products; Kennungen aus dem Katalog gehören nicht hierher. Ist ein Produkt schon im Warenkorb, kommt die Menge dazu. Zeilen inneedsConfirmationundrejectedwurden nicht hinzugefügt.get_checkout_linkmitplanIdnennt inorderden Warenkorb: die Zeilen mit Grundpreis, je Verkäufer den Zahlweg (paymentPath:checkoutan der Kasse von Choicera,shopim Shop der Marke), Zwischensumme, Nachlass und Versand, dazu den Versand gesamt, den Gesamtpreis und inpriceNoteden Preishinweis der App. Zeig das dem Mitglied vor dem Link, den Preishinweis beim Gesamtpreis. Werden alle Verkäufer an der Kasse bezahlt, öffnet der Link die Kasse von Choicera bei „Bestellung prüfen“ (target: "checkout",https://choicera.com/supps/checkout?plan=<planId>&step=review&via=ai), sonst die Planseite (target: "plan_page"); ebenso bei leerem Warenkorb und bei einem Entwurf, dann ohneorder. MitproductId(stattplanId, nie beides) kommt ein einfacher Produktlink in den Shop der Marke (mode: "catalog"). Rufeget_checkout_linkerst auf, wenn das Mitglied bestellen will: Jeder Aufruf legt den Eintrag an, über den ein späterer Kauf zugeordnet wird. Liefert der Shop der Marke für ein Produkt keinen Link, kommt heuteupstream_error.- An der Kasse bestellt das Mitglied selbst mit dem Knopf „Zahlungspflichtig bestellen“ und bezahlt bei Novalnet; Zahlungsdaten laufen nie durch deinen Kanal. Kennt die Kasse eine Lieferadresse aus einer früheren Bestellung, steht sie gleich bei „Bestellung prüfen“, sonst fragt sie zuerst die Adresse; die E-Mail kommt aus dem Konto. Ohne Choicera-Sitzung im Browser, auch mit einer Gast-Sitzung, meldet sich das Mitglied zuerst an und landet danach an derselben Stelle. Der Link trägt weder ein Token noch personenbezogene Daten;
via=aisagt der Kasse nur, dass er aus einem KI-Chat kommt. Jeder Aufruf liest den Warenkorb neu. - Produkte, deren Warnhinweis Medikamente, Schwangerschaft oder Stillzeit betrifft, fehlen ohne die passende Freigabe in
order.linesund zählen inhiddenLines, wie im Warenkorb vonget_plan_products. Fehlt eine der beiden Freigaben, fehlen dort auch Produkte aus allen Marken, die das Angebot des Plans nicht führt, weil Choicera ihre Hinweise für diesen Plan nicht geprüft hat. get_orders(mitcheckout:personalized, liest nur) liefert die Bestellungen des Mitglieds an der Kasse, neueste zuerst, höchstens 20, mitorderNumbergenau eine. Jede trägtpayment(paid,pendingsolange der Zahlungsdienst die Zahlung nicht bestätigt hat,cancelled), den Betrag und je Verkäufer Versandstand (delivery), Lieferfenster und Sendungsverfolgung. Fehlgeschlagene und abgelaufene Zahlungen fehlen; der Warenkorb bleibt dann, und derselbe Link führt wieder hin. Die Seite hinterordersUrlzeigt bezahlte und stornierte Bestellungen, eine mit offener Zahlung erscheint dort erst, wenn die Zahlung bestätigt ist. Eine fremde oder unbekannte Bestellnummer antwortetnot_found. Eine Benachrichtigung über neue Bestellungen gibt es nicht: Frag den Stand ab, wenn das Mitglied nach dem Link in den Chat zurückkommt. Käufe im Shop einer Marke stehen nicht darin.
Namen im Katalog und im Plan
Katalog und Plan benennen dieselben Dinge verschieden:
| Was | Katalog (search_products, get_product) | Plan (get_plan_products, add_to_cart) |
|---|---|---|
| Produkt-Kennung | id | productId |
| Varianten-Kennung | variants[].id | variants[].variantId |
| Marke | brand: Objekt mit id, slug, name, color, logoUrl | brand: Text mit dem Namen der Marke; die Kennung steht in brands[].brandId |
| Währung | currency am Produkt | currency an jeder Variante |
| Preis | price am Produkt (immer), variants[].price (auch null) | variants[].price (auch null) |
| Verfügbarkeit | variants[].available | nur verfügbare Varianten stehen in der Liste |
| Vorauswahl | keine | defaultVariantId |
| Packung und Geschmack | variants[].containerSize, containerUnit, flavor | dieselben Namen |
Für den Warenkorb zählen nur die Kennungen aus get_plan_products.
Änderungen, die das Mitglied in deinem Kanal macht, laufen über die Werkzeuge von Choicera, nicht über einen Nachbau bei dir; so gelten dieselben Regeln wie auf der Planseite. get_plan_products liest bei jedem Aufruf den aktuellen Stand; ändert das Mitglied auf der Planseite etwas, siehst du es beim nächsten Aufruf. Eine Benachrichtigung darüber gibt es nicht.
Sets, Warenkorb und Marken:
get_plan_productsliefert dazusets(cheap: niedrigster Gesamtpreis mit Versand;value: das empfohlene Produkt je Wirkstoff),brands,brandsEditable,shippingCountryundcartmitlineIdje Zeile; Varianten tragenflavor,containerSizeundcontainerUnit. Lesen legt nie etwas in den Warenkorb.fill_cart_with_setmitplanIdundset(cheapodervalue) legt ein Set in den Warenkorb und ersetzt den ganzen Warenkorb; liegt schon etwas darin, sag das dem Mitglied vorher. Biete beide Sets als Auswahl an; istsets.cheap.sameAsValuewahr, nur „Empfohlen“. Ein Set enthält je ein Produkt für jeden Basis-Wirkstoff und jeden selbst hinzugefügten Wirkstoff, keine Plus-Wirkstoffe.update_cart_linemitplanId,lineIdundquantityändert die Menge;0entfernt die Zeile. Tauschen heißt: Zeile mit0entfernen, dann das andere Produkt oder die andere Variante mitadd_to_carthinzufügen.search_substancesmitplanIdliefert je Option einenstate(available,inPlan,blockedmitblockedReason,noProducts); nuravailablelässt sich mitadd_substance(planId,key) hinzufügen, höchstens zehn selbst hinzugefügte Wirkstoffe je Plan. Liegt ein Set unverändert im Warenkorb, kommt das passende Produkt des Sets sofort dazu.set_brand_scopemitplanIdund allen Marken, die das Mitglied nicht will, alsdeselectedBrandIds(ausbrands[].brandId, einschließlich früher abgewählter). Eine leere Liste wählt alle wieder an; alle abzuwählen wählt alle an. Produkte abgewählter Marken verlassen den Warenkorb; lag ein Set darin, wird es aus den übrigen Marken neu gelegt. BeibrandsEditable: falsesind die Marken durch einen Link festgelegt.
sets.<set>.starOnlyenthält nur die drei wichtigsten und die selbst hinzugefügten Wirkstoffe des Sets, wie der Schalter der Planseite;fill_cart_with_setmitstarOnly: truelegt genau diese ein. Ob der Schalter steht, liest du auscart.starOnly.remove_substancemitplanIdundpositionIdnimmt einen selbst hinzugefügten Wirkstoff (userAdded: true) wieder heraus.set_shipping_countrymitplanIdundcountry(DEoderAT) setzt das Versandland; die Preise der Sets und die Summe des Warenkorbs gelten dann dafür. Lag das Set „Günstig“ im Warenkorb, wird es für das neue Land neu zusammengestellt (recomposed: true).cart.shopsnennt die Kosten je Shop mit Versand und Nachlass, wie der Warenkorb der Planseite.get_position_productsmitplanIdundpositionIdliefert alle Produkte eines Planpunkts, sortiert nachrecommendedoderpriceund gefiltert nachformunddiet.
8. Beratung fortsetzen und gespeicherte Angaben
Eine neue Unterhaltung in deinem Kanal muss nicht blind beginnen. Wann du die Werkzeuge rufst, entscheidet dein Agent; nach Verlauf oder Zusammenfassungen fragen sie nicht.
list_consultationsliefert die Beratungen des Mitglieds, neueste zuerst, höchstens 20: in der App begonnene (channel: "app") und über einen Agenten begonnene (channel: "agent").resumable: truetragen dieselben Beratungen, die die App zum Weitermachen anbietet (Standgathering_info,plan_generatedoderrefining_intake). Bei allen anderen stehtresumeHint: "continue_in_app": das Mitglied findet sie in der App.get_consultationmit derconversationIdliefert Stand, Ziele,planIdund inreplydie offene Frage oder die letzte Antwort der Beratung, genau wiesend_message. Reiche sie weiter und sende die Antwort des Mitglieds mitsend_messageoderanswer_intake. Bei offenem Entwurf istreply.typeready_to_generate; dann geht es mitget_planweiter. Ohnereplyist hier nichts weiterzugeben; beicompletedzeigtget_planden fertigen Plan.- Antworten nimmt eine Beratung so lange an wie in der App: in den Ständen
gathering_info,plan_generated,refining_intakeundrefining. Sonst antwortensend_message,answer_intake(ohneamend),undo_last_answerundsearch_substancesmitconversationIdmitconversation_closed, während der Plan entsteht mitplan_pending.get_planbleibt in jedem Stand offen. - Ohne
advisor:medicationfehlen Beratungen mit Angaben zu Medikamenten inlist_consultationsundget_consultation, ohneadvisor:maternalBeratungen, in denen es um Schwangerschaft oder Stillzeit geht; sie antworten dortnot_found, wie eine fremde Beratung. In der App begonnene solche Beratungen lassen sich auch über ihreconversationIdnicht fortsetzen. Eine über einen Agenten begonnene Beratung läuft weiter, auch wenn das Mitglied dort selbst Medikamente, Schwangerschaft oder Stillzeit nennt. Eine Frage der Beratung zu Medikamenten reichtget_consultationohneadvisor:medicationnicht weiter. get_profileliest die gespeicherten Angaben: Körperwerte, Ernährung, Allergien, Präparate, die das Mitglied schon nimmt, die bevorzugte Darreichungsform und die Sport-Vorlieben, mitadvisor:medicationauch die Medikamente, mitadvisor:maternalauch Schwangerschaft oder Stillzeit. Ohne diese Berechtigungen fehlen die Teile ganz, auch ihre Zeitstempel. Jeder Teil nennt die letzte Bestätigung undisStalenach denselben Fristen wie die App: 300 Tage für Körperwerte, 90 Tage für Medikamente und für Schwangerschaft oder Stillzeit.- Stimmt das Mitglied den gezeigten Angaben zu, markiert
confirm_profilesie als bestätigt, wie „Ja, stimmt“ in der App; die App fragt dann nicht mehr nach. Gibfacetsund dieprofileVersionderget_profile-Antwort mit, die das Mitglied gesehen hat. Ändern lassen sich die Angaben hier nicht; das geht in der App oder in der Beratung. - Alle verbundenen Anwendungen bekommen dieselben Antworten; was gezeigt wird, hängt nur an den Berechtigungen des Tokens.
9. Bewerten
Das Mitglied kann seinen Plan und einzelne Antworten der Beratung bewerten wie in der App. Die Bewertungen landen dort, wo auch die aus der App landen, und tragen den Kanal agent, damit Choicera App und KI-Kanal getrennt auswerten kann. Die Werkzeuge übermitteln eine Bewertung, die das Mitglied selbst gibt; dein Agent fragt nicht von sich aus danach und bewertet nicht an Stelle des Mitglieds.
rate_planmitplanIdundstars(1 bis 5) bewertet den fertigen Plan, wie die Sterne unter dem Plan in der App. Bei 1 bis 3 Sternen nimmt esreasonCodesaus der Liste der App:not_for_me(Passt nicht zu mir),too_many_products(Zu viele Produkte),too_expensive(Zu teuer),other(Etwas anderes).commentist, was das Mitglied dazu schreibt, in seinen Worten, bis 500 Zeichen.- Eine weitere Bewertung desselben Plans ersetzt die frühere, wie in der App; ohne Gründe oder Kommentar bleiben die früheren stehen, bei 4 oder 5 Sternen fallen die Gründe weg.
- Ein Entwurf lässt sich nicht bewerten (
plan_not_final). Nennt der Kommentar Medikamente ohneadvisor:medicationoder Schwangerschaft oder Stillzeit ohneadvisor:maternal, speichert Choicera nichts (comment_withheld); die Bewertung geht dann ohne Kommentar. rate_messagemitmessageIdundrating(up,down,none) bewertet eine Antwort der Beratung mit dem Daumen.messageIdsteht an den Antworten vonstart_consultation,send_messageundanswer_intake, unter denen die App Daumen zeigt: Text ohne Antwortmöglichkeiten und ohne Formular.nonenimmt den Daumen zurück; ein neuer Daumen ersetzt den alten.- Beide Werkzeuge ersetzen eine frühere Bewertung und tragen deshalb
destructiveHint: true. Für sie gilt die Grenze für Bewertungen, siehe Grenzen.
Fehler
Fehler kommen auf drei Ebenen. Prüfe sie in dieser Reihenfolge.
1. HTTP-Fehler am Endpunkt
Diese Antworten kommen vor jeder MCP-Verarbeitung. Der Inhalt ist JSON, aber nicht immer ein JSON-RPC-Objekt.
| Status | Inhalt | Wann | Handlung |
|---|---|---|---|
400 | {"error":"invalid_request"} | leerer Inhalt, kein JSON, JSON-Array | Anfrage korrigieren |
400 | {"jsonrpc":"2.0","error":{"code":-32700,"message":"Parse error: Invalid JSON-RPC message"},"id":null} | gültiges JSON, aber keine JSON-RPC-Nachricht | Anfrage korrigieren |
400 | JSON-RPC-Fehler -32000, Bad Request: Unsupported protocol version: ... | Mcp-Protocol-Version mit einem nicht unterstützten Wert | Kopfzeile weglassen oder unterstützten Wert senden |
401 | {"error":"invalid_token"} mit WWW-Authenticate: Bearer error="invalid_token", resource_metadata="https://choicera.com/.well-known/oauth-protected-resource/agent/mcp" | Authorization vorhanden, aber nicht Bearer <token>, oder Token unbekannt, abgelaufen oder widerrufen | Token einmal erneuern, sonst neu verbinden lassen |
403 | {"error":"forbidden_origin"} | fremde Origin-Kopfzeile | vom Server aus aufrufen, ohne Origin |
404 | {"error":"not_found"} | andere Pfade unter /agent/mcp | Adresse prüfen |
405 | {"error":"method_not_allowed"} | nicht POST an /agent/mcp | nur POST |
406 | {"jsonrpc":"2.0","error":{"code":-32000,"message":"Not Acceptable: Client must accept both application/json and text/event-stream"},"id":null} | Accept ohne einen der beiden Typen | beide Typen senden |
413 | {"error":"payload_too_large"} | Anfrage über 256 KB | Anfrage verkleinern |
415 | JSON-RPC-Fehler -32000, Unsupported Media Type: Content-Type must be application/json | anderer Content-Type | application/json senden |
429 | {"jsonrpc":"2.0","error":{"code":-32000,"message":"rate_limited"},"id":null} mit Retry-After | Grenze je Mitglied oder je Absenderadresse, auch bei der Prüfung des Tokens | so viele Sekunden warten |
500 | {"error":"internal_error"} | interner Fehler | später erneut versuchen |
503 | {"jsonrpc":"2.0","error":{"code":-32000,"message":"server_busy"},"id":null} mit Retry-After: 1 | zu viele gleichzeitige Anfragen | kurz warten, wiederholen |
503 | {"jsonrpc":"2.0","error":{"code":-32000,"message":"upstream_unavailable"},"id":null} mit Retry-After | die Prüfung des Tokens ist gerade nicht erreichbar | so viele Sekunden warten, wiederholen |
Ohne Authorization-Kopfzeile gibt es kein 401: Die Anfrage läuft ohne Konto, und es gibt nur die Katalogwerkzeuge.
2. JSON-RPC-Fehler
HTTP 200, im Inhalt ein error-Objekt statt result. Das betrifft Methoden, die der Server nicht kennt, etwa resources/list oder prompts/list:
{"jsonrpc":"2.0","id":5,"error":{"code":-32601,"message":"Method not found"}}Der Server bietet nur Werkzeuge an (tools/list, tools/call), keine Ressourcen und keine Prompts.
3. Fehler eines Werkzeugaufrufs
HTTP 200 und ein normales result mit isError: true, ohne structuredContent. Erfolgreiche Antworten haben kein Feld isError. Es gibt zwei Arten, die du am Text in content[0].text erkennst.
a) Protokollfehler des MCP-Servers. Der Text ist Klartext und beginnt mit MCP error und dem JSON-RPC-Code:
| Text | Bedeutung | Handlung |
|---|---|---|
MCP error -32602: Tool <name> not found | Das Werkzeug gibt es nicht, oder es fehlt für dieses Token, weil das Token fehlt oder die Berechtigung nicht trägt | tools/list mit demselben Token prüfen; fehlt es dort, Mitglied mit der nötigen Berechtigung (neu) verbinden lassen |
MCP error -32602: Input validation error: Invalid arguments for tool <name>: <Grund> | Argumente passen nicht zum inputSchema, etwa limit 0 | Argumente nach dem inputSchema korrigieren |
MCP error -32602: Output validation error: ... | Antwort passte nicht zum eigenen outputSchema (Fehler bei Choicera) | später erneut versuchen; bleibt er, melden |
Antwort des Servers auf search_products mit limit 0:
{"result":{"content":[{"type":"text","text":"MCP error -32602: Input validation error: Invalid arguments for tool search_products: Number must be greater than or equal to 1 at limit"}],"isError":true},"jsonrpc":"2.0","id":2}Werte nur Präfix und Code aus. Der Rest des Textes ist englisch, kommt aus der MCP-Bibliothek und kann sich mit deren Updates ändern.
b) Fehler von Choicera. Der Text ist JSON mit error und je nach Fall weiteren Feldern. Antwort des Servers auf search_products mit goal schlaf:
{"result":{"content":[{"type":"text","text":"{\"error\":\"invalid_request\",\"detail\":\"invalid_query\",\"hint\":\"goal must be a slug from get_goals; brand must be a slug from list_brands.\"}"}],"isError":true},"jsonrpc":"2.0","id":6}error | Zusatzfelder | Bedeutung | Handlung |
|---|---|---|---|
rate_limited | retryAfterSeconds (falls bekannt) | Kontingent erreicht | warten, dann denselben Aufruf wiederholen |
authorization_required | reason: consent_required, consent_stale oder health_data_consent_required; ohne reason: Token ist zwischendurch ungültig geworden | Einwilligung fehlt oder ist veraltet | Mitglied neu verbinden lassen; es bestätigt auf choicera.com |
insufficient_scope | scope | Das Werkzeug ist sichtbar, aber dieser Aufruf braucht eine andere Berechtigung: get_checkout_link mit planId ohne checkout:personalized oder mit productId ohne checkout:catalog; search_substances mit planId ohne checkout:personalized; confirm_profile mit medication ohne advisor:medication oder mit maternal ohne advisor:maternal | mit dieser Berechtigung neu verbinden oder den anderen Weg nehmen |
invalid_request | detail, manchmal hint oder retryAfterSeconds | Eingabe passt nicht oder der Stand erlaubt den Aufruf nicht | detail lesen, siehe unten |
not_found | Beratung, Plan, Warenkorbzeile, Wirkstoff oder Bestellnummer gehört nicht diesem Mitglied, existiert nicht oder ist über diese Verbindung nicht erreichbar (siehe Beratung fortsetzen) | Kennung prüfen, mit dem letzten Stand weitermachen | |
product_not_found | Produkt-Kennung unbekannt (get_product) | Kennung aus search_products nehmen | |
upstream_error | manchmal detail | Fehler bei Choicera | später erneut versuchen; bleibt er, melden |
Werte von detail bei invalid_request:
detail | Werkzeug | Bedeutung |
|---|---|---|
invalid_query (mit hint) | search_products | goal ist keine Kennung aus get_goals oder brand keine aus list_brands |
unknown_topic (mit hint) | search_products | topic steht nicht in list_topics |
topic_and_goal | search_products | goal und topic zugleich |
topic_and_goal_slugs, missing_topic_or_goal_slugs | start_consultation | höchstens eines von goalSlugs und topic angeben; ohne beide braucht der Start message |
event_date_without_topic | start_consultation | eventDate nur mit topic |
trimester_without_pregnancy | start_consultation | statedProfile.trimester nur mit lifeStage: pregnant |
handover_field_not_on_card | answer_intake mit kind: handover | changes oder rejectedFields nennen ein Feld, das nicht auf der Karte steht |
handover_in_progress (mit retryAfterSeconds) | Aufrufe mit der Kennung einer Karte | die Bestätigung läuft noch: warten, dann denselben Aufruf wiederholen |
handover_expired | Aufrufe mit der Kennung einer Karte | die Karte ist älter als eine Stunde: Beratung neu beginnen |
on_behalf_not_for_medication | send_message, answer_intake | onBehalf gilt nicht für das Medikamenten-Formular; das Mitglied beantwortet es selbst |
on_behalf_not_for_handover | send_message, answer_intake | onBehalf gilt nicht für die Karte handover_confirm; das Mitglied bestätigt sie selbst |
message_in_flight | Beratungswerkzeuge | die Beratung arbeitet noch an der letzten Nachricht: kurz warten, denselben Aufruf wiederholen |
conversation_closed | send_message, answer_intake, undo_last_answer, search_substances mit conversationId | die Beratung ist abgeschlossen und nimmt keine Antworten mehr; den Plan zeigt get_plan, eine neue Beratung beginnt start_consultation |
plan_pending (mit retryAfterSeconds) | wie conversation_closed | der Plan der Beratung entsteht gerade: retryAfterSeconds warten, dann den Plan mit get_plan holen |
consultation_open_in_app | start_consultation mit topic | zu diesem Thema gibt es schon eine Beratung, die hier nicht weitergeht; das Mitglied setzt sie in der App fort |
profile_changed | confirm_profile | die Angaben haben sich seit get_profile geändert oder es gibt keine: neu lesen und dem Mitglied zeigen |
intake_not_open | answer_intake | kein solches Formular mehr offen: mit der letzten Antwort weitermachen |
answer_block_missing, answer_block_does_not_match_kind, declined_with_answer, amend_only_for_medication, medication_none_with_details, medication_details_required | answer_intake | Aufbau der Formularantwort |
answer_not_undoable | undo_last_answer | die letzte Antwort lässt sich nicht zurücknehmen |
draft_not_open | get_plan | kein Entwurf zur Antwort offen |
invalid_draft_feedback | get_plan | Antwort zum Entwurf passt nicht zu den Zeilen |
provide exactly one of planId or productId | get_checkout_link | genau eines angeben |
provide exactly one of conversationId or planId | search_substances | genau eines angeben |
set_empty, substance_in_plan, substance_limit, substance_blocked, substance_no_products, scope_locked, brand_deselected | fill_cart_with_set, add_substance, set_brand_scope, update_cart_line | Set leer, Wirkstoff schon im Plan, Höchstzahl erreicht, Wirkstoff gesperrt oder ohne Produkte, Marken durch einen Link festgelegt, Marke abgewählt |
plan_not_final | rate_plan | der Plan ist noch ein Entwurf; nichts gespeichert |
invalid_reason_codes | rate_plan | Gründe gibt es nur bei 1 bis 3 Sternen |
comment_withheld | rate_plan | der Kommentar nennt Medikamente ohne advisor:medication oder Schwangerschaft oder Stillzeit ohne advisor:maternal; nichts gespeichert, die Bewertung geht ohne Kommentar |
invalid_target | rate_message | die Kennung gehört nicht zu einer Antwort der Beratung |
Behandle unbekannte Werte von error, detail, reply.type und status so, dass dein Agent weiterläuft, etwa mit einem allgemeinen Hinweis an das Mitglied.
Grenzen
Anfragen je Minute
Die Grenzen zählen je Mitglied, je OAuth-Client oder je Absenderadresse deines Servers. Gemeinsam für alle verbundenen KI-Anwendungen (Assistenten wie Claude oder ChatGPT und Partner) gelten nur die Grenzen der Katalogwerkzeuge. Die Zahlen gelten derzeit; Choicera kann sie ändern.
| Grenze | Gilt für | Derzeit | Bei Überschreitung |
|---|---|---|---|
Anfragen an /agent/mcp ohne Token | je Absenderadresse deines Servers (IPv6 je /64) | 120 je Minute | HTTP 429 mit Retry-After |
Anfragen an /agent/mcp mit Token | je Mitglied | 120 je Minute | HTTP 429 mit Retry-After |
Anfragen an /agent/mcp mit Token | je Absenderadresse deines Servers; alle deine Mitglieder teilen sie | 1200 je Minute | HTTP 429 mit Retry-After |
| abgewiesene Tokens | je Absenderadresse | 30 je Minute; danach kommt jede Anfrage mit Token von dieser Adresse als 429, bis die Minute um ist | HTTP 429 mit Retry-After |
| Anfragen ohne erkennbare Absenderadresse | alle gemeinsam | 20 je Minute | HTTP 429 mit Retry-After |
| gleichzeitig eingelesene Anfragen | ganzer Endpunkt | 32 | HTTP 503 mit Retry-After: 1 |
Katalogsuche (search_products) | alle Anwendungen gemeinsam | 600 je Minute | Werkzeugfehler rate_limited mit retryAfterSeconds |
Katalog lesen (get_product, list_brands, get_goals, list_topics; search_products mit topic zählt zusätzlich hier) | alle Anwendungen gemeinsam | 600 je Minute | Werkzeugfehler rate_limited mit retryAfterSeconds |
Beratungsaufrufe (start_consultation, send_message, answer_intake, undo_last_answer, get_plan, search_substances im Entwurf); jedes Abfragen von get_plan zählt mit | je Mitglied | 30 je Minute | Werkzeugfehler rate_limited mit retryAfterSeconds |
| Beratungsaufrufe, wie oben | je OAuth-Client, alle Mitglieder deines Clients zusammen | 300 je Minute | Werkzeugfehler rate_limited mit retryAfterSeconds |
Bewertungen (rate_plan, rate_message), dieselbe Grenze wie für Bewertungen in der App | je Mitglied | 30 je Minute | Werkzeugfehler rate_limited |
Beratungen finden und gespeicherte Angaben (list_consultations, get_consultation, get_profile, confirm_profile); zählen nicht zu den Beratungsaufrufen | je Mitglied | 60 je Minute | Werkzeugfehler rate_limited mit retryAfterSeconds |
Prüfung des Tokens (jede Anfrage mit Authorization, auch initialize und tools/list) | je Mitglied | 240 je Minute | HTTP 429 mit Retry-After |
| Client-Registrierung | je Adresse | 5 je Minute | Fehler des Autorisierungsservers |
| Token-Endpunkt (Tausch und Erneuerung) | je Adresse | 30 je Minute | Fehler des Autorisierungsservers |
Folgen für deine Integration:
- Ein
401heißt immer: Das Token ist ungültig, abgelaufen oder widerrufen. Erneuere es einmal; scheitert die Erneuerung mitinvalid_grant, lass das Mitglied neu verbinden. Überlastung kommt als429oder503mitRetry-After; dann warten und denselben Aufruf wiederholen, nicht neu verbinden. - Halte dich an
Retry-AfterundretryAfterSeconds. Wiederhole nicht schneller. - Sag uns vor dem Start, mit wie vielen Mitgliedern und welcher Spitzenlast je Minute du rechnest: partner@choicera.com.
Grenzen der Eingaben
| Eingabe | Erlaubt | Standard |
|---|---|---|
search_products.limit | 1 bis 50 | 10 |
search_products.offset | 0 bis 1000 | 0 |
search_products.query | bis 128 Zeichen | |
start_consultation.goalSlugs | 1 bis 10 Kennungen | |
start_consultation.message | bis 2000 Zeichen | |
send_message.message | 1 bis 5000 Zeichen | |
answer_intake.medication.freetext | bis 200 Zeichen | |
get_plan.draftFeedback | bis 40 Einträge | |
get_plan.draftAdded | bis 10 Kennungen (draft.addLimit) | |
search_substances.query | bis 80 Zeichen, leer für Vorschläge | |
add_to_cart.items | 1 bis 20 Produkte je Aufruf | |
add_to_cart.items[].quantity | 1 bis 20 | 1 |
update_cart_line.quantity | 0 bis 20; 0 entfernt die Zeile | |
set_brand_scope.deselectedBrandIds | bis 100 | |
rate_plan.stars | 1 bis 5 | |
rate_plan.comment | bis 500 Zeichen |
Mit offset höchstens 1000 und limit höchstens 50 erreichst du höchstens die ersten 1050 Treffer einer Suche. total kann größer sein (ohne Suchwort derzeit über 1000); grenze die Suche dann ein. Blättere mit offset plus limit, nicht mit der Länge von products: Ein Produkt, das die Prüfung von Choicera nicht besteht, fällt aus der Seite, sodass products kürzer als limit sein kann, obwohl es weitere Treffer gibt.
Größe der Antworten
Jede erfolgreiche Antwort enthält dasselbe JSON zweimal, als Text in content[0].text und als structuredContent. Gemessen am 12. November 2026, ganze HTTP-Antwort:
| Aufruf | Größe |
|---|---|
search_products mit limit 1 | etwa 3 KB |
search_products mit limit 10 (Standard) | etwa 25 bis 27 KB, je nach Suche |
search_products mit limit 20 | etwa 55 KB |
search_products mit limit 50 | etwa 137 KB |
get_product mit einer Variante | etwa 6 KB |
Frage nur so viele Treffer ab, wie dein Agent zeigt, und gib deinem Modell möglichst nur eine der beiden Kopien. Die Trefferliste trägt nur die Felder zum Auswählen; die Einzelheiten stehen in get_product.
Welche Daten Choicera bekommt und zurückgibt
Daten an Choicera
| Woher | Was | Hinweis |
|---|---|---|
| Katalogwerkzeuge | Suchwörter, Ziel-, Themen- und Marken-Kennungen, Produkt-Kennungen | keine personenbezogenen Daten übergeben; Suchwörter werden im Zugriffsprotokoll unkenntlich gemacht |
| jede Anfrage | Adresse deines Servers (im Protokoll gekürzt), Client-Name und Version aus initialize, User-Agent | |
start_consultation | goalSlugs oder topic und eventDate, dazu oder allein message in den Worten des Mitglieds; dazu statedProfile mit Angaben, die das Mitglied schon gemacht hat | keine Medikamente, Diagnosen oder Gesundheitsdaten in message; statedProfile übernimmt Choicera erst nach der Bestätigung des Mitglieds |
send_message, answer_intake | Antworten des Mitglieds auf die Fragen und Formulare der Beratung | die Antworten kommen vom Mitglied, direkt oder mit onBehalf aus dem, was es im Chat schon gesagt hat |
get_plan | Antworten zum Entwurf, hinzugefügte Wirkstoffe | |
rate_plan, rate_message | Sterne, Gründe und Kommentar zum Plan, Daumen zu einer Antwort der Beratung | nur, was das Mitglied selbst bewertet; Medikamente, Schwangerschaft und Stillzeit im Kommentar nur mit der passenden Freigabe |
| Warenkorb-Werkzeuge | gewählte Produkte, Mengen, Sets, abgewählte Marken | |
| Anmeldung | das Choicera-Konto meldet das Mitglied selbst im Fenster von Choicera an | dein Client übergibt keine Konto-Daten |
Angaben, die das Mitglied deinem Agenten schon gesagt hat, gehen nur über statedProfile beim Start und erst nach der Bestätigung des Mitglieds auf der Karte ins Konto (siehe Angaben beim Start). Was Choicera aus früheren Beratungen desselben Kontos weiß, ist in Formularen vorbelegt (preset) oder wird nicht erneut gefragt.
Daten von Choicera
| Werkzeug | Was zurückkommt |
|---|---|
| Katalogwerkzeuge | Katalogdaten: siehe Katalogprodukt |
start_consultation, send_message, answer_intake, undo_last_answer | conversationId, status, reply, compliance, an bewertbaren Antworten messageId; nach statedProfile dazu adopted und ignored |
rate_plan, rate_message | die gespeicherte Bewertung |
get_plan | Stand; Plan mit planId, Phasen, je Punkt Wirkstoff, Menge, Einnahmezeit, Basis oder Plus, Stern, Rolle, Beschreibung und Pflichttext F11; disclosure, compliance |
get_plan_products | je Planpunkt Produkte mit Varianten, Preis, Grundpreis, Monatspreis, Passung, Warnhinweisen; Sets, Marken, Warenkorb mit Kosten je Shop |
add_to_cart | hinzugefügte, zu bestätigende und abgelehnte Zeilen, Warenkorb-Summe |
get_checkout_link | Link mit Pflichttexten; mit planId dazu Ziel des Links und Warenkorb mit Verkäufern, Zahlweg, Versand und Gesamtpreis |
get_orders | eigene Bestellungen an der Kasse: Bestellnummer, Zeitpunkt, Zahlstand, Betrag, je Verkäufer Versandstand, Lieferfenster und Sendungsverfolgung |
Die MCP-Werkzeuge geben keine E-Mail-Adresse, keinen Namen und keine Konto-Kennung des Mitglieds heraus.
Choicera protokolliert jede Antwort an KI-Anwendungen samt Pflichttexten als Nachweis, pseudonymisiert und bis zu zehn Jahre. Einzelheiten stehen in der Datenschutzerklärung.
Gesundheitsdaten und Freigaben
- Die Beratung verarbeitet Gesundheitsangaben nur, wenn das Mitglied das Häkchen „Beratung“ gesetzt hat.
- Medikamente sind nur mit
advisor:medicationThema der Beratung, Schwangerschaft und Stillzeit nur mitadvisor:maternal. Beide erteilt das Mitglied einzeln auf dem Einwilligungsbildschirm. - Ohne diese Freigaben ist die Beratung angewiesen, nicht danach zu fragen, keine Antwort dazu anzubieten und nicht nachzufragen, wenn das Mitglied es selbst erwähnt. Das Medikamenten-Formular gibt es dann nicht. Produkte, deren Hinweise sich auf Medikamente oder Schwangerschaft beziehen, fehlen in
get_plan_productsund im Warenkorb vonget_checkout_link. Antworten mit F5 und der Plan tragen dann den Hinweis F10, dass dies nicht geprüft wurde. Fehltadvisor:medication, steht einmal je Beratung an der Stelle, an der sonst das Medikamenten-Formular käme, ein fester Satz am Ende vonreply.text, wie das Mitglied die Freigabe „Medikamente“ nachholt (Wortlaut unter Pflichten). - Als Partner fragst du diese beiden Freigaben nicht an. Technisch kann heute jeder Client sie anfragen; für Partner gilt trotzdem: Medikamente, Schwangerschaft und Stillzeit sind über deinen Agenten kein Thema der Beratung.
- Gib in
messageund in Suchanfragen keine Medikamente, Diagnosen oder anderen Gesundheitsdaten weiter. - Die Hinweise von Choicera ersetzen keine ärztliche oder pharmazeutische Beratung.
Zuordnung zum Partner
Eine Anbindung mit deiner Partner-Kennung steht einem Aufruf über deinen Partner-Link gleich (§ 9 Abs. 8 der Partnerbedingungen).
- Kennung mitgeben: Deine Kennung ist der letzte Teil deines Partner-Links
https://choicera.com/supps/affiliate/<Kennung>. Trag als Serveradressehttps://choicera.com/agent/mcp?partner=<Kennung>ein. Baust du die Anfragen selbst, kannst du stattdessen bei jeder Anfrage die KopfzeileX-Choicera-Partner: <Kennung>senden; kommen beide, gilt die Kopfzeile. Die OAuth-Metadaten nennen die Adresse ohne?partner=; verlangt dein Client, dass beide gleich sind, nimm die Kopfzeile. - Wann sie zählt: Beginnt das Mitglied über diese Verbindung eine Beratung mit
start_consultation, auch nach der Kartehandover_confirm, vermerkt Choicera deine Kennung an dieser Beratung. Eine Beratung, die schon offen war und nur fortgesetzt wird, bekommt keinen neuen Vermerk. - Erster Kauf: Kauft das Mitglied aus dieser Beratung innerhalb von sieben Tagen nach ihrem Beginn, im Shop der Marke oder an der Kasse von Choicera, ist der Kauf dir zugeordnet (ausgelöster Kauf, § 5 Abs. 3).
- Wiederkäufe: Mit diesem Kauf beginnt am Konto des Mitglieds ein Zuordnungszeitraum von sechs Monaten (§ 5 Abs. 3a). Käufe desselben Kontos in dieser Zeit sind dir zugeordnet, ohne Cookie und ohne neuen Aufruf über deine Anbindung. Jeder weitere ausgelöste Kauf über deine Anbindung oder deinen Partner-Link beginnt die sechs Monate neu.
- Letzter Klick gewinnt: Ruft das Mitglied danach den Partner-Link eines anderen Partners auf oder beginnt es eine Beratung über dessen Anbindung, gilt für die folgenden Käufe der andere Partner, nach denselben Regeln. Hat das Mitglied dem Tracking nicht zugestimmt, zählt ein späterer Partner-Link des anderen Partners nur für Käufe aus der Beratung, die es über diesen Link beginnt, und nur sieben Tage lang; dein Zuordnungszeitraum läuft weiter.
- Ohne gültige Kennung: Fehlt die Kennung, ist sie falsch geschrieben oder gehört sie zu keinem aktiven Partner-Link, läuft die Beratung wie ohne Partner. Choicera meldet dafür keinen Fehler.
- Widerspruch: Widerspricht das Mitglied über den Schalter „Tracking & Analyse“ in seinen Einstellungen, endet die Zuordnung, auch ein laufender Zuordnungszeitraum.
- Daten und Abrechnung: Du bekommst keine personenbezogenen Daten des Mitglieds. Die Käufe stehen in deiner monatlichen Übersicht wie Käufe über deinen Partner-Link.
- Testen: Ein Kauf über deine eigene Kennung ist eine Eigenbestellung und wird nicht vergütet (§ 7). Sprich Testkäufe vorher mit uns ab.
Feldreferenz
Erzeugt aus inputSchema und outputSchema in tools/list des Servers, mit allen Berechtigungen. Heute kommen keine anderen Felder als die hier genannten. Lies die Schemas trotzdem zur Laufzeit und lass unbekannte Felder zu: Neue Felder können hinzukommen.
Spalte „Vorhanden“: immer heißt, das Feld steht in jeder Antwort; optional heißt, das Feld kann fehlen; auch `null` heißt, der Wert kann null sein. Bei Feldern in einem Objekt, etwa medication.choice, gelten „Pflicht“ und „Vorhanden“ innerhalb dieses Objekts. Zahlen hinter string nennen die Länge in Zeichen, hinter array die Zahl der Einträge, hinter integer und number den Wertebereich.
list_brands
Eingabe: keine.
Antwort
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
brands | array ≤ 1000 von Marke | immer | die aktiven Marken |
Marke
Alle Felder von Markenverweis, dazu:
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
tagline | string ≤ 1024 | immer, auch null | Kurzbeschreibung |
description | string ≤ 8000 | immer, auch null | Beschreibung der Marke |
traits | array ≤ 128 von string ≤ 256 | immer | Merkmale der Marke |
Markenverweis
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
id | string ≤ 64 | immer | Kennung der Marke |
slug | string ≤ 128 | immer | Kennung für search_products.brand |
name | string ≤ 256 | immer | Name der Marke |
color | string ≤ 64 | immer | Farbe der Marke, etwa #007ab3 |
logoUrl | string ≤ 4096 | immer, auch null | Logo der Marke |
list_topics
Eingabe: keine.
Antwort
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
topics | array ≤ 50 von Thema | immer | die laufenden Themen; die Liste kann leer sein |
Thema
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
slug | string ≤ 128 | immer | Kennung für topic |
labelDe | string ≤ 256 | immer | Name deutsch |
labelEn | string ≤ 256 | immer | Name englisch |
activeFrom | string ≤ 64 | immer | Beginn des Zeitraums als ISO-Zeitpunkt |
activeTo | string ≤ 64 | immer | Ende des Zeitraums als ISO-Zeitpunkt |
eventDate | string ≤ 64 | immer, auch null | Datum des Ereignisses, etwa ein Wettkampf |
goalSlugs | array 1 bis 20 von string ≤ 64 | immer | Ziele des Themas |
search_products
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
query | string ≤ 128 | nein | Suchwort für Produkt, Inhaltsstoff oder Marke; keine Angaben über die Person; siehe Katalogsuche |
goal | string ≤ 64 | nein | eine Kennung aus get_goals; nicht zusammen mit topic |
topic | string 1 bis 128 | nein | eine Kennung aus list_topics; sucht wie die Ziele des Themas; nicht zusammen mit goal |
brand | string ≤ 64 | nein | slug einer Marke aus list_brands |
limit | integer 1 bis 50 | nein | Treffer je Seite, Standard 10 |
offset | integer 0 bis 1000 | nein | Beginn der Seite, Standard 0 |
language | de, en | nein | de oder en; ohne Angabe die Sprache des verknüpften Kontos, ohne Konto Deutsch |
Antwort
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
products | array ≤ 50 von Katalogprodukt | immer | die Treffer dieser Seite |
total | integer | immer | Zahl aller Treffer |
limit | integer | immer | verwendetes limit |
offset | integer | immer | verwendeter offset |
matchMode | all, any | immer | all, wenn jeder Treffer zu allen Suchwörtern passt; any, wenn es dafür keinen Treffer gab und die Suche auf einzelne Suchwörter ausweicht |
Katalogprodukt
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
id | string ≤ 64 | immer | Produkt-Kennung, Eingabe für get_product und get_checkout_link (productId) |
title | string ≤ 512 | immer | Produktname der Marke |
price | number | immer | Preis in currency |
currency | string ≤ 16 | immer | Währung, etwa EUR |
basePrice | Grundpreis | optional | fehlt, wenn der Shop keine Füllmenge nennt; nie schätzen |
productUrl | string ≤ 4096 | immer, auch null | Produktlink über https://choicera.com/go/... mit Kanal-Kennung c=agent; führt in den Shop der Marke; unverändert weitergeben |
productUrlDisplay | string ≤ 8192 | immer, auch null | Marke, Link und Pflichttext F6, fertig zum Anzeigen; null, wenn productUrl null ist |
compliance | array ≤ 4 von Pflichttext | optional | Pflichttexte einzeln: F6 zum Link, F8 zum Preis |
formFactor | string ≤ 128 | immer, auch null | Darreichungsform, etwa capsule, tablet, powder |
servingSizeDisplay | string ≤ 512 | immer, auch null | Portion als Text, etwa 2 Tabletten |
strengthPerServing | string ≤ 512 | immer, auch null | Wirkstoffmenge je Portion als Text |
pricePerServing | number | immer, auch null | Preis je Portion in currency |
dietCompatibility | array ≤ 128 von string ≤ 128 | immer | Ernährungsformen, etwa vegan, vegetarian |
allergens | array ≤ 128 von string ≤ 128 | immer | Allergene einschließlich Spuren, sortiert; eine leere Liste heißt „keine angegeben“, nicht „geprüft frei von Allergenen“ |
minAgeYears | integer | immer, auch null | Mindestalter laut Marke |
maxAgeYears | integer | immer, auch null | Höchstalter laut Marke |
brand | Objekt | immer | die Marke |
brand.slug | string ≤ 128 | immer | Kennung für search_products.brand |
brand.name | string ≤ 256 | immer | Name der Marke |
primaryIngredients | array ≤ 5 von string ≤ 1024 | immer | Namen der Hauptbestandteile laut Katalog; kann Hilfsstoffe enthalten |
matchReasons | array ≤ 2 von string ≤ 256 | immer | bis zu zwei Gründe, warum das Produkt passt, etwa der gefundene Wirkstoff oder das Ziel |
Grundpreis
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
amount | number | immer | Preis je 1 kg oder 1 l in der Währung des Preises |
amountLabel | string | immer | derselbe Betrag deutsch formatiert, etwa 173,33 |
unit | string | immer | kg oder l |
Pflichttext
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
id | string, nicht leer | immer | Kennung des Pflichttexts: F2, F4, F5, F6, F7, F8, F10 oder F11 |
text | string, nicht leer | immer | der Text, wörtlich anzuzeigen |
trigger | string, nicht leer | immer | worauf er sich bezieht, etwa buy_link:<Kennung oder Adresse>, price:<...>, voucher:<...>, ai_recommendation, health_recommendation, authorized_claim, degraded_medication, degraded_maternal |
get_product
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
productId | string ≤ 64 | ja | eine id aus search_products; eine unbekannte oder falsch geformte Kennung ergibt product_not_found |
language | de, en | nein | de oder en; ohne Angabe die Sprache des verknüpften Kontos, ohne Konto Deutsch |
Antwort: Produktdetail
Produktdetail
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
id | string ≤ 64 | immer | Produkt-Kennung, Eingabe für get_product und get_checkout_link (productId) |
title | string ≤ 512 | immer | Produktname der Marke |
sourceLanguage | de | immer | Sprache der Katalogtexte; heute immer Deutsch |
brand | Markenverweis | immer | die Marke |
price | number | immer | Preis in currency |
currency | string ≤ 16 | immer | Währung, etwa EUR |
basePrice | Grundpreis | optional | fehlt, wenn der Shop keine Füllmenge nennt; nie schätzen |
imageUrl | string ≤ 4096 | immer, auch null | Produktbild |
productUrl | string ≤ 4096 | immer, auch null | Produktlink über https://choicera.com/go/... mit Kanal-Kennung c=agent; führt in den Shop der Marke; unverändert weitergeben |
productUrlDisplay | string ≤ 8192 | immer, auch null | Marke, Link und Pflichttext F6, fertig zum Anzeigen; null, wenn productUrl null ist |
compliance | array ≤ 4 von Pflichttext | optional | Pflichttexte einzeln: F6 zum Link, F8 zum Preis |
coupon | Gutschein | optional | nur, wenn die Marke einen Gutschein mit nennbaren Bedingungen hat |
formFactor | string ≤ 128 | immer, auch null | Darreichungsform, etwa capsule, tablet, powder |
servingSizeDisplay | string ≤ 512 | immer, auch null | Portion als Text, etwa 2 Tabletten |
servingsPerContainer | integer | immer, auch null | Portionen je Packung |
dosageText | string ≤ 8000 | immer, auch null | Verzehrempfehlung der Marke |
strengthPerServing | string ≤ 512 | immer, auch null | Wirkstoffmenge je Portion als Text |
servingUnit | string ≤ 128 | immer, auch null | Einheit einer Portion, etwa Tabletten |
pricePerServing | number | immer, auch null | Preis je Portion in currency |
primaryIngredients | array ≤ 256 von string ≤ 1024 | immer | Namen der Hauptbestandteile laut Katalog; kann Hilfsstoffe enthalten |
dietCompatibility | array ≤ 128 von string ≤ 128 | immer | Ernährungsformen, etwa vegan, vegetarian |
allergens | array ≤ 128 von string ≤ 128 | immer | Allergene einschließlich Spuren, sortiert; eine leere Liste heißt „keine angegeben“, nicht „geprüft frei von Allergenen“ |
minAgeYears | integer | immer, auch null | Mindestalter laut Marke |
maxAgeYears | integer | immer, auch null | Höchstalter laut Marke |
intakeAdvice | string ≤ 2000 | immer, auch null | Einnahmehinweis der Marke |
warnings | string ≤ 2000 | immer, auch null | Warnhinweise der Marke als Text |
pzn | string ≤ 32 | immer, auch null | Pharmazentralnummer |
servingIntervalDays | integer | immer | Abstand zwischen zwei Portionen in Tagen; 1 heißt täglich |
ingredientsDeclaration | array ≤ 128 von string ≤ 4000 | immer | Zutatenliste laut Marke |
variants | array ≤ 512 von Katalogvariante | immer | alle Varianten, auch nicht verfügbare |
substanceDescription | string ≤ 16000 | immer, auch null | allgemeine Beschreibung des Wirkstoffs, deutsch |
Gutschein
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
code | string ≤ 64 | immer | Gutscheincode; Code und Bedingungen so zeigen, wie sie kommen, ohne eigenen Satz daraus |
discountType | percent, fixed | immer, auch null | Art des Nachlasses |
discountValue | number | immer, auch null | Höhe des Nachlasses |
newCustomerDiscountValue | number | immer, auch null | Nachlass nur für Neukunden des Shops, gilt nicht für discountValue |
minOrderValue | number | immer, auch null | Mindestbestellwert |
conditionsNote | string ≤ 500 | immer, auch null | Bedingungen als Text |
Katalogvariante
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
id | string ≤ 64 | immer | Kennung der Variante |
title | string ≤ 512 | immer | Name der Variante |
position | integer | immer | Reihenfolge im Shop |
containerSize | number | immer, auch null | Packungsgröße in containerUnit |
containerUnit | string ≤ 64 | immer, auch null | Einheit der Packungsgröße |
price | number | immer, auch null | Preis der Variante in currency des Produkts |
basePrice | Grundpreis | optional | Grundpreis der Variante |
available | boolean | immer | lieferbar |
imageUrl | string ≤ 4096 | immer, auch null | Bild der Variante |
servingSizeMin | number | immer, auch null | kleinste Portionsgröße |
servingSizeMax | number | immer, auch null | größte Portionsgröße |
servingSizeUnit | string ≤ 128 | immer, auch null | Einheit der Portionsgröße |
servingsPerContainerMin | integer | immer, auch null | kleinste Zahl der Portionen je Packung |
servingsPerContainerMax | integer | immer, auch null | größte Zahl der Portionen je Packung |
flavor | string ≤ 256 | immer, auch null | Geschmack |
get_goals
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
language | de, en | nein | de oder en; ohne Angabe die Sprache des verknüpften Kontos, ohne Konto Deutsch |
Antwort
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
goals | array ≤ 200 von Ziel | immer | die festen Ziele |
Ziel
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
slug | string ≤ 64 | immer | Kennung, etwa sleep-relaxation; nur diese Werte gelten |
label | string ≤ 256 | immer | Name des Ziels, heute nur deutsch |
start_consultation
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
goalSlugs | array 1 bis 14 von string 1 bis 64 | nein | Kennungen aus get_goals; höchstens eines von goalSlugs und topic, ohne beide reicht message |
topic | string 1 bis 128 | nein | Kennung aus list_topics; höchstens eines von goalSlugs und topic, ohne beide reicht message |
eventDate | string, Muster ^\d{4}-\d{2}-\d{2}$ | nein | Datum des Ereignisses als JJJJ-MM-TT, nur mit topic |
message | string ≤ 2000 | nein | Anliegen in den Worten des Mitglieds, ohne Medikamente, Diagnosen oder andere Gesundheitsdaten; reicht allein für den Start |
statedProfile | Objekt | nein | feste Angaben, die das Mitglied schon gemacht hat; das Mitglied bestätigt sie auf einer Karte, bevor die Beratung beginnt, siehe Angaben beim Start |
statedProfile.gender | female, male, diverse, prefer_not_to_say | nein | Geschlecht, Options-id wie im Formular zu den Körperwerten |
statedProfile.ageRange | under_18, 18_29, 30_44, 45_59, 60_plus | nein | Altersspanne, Options-id wie im Formular zu den Körperwerten |
statedProfile.weightKg | number größer 0 | nein | Gewicht in kg |
statedProfile.heightCm | number größer 0 | nein | Größe in cm |
statedProfile.diet | array 1 bis 4 aus vegan, vegetarian, gluten-free, lactose-free | nein | Ernährungsformen |
statedProfile.formPreference | capsule, powder, liquid, chewable | nein | bevorzugte Darreichungsform |
statedProfile.sportPreferences | Objekt | nein | Vorlieben bei Sportnahrung, Options-ids wie im Formular sport_preferences |
statedProfile.sportPreferences.protein | any, lactose_free, plant_only | nein | Eiweißquelle |
statedProfile.sportPreferences.texture | any, creamy, clear | nein | Konsistenz |
statedProfile.sportPreferences.sweetness | any, no_artificial, unsweetened | nein | Süße |
statedProfile.sportPreferences.form | powder_ok, capsule_tablet | nein | Darreichungsform |
statedProfile.sportPreferences.caffeine | without, with | nein | Koffein |
statedProfile.sleepQuality | good, medium, poor | nein | wie das Mitglied schläft |
statedProfile.stressLevel | low, medium, high | nein | Stress; bei getrennten Werten für Arbeit und Freizeit der höhere |
statedProfile.workShift | none, rotating, night | nein | Schichtarbeit |
statedProfile.existingSupplements | array 1 bis 15 von string 1 bis 64 | nein | Namen der Präparate, die das Mitglied schon nimmt; kommen zu den gespeicherten dazu; ein Name, der nach einem Medikament klingt, bleibt draußen |
statedProfile.allergies | array 1 bis 10 von string 1 bis 64 | nein | Namen der Allergien; kommen zu den gespeicherten dazu; nur mit der Einwilligung des Mitglieds für Allergien |
statedProfile.lifeStage | pregnant, lactating | nein | nur mit advisor:maternal: pregnant oder lactating; nur mit der Einwilligung des Mitglieds dafür |
statedProfile.trimester | integer 1 bis 3 | nein | nur mit advisor:maternal und lifeStage: pregnant: Schwangerschaftsdrittel 1 bis 3 |
statedProfile.observedAt | Objekt | nein | je Angabe das Datum als JJJJ-MM-TT, Schlüssel ist der Name der Angabe; älter als 300 Tage steht sie auf der Karte als „bitte prüfen“ |
Antwort: Beratungszug
Beratungszug
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
conversationId | string, nicht leer | immer | Kennung der Beratung, für alle weiteren Aufrufe |
status | string, nicht leer | immer | Stand des Gesprächs nach diesem Zug, etwa gathering_info, analyzing, plan_generated, refining_intake, refining oder completed |
reply | Antwort der Beratung | immer | was die Beratung sagt oder fragt |
messageId | string | optional | Kennung dieser Antwort für rate_message; nur an Antworten, unter denen die App Daumen zeigt: Text ohne Antwortmöglichkeiten und ohne Formular |
compliance | array von Pflichttext | optional | die Pflichttexte dieses Zugs einzeln; sie stehen auch am Ende von reply.text; leer bei einer reinen Frage |
ignored | array ≤ 40 von Objekt | optional | Angaben, die Choicera nicht übernommen hat, je mit Grund; nie der Wert selbst |
ignored[].field | string 1 bis 64 | immer | Name der Angabe |
ignored[].reason | sender_not_allowed, scope_missing, consent_missing, medication_mention, user_edit_kept | immer | scope_missing: Berechtigung fehlt; consent_missing: Einwilligung des Mitglieds fehlt; medication_mention: ein Name klingt nach einem Medikament; user_edit_kept: das Mitglied hat den Wert selbst gesetzt, er bleibt; sender_not_allowed: dieser Absender darf die Angabe nicht übergeben |
adopted | array ≤ 40 von Objekt | optional | die bestätigten Angaben samt Korrekturen, nach der Karte |
adopted[].field | string 1 bis 64 | immer | Feld-id der Karte |
adopted[].value | array ≤ 20 von string ≤ 64 | immer | der bestätigte Wert wie auf der Karte: Options-ids, eine Zahl als Text oder Namen |
Antwort der Beratung
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
type | string, nicht leer | immer | siehe Antworttypen |
text | string | immer | Text der Beratung; gehören Pflichttexte dazu, stehen sie am Ende; vollständig zeigen |
options | array (mindestens 1) von Option | optional | Antwortmöglichkeiten wie die Knöpfe in der App |
multiSelect | boolean | optional | true: mehrere Optionen wählbar |
freeText | boolean | optional | true: freie Antwort statt Option möglich |
form | Formular | optional | bei den Formular-Typen, siehe Formulare |
identifiedGoals | array ≤ 20 von string 1 bis 128 | optional | nur bei ready_to_generate: Namen der Ziele, für die der Plan entsteht, wie get_goals sie nennt |
Option
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
label | string, nicht leer | immer | was das Mitglied sieht |
value | string, nicht leer | immer | was du mit send_message sendest |
Formular
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
kind | demographics, medication, sport_preferences, handover | immer | als kind an answer_intake senden |
title | string, nicht leer | immer | Überschrift wie in der App |
skip | Objekt | immer, auch null | Knopf zum Überspringen des ganzen Formulars |
skip.label | string, nicht leer | immer | Text des Knopfs |
fields | array (mindestens 1) von Formularfeld | immer | die Felder in ihrer Reihenfolge |
Formularfeld
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
id | string, nicht leer | immer | Name des Felds im Antwortblock |
label | string, nicht leer | immer | Frage des Felds wie in der App |
options | array von Objekt | immer | Auswahl; leer, wenn das Feld nur eigene Worte nimmt |
options[].id | string, nicht leer | immer | Kennung, die du an answer_intake sendest |
options[].label | string, nicht leer | immer | was das Mitglied sieht |
multiSelect | boolean | immer | mehrere Optionen wählbar |
optional | boolean | immer | darf fehlen; dann nicht senden |
preset | array von string | immer | schon Bekanntes: Options-ids oder Text; vorausgewählt zeigen |
freeText | Objekt | immer, auch null | Feld nimmt eigene Worte; anders als reply.freeText ein Objekt, kein boolean |
freeText.label | string, nicht leer | immer | Beschriftung des Eingabefelds |
freeText.maxLength | integer größer 0 | immer | höchstens so viele Zeichen |
showIf | Objekt | immer, auch null | Feld nur fragen, wenn die Bedingung gilt |
showIf.field | string, nicht leer | immer | Feld, dessen Antwort zählt |
showIf.optionId | string, nicht leer | immer | Option, die dort gewählt sein muss |
stored | array von string | optional, auch null | nur auf der Karte handover: der gespeicherte Wert; null ohne |
needsReview | boolean | optional | nur auf der Karte handover: true, wenn der Wert veraltet sein kann |
differs | boolean | optional | nur auf der Karte handover: true, wenn der Wert vom gespeicherten abweicht und ihn ersetzt |
note | string | optional | nur auf der Karte handover: Hinweis der Karte zum Feld, etwa „bisher 80 kg“ |
send_message
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
conversationId | string 1 bis 64 | ja | aus start_consultation oder list_consultations |
message | string 1 bis 5000 | ja | value der gewählten Option oder die Worte des Mitglieds |
onBehalf | true | nein | true: die eigene KI des Mitglieds gibt weiter, was das Mitglied im Chat schon gesagt hat; nicht für die Karte und nicht für das Medikamenten-Formular, nie von Partnern |
Antwort: Beratungszug
answer_intake
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
conversationId | string 1 bis 64 | ja | aus start_consultation |
kind | demographics, medication, sport_preferences, handover | ja | aus reply.form.kind; medication nur mit advisor:medication |
declined | true | nein | nur nach Wahl des Knopfs aus reply.form.skip, dann ohne Antwortblock |
amend | true | nein | nur mit kind: medication: Medikamenten-Antwort später ändern, auch nach dem Plan |
demographics | Objekt | nein | Antwortblock zu demographics: nur die beantworteten Felder |
demographics.gender | female, male, diverse, prefer_not_to_say | nein | Geschlecht |
demographics.ageBracket | under_18, 18_29, 30_44, 45_59, 60_plus | nein | Altersspanne |
demographics.weightBracket | under_60, 60_75, 75_90, 90_plus | nein | Gewichtsspanne in kg |
demographics.heightBracket | under_160, 160_175, 175_190, 190_plus | nein | Größenspanne in cm |
medication | Objekt | nein | Antwortblock zu medication; ersetzt die frühere Antwort ganz |
medication.choice | none, meds | ja | none: keine Medikamente, meds: Medikamente |
medication.drugClasses | array ≤ 6 aus pill_contraceptive, blood_thinner, thyroid_medication, antidepressant_ssri, antibiotic, other | nein | Medikamentenklassen; bei meds mindestens eine Klasse oder ein Freitext |
medication.freetext | string ≤ 200 | nein | eigene Worte, nur mit meds |
sport_preferences | Objekt | nein | Antwortblock zu sport_preferences |
sport_preferences.protein | any, lactose_free, plant_only | nein | Eiweißquelle |
sport_preferences.texture | any, creamy, clear | nein | Konsistenz |
sport_preferences.sweetness | any, no_artificial, unsweetened | nein | Süße |
sport_preferences.form | powder_ok, capsule_tablet | nein | Darreichungsform |
sport_preferences.caffeine | without, with | nein | Koffein |
handover | Objekt | nein | Antwortblock zu handover, der Karte mit den Angaben beim Start |
handover.confirmed | true | ja | immer true: das Mitglied hat die Karte bestätigt |
handover.changes | Objekt | nein | die Werte, die das Mitglied auf der Karte korrigiert hat, benannt wie statedProfile |
handover.changes.gender | female, male, diverse, prefer_not_to_say | nein | Geschlecht, Options-id wie im Formular zu den Körperwerten |
handover.changes.ageRange | under_18, 18_29, 30_44, 45_59, 60_plus | nein | Altersspanne, Options-id wie im Formular zu den Körperwerten |
handover.changes.weightKg | number größer 0 | nein | Gewicht in kg |
handover.changes.heightCm | number größer 0 | nein | Größe in cm |
handover.changes.diet | array 1 bis 4 aus vegan, vegetarian, gluten-free, lactose-free | nein | Ernährungsformen |
handover.changes.formPreference | capsule, powder, liquid, chewable | nein | bevorzugte Darreichungsform |
handover.changes.sportPreferences | Objekt | nein | Vorlieben bei Sportnahrung, Options-ids wie im Formular sport_preferences |
handover.changes.sportPreferences.protein | any, lactose_free, plant_only | nein | Eiweißquelle |
handover.changes.sportPreferences.texture | any, creamy, clear | nein | Konsistenz |
handover.changes.sportPreferences.sweetness | any, no_artificial, unsweetened | nein | Süße |
handover.changes.sportPreferences.form | powder_ok, capsule_tablet | nein | Darreichungsform |
handover.changes.sportPreferences.caffeine | without, with | nein | Koffein |
handover.changes.sleepQuality | good, medium, poor | nein | wie das Mitglied schläft |
handover.changes.stressLevel | low, medium, high | nein | Stress; bei getrennten Werten für Arbeit und Freizeit der höhere |
handover.changes.workShift | none, rotating, night | nein | Schichtarbeit |
handover.changes.existingSupplements | array 1 bis 15 von string 1 bis 64 | nein | Namen der Präparate, die das Mitglied schon nimmt; kommen zu den gespeicherten dazu; ein Name, der nach einem Medikament klingt, bleibt draußen |
handover.changes.allergies | array 1 bis 10 von string 1 bis 64 | nein | Namen der Allergien; kommen zu den gespeicherten dazu; nur mit der Einwilligung des Mitglieds für Allergien |
handover.changes.lifeStage | pregnant, lactating | nein | nur mit advisor:maternal: pregnant oder lactating; nur mit der Einwilligung des Mitglieds dafür |
handover.changes.trimester | integer 1 bis 3 | nein | nur mit advisor:maternal und lifeStage: pregnant: Schwangerschaftsdrittel 1 bis 3 |
handover.rejectedFields | array ≤ 32 von string 1 bis 64 | nein | Feld-ids der Karte, die das Mitglied nicht übernehmen will |
onBehalf | true | nein | true: die Antworten hat das Mitglied im Chat schon gegeben, seine eigene KI gibt sie weiter; nicht für handover und medication, nie von Partnern |
Antwort: Beratungszug
undo_last_answer
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
conversationId | string 1 bis 64 | ja | aus start_consultation |
Antwort: Beratungszug
get_plan
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
conversationId | string 1 bis 64 | ja | die Beratung |
jobId | string 1 bis 64 | nein | aus einer pending-Antwort, zum erneuten Abfragen |
draftFeedback | array ≤ 40 von Objekt | nein | nach draft_review: Antwort je Zeile; eine leere Liste bestätigt den Entwurf unverändert |
draftFeedback[].key | string 1 bis 80 | ja | key aus draft.rows |
draftFeedback[].feedback | already_taking, preferred_form, do_not_want, not_taking | ja | Antwort zur Zeile, siehe Plan erzeugen |
draftFeedback[].form | capsule, powder, liquid, chewable | nein | nur mit preferred_form |
draftAdded | array ≤ 10 von string 1 bis 80 | nein | nach draft_review: keys aller hinzuzufügenden Wirkstoffe, auch der behaltenen aus draft.added; fehlt es, bleibt draft.added |
reopenDraft | true | nein | nur bei refining_intake: öffnet den Entwurf erneut |
Antwort
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
conversationId | string, nicht leer | immer | Kennung der Beratung |
status | completed, pending, regenerating, no_plan, failed, draft_review, plan_generated, refining_intake, intake_open | immer | siehe Plan erzeugen |
plan | Plan | optional | bei draft_review, refining_intake, plan_generated, completed |
draft | Entwurf | optional | bei draft_review |
reply | Antwort der Beratung | optional | bei intake_open und refining_intake |
jobId | string, nicht leer | optional | bei pending, manchmal bei failed |
reason | string, nicht leer | optional | bei pending und failed |
retryAfterSeconds | integer größer 0 | optional | bei pending: so lange warten |
disclosure | string | optional | Pflichttexte zum Plan als ein Text; vollständig mit dem Plan zeigen |
compliance | array von Pflichttext | optional | dieselben Pflichttexte einzeln |
Plan
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
planId | string, nicht leer | immer | Kennung des Plans, für die Werkzeuge mit planId |
degraded | boolean | optional | true: vorsichtige Grundempfehlung statt persönlichem Plan |
phases | array von Objekt | immer | die Phasen in ihrer Reihenfolge |
phases[].phaseNumber | integer | immer | Nummer der Phase |
phases[].name | string ≤ 300 | optional | Name der Phase wie in der App; fehlt, wenn der Text zurückgehalten wird |
phases[].description | string ≤ 2000 | optional | wofür die Phase steht, wie in der App; fehlt, wenn der Text zurückgehalten wird |
phases[].items | array von Objekt | immer | Planpunkte der Phase |
phases[].items[].supplementName | string, nicht leer | immer | Wirkstoff |
phases[].items[].dosage | string | immer | Menge, etwa 300 mg |
phases[].items[].tier | basic, plus | optional | basic: Basis des Plans; plus: optionale Ergänzung |
phases[].items[].frequency | daily, twice_daily | optional | wie oft am Tag die Menge genommen wird: daily einmal, twice_daily zweimal |
phases[].items[].priority | boolean | optional | true: einer der drei wichtigsten Wirkstoffe (Stern) |
phases[].items[].role | string ≤ 300 | optional | Satz der App zur Rolle des Wirkstoffs im Plan |
phases[].items[].timing | string ≤ 300 | optional | Einnahmezeit in den Worten der App |
phases[].items[].description | string ≤ 2000 | optional | wofür der Wirkstoff im Plan steht, geprüfter Text der App; fehlt, wenn der Text zurückgehalten wird |
phases[].items[].traditional | boolean | optional | true: für den Wirkstoff liegt keine zugelassene gesundheitsbezogene Angabe vor; dann traditionalNote mit zeigen |
phases[].items[].traditionalNote | string ≤ 300 | optional | bei traditional: der Satz der App dazu |
phases[].items[].consultNotice | string ≤ 300 | optional | Pflichttext F11: vor der Einnahme mit Arzt oder Apotheke sprechen; mit dem Wirkstoff zeigen |
footerDisclosure | string ≤ 2000 | optional | Hinweis unter dem Plan, wenn ein Wirkstoff keine zugelassene gesundheitsbezogene Angabe hat, wie in der App |
approximateDosing | string ≤ 2000 | optional | nur, wenn der Plan ohne Alter, Geschlecht, Gewicht oder Größe entstand: die Mengen sind allgemein |
allergyNotChecked | string ≤ 2000 | optional | nur, wenn das Mitglied eine Allergie genannt hat, die Choicera nicht kennt: sie ließ sich bei den Produkten nicht prüfen |
legend | string ≤ 300 | optional | erklärt den Stern; die App zeigt den Text nach „★ “ |
Entwurf
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
rows | array von Entwurfszeile | immer | die Wirkstoffe zum Beantworten |
added | array von Wirkstoff zum Hinzufügen | immer | früher hinzugefügte Wirkstoffe |
addLimit | integer ab 0 | immer | wie viele Wirkstoffe insgesamt hinzugefügt werden dürfen |
degraded | boolean | immer | true: vorsichtige Grundempfehlung; beantworten geht wie sonst |
feedback | array aus already_taking, preferred_form, do_not_want, not_taking | immer | erlaubte Antworten |
forms | array aus capsule, powder, liquid, chewable | immer | wählbare Darreichungsformen |
labels | Objekt | immer | Texte der App für die Antworten zum Entwurf |
labels.taking | string, nicht leer | immer | Text für already_taking |
labels.omit | string, nicht leer | immer | Text für do_not_want |
labels.preferredForm | string, nicht leer | immer | Text für preferred_form |
labels.forms | Objekt | immer | Namen der Darreichungsformen |
labels.forms.capsule | string, nicht leer | immer | Name für capsule |
labels.forms.powder | string, nicht leer | immer | Name für powder |
labels.forms.liquid | string, nicht leer | immer | Name für liquid |
labels.forms.chewable | string, nicht leer | immer | Name für chewable |
labels.formHint | string, nicht leer | immer | Hinweis zur Wahl der Form |
labels.add | string, nicht leer | immer | Text des Knopfs zum Hinzufügen |
labels.confirm | string, nicht leer | immer | Text des Knopfs zum Bestätigen |
Entwurfszeile
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
key | string, nicht leer | immer | Kennung für draftFeedback |
name | string, nicht leer | immer | Name des Wirkstoffs |
dosage | string | immer | Menge |
timing | string | immer | Einnahmezeit als Schlüssel, etwa evening |
tier | string | immer | basic (Basis) oder plus |
priority | boolean | immer | true: einer der drei wichtigsten Wirkstoffe (Stern) |
description | string | immer | wofür der Wirkstoff im Plan steht, Text der App |
alreadyTaking | boolean | immer | als „nehme ich schon“ markiert |
preferredForm | capsule, powder, liquid, chewable | immer, auch null | früher gewählte Form |
doNotWant | boolean | immer | durch eine frühere Antwort aus dem Plan genommen |
Wirkstoff zum Hinzufügen
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
key | string, nicht leer | immer | Kennung für draftAdded |
name | string, nicht leer | immer | Name des Wirkstoffs |
dosage | string | immer | Menge |
timing | string | immer | Einnahmezeit als Schlüssel |
search_substances
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
conversationId | string 1 bis 64 | nein | im Entwurf: die Beratung mit dem Entwurf; genau eines von conversationId und planId |
planId | string 1 bis 64 | nein | am fertigen Plan: planId aus get_plan, braucht checkout:personalized; genau eines von conversationId und planId |
query | string ≤ 80 | ja | Name oder Teil des Namens; leer für Vorschläge |
Antwort
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
conversationId | string, nicht leer | optional | bei der Suche zum Entwurf: Kennung der Beratung |
planId | string 1 bis 64 | optional | bei der Suche zum fertigen Plan: Kennung des Plans |
query | string | immer | die Suche |
options | array ≤ 100 von Objekt | immer | passende Wirkstoffe, zuerst die Vorschläge |
options[].key | string 1 bis 80 | immer | Kennung für draftAdded im Entwurf oder für add_substance am fertigen Plan |
options[].name | string ≤ 256 | immer | Name des Wirkstoffs |
options[].dosage | string | optional | Menge; nur im Entwurf |
options[].timing | string | optional | Einnahmezeit als Schlüssel; nur im Entwurf |
options[].state | available, inPlan, blocked, noProducts | optional | nur am fertigen Plan: available lässt sich mit add_substance hinzufügen, inPlan steht schon im Plan, blocked lässt sich nicht hinzufügen, noProducts steckt in keinem Produkt der gewählten Marken |
options[].blockedReason | string ≤ 500 | optional, auch null | bei blocked: der Grund als Text der App |
moreCount | integer ab 0 | optional | nur am fertigen Plan: weitere Wirkstoffe, die sich über den Namen finden lassen |
get_plan_products
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
planId | string 1 bis 64 | ja | planId aus get_plan |
include | array ≤ 1 aus trust | nein | trust: dazu die festen Texte „Was wir prüfen“ und „So wählen wir die Sets“ der Planseite |
Antwort: Produkte zum Plan
Produkte zum Plan
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
planId | string 1 bis 64 | immer | Kennung des Plans |
status | ok, plan_not_final | immer | plan_not_final: Entwurf, positions ist leer |
positions | array ≤ 64 von Position | immer | je Planpunkt |
sets | Sets | optional | die zwei fertigen Sets der Planseite; als Auswahl anbieten, erst nach der Wahl des Mitglieds mit fill_cart_with_set in den Warenkorb |
brands | array ≤ 200 von Marke im Plan | optional | die Marken des Plans; Auswahl ändern mit set_brand_scope |
brandsEditable | boolean | optional | false: die Marken sind durch einen Link festgelegt und lassen sich nicht ändern |
shippingCountry | DE, AT | optional | Versandland, für das Preise der Sets und Summe des Warenkorbs gelten |
cart | Warenkorb | optional, auch null | was der Warenkorb des Plans jetzt enthält; null, solange er leer ist und nie gefüllt wurde |
shippingCountrySource | account, default | optional | account: das Mitglied hat das Versandland gesetzt; default: keines gesetzt, die Preise gelten für Deutschland |
trust | Texte der Planseite zu Prüfung und Sets | optional | nur mit include trust: die festen Texte der Planseite |
compliance | array von Pflichttext | optional | Pflichttexte einzeln: F4 und F5, ohne Freigaben F10, F6 zu den Werbelinks und F11 zur Rücksprache mit Arzt oder Apotheke |
Position
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
positionId | string 1 bis 128 | immer | Kennung des Planpunkts für add_to_cart |
supplementName | string ≤ 256 | immer | Wirkstoff |
dosage | string ≤ 512 | immer | Menge |
tier | string ≤ 16 | immer | basic oder plus |
products | array ≤ 12 von Planprodukt | immer | passende zuerst, heute höchstens 8 |
moreOnPlanPage | integer ab 0 | immer | weitere Produkte, die nur auf der Planseite stehen |
priority | boolean | optional | true: einer der drei wichtigsten Wirkstoffe (Stern) |
role | string ≤ 300 | optional | Satz der App zur Rolle des Wirkstoffs im Plan |
timing | string ≤ 300 | optional | Einnahmezeit in den Worten der App |
description | string ≤ 2000 | optional | wofür der Wirkstoff im Plan steht, geprüfter Text der App; fehlt, wenn der Text zurückgehalten wird |
traditional | boolean | optional | true: für den Wirkstoff liegt keine zugelassene gesundheitsbezogene Angabe vor; dann traditionalNote mit zeigen |
traditionalNote | string ≤ 300 | optional | bei traditional: der Satz der App dazu |
consultNotice | string ≤ 300 | optional | Pflichttext F11: vor der Einnahme mit Arzt oder Apotheke sprechen; mit dem Wirkstoff zeigen |
userAdded | boolean | optional | true: das Mitglied hat den Wirkstoff hinzugefügt; remove_substance nimmt ihn wieder heraus |
alreadyTaking | string ≤ 300 | optional | nur, wenn das Mitglied ihn schon nimmt: der Satz der App |
preferredForm | string ≤ 300 | optional | nur, wenn das Mitglied eine Darreichungsform bevorzugt: der Satz der App |
gapReason | string ≤ 2000 | optional | nur, wenn kein Produkt steht: der Grund wie in der App |
partnerRecommendation | string ≤ 2000 | optional | nur, wenn der Partner, über den das Mitglied kam, dafür ein Produkt außerhalb von Choicera empfiehlt: der Satz der App |
Sets
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
cheap | Set „Günstig“ | immer | Set „Günstig“: niedrigster Gesamtpreis mit Versand |
value | Set | immer | Set „Empfohlen“: das empfohlene Produkt je Wirkstoff |
Marke im Plan
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
brandId | string 1 bis 64 | immer | Kennung der Marke für set_brand_scope |
name | string ≤ 256 | immer | Name der Marke |
selected | boolean | immer | false: das Mitglied hat die Marke abgewählt, ihre Produkte fehlen im Plan |
disclosure | string ≤ 500 | optional | vollständiger Werbehinweis zu Links dieser Marke; mit ihren Produkten zeigen |
Warenkorb
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
lines | array ≤ 200 von Warenkorbzeile | immer | die Zeilen des Warenkorbs |
moreOnPlanPage | integer ab 0 | immer | weitere Zeilen, die nur die Planseite zeigt |
itemCount | integer ab 0 | immer | Zahl der Packungen |
total | number | immer | Summe |
currency | string ≤ 16 | immer | Währung |
set | cheap, value | immer, auch null | welches Set unverändert im Warenkorb liegt; null bei eigener Auswahl oder geändertem Set |
starOnly | boolean | optional | true: der Warenkorb enthält nur die drei wichtigsten Wirkstoffe des eingelegten Sets |
shops | array ≤ 64 von Kosten je Shop | optional | Kosten je Shop wie im Warenkorb der Planseite |
discountTotal | number | optional | Summe der Nachlässe |
shippingUnknown | boolean | optional | true: mindestens ein Shop nennt keine Versandkosten; es gilt der Preis des Shops |
priceNote | string ≤ 300 | optional | Hinweis der App zu den Preisen |
Texte der Planseite zu Prüfung und Sets
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
checks | Objekt | immer | Text „Was wir prüfen“ |
checks.title | string ≤ 300 | immer | Überschrift |
checks.sections | array ≤ 6 von Textabschnitt | immer | Abschnitte |
checks.closing | string ≤ 300 | immer | Schlusssatz |
sets | Objekt | immer | Text „So wählen wir die Sets“ |
sets.title | string ≤ 300 | immer | Überschrift |
sets.sections | array ≤ 6 von Textabschnitt | immer | Abschnitte |
sets.footer | string ≤ 300 | immer | Satz unter den Abschnitten |
Planprodukt
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
productId | string 1 bis 64 | immer | Produkt-Kennung für add_to_cart |
brand | string ≤ 256 | immer | Name der Marke |
title | string ≤ 512 | immer | Produktname |
defaultVariantId | string 1 bis 128 | immer | vorgeschlagene Variante |
variants | array 1 bis 32 von Planvariante | immer | nur lieferbare Varianten |
badges | array ≤ 4 von string ≤ 32 | immer | heute cheapest oder recommended; leer bei weniger passenden |
lessFitting | boolean | immer | true: passt weniger gut |
needsConfirmation | boolean | immer | true: nur nach ausdrücklicher Bestätigung des Warnhinweises in den Warenkorb |
warnings | array ≤ 16 von Objekt | immer | mit dem Produkt zeigen |
warnings[].code | string 1 bis 64 | immer | Kennung des Hinweises |
warnings[].level | hint, warn | immer | Stufe des Hinweises |
warnings[].text | string 1 bis 500 | immer | Text des Hinweises |
alternativeFor | string ≤ 256 | immer, auch null | Wirkstoff, für den das Produkt als Ausweichprodukt dasteht |
alsoCovers | array ≤ 16 von string ≤ 256 | immer | weitere Wirkstoffe des Plans, die das Produkt abdeckt |
formFactor | string ≤ 64 | optional, auch null | Darreichungsform laut Marke, etwa capsule |
dietCompatibility | array ≤ 16 von string ≤ 64 | optional | Ernährungsformen laut Marke, etwa vegan |
origin | string ≤ 256 | optional, auch null | Herstellungsort laut Marke |
fit | full, near, low | optional | wie gut eine Portion die Menge deckt: full, near (knapp darunter) oder low |
servingsPerDay | integer größer 0 | optional | Portionen am Tag für die Menge des Plans |
fitText | string ≤ 300 | optional | Satz der App zur Passung |
monthlyText | string ≤ 300 | optional | Monatspreis der vorgeschlagenen Variante wie in der App |
alternativeText | string ≤ 300 | optional | nur bei einer anderen Form des Wirkstoffs: der Satz der App |
caffeineText | string ≤ 300 | optional | nur, wenn das Produkt Koffein enthält: der Satz der App |
recommendedBy | string ≤ 300 | optional | nur, wenn der Partner, über den das Mitglied kam, das Produkt empfiehlt |
adLabel | string ≤ 64 | optional | Kennzeichnung der App neben einem Produkt, an dem Choicera eine Provision verdienen kann; der volle Hinweis steht in brands[].disclosure |
Set „Günstig“
Alle Felder von Set, dazu:
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
sameAsValue | boolean | immer | true: dieselben Produkte wie im Set „Empfohlen“; dann nur „Empfohlen“ anbieten |
Set
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
label | string 1 bis 64 | immer | Name des Sets auf der Planseite |
description | string 1 bis 256 | immer | wie die Planseite das Set wählt, Text der App |
lines | array ≤ 64 von Setzeile | immer | je ein Produkt für jeden Basis-Wirkstoff und jeden selbst hinzugefügten Wirkstoff; Plus-Wirkstoffe gehören nicht dazu |
total | number | immer, auch null | Preis des Sets mit Versand und Rabatten der Marken, wie die Planseite ihn zeigt; null ohne Zeilen |
currency | string ≤ 16 | immer, auch null | Währung |
starOnly | Objekt | optional | nur die drei wichtigsten und die selbst hinzugefügten Wirkstoffe aus diesem Set, wie der Schalter der Planseite; mit starOnly an fill_cart_with_set |
starOnly.lines | array ≤ 64 von Objekt | immer | die Zeilen |
starOnly.lines[].positionId | string 1 bis 128 | immer | Planpunkt |
starOnly.lines[].productId | string 1 bis 64 | immer | Produkt |
starOnly.lines[].variantId | string 1 bis 128 | immer | Variante |
starOnly.total | number | immer, auch null | Preis wie auf der Planseite; null ohne Zeilen |
starOnly.currency | string ≤ 16 | immer, auch null | Währung |
Warenkorbzeile
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
positionId | string 1 bis 128 | immer | Planpunkt |
productId | string 1 bis 64 | immer | Produkt |
variantId | string 1 bis 128 | immer | Variante |
lineId | string 1 bis 64 | immer | Kennung der Zeile für update_cart_line |
brand | string ≤ 256 | immer | Name der Marke |
title | string ≤ 512 | immer | Produktname |
variantTitle | string ≤ 512 | immer, auch null | Name der Variante |
quantity | integer größer 0 | immer | Zahl der Packungen |
unitPrice | number | immer | Preis je Packung |
Kosten je Shop
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
brandId | string 1 bis 64 | immer | Kennung der Marke |
brand | string ≤ 256 | immer | Name der Marke |
itemCount | integer ab 0 | immer | Zahl der Packungen |
subtotal | number | immer | Zwischensumme |
discount | number | immer, auch null | Nachlass durch das Angebot der Marke; null ohne Angebot |
discountText | string ≤ 300 | immer, auch null | das Angebot in den Worten der App; null ohne Angebot |
shipping | number | immer, auch null | Versandkosten; null, wenn der Shop keine nennt |
shippingText | string ≤ 300 | immer | Versandkosten in den Worten der App |
freeShippingText | string ≤ 300 | immer, auch null | wie weit der Warenkorb vom kostenlosen Versand entfernt ist |
total | number | immer | Summe des Shops |
Textabschnitt
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
title | string ≤ 300 | immer | Überschrift des Abschnitts |
lines | array ≤ 12 von string ≤ 300 | immer | Zeilen des Abschnitts |
Planvariante
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
variantId | string 1 bis 128 | immer | Varianten-Kennung für add_to_cart |
title | string ≤ 512 | immer | Name der Variante |
flavor | string ≤ 256 | immer, auch null | Geschmack; null, wenn das Produkt keinen hat |
containerSize | number | immer, auch null | Packungsgröße in containerUnit; null, wenn der Shop keine nennt; nie schätzen |
containerUnit | string ≤ 32 | immer, auch null | Einheit der Packungsgröße |
price | number | immer, auch null | Preis |
currency | string ≤ 16 | immer | Währung |
monthlyPrice | number | optional, auch null | Monatspreis der Variante bei der Menge des Plans |
basePrice | Grundpreis | optional | Grundpreis; im selben Satz wie den Preis zeigen |
Setzeile
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
positionId | string 1 bis 128 | immer | Planpunkt |
productId | string 1 bis 64 | immer | Produkt |
variantId | string 1 bis 128 | immer | Variante |
brand | string ≤ 256 | immer | Name der Marke |
title | string ≤ 512 | immer | Produktname |
price | number | immer, auch null | Preis |
add_to_cart
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
planId | string 1 bis 64 | ja | planId aus get_plan |
items | array 1 bis 20 von Objekt | ja | die Produkte, die das Mitglied gewählt hat |
items[].positionId | string 1 bis 128 | ja | aus get_plan_products |
items[].productId | string 1 bis 64 | ja | aus get_plan_products |
items[].variantId | string 1 bis 128 | ja | aus get_plan_products |
items[].quantity | integer 1 bis 20 | nein | Zahl der Packungen, Standard 1 |
items[].confirmWarning | boolean | nein | nur nach ausdrücklicher Bestätigung des Warnhinweises im Chat |
Antwort
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
planId | string 1 bis 64 | immer | Kennung des Plans |
status | ok, plan_not_final | immer | Stand des Plans wie bei get_plan_products |
added | array ≤ 20 von Objekt | immer | hinzugefügt |
added[].positionId | string 1 bis 128 | immer | Planpunkt |
added[].productId | string 1 bis 64 | immer | Produkt |
added[].variantId | string 1 bis 128 | immer | Variante |
added[].quantity | integer größer 0 | immer | Zahl der Packungen |
added[].lineId | string 1 bis 64 | optional | Kennung der Zeile für update_cart_line |
needsConfirmation | array ≤ 20 von Objekt | immer | nicht hinzugefügt: der Warnhinweis braucht die Bestätigung des Mitglieds |
needsConfirmation[].positionId | string 1 bis 128 | immer | Planpunkt |
needsConfirmation[].productId | string 1 bis 64 | immer | Produkt |
needsConfirmation[].variantId | string 1 bis 128 | immer | Variante |
needsConfirmation[].reasonCodes | array ≤ 16 von string ≤ 64 | immer | Gründe als Kennungen |
rejected | array ≤ 20 von Objekt | immer | nicht hinzugefügt |
rejected[].positionId | string 1 bis 128 | immer | Planpunkt |
rejected[].productId | string 1 bis 64 | immer | Produkt |
rejected[].variantId | string 1 bis 128 | immer | Variante |
rejected[].reason | string 1 bis 64 | immer | Grund, etwa not_in_offer, rate_limited, upstream_error |
cart | Warenkorbsumme | immer, auch null | Stand des Warenkorbs |
Warenkorbsumme
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
itemCount | integer ab 0 | immer | Zahl der Packungen |
total | number | immer | Summe |
currency | string ≤ 16 | immer | Währung |
get_checkout_link
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
planId | string 1 bis 64 | nein | Kennung des Plans; genau eines von planId und productId |
productId | string 1 bis 64 | nein | Produkt-Kennung aus dem Katalog; genau eines von planId und productId |
Antwort
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
mode | personalized, catalog | immer | personalized mit planId, catalog mit productId |
links | array von Link | immer | mit planId genau ein Link, in die Kasse oder zur Planseite (siehe target); mit productId die Links in den Shop der Marke |
reason | catalog_links_empty | optional | catalog_links_empty: der Shop der Marke bietet für das Produkt gerade keinen Link; links ist dann leer |
target | checkout, plan_page | optional | nur mit planId: checkout, wenn alle Verkäufer des Warenkorbs an der Kasse von Choicera bezahlt werden; der Link öffnet dann die Kasse bei „Bestellung prüfen“, ohne Adresse aus einer früheren Bestellung zuerst bei der Adresse; sonst plan_page |
order | Warenkorb zum Bestellen | optional | nur mit planId: der Warenkorb, wie er bestellt würde; fehlt bei leerem Warenkorb und bei einem Entwurf |
compliance | array von Pflichttext | optional | F6 je Link, dazu F7 (Gutschein) und F8 (Preis), wenn sie dazugehören |
Link
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
brand | string | immer, auch null | Name der Marke; null beim Link zur Planseite oder in die Kasse |
brandSlug | string | immer, auch null | Kennung der Marke |
url | string, nicht leer | immer | die Adresse; unverändert weitergeben |
notice | string | immer, auch null | Hinweis des Shops |
display | string, nicht leer | optional | Link mit Pflichttexten, fertig zum Anzeigen; zeige ihn statt url |
Warenkorb zum Bestellen
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
lines | array ≤ 200 von Zeile zum Bestellen | immer | die Zeilen des Warenkorbs |
hiddenLines | integer ab 0 | immer | weitere Zeilen, die diese Verbindung nicht nennt, weil ihr Warnhinweis Medikamente, Schwangerschaft oder Stillzeit betrifft; die verlinkte Seite zeigt sie |
sellers | array ≤ 64 von Verkäufer im Warenkorb | immer | je Verkäufer ein Eintrag mit Zahlweg und Kosten |
shipping | number | immer, auch null | Versand aller Verkäufer zusammen; null, wenn ein Verkäufer keine Versandkosten nennt |
total | number | immer | Gesamtpreis mit den Nachlässen der Marken und Versand |
currency | string ≤ 16 | immer | Währung |
priceNote | string ≤ 300 | immer | Hinweis der App zu den Preisen, wie ihr Warenkorb ihn neben der Summe zeigt |
Zeile zum Bestellen
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
brand | string ≤ 256 | immer | Name der Marke |
title | string ≤ 512 | immer | Produktname |
variantTitle | string ≤ 512 | immer, auch null | Name der Variante |
quantity | integer größer 0 | immer | Zahl der Packungen |
unitPrice | number | immer | Preis je Packung |
basePrice | Grundpreis | optional | Grundpreis; im selben Satz wie den Preis zeigen; fehlt, wenn der Shop keine Füllmenge nennt |
Verkäufer im Warenkorb
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
brandId | string 1 bis 64 | immer | Kennung der Marke |
seller | string ≤ 256 | immer | Name der Marke, die verkauft und versendet |
paymentPath | shop, checkout | immer | checkout: bezahlt an der Kasse von Choicera; shop: bestellt und bezahlt im Shop der Marke |
itemCount | integer ab 0 | immer | Zahl der Packungen |
subtotal | number | immer | Zwischensumme |
discount | number | immer, auch null | Nachlass durch das Angebot der Marke; null ohne Angebot |
shipping | number | immer, auch null | Versandkosten; null, wenn der Verkäufer keine nennt |
total | number | immer | Summe des Verkäufers |
fill_cart_with_set
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
planId | string 1 bis 64 | ja | planId aus get_plan |
set | cheap, value | ja | das Set, das das Mitglied gewählt hat |
starOnly | true | nein | true: nur die drei wichtigsten und die selbst hinzugefügten Wirkstoffe, aus sets.<set>.starOnly |
Antwort
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
planId | string 1 bis 64 | immer | Kennung des Plans |
set | cheap, value | immer | das eingelegte Set |
starOnly | boolean | optional | true: nur die drei wichtigsten und die selbst hinzugefügten Wirkstoffe sind eingelegt |
placed | array ≤ 64 von Objekt | immer | die Produkte des Sets, jetzt im Warenkorb; sonst liegt nichts darin |
placed[].positionId | string 1 bis 128 | immer | Planpunkt |
placed[].productId | string 1 bis 64 | immer | Produkt |
placed[].variantId | string 1 bis 128 | immer | Variante |
placed[].brand | string ≤ 256 | immer | Name der Marke |
placed[].title | string ≤ 512 | immer | Produktname |
placed[].price | number | immer, auch null | Preis |
placed[].lineId | string 1 bis 64 | optional | Kennung der Zeile für update_cart_line |
cart | Warenkorbsumme | immer, auch null | Stand des Warenkorbs |
update_cart_line
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
planId | string 1 bis 64 | ja | planId aus get_plan |
lineId | string 1 bis 64 | ja | lineId der Zeile aus cart.lines oder added |
quantity | integer 0 bis 20 | ja | gewünschte Zahl der Packungen; 0 nimmt das Produkt aus dem Warenkorb |
Antwort
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
planId | string 1 bis 64 | immer | Kennung des Plans |
lineId | string 1 bis 64 | immer | Kennung der Zeile |
quantity | integer ab 0 | immer | Zahl der Packungen jetzt; 0: die Zeile ist entfernt |
cart | Warenkorbsumme | immer, auch null | Stand des Warenkorbs |
add_substance
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
planId | string 1 bis 64 | ja | planId aus get_plan |
key | string 1 bis 80 | ja | key einer Option mit state: available aus search_substances mit planId |
Antwort: Produkte zum Plan mit neuem Wirkstoff
Produkte zum Plan mit neuem Wirkstoff
Alle Felder von Produkte zum Plan, dazu:
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
positionId | string 1 bis 128 | immer | Planpunkt des neu hinzugefügten Wirkstoffs |
set_brand_scope
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
planId | string 1 bis 64 | ja | planId aus get_plan |
deselectedBrandIds | array ≤ 100 von string 1 bis 64 | ja | alle brandIds, die das Mitglied nicht will, auch früher abgewählte; eine leere Liste wählt alle Marken wieder |
Antwort: Produkte zum Plan
remove_substance
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
planId | string 1 bis 64 | ja | planId aus get_plan |
positionId | string 1 bis 128 | ja | positionId eines Wirkstoffs mit userAdded: true aus get_plan_products |
Antwort: Produkte zum Plan ohne den Wirkstoff
Produkte zum Plan ohne den Wirkstoff
Alle Felder von Produkte zum Plan, dazu:
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
removedPositionId | string 1 bis 128 | immer | Planpunkt des herausgenommenen Wirkstoffs |
set_shipping_country
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
planId | string 1 bis 64 | ja | planId aus get_plan |
country | DE, AT | ja | Land, in das das Mitglied liefern lassen will |
Antwort: Produkte zum Plan nach neuem Versandland
Produkte zum Plan nach neuem Versandland
Alle Felder von Produkte zum Plan, dazu:
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
recomposed | boolean | immer | true: im Warenkorb lag das Set „Günstig“; es ist für das neue Land neu zusammengestellt, wie auf der Planseite |
get_position_products
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
planId | string 1 bis 64 | ja | planId aus get_plan |
positionId | string 1 bis 128 | ja | positionId aus get_plan_products |
sort | recommended, price | nein | recommended (Standard) wie auf der Planseite oder price |
form | capsule, tablet, powder, liquid, sachet | nein | nur Produkte in dieser Darreichungsform |
diet | vegan, vegetarian, organic, gluten-free, lactose-free, sugar-free | nein | nur Produkte, die laut Marke zu dieser Ernährungsform passen |
wide | true | nein | nur bei einem Wirkstoff mit gapReason und brandsEditable: true: in allen Marken suchen, wie die Planseite |
Antwort
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
planId | string 1 bis 64 | immer | Kennung des Plans |
positionId | string 1 bis 128 | immer | Planpunkt |
supplementName | string ≤ 256 | immer | Wirkstoff |
wide | boolean | immer | true: die Produkte kommen aus allen Marken, nicht nur aus denen des Plans |
products | array ≤ 30 von Planprodukt | immer | die Produkte des Planpunkts |
moreOnPlanPage | integer ab 0 | immer | weitere passende Produkte, die nur auf der Planseite stehen |
compliance | array von Pflichttext | optional | Pflichttexte einzeln |
rate_plan
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
planId | string 1 bis 64 | ja | planId des fertigen Plans aus get_plan |
stars | integer 1 bis 5 | ja | die Sterne, die das Mitglied vergibt, 1 bis 5 |
reasonCodes | array ≤ 4 aus not_for_me, too_many_products, too_expensive, other | nein | nur bei 1 bis 3 Sternen: die Gründe, die das Mitglied aus der Liste der App wählt, not_for_me, too_many_products, too_expensive, other |
comment | string ≤ 500 | nein | was das Mitglied zum Plan schreibt, in seinen Worten; Medikamente nur mit advisor:medication, Schwangerschaft und Stillzeit nur mit advisor:maternal |
Antwort
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
planId | string, nicht leer | immer | Kennung des Plans |
stars | integer 1 bis 5 | immer | die gespeicherten Sterne |
rate_message
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
messageId | string | ja | messageId der Antwort aus start_consultation, send_message oder answer_intake |
rating | up, down, none | ja | up oder down; none nimmt den Daumen des Mitglieds zurück |
Antwort
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
messageId | string, nicht leer | immer | Kennung der Antwort |
rating | up, down, none | immer | der gespeicherte Daumen; none: kein Daumen gespeichert |
list_consultations
Eingabe: keine.
Antwort
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
consultations | array ≤ 20 von Beratung | immer | eigene Beratungen, neueste zuerst, höchstens 20; Beratungen mit Inhalten, die diese Verbindung nicht sehen darf, fehlen ganz |
Beratung
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
conversationId | string 1 bis 64 | immer | Kennung der Beratung, für get_consultation, send_message und get_plan |
startedAt | string | immer | Beginn als ISO-Zeitpunkt |
lastActivityAt | string | immer | letzte Nachricht des Mitglieds oder der Beratung als ISO-Zeitpunkt |
status | gathering_info, analyzing, plan_generated, refining_intake, refining, completed | immer | Stand des Gesprächs: gathering_info, analyzing (der Plan entsteht), plan_generated, refining_intake, refining oder completed |
goals | array ≤ 20 von Objekt | immer | Ziele der Beratung |
goals[].slug | string 1 bis 64 | immer | Kennung wie in get_goals |
goals[].name | string 1 bis 120 | immer | Name des Ziels in der Sprache der Antwort |
topic | Objekt | immer, auch null | Thema, mit dem die Beratung begann; null ohne Thema |
topic.slug | string 1 bis 128 | immer | Kennung wie in list_topics |
topic.name | string 1 bis 200 | immer | Name des Themas in der Sprache der Antwort |
hasPlan | boolean | immer | true: zur Beratung gibt es einen Plan |
channel | agent, app | immer | agent: über eine KI begonnen, app: in der App begonnen |
resumable | boolean | immer | true: geht hier weiter; dieselben Beratungen, die die App zum Weitermachen anbietet |
resumeHint | continue_in_app | optional | continue_in_app: das Mitglied findet die Beratung in der App; sie geht hier nicht weiter |
get_consultation
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
conversationId | string 1 bis 64 | ja | aus list_consultations oder start_consultation |
Antwort: Beratung mit offener Frage
Beratung mit offener Frage
Alle Felder von Beratung, dazu:
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
planId | string 1 bis 64 | optional | Kennung des Plans, für get_plan_products und get_checkout_link; fehlt ohne Plan |
reply | Antwort der Beratung | optional | offene Frage oder letzte Antwort der Beratung wie bei send_message; ready_to_generate auch bei offenem Entwurf; fehlt, wenn hier nichts weiterzugeben ist |
compliance | array von Pflichttext | optional | die Pflichttexte einzeln; sie stehen auch am Ende von reply.text |
get_profile
Eingabe: keine.
Antwort
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
profileVersion | string 1 bis 64 | immer, auch null | Stand der gespeicherten Angaben, für confirm_profile; null, wenn nichts gespeichert ist |
demographics | Objekt | immer | Körperwerte wie in der App |
demographics.gender | string ≤ 32 | immer, auch null | Geschlecht; null ohne Angabe |
demographics.ageRange | string ≤ 32 | immer, auch null | Altersspanne; null ohne Angabe |
demographics.weightKg | number größer 0 | immer, auch null | Gewicht in kg; null ohne Angabe |
demographics.heightCm | number größer 0 | immer, auch null | Größe in cm; null ohne Angabe |
demographics.confirmedAt | string | immer, auch null | letzte Bestätigung durch das Mitglied als ISO-Zeitpunkt; null, wenn nie bestätigt |
demographics.daysSinceConfirmed | integer | immer, auch null | Tage seit der letzten Bestätigung; null, wenn nie bestätigt |
demographics.isStale | boolean | immer | true ab 300 Tagen oder ohne Bestätigung: die App würde fragen, ob die Angaben noch stimmen |
diet | array ≤ 20 von string 1 bis 64 | immer | angegebene Ernährungsformen, etwa vegan |
allergies | array ≤ 30 von string 1 bis 64 | immer | angegebene Allergien |
existingSupplements | string ≤ 2000 | immer, auch null | Präparate, die das Mitglied schon nimmt; null ohne Angabe |
formPreference | string ≤ 64 | immer, auch null | bevorzugte Darreichungsform; null ohne Angabe |
sportPreferences | Objekt | immer | Antworten aus dem Formular zur Sportnahrung; leer ohne Antworten |
sportPreferences.protein | any, lactose_free, plant_only | optional | Eiweißquelle |
sportPreferences.texture | any, creamy, clear | optional | Konsistenz |
sportPreferences.sweetness | any, no_artificial, unsweetened | optional | Süße |
sportPreferences.form | powder_ok, capsule_tablet | optional | Darreichungsform |
sportPreferences.caffeine | without, with | optional | Koffein |
medication | Objekt | optional | nur mit advisor:medication: gespeicherte Medikamente |
medication.drugClasses | array ≤ 16 von string 1 bis 64 | immer | Medikamentenklassen wie im Formular |
medication.freetext | string ≤ 2000 | immer, auch null | eigene Worte des Mitglieds; null ohne |
medication.recognizedDrugClasses | array ≤ 16 von string 1 bis 64 | immer | Klassen, die Choicera im Freitext erkennt |
medication.confirmedAt | string | immer, auch null | letzte Bestätigung durch das Mitglied als ISO-Zeitpunkt; null, wenn nie bestätigt |
medication.daysSinceConfirmed | integer | immer, auch null | Tage seit der letzten Bestätigung; null, wenn nie bestätigt |
medication.isStale | boolean | immer | true ab 90 Tagen oder ohne Bestätigung, wenn Medikamente gespeichert sind |
maternal | Objekt | optional | nur mit advisor:maternal: Schwangerschaft oder Stillzeit |
maternal.lifeStage | string ≤ 32 | immer, auch null | pregnant oder lactating; null ohne Angabe |
maternal.trimester | integer 1 bis 3 | immer, auch null | Schwangerschaftsdrittel 1 bis 3; null ohne Angabe |
maternal.confirmedAt | string | immer, auch null | letzte Bestätigung durch das Mitglied als ISO-Zeitpunkt; null, wenn nie bestätigt |
maternal.daysSinceConfirmed | integer | immer, auch null | Tage seit der letzten Bestätigung; null, wenn nie bestätigt |
maternal.isStale | boolean | immer | true ab 90 Tagen oder ohne Bestätigung |
confirm_profile
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
facets | array 1 bis 3 aus demographics, medication, maternal | ja | Teile, denen das Mitglied zugestimmt hat: demographics, mit advisor:medication auch medication, mit advisor:maternal auch maternal |
profileVersion | string 1 bis 64 | ja | profileVersion aus der get_profile-Antwort, die das Mitglied gesehen hat |
Antwort
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
confirmed | array 1 bis 3 aus demographics, medication, maternal | immer | die jetzt bestätigten Teile |
confirmedAt | string | immer | Zeitpunkt der Bestätigung |
profileVersion | string 1 bis 64 | immer | neuer Stand der Angaben, für ein weiteres confirm_profile |
get_orders
Eingabe
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
orderNumber | string 1 bis 32 | nein | eine Bestellnummer des Mitglieds, etwa aus der Bestellmail; ohne sie die neuesten Bestellungen |
Antwort
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
orders | array ≤ 20 von Bestellung | immer | eigene Bestellungen an der Kasse, neueste zuerst, höchstens 20, auch mit offener Zahlung; fehlgeschlagene und abgelaufene Zahlungen fehlen |
ordersUrl | string, nicht leer | immer | Seite der App mit den bezahlten und stornierten Bestellungen; eine Bestellung mit offener Zahlung steht dort noch nicht; ohne Sitzung im Browser kommt zuerst die Anmeldung |
Bestellung
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
orderNumber | string 1 bis 32 | immer | Bestellnummer wie in der Bestellmail und in der App, Eingabe für get_orders |
orderedAt | string | immer | Zeitpunkt der Bestellung als ISO-Zeitpunkt |
payment | paid, pending, cancelled | immer | paid: Zahlung bestätigt; pending: der Zahlungsdienst hat sie noch nicht bestätigt; cancelled: storniert |
total | number | immer | Gesamtbetrag mit Versand |
currency | string ≤ 16 | immer | Währung |
sellers | array ≤ 64 von Teil einer Bestellung | immer | je Verkäufer ein Teil der Bestellung |
Teil einer Bestellung
| Feld | Typ | Vorhanden | Bedeutung |
|---|---|---|---|
seller | string ≤ 256 | immer | Name der Marke, die verkauft und versendet |
itemCount | integer ab 0 | immer | Zahl der Packungen |
amount | number | immer | Betrag des Verkäufers mit Versand |
delivery | ordered, shipped, cancelled, refunded, withdrawn, undeliverable | immer | ordered: noch nicht versandt; shipped: dem Versand übergeben; cancelled: storniert; refunded: erstattet; withdrawn: vom Kunden vor dem Versand widerrufen, stornierte Ware kostet ihn nichts; undeliverable: das Paket war nicht zustellbar und geht zur Marke zurück, der Kunde bekommt sein Geld zurück oder zahlt nichts, wenn noch nichts abgebucht war |
expectedDelivery | Objekt | immer, auch null | erwartetes Lieferfenster; null nach der Zustellung, solange die Zahlung offen ist oder ohne Lieferzeit des Verkäufers |
expectedDelivery.earliest | string ≤ 10 | immer | erster Tag, JJJJ-MM-TT |
expectedDelivery.latest | string ≤ 10 | immer | letzter Tag, JJJJ-MM-TT |
deliveredAt | string | immer, auch null | Zustellung als ISO-Zeitpunkt; null davor |
trackingUrl | string ≤ 2048 | immer, auch null | Seite der Sendungsverfolgung; null ohne |
Beispiele
Katalog: von der Suche zum Produkt
Ohne Konto, mit curl:
curl -s https://choicera.com/agent/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_products","arguments":{"query":"magnesium","limit":1}}}'structuredContent der Antwort hat den Aufbau {"products":[<Katalogprodukt>],"total":<Zahl>,"limit":1,"offset":0,"matchMode":"all"}. Der Treffer in products[0] ist die schlanke Form aus der Feldreferenz, mit matchReasons.
Danach ein Produkt im Einzelnen, hier als Beispiel:
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_product","arguments":{"productId":"4087c20a-c60f-4050-b3d9-86f530242f9b"}}}Antwort des Servers, Inhalt von structuredContent (Stand November 2026):
{
"id": "4087c20a-c60f-4050-b3d9-86f530242f9b",
"title": "Acerola Vitamin C (120 Lutschtabletten)",
"sourceLanguage": "de",
"brand": { "id": "3d89bd07-0724-41e0-91de-42ab539ab8be", "slug": "lifelight", "name": "Life Light", "color": "#007ab3", "logoUrl": "https://choicera.com/brand-logos/lifelight.webp?v=1" },
"price": 20.8,
"currency": "EUR",
"basePrice": { "amount": 173.33, "amountLabel": "173,33", "unit": "kg" },
"imageUrl": "https://choicera.com/product-images/4087c20a-c60f-4050-b3d9-86f530242f9b.webp?v=d4172c6a83d9",
"productUrl": "https://choicera.com/go/4087c20a-c60f-4050-b3d9-86f530242f9b?c=agent",
"productUrlDisplay": "Life Light: https://choicera.com/go/4087c20a-c60f-4050-b3d9-86f530242f9b?c=agent\n\nWerbelink: Choicera kann bei einem Kauf über diesen Link eine Provision vom Partnershop erhalten. Choicera vermittelt ausschließlich Produkte seiner Partnermarken.",
"compliance": [
{ "id": "F6", "text": "Werbelink: Choicera kann bei einem Kauf über diesen Link eine Provision vom Partnershop erhalten. Choicera vermittelt ausschließlich Produkte seiner Partnermarken.", "trigger": "buy_link:4087c20a-c60f-4050-b3d9-86f530242f9b" },
{ "id": "F8", "text": "Preisangabe: Gesamtpreis 20,80 €; Grundpreis 173,33 €/kg.", "trigger": "price:4087c20a-c60f-4050-b3d9-86f530242f9b" }
],
"formFactor": "tablet",
"servingSizeDisplay": "2 Tabletten",
"servingsPerContainer": 60,
"dosageText": "Täglich 2 Tabletten im Mund lutschen.",
"strengthPerServing": "200 mg",
"servingUnit": "Tabletten",
"pricePerServing": 0.3467,
"primaryIngredients": ["Vitamin C", "Vitamin C aus Acerola-Kirschen", "Acerola-Kirschen", "Acerola Fruchtsaft Pulver", "Traubenzucker", "Magnesiumsalze der Speisefettsäuren"],
"dietCompatibility": [],
"allergens": [],
"minAgeYears": null,
"maxAgeYears": null,
"intakeAdvice": "Täglich 2 Tabletten im Mund lutschen.",
"warnings": null,
"pzn": null,
"servingIntervalDays": 1,
"ingredientsDeclaration": ["Acerola-Fruchtsaftpulver 56%", "Traubenzucker", "Trennmittel: Stearinsäure", "Magnesiumsalze der Speisefettsäuren", "Kirscharoma", "Süßungsmittel: Steviolgylcoside"],
"variants": [
{ "id": "e1c446b4-7cbd-49fa-8cb8-75f75d63a1d7", "title": "Standard", "position": 1, "containerSize": null, "containerUnit": null, "price": 20.8, "basePrice": { "amount": 173.33, "amountLabel": "173,33", "unit": "kg" }, "available": true, "imageUrl": null, "servingSizeMin": null, "servingSizeMax": null, "servingSizeUnit": null, "servingsPerContainerMin": null, "servingsPerContainerMax": null, "flavor": null }
],
"substanceDescription": "Vitamin C ist ein wasserlösliches Vitamin, das in vielen Obst- und Gemüsesorten vorkommt."
}So zeigst du es: Titel und Marke; Preis mit Grundpreis in einem Satz („20,80 € (173,33 €/kg)“) und daneben den F8-Text aus compliance; statt der nackten Adresse productUrlDisplay vollständig. Bestellt wird über productUrl im Shop der Marke.
Beratung: Folge der Aufrufe
Skizze mit Konto (Token mit advisor checkout:personalized offline_access). Gezeigt sind die params von tools/call und was in der Antwort zählt; Kennungen und Werte sind Beispiele, die vollständigen Felder stehen in der Feldreferenz.
| Schritt | Aufruf | Antwort | Dein Agent |
|---|---|---|---|
| 1 | {"name":"start_consultation","arguments":{"goalSlugs":["sleep-relaxation"],"message":"Ich komme abends schlecht zur Ruhe."}} | conversationId cmhq8x2k40001abcd, status gathering_info, reply.type question mit options und freeText: true | reply.text vollständig zeigen, Optionen als Auswahl |
| 2 | {"name":"send_message","arguments":{"conversationId":"cmhq8x2k40001abcd","message":"Länger als 30 Minuten"}} | reply.type demographic_intake, reply.form.kind demographics | Felder einzeln abfragen |
| 3 | {"name":"answer_intake","arguments":{"conversationId":"cmhq8x2k40001abcd","kind":"demographics","demographics":{"gender":"female","ageBracket":"30_44","weightBracket":"60_75"}}} | reply.type question oder message | weiterreichen; Schritte 2 und 3 wiederholen sich, bis ready_to_generate |
| 4 | {"name":"get_plan","arguments":{"conversationId":"cmhq8x2k40001abcd"}} | status pending, jobId job_7f3c, retryAfterSeconds 5 | 5 Sekunden warten |
| 5 | {"name":"get_plan","arguments":{"conversationId":"cmhq8x2k40001abcd","jobId":"job_7f3c"}} | status draft_review, plan und draft.rows | Entwurf zeigen, Zeile für Zeile fragen |
| 6 | {"name":"search_substances","arguments":{"conversationId":"cmhq8x2k40001abcd","query":"zink"}} | options mit key zinc | nur, wenn das Mitglied etwas hinzufügen will |
| 7 | {"name":"get_plan","arguments":{"conversationId":"cmhq8x2k40001abcd","draftFeedback":[{"key":"magnesium","feedback":"preferred_form","form":"capsule"}],"draftAdded":["zinc"]}} | je nach Beratung pending, refining_intake (dann reply wie bei send_message) oder completed | bis completed weiter wie in Plan erzeugen |
| 8 | (bei completed) | plan.planId cmhqa4d2s000blmno, plan.phases, disclosure | Plan mit disclosure vollständig zeigen |
| 9 | {"name":"get_plan_products","arguments":{"planId":"cmhqa4d2s000blmno"}} | status ok, positions mit products | Produkte mit warnings und Grundpreis zeigen, Mitglied wählen lassen |
| 10 | {"name":"add_to_cart","arguments":{"planId":"cmhqa4d2s000blmno","items":[{"positionId":"pos_magnesium","productId":"b1e0c7a2-0000-4000-8000-000000000001","variantId":"v_120","quantity":1}]}} | added, needsConfirmation, rejected, cart | Ergebnis nennen; Zeilen in needsConfirmation erst nach Bestätigung erneut senden |
| 11 | {"name":"get_checkout_link","arguments":{"planId":"cmhqa4d2s000blmno"}} | mode personalized, order mit Zeilen, Verkäufern, Versand und Gesamtpreis; target checkout mit links[0].url https://choicera.com/supps/checkout?plan=cmhqa4d2s000blmno&step=review&via=ai, sonst plan_page mit https://choicera.com/supps/plan?conv=cmhq8x2k40001abcd; links[0].display | Warenkorb aus order zeigen, dann links[0].display vollständig |
| 12 | {"name":"get_orders","arguments":{}} | orders[0].orderNumber C7K2M9P4QXR, orders[0].payment paid, je Verkäufer delivery | wenn das Mitglied zurückkommt: Bestellnummer, Zahlstand und Versandstand nennen |
Zum Vergleich, eine vollständige Antwort aus Schritt 1 (Beispielwerte, Aufbau nach Schema, ohne die Freigaben für Medikamente und Schwangerschaft):
{
"conversationId": "cmhq8x2k40001abcd",
"status": "gathering_info",
"reply": {
"type": "question",
"text": "Wie lange brauchst du meistens zum Einschlafen?\n\nDiese Empfehlung wurde automatisiert durch das KI-System von Choicera erstellt.\n\nDies ist keine medizinische Beratung und ersetzt keine ärztliche oder apothekerliche Beratung. Bei bestehenden Erkrankungen, Medikamenteneinnahme, Schwangerschaft oder Stillzeit hole vor der Einnahme ärztlichen Rat ein.\n\nWechselwirkungen mit Medikamenten konnten nicht geprüft werden\n\nEignung bei Schwangerschaft/Stillzeit nicht geprüft",
"options": [
{ "label": "Unter 15 Minuten", "value": "Unter 15 Minuten" },
{ "label": "15 bis 30 Minuten", "value": "15 bis 30 Minuten" },
{ "label": "Länger als 30 Minuten", "value": "Länger als 30 Minuten" }
],
"multiSelect": false,
"freeText": true
},
"compliance": [
{ "id": "F4", "text": "Diese Empfehlung wurde automatisiert durch das KI-System von Choicera erstellt.", "trigger": "ai_recommendation" },
{ "id": "F5", "text": "Dies ist keine medizinische Beratung und ersetzt keine ärztliche oder apothekerliche Beratung. Bei bestehenden Erkrankungen, Medikamenteneinnahme, Schwangerschaft oder Stillzeit hole vor der Einnahme ärztlichen Rat ein.", "trigger": "health_recommendation" },
{ "id": "F10", "text": "Wechselwirkungen mit Medikamenten konnten nicht geprüft werden", "trigger": "degraded_medication" },
{ "id": "F10", "text": "Eignung bei Schwangerschaft/Stillzeit nicht geprüft", "trigger": "degraded_maternal" }
]
}Als erste Antwort der Beratung trägt diese Frage die Pflichttexte. Ein Formular wie in Schritt 2 und eine spätere reine Frage (question) tragen keine: reply.text ist dann nur die Frage, compliance ist leer.