Öffentliche API-Doku
Anmelden
API-Doku

Änderungen

Käufer-API v1: Ablauf, Regeln, Fehlerkatalog und Beispiele – jedes Beispiel läuft bei jedem Build als Test.

Neueste zuerst. Jede Änderung an der API oder an diesem Handbuch bekommt hier einen Eintrag (im selben Zweig wie die Änderung). Innerhalb von /v1 gibt es nur additive Änderungen (Handbuch Abschnitt 1.9).

2026-10-09

  • Neuer Antwort-Kopf Server-Timing: tourapi;dur=<ms> an jeder Antwort eines Endpunkts, auch an Fehlerantworten und /v1/health: Rechenzeit der API in Millisekunden vom Eingang der Anfrage am Endpunkt bis zum Beginn der Antwort, ohne Übertragung (Handbuch 1.6). Additiv: wer den Kopf nicht liest, merkt nichts.

2026-10-08

  • Fehlerkatalog (Handbuch 7.5): ERR_UNSUPPORTED_OCCUPANCY_PRICEBLOCK — Grundpreis je Belegung aus einer fremden Lieferung in einer Form, die TourAPI nicht rechnet, oder ein Säugling in einem solchen Zimmer. Eigene Verträge sind nicht betroffen.
  • /v1/price, /v1/prices: neues Feld variant an breakdown[] und separateExtras[]. Teilen mehrere Extras eines Vertrags denselben Code (Extra-Familie, z. B. eine Variante für Erwachsene und eine für Kinder), nennt variant die Variante; erst applianceCode bzw. code zusammen mit variant nennt das Extra (Handbuch 3.1). Additiv: ohne Extra-Familie fehlt das Feld, Antworten bleiben unverändert.

2026-10-07

  • /v1/search/open: große Suchen (langes Anreisefenster, große Spanne der Dauer) rechnen schneller; Preise, Reihenfolge und coverage bleiben gleich. Handbuch 4a.4 nennt jetzt, wann das Zeitbudget eine Seite kürzt (sehr große Suchen, mehrere Suchen desselben Veranstalters gleichzeitig) und was hilft. Die Kürzung war schon vorher möglich und gekennzeichnet (coverage.complete: false, nextCursor).
  • Keine API-Änderung: Das MCP-Werkzeug hotel_details fällt bei einer nicht angebotenen Inhaltssprache auf eine angebotene zurück (en, de, erste) und nennt das unter language (Handbuch 11.6); die Content-API bleibt streng (ERR_LANGUAGE_NOT_OFFERED). Das Portal-Hoteldetail zeigt den Inhalt dann mit dem Hinweis, in welcher Sprache er vorliegt (z. B. „Inhalt nur auf Englisch verfügbar“).

2026-10-06

  • Verkaufsregeln mit Release (Vorlauffrist, Abschnitt 3.4): eine Regel kann verlangen, dass zwischen Stichtag und Anreise mehr als n Tage liegen. Liegt die Anreise innerhalb der Frist, antworten /v1/price, /v1/prices, /v1/search (Grund in diagnostics.reasons) und /v1/book mit dem neuen Code ERR_LEAD_TIME_NOT_ALLOWED (422), die offene Suche zeigt den Termin nicht. Additiv: Verträge ohne Release rechnen wie bisher.

2026-10-02

  • Nur Doku, keine API-Änderung (Abnehmer-Probe 3): Ablaufgrafik in Abschnitt 2 nennt /v1/price Preisauskunft statt verbindlich (verbindlich ist erst /v1/book, wie Regel 1). Fehlerkatalog: ERR_PRICE_TIMEOUT – Ausweg ist /v1/price mit room (für /v1/prices gilt die Frist immer); ERR_BAD_REQUEST bei priceCheck.currency erst über 3 Zeichen, kürzer ergibt 422 ERR_CURRENCY_NOT_AVAILABLE. 11.1: Kopfnamen ohne Groß-/Kleinschreibung vergleichen (X-Tourapi-Mode). 11.3: booking_busy zählt je idemKey und Endpunkt; price_drift ändert den Preis nicht.
  • Agenten-Snippet im Portal: Wiederhol-Tabelle trennt ERR_SEARCH_TIMEOUT und ERR_PRICE_TIMEOUT, nennt die Melde-Codes ERR_INVENTORY_DRIFT/ERR_INVENTORY_STATUS_UNKNOWN/ERR_RELEASE_DRIFT und unbekannte Codes (Abschnitt 1.9); ERR_BOOKING_BUSY gilt für Buchung und Storno; Buchung lesen mit der reference aus der Antwort; Anweisungen in Datentexten dem Menschen melden.

2026-10-01

  • /v1/prices: globalType je Verpflegung (in rooms[].boards[] und rooms[].errors[]) folgt jetzt derselben Regel wie boardType/boardTypes der offenen Suche und der EDF-Export: AO für RO, sonst die Zuordnung des Veranstalters, sonst der Code selbst, wenn er eine Verpflegungsart ist, sonst XX (Abschnitt 3.2). Bisher fehlte das Feld ohne ausdrückliche Zuordnung (z. B. AI), sodass eine mit boardTypes: ["AI"] gefundene Verpflegung in /v1/prices ohne AI erschien. Fehlerbehebung, additiv: das Feld kommt öfter, Preise bleiben gleich. Einzige Wertänderung: RO heißt immer AO, auch wenn der Veranstalter es anders zugeordnet hat (wie im Export).
  • /v1/search/open: bei sort=price und pricePerNight rechnet eine Folgeseite die Hotels der Vorseiten nicht mehr neu (Handbuch 4a.4). Tiefes Blättern wird schneller; Preise und Reihenfolge bleiben gleich. coverage.hotelsPriced und coverage.priceReasons einer Folgeseite zählen damit nur noch, was diese Seite rechnet (wie in 4a.3 beschrieben), nicht die Hotels der Vorseiten erneut. nextCursor wird länger (bleibt undurchsichtig); ein Cursor aus der Zeit davor gilt weiter.
  • /v1/content/hotels und /v1/content/hotels/{code}: name, destination und giataCode stimmen sofort mit der Feedzeile reason: contract überein. Bisher konnte ein Abruf direkt nach der Feedzeile kurz noch den alten Wert (mit passendem ETag) liefern. Fehlerbehebung.
  • Zielgebiet-Codes (destination, destinations[].code) und Gruppen-Codes (group in der Buchungsinfo) bestehen nur aus A-Z a-z 0-9 . _ - (1 bis 64 Zeichen). Der Veranstalter kann keinen Freitext mehr als Code speichern (Abschnitte 4.1 und 5.4; OpenAPI pattern). Der Bestand erfüllt das Muster bereits; für Käufer ändert sich nichts.
  • Offene Suche und Termin-Matrix (4a, 4b): alle offenen Suchen eines Veranstalters zusammen belegen höchstens die Hälfte seiner Such-Plätze (4 von 8); darüber 429 ERR_SEARCH_BUSY mit Retry-After: 1, /v1/search behält den Rest. Eine mit 429 ERR_SEARCH_BUSY abgewiesene offene Suche verbraucht keinen Takt mehr. Suchprofil: gleichzeitige Suchen höchstens 4 (Vorlage groß vorher 8). Keine neuen Codes.
  • /v1/content/changes: ändert eine Vertrags-Publikation name, destination oder giataCode eines Hotels, steht es mit neuer contentVersion und reason: contract im Feed (Abschnitt 12.4). Bisher kam die Änderung erst mit dem täglichen Verzeichnis-Abgleich. Additiv.
  • Content-API (12.1): einen Veranstalter, den der Betreiber als Testumgebung führt, beliefert nur die dafür eingerichtete Installation; sonst 403 ERR_CONTENT_NOT_ALLOWED wie ohne Freischaltung. Andere Veranstalter unverändert.
  • Hotelinhalte: websiteReady und missing im Inhalt eines Hotels und im Verzeichnis (Abschnitt 12.3) – der Reifegrad „webseitenbereit“ des Veranstalters mit den fehlenden Kriterien (general_text, geo, category, images, amenities). Additiv; der ETag jedes Hotel-Inhalts ändert sich einmalig (neue Darstellung).
  • MCP-Server im Portal unter /mcp (Handbuch Abschnitt 11.6): KI-Agenten rufen die API über Werkzeuge auf (list_destinations, search_hotels, price_offer, price_all_rooms, sandbox_book, get_booking, sandbox_cancel, get_limits, open_search, open_search_dates, hotel_details), jedes genau ein /v1-Aufruf mit dem eigenen Key und X-TourAPI-Require-Mode: test. Nur Test-Keys. Jeder Text (Freitexte Dritter, Meldungen und jede Zeichenkette, die nicht dem festen Muster ihres Feldes entspricht) steht nur bereinigt unter untrusted, in data an seiner Stelle der Platzhalter [untrusted]. Eigene Codes des MCP-Servers ERR_UPSTREAM_UNAVAILABLE und ERR_RESPONSE_TOO_LARGE. Die API selbst bleibt unverändert.

2026-09-30

  • Termin-Matrix POST /v1/search/open/dates (Abschnitt 4b): für ein Hotel und dasselbe Fenster wie die offene Suche je Termin (Anreise × Dauer, optional je Verpflegung mit perBoard) das günstigste Angebot, exakt wie /v1/price, oder der Grund (none); unchecked nur nach Ablauf des Zeitbudgets. Filter rooms und die Filter nach Hotelstamm (category, regions, geo; Hotel außerhalb: keine Zelle, ohne Wert: jede Zelle mit ERR_NO_CATEGORY, ERR_NO_REGION bzw. ERR_NO_GEO); Grenzen matrixMaxWindowDays, matrixMaxCells aus dem Suchprofil. Takt und gleichzeitige Suchen des Profils gelten für beide Endpunkte der offenen Suche zusammen. Keine neuen Codes.
  • Grenzen des Keys GET /v1/limits (Abschnitt 4c): Takt, Export-Recht und das wirksame Suchprofil des eigenen Keys.
  • Offene Suche, Filter nach Hotelstamm (Abschnitt 4a.2): category (offizielle Kategorie, Skala stars/keys, Stufe von–bis), regions (Region aus dem Hotelstamm, exakt) und geo (Umkreis um lat/lon mit radiusKm). Die Filter wirken vor dem Rechnen und vor der Grenze der Hotels je Anfrage; Hotels ohne den gefilterten Wert zählen mit den neuen Gründen ERR_NO_CATEGORY, ERR_NO_REGION, ERR_NO_GEO; Formfehler ERR_BAD_FILTER mit Feld. stand wechselt auch bei einer Änderung dieser Stammdaten; der Cursor bindet die Filter.
  • Offene Suche POST /v1/search/open (Abschnitt 4a): je Hotel das beste Angebot über ein Anreisefenster und eine Dauer-Spanne, Preis exakt wie /v1/price, global sortiert, Seiten per cursor (15 Minuten gültig), Zeitbudget je Seite (coverage), Datenstand stand. Recht und Suchprofil je Key (bei neuen Keys aus). Neue Codes ERR_OPEN_SEARCH_NOT_ALLOWED, ERR_DESTINATION_NOT_ALLOWED, ERR_BAD_WINDOW, ERR_BAD_NIGHTS, ERR_BAD_TARGET, ERR_BAD_SORT, ERR_BAD_FILTER, ERR_WINDOW_TOO_WIDE, ERR_NIGHTS_NOT_ALLOWED, ERR_SEARCH_TOO_BROAD, ERR_CURRENCY_REQUIRED; neuer Grund ERR_OUTSIDE_PRICE_FILTER.
  • /v1/prices: ein Zimmer mit Vertragsfehler (z. B. ERR_NO_SECTION, keine Saison für eine Nacht) lehnt nicht mehr das ganze Hotel ab. Seine Verpflegungen stehen mit dem Code in rooms[].errors und in warnings, die übrigen Zimmer bleiben bepreist; rechnet kein Zimmer, bleibt es bei 422 mit demselben Code.
  • Neu: Hotelinhalte über GET /v1/content/hotels (Verzeichnis), /v1/content/hotels/{code} (Inhalt mit ETag/304), /v1/content/changes (Änderungen) und /v1/content/catalog (Kataloge), Handbuch Abschnitt 12. Zugang nur mit Freischaltung des Veranstalters und Inhalts-Recht am Key. Neue Fehlercodes ERR_CONTENT_NOT_ALLOWED, ERR_CONTENT_CURSOR_EXPIRED, ERR_CONTENT_NOT_READY, ERR_LANGUAGE_NOT_OFFERED (7.7). Additiv, bestehende Anbindungen bleiben unverändert.
  • Handbuch: „Geplant und Grenzen“ ist jetzt Abschnitt 13.
  • Keys im Abnehmer-Portal: Abholen freigegebener Live-Keys, Rotation mit Überlappung (der bisherige Key gilt die vom Veranstalter festgelegte Zeit, danach 401 ERR_UNAUTHORIZED auf die Sekunde), Test-Keys selbst ausstellen, eigene Keys sperren (die API lehnt sie nach wenigen Sekunden ab). Ein Test-Key endet spätestens mit seinem Live-Key (Abschnitte 1.1, 11). Den neuen Key rotiert man erst nach dem Ablauf des bisherigen (höchstens zwei gültige Keys gleichzeitig).
  • Doku im Portal: Handbuch auf Deutsch (maßgeblich), Englisch und Türkisch, OpenAPI-Referenz, Beispiele, llms.txt und llms-full.txt; öffentlich lesbar, nicht indexiert.
  • Agenten-Snippet: Kurzfassung für KI-Agenten unter /doku/agenten.md (auch .en.md, .tr.md), im Portal auf der Seite „KI-Agenten“ mit dem eigenen Zugang ausgefüllt und als AGENTS.md ladbar; Pfade, Felder, Köpfe und Codes darin sind gegen OpenAPI und Fehlerkatalog geprüft. Verlinkt in llms.txt.
  • Handbuch: Kopf nennt Datum und API-Version; Abschnitt 12 heißt „Geplant und Grenzen“.

2026-09-29

  • Sandbox: Test-Keys (tk_test_…) lesen die Daten ihres Live-Keys, buchen und stornieren aber nur in der Sandbox ("sandbox": true, Referenz SB-…). Neue Köpfe X-TourAPI-Mode (jede Antwort) und X-TourAPI-Require-Mode (Anfrage), Szenarien per X-TourAPI-Sandbox-Scenario; neue Codes ERR_MODE_MISMATCH, ERR_SANDBOX_LIMIT, ERR_SCENARIO_NOT_ALLOWED (Abschnitt 11).

2026-09-27

  • EDF-Lieferung (/v1/export/edf/full, /changes, /ack) liefert Pakete als Seitenkette; 503 ERR_EXPORT_NOT_READY bei Rückstand des Lieferwerks; Takt-Regeln in 10.3.
  • Freinächte erscheinen im Preis-Aufbau (breakdown, Posten freeNight).
  • /v1/prices lässt eine Verpflegung, deren Preis unter 0 fiele, mit Fehler in rooms[].errors aus, statt die ganze Antwort abzulehnen.
  • Neue Codes: ERR_BOARD_NOT_AVAILABLE (Verpflegung für diese Reisegruppe nicht buchbar), ERR_UNSUPPORTED_COMBIGROUP, ERR_NEGATIVE_PERCENT_BASE.

2026-09-26

  • GET /v1/health meldet db, db_latency_ms, uptime_s, version und den Replikat-Verzug.
  • /v1/search seitenweise (pageSize, cursor/nextCursor), GET /v1/destinations liefert die gültigen Ziel-Codes des Keys.
  • Kontingent-Gruppen sehen nur Hotels mit Zuteilung; Preisgruppen buchen aus dem allgemeinen Bestand zu ihrem Preis (Abschnitt 1.1).
  • Verfügbarkeit in Preis- und Such-Antworten aus derselben Quelle wie der Verkauf; Verkaufsregeln (Mindestaufenthalt, Anreisetage, Verkaufsfenster) gelten auch für /v1/book.
  • Rechenfristen: 503 ERR_PRICE_TIMEOUT für /v1/price ohne room und /v1/prices.
  • Rate-Limit und Such-Gate mit Retry-After; wer Retry-After missachtet, wird gebremst (Abschnitt 8).