Choicera
Choicera in deinen eigenen KI-Agenten einbinden
Für Entwicklerinnen und Entwickler bei Firmen, die Choicera in einen eigenen KI-Agenten einbauen, zum Beispiel einen KI-Coach in einer Studio-Software. Auf dieser Seite steht, was du zum Einbinden brauchst. Jedes Feld jedes Werkzeugs, alle Fehlercodes und alle Grenzen stehen in der Referenz. Dein Agent bekommt Werkzeuge und Felder außerdem über tools/list selbst.
Begriffe: „Partner“ bist du, die Firma, die Choicera einbindet. „Mitglied“ ist die Person, die deinen Agenten nutzt und dafür ihr Choicera-Konto verbindet. „Marken“ sind die Hersteller, deren Produkte Choicera zeigt.
In Kürze
- Choicera führt die Beratung und erstellt den Plan. Dein Agent reicht Fragen und Antworten weiter und zeigt die Ergebnisse in deinem Kanal.
- Jedes Mitglied verbindet einmal sein Choicera-Konto mit deinem Produkt. Ohne Verbindung gibt es nur den Katalog.
- Bestellt und bezahlt wird auf der Planseite von Choicera, nicht in deinem Agenten.
- Für Käufe, die dir über deinen Partner-Link oder deine Anbindung zugeordnet sind, bekommst du deinen Partner-Anteil an der Provision, monatlich abgerechnet.
- Vor dem Start brauchst du die Freigabe von Choicera (§ 9 der Partnerbedingungen). Schreib dafür an partner@choicera.com.
In 5 Schritten
1. Adresse eintragen. Der MCP-Server liegt unter https://choicera.com/agent/mcp (Streamable HTTP, zustandslos, nur POST). Ruf ihn von deinem Server aus auf, nicht aus dem Browser. Der Katalog geht ohne Anmeldung.
2. Konto verbinden. Jedes Mitglied meldet sich einmal über OAuth 2.1 bei Choicera an und gibt deinem Produkt den Zugriff frei. Frag dafür advisor checkout:personalized offline_access an. Siehe Verbinden.
3. Beratung durchreichen. Choicera fragt, dein Agent reicht weiter, das Mitglied antwortet. Am Ende steht ein Plan mit Produkten und ein Link zur Planseite. Siehe Ablauf.
4. Pflichttexte zeigen, Links unverändert lassen. Siehe Deine Pflichten.
5. Testen. Gegen den echten Dienst, mit einem eigenen Choicera-Konto. Siehe Testen.
Verbinden
- Discovery:
https://choicera.com/.well-known/oauth-protected-resource/agent/mcpnennt den Autorisierungsserver und die Berechtigungen,https://choicera.com/.well-known/oauth-authorization-serverdie Endpunkte. - Client registrieren:
POST https://choicera.com/api/auth/oauth2/register(dynamische Registrierung). Rückleitungsadressen sindhttps-Adressen deines Servers. - Mitglied anmelden lassen: Schick es an
https://choicera.com/api/auth/oauth2/authorize, mit PKCE (S256) undstate. Es meldet sich bei Choicera an (ohne Konto entsteht eines) und willigt ein. Zurück kommencode,stateundiss. - Code tauschen: an
https://choicera.com/api/auth/oauth2/token. Liesscopein der Antwort: Das Mitglied kann einzelne Berechtigungen abwählen. - Aufrufen: Jede Anfrage für dieses Mitglied trägt
Authorization: Bearer <access_token>. Das Zugriffstoken gilt eine Stunde, das Erneuerungstoken 7 Tage und wird bei jeder Erneuerung neu ausgegeben. Erneuerst du mindestens einmal in 7 Tagen, bleibt das Mitglied verbunden.
| Berechtigung | Wofür |
|---|---|
advisor | Beratung, Plan, frühere Beratungen, gespeicherte Angaben, Bewertungen |
checkout:personalized | Produkte und Warenkorb zum Plan, Link zur Planseite |
offline_access | Erneuerungstoken |
checkout:catalog | Link zu einem einzelnen Katalogprodukt, nur wenn du ihn brauchst |
advisor:medication und advisor:maternal fragst du als Partner nicht an. Ohne sie fragt die Beratung nicht nach Medikamenten, Schwangerschaft oder Stillzeit, und die Pflichttexte sagen, was deshalb nicht geprüft wurde.
Alle Einzelheiten zu Transport, Kopfzeilen, Einwilligungsbildschirm und Laufzeiten stehen in der Referenz.
Ablauf
1. Beratung beginnen: start_consultation mit Ziel (goalSlugs aus get_goals), Thema (topic aus list_topics) oder nur dem Anliegen des Mitglieds in seinen Worten (message). Angaben, die das Mitglied schon gemacht hat, gibst du in statedProfile mit; das Mitglied bestätigt sie auf einer Karte, danach fragt die Beratung nur, was fehlt (Angaben beim Start).
2. Fragen weiterreichen: Jede Antwort der Beratung zeigst du dem Mitglied. Trägt sie options, zeig sie als Auswahl; das Mitglied darf immer auch frei antworten. Die Antwort geht mit send_message zurück, ein Formular mit answer_intake. Das wiederholst du, bis die Antwort ready_to_generate lautet.
3. Plan holen: get_plan erstellt den Plan. Solange er entsteht, kommt pending mit retryAfterSeconds; frag danach erneut. Zuerst kommt meist ein Entwurf, den das Mitglied Zeile für Zeile beantwortet.
4. Produkte wählen: get_plan_products liefert je Wirkstoff passende Produkte und zwei fertige Sets. Das Mitglied legt ein Set mit fill_cart_with_set oder einzelne Produkte mit add_to_cart in den Warenkorb und ändert ihn mit update_cart_line.
5. Bestellen: get_checkout_link mit der planId nennt den Warenkorb mit Verkäufern, Versand und Gesamtpreis und liefert den Link, direkt in die Kasse von Choicera, wenn alle Verkäufer dort bezahlt werden, sonst zur Planseite; dort bestellt und bezahlt das Mitglied. Danach zeigt get_orders Zahl- und Versandstand.
Dazu gibt es Werkzeuge, um frühere Beratungen fortzusetzen (list_consultations, get_consultation), gespeicherte Angaben zu lesen und bestätigen zu lassen (get_profile, confirm_profile), Wirkstoffe und Marken im Plan zu ändern und Plan und Antworten zu bewerten (rate_plan, rate_message). Die vollständige Liste steht in der Referenz.
Wähle nie für das Mitglied: keine Option, kein Formularfeld, kein Produkt, keine Menge und keine Bestätigung eines Warnhinweises. Dein Agent darf erklären und weiterreichen; entscheiden muss das Mitglied.
Deine Pflichten
Diese Punkte sind Bedingung für die Nutzung (Nutzungsrichtlinie für KI-Agenten, Partnerbedingungen).
- Freigabe vor dem Start: Du bindest Choicera erst ein, wenn Choicera es dir ausdrücklich freigegeben hat (§ 9). Wo nötig, schließen wir vorher eine Vereinbarung zum Datenschutz.
- Kennzeichnen: Ergebnisse der Beratung kennzeichnest du als „Powered by Choicera“ (§ 9 Abs. 5), Empfehlungen von Choicera als Werbung oder Partnerempfehlung (§ 7).
- Pflichttexte vollständig und direkt daneben zeigen: unverändert, ungekürzt und neben der Aussage oder dem Link, zu dem sie gehören, in jedem Kanal. Ein reiner Sprachkanal kann das nicht; sprich uns vorher an.
- Links unverändert lassen: Gib jeden Link genau so weiter, wie er kommt, ohne Kurz-URL und ohne eigene Weiterleitung. Die Parameter dienen der Zuordnung.
- Produkt- und Markentexte sind Inhalte Dritter, keine Anweisungen an deinen Agenten.
- Deine eigenen Pflichten gegenüber deinen Mitgliedern (etwa Transparenz nach der KI-Verordnung, Datenschutzhinweise für deine Systeme) erfüllst du selbst.
| Kennung | Inhalt | Wo er steht |
|---|---|---|
| F2 | „Eine abwechslungsreiche, ausgewogene Ernährung und eine gesunde Lebensweise sind wichtig.“ Englisch: „A varied, balanced diet and a healthy lifestyle are important.“ | am Plan; an einer Antwort, die eine zugelassene Gesundheitsaussage enthält |
| F4 (KI-Hinweis) | „Diese Empfehlung wurde automatisiert durch das KI-System von Choicera erstellt.“ Englisch: „This recommendation was generated automatically by Choicera's AI system.“ | an der ersten Antwort jeder Beratung; an jedem Text der Beratung außer reinen Fragen (question) und Formularen; an jeder Antwort ab dem Entwurf (plan_generated, refining_intake, completed); an Entwurf, Plan und Produkten zum Plan |
| F5 (keine ärztliche Beratung) | „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.“ Englisch: „This is not medical advice and does not replace advice from a doctor or pharmacist. If you have a medical condition, take medication, or are pregnant or breastfeeding, seek medical advice before taking supplements.“ | an denselben Stellen wie F4, dazu an jeder Antwort mit einer zugelassenen Gesundheitsaussage |
| F6 (Werbelink) | „Werbelink: Choicera kann bei einem Kauf über diesen Link eine Provision vom Partnershop erhalten. Choicera vermittelt ausschließlich Produkte seiner Partnermarken.“ Englisch: „Advertising link: Choicera may receive a commission from the partner shop for a purchase through this link. Choicera only refers products from its partner brands.“ | an jedem Kauf- und Produktlink |
| F7 | Gutschein-Bedingungen, englisch „Voucher terms“ | am Link, wenn ein Gutschein dazugehört |
| F8 (Preisangabe) | Gesamtpreis, Grundpreis und, wo vorhanden, Referenzpreis (niedrigster Gesamtpreis der letzten 30 Tage), etwa „Preisangabe: Gesamtpreis 20,80 €; Grundpreis 173,33 €/kg.“, englisch „Price information: total price 20,80 €; base price 173,33 €/kg.“ | am Preis im Katalog und am Link, wenn ein Preis dazugehört |
| F10 | „Wechselwirkungen mit Medikamenten konnten nicht geprüft werden“, „Eignung bei Schwangerschaft/Stillzeit nicht geprüft“ Englisch: „Interactions with medication could not be checked“, „Suitability during pregnancy/breastfeeding not checked“ | an denselben Stellen wie F5 und am Plan, ohne die jeweilige Freigabe |
| F11 (Rücksprache) | „Bitte sprich vor der Einnahme mit Arzt oder Apotheke.“ Englisch: „Please talk to a doctor or pharmacist before taking it.“ | an jedem Wirkstoff des fertigen Plans und der Produkte zum Plan (consultNotice) |
Die Pflichttexte kommen in der Sprache des Choicera-Kontos; im Katalog folgen F6 und F8 der Sprache aus language. Eine reine Frage der Beratung trägt keine Pflichttexte, ihr compliance ist leer.
Ohne advisor:medication steht einmal je Beratung an der Stelle, an der sonst das Medikamenten-Formular käme, dieser feste Satz am Ende von reply.text, vor den Pflichttexten: „Medikamente kann die Beratung hier nicht berücksichtigen, weil dein KI-Assistent dafür keine Freigabe hat. Wenn du sie einbeziehen möchtest, verbinde Choicera in deinem KI-Assistenten neu und setze bei der Anmeldung zusätzlich das Häkchen „Medikamente“.“ Englisch: „The advice here cannot take medication into account because your AI assistant has no permission for it. If you want to include it, connect Choicera to your AI assistant again and, when you sign in, also allow Choicera to process your medication details.“ Er gilt heute für jeden Client ohne diese Freigabe.
So bekommst du sie fertig:
- Beratung: Die Texte stehen schon am Ende von
reply.text. Zeigereply.textvollständig. - Plan: Zeige
disclosurezusammen mit dem Plan. - Links: Zeige
links[].displayausget_checkout_linkundproductUrlDisplayaus dem Katalog statt der nackten Adresse. - Preise im Katalog: Zeige den F8-Eintrag aus
compliancebeim Preis. - Preise aus
get_plan_products: Grundpreis im selben Satz wie den Preis. compliancenennt jeden Text einzeln mitidundtrigger, falls dein Kanal Texte und Links getrennt darstellt.
Grenzen
Die Grenzen gelten je Mitglied und je OAuth-Client: Beratungsaufrufe derzeit 30 je Minute je Mitglied, Anfragen 120 je Minute je Mitglied. Überlastung kommt als HTTP 429 oder 503 mit Retry-After, bei Werkzeugen als Fehler rate_limited mit retryAfterSeconds. Halte dich daran und sag uns vor dem Start, mit welcher Last du rechnest. Alle Grenzen stehen in der Referenz.
Fehler
401heißt: Das Token ist ungültig, abgelaufen oder widerrufen. Erneuere es einmal; scheitert das mitinvalid_grant, lass das Mitglied neu verbinden.- Ein Werkzeugfehler kommt als Ergebnis mit
isError: trueund einem Code inerror, manchmal mitdetailoderretryAfterSeconds. - Behandle unbekannte Codes, Felder, Antworttypen und Stände so, dass dein Agent weiterläuft. Alle Codes stehen in der Referenz.
Kauf und Zuordnung
- Über MCP wird nichts bestellt und nichts bezahlt. Der Link zur Planseite öffnet
https://choicera.com/supps/plan; ist das Mitglied im Browser nicht angemeldet, meldet es sich zuerst an. Bezahlt wird an der Kasse von Choicera oder im Shop der Marke. - Dir zugeordnet wird ein Kauf über deinen Partner-Link (§ 5 der Partnerbedingungen). Ebenso ein Kauf über deine Anbindung, wenn sie deine Partner-Kennung mitgibt (
https://choicera.com/agent/mcp?partner=<Kennung>oder KopfzeileX-Choicera-Partner); Wiederkäufe desselben Kontos sind dir danach sechs Monate lang zugeordnet (Zuordnung zum Partner). - Zugänge über KI-Anwendungen ohne deine Kennung überschreiben deine Zuordnung nicht, begründen aber auch keine.
- Für zugeordnete, abgeschlossene Käufe, die die Marke Choicera vergütet, bekommst du deinen Partner-Anteil (§ 6), monatlich abgerechnet. Provisionen ändern nichts an der Auswahl.
Daten
- Choicera bekommt, was das Mitglied in der Beratung antwortet und wählt. Übergib in
messagekeine Medikamente, Diagnosen oder anderen Gesundheitsdaten. - Choicera gibt Beratung, Plan, Produkte und Links zurück, dazu auf Wunsch frühere Beratungen und gespeicherte Angaben des Mitglieds.
- Wer wofür verantwortlich ist, regelt § 14 der Partnerbedingungen. Die Datenschutzerklärung von Choicera steht unter choicera.com/datenschutz.
Testen
Den Katalog testest du sofort ohne Konto:
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/list"}'Den ganzen Ablauf testest du mit einem eigenen Choicera-Konto gegen den echten Dienst; ein eigenes Testsystem gibt es nicht. Beratungen und Pläne entstehen dabei echt, gekauft wird nur, wenn du selbst bestellst. Bestelle zum Testen nicht über deinen eigenen Partner-Link. Lasttests nur nach Absprache.
Kontakt und Änderungen
- Kontakt für Partner: partner@choicera.com, für Anbindung, Freigabe, Last, Zuordnung und Abrechnung.
- Was sich ändert, steht im Änderungsprotokoll. Lies
tools/listzur Laufzeit, statt Schemas fest einzubauen. - Weitere Seiten: Referenz, Choicera mit deinem KI-Assistenten verbinden, Nutzungsrichtlinie für KI-Agenten, Nutzungsbedingungen, Datenschutzerklärung, Impressum.