REST API & MCP integrieren.

MCP verbinden

1. Im MCP-Client einen Remote-Server hinzufügen.
2. Die folgende URL mit Streamable HTTP verbinden. Keine Zugangsdaten erforderlich.
3. Die Werkzeuge auflisten und mit get_service_options beginnen.

https://platform-api.samuelz.com/api/v1/mcp/chauffeur/samuelz-chauffeur

Für eigene Browseranwendungen verwenden Sie REST. Der MCP-Zugang akzeptiert Browser-Origins nur aus freigegebenen Domains.

Samuelz in der offiziellen MCP Registry ansehen ↗

Info2 liest Informationen. Quote3 ergänzt anonyme Preisvorschauen. Nur Full5 kann ein ausdrücklich angefordertes unbezahltes Angebot vorbereiten.

Generierte Profil-, Feld- und Antwortschemas ↗

REST API nutzen

Sicherer erster Schritt: Leistungen und Vorbereitungspolicy lesen. Diese GET-Aufrufe berechnen keinen Preis und benötigen keine Kundendaten; das gemeinsame Pilotlimit gilt trotzdem.

https://platform-api.samuelz.com/api/v1/public/chauffeur/samuelz-chauffeur

curl --fail-with-body "https://platform-api.samuelz.com/api/v1/public/chauffeur/samuelz-chauffeur/services?locale=de"
curl --fail-with-body "https://platform-api.samuelz.com/api/v1/public/chauffeur/samuelz-chauffeur/policy?locale=de"

Eine Preisvorschau abrufen

JavaScript-Beispiel mit synthetischer Strecke und Datum in sieben Tagen. Beim Ausführen wird die echte, begrenzte Preis-API aufgerufen; dies ist keine Sandbox. Auf dieser Seite wird nichts automatisch ausgeführt.

const date = new Date(Date.now() + 7 * 86400000).toISOString().slice(0, 10);
const input = {
  "locale": "de",
  "ride": {
    "pickup": "Munich Airport (MUC)",
    "destination": "Marienplatz 1, München",
    "date": date,
    "time": "10:30",
    "passengers": 2,
    "tripType": "one_way"
  }
};
const response = await fetch("https://platform-api.samuelz.com/api/v1/public/chauffeur/samuelz-chauffeur/quotes", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(input),
  signal: AbortSignal.timeout(20000)
});
const result = await response.json();
console.log(response.status, response.headers.get("Retry-After"), result);

Datum und Uhrzeit gelten in der servicebezogenen Zeitzone aus /services. Rückfahrten benötigen tripType: "return", returnDate und returnTime nach der Hinfahrt. Geben Sie keine Kundennamen oder Kontaktdaten an.

Prüfen Sie immer status. Bei quoted stehen Geldbeträge als ganze Cent mit Währung in quote. revalidationRequired: true bedeutet: Preis und Angebot vor der Buchung erneut prüfen. Eine Vorschau reserviert kein Fahrzeug.

Ein verbindliches Angebot vorbereiten

prepare_offer darf erst nach ausdrücklicher Angebotsanforderung des Kunden ausgeführt werden und verlangt offerRequested: true, eine UUID als submissionId, ein zufälliges 64-stelliges Hex-resumeToken und E-Mail oder E.164-Mobilnummer. Ältere Clients ohne offerRequested werden sicher abgewiesen. Bewahren Sie beide Werte geschützt auf. Freigegebene Pilotpartner können zusätzlich ihre distributionPartnerCapability senden. Wiederholungen mit denselben Werten liefern dasselbe Angebot; Änderungen benötigen eine neue ID und Capability; get_offer_status liest nur diesen Vorgang. prepared reserviert noch keinen Chauffeur und belastet keine Zahlung.

const date = new Date(Date.now() + 7 * 86400000).toISOString().slice(0, 10);
const submissionId = crypto.randomUUID();
const resumeToken = Array.from(crypto.getRandomValues(new Uint8Array(32)),
  byte => byte.toString(16).padStart(2, "0")).join("");
const input = { ...{
    "locale": "de",
    "ride": {
      "pickup": "Munich Airport (MUC)",
      "destination": "Marienplatz 1, München",
      "date": date,
      "time": "10:30",
      "passengers": 2,
      "tripType": "one_way"
    }
  },
// Only after the customer explicitly requests an offer.
  submissionId, resumeToken, offerRequested: true,
  contact: { email: "REPLACE ME" } };
const response = await fetch("https://platform-api.samuelz.com/api/v1/public/chauffeur/samuelz-chauffeur/offers/prepare", {
  method: "POST", headers: { "Content-Type": "application/json" },
  body: JSON.stringify(input)
});
console.log(response.status, await response.json());

Ein prepared-Angebot bindet Preis, Ablauf, Route sowie die geltenden Storno-, Warte-, Leistungs- und Rechtsbedingungen. checkoutUrl und termsUrl führen zum selben revisionsgebundenen Kundenentscheid. Erst die ausdrückliche Zustimmung dort kann die Buchung bestätigen; die API nimmt keine Zahlung an.

Die Resume-Capability gilt 24 Stunden; die Angebotsgültigkeit steht separat in offer.expiresAt. not_found kann eine fehlende, falsche oder abgelaufene Capability bedeuten und beweist nicht, dass kein Angebot erstellt wurde. Bei pending retryAfterSeconds beachten und denselben Status lesen. Bei ambiguous/conflict kein neues Angebot automatisch anlegen. unavailable ist keine Zahlungsauskunft; bezahlte, stornierte oder gelöschte Angebote können so antworten.

Limits und Fehler behandeln

Der Pilot hat ein begrenztes, kanalübergreifendes Abrufkontingent. Für einen größeren Einsatz stimmen wir Kapazität und Ablauf gemeinsam ab.

REST und MCP teilen sich Limits je Anbieter und Client. Kanalwechsel erhöht das Kontingent nicht. Keine automatischen Wiederholungsschleifen; nach einem Timeout kann der Abruf bereits gezählt sein.

Buchung und Bedingungen

Ein prepared-Angebot bindet Preis, Ablauf, Route sowie die geltenden Storno-, Warte-, Leistungs- und Rechtsbedingungen. checkoutUrl und termsUrl führen zum selben revisionsgebundenen Kundenentscheid. Erst die ausdrückliche Zustimmung dort kann die Buchung bestätigen; die API nimmt keine Zahlung an.

Ihr System liest die aktuellen Informationen und ermittelt eine Preisvorschau. Über den zurückgegebenen Buchungslink prüft der Kunde das aktuelle Angebot, die geltenden Bedingungen und die Zahlung.

Öffentlich festgelegt sind weder Provisionssatz noch Abrechnungsfrist oder SLA. Pro Partner sind Vergütung und Abrechnung, Storno/Erstattung, Rollen und Datenverarbeitung, Zugangskontingent sowie Support vor dem Pilotstart zu klären. Die Fahrtbedingungen bestätigt der Kunde im Samuelz-Checkout.

Version, Status und Support

Öffentliche REST API v1 (OpenAPI-Informationsversion 1.0.0). MCP-Verträge: Full5 2.2.0 (5 Tools), Quote3 1.3.0 (3 Tools), Info2 1.1.0 (2 Tools). OpenAPI-Vertrag und MCP-Tool-Schemas bestimmen die generierte Referenz. Preise und Regeln kommen aus der aktuellen Anbieterpolicy.

Für dieses Pilotangebot sind weder ein öffentlicher Verfügbarkeitsstatus noch eine Uptime-Zusage veröffentlicht. Technische Fragen an support@samuelz.com; bitte keine Fahrgastdaten, Zugangscodes oder Tokens mitsenden.