OpenAPI-Referenz

TourAPI Kaeufer-API · 1.0.0-entwurf

Verfuegbarkeit, Preis, Suche, Buchung, Buchungsinfo und Storno fuer Abnehmer eines Veranstalters.

Maschinenlesbarer Vertrag zum API-Handbuch (HANDBUCH.md, liegt neben dieser Datei). Das Handbuch erklaert Ablauf, Regeln, Fehlerkatalog und Beispiele; jedes Beispiel dort laeuft bei jedem Build als Test gegen eine echte Instanz.

• Alle Betraege sind ganze Cent in der Vertragswaehrung des Hotels (keine Umrechnung).
• Datumsfelder sind Kalendertage JJJJ-MM-TT; ein Aufenthalt ist [checkIn, checkOut).
• Stichtag ist das Serverdatum (Europe/Berlin); das Feld now wird ignoriert.
• Kompatibilitaet innerhalb v1 nur additiv (neue optionale Felder, neue Endpunkte, neue ERR_*-Codes); unbekannte Antwortfelder ignorieren. Details: Handbuch Abschnitt 1.9.

Authentifizierung

X-Api-Key (header)

API-Key aus dem Zugangspaket; bestimmt Veranstalter und Kundengruppe. Test-Keys (tk_test_...) lesen wie ihr Live-Key und buchen nur in der Sandbox; jede Antwort auf einen angenommenen Key traegt den Kopf X-TourAPI-Mode (test|live), Handbuch Abschnitt 11.

Server

{baseUrl} – Basis-URL aus dem Zugangspaket

{baseUrl}

Basis-URL aus dem Zugangspaket

Gruppen

Auskunft

Verfuegbarkeit und Preis (BA)

Buchung

Buchung (B), Buchungsinfo, Storno (S)

Betrieb

Gesundheit des Knotens

Lieferung

EDF-Lieferung (Cache-Export) fuer Abnehmer mit Export-Recht

Inhalte

Hotelinhalte (Content-API) fuer Abnehmer mit Inhalts-Recht (Handbuch Abschnitt 12)

Maschinenlesbar: openapi.yaml

Endpunkte

• POST /v1/price
• POST /v1/prices
• GET /v1/destinations
• POST /v1/search
• POST /v1/search/open
• POST /v1/search/open/dates
• GET /v1/limits
• POST /v1/book
• GET /v1/booking
• POST /v1/cancel
• GET /v1/health
• GET /v1/export/edf/full
• GET /v1/export/edf/changes
• POST /v1/export/edf/ack
• GET /v1/content/hotels
• GET /v1/content/hotels/{code}
• GET /v1/content/changes
• GET /v1/content/catalog

POST /v1/price

Preis fuer ein Zimmer, eine Verpflegung, eine Belegung

Ohne room wird das guenstigste VERFUEGBARE Zimmer bepreist, das die Belegung zulaesst und das board anbietet (ist keines verfuegbar, das guenstigste davon mit availability.available=false); room in der Antwort nennt es. Nicht angebotenes board -> 422 ERR_BOARD_NOT_OFFERED.

Parameter

Anfrage

Antworten

POST /v1/prices

Preise aller Verpflegungen (und Zimmer) in einer Antwort

Parameter

Anfrage

Antworten

GET /v1/destinations

Gueltige destination-Codes des Keys

Zielgebiet- und Flughafen-Codes der Hotels dieses Keys (Hotels des Veranstalters; beim Key einer Kundengruppe mit Zuteilung nur Hotels mit Zuteilung), aufsteigend, je Code einmal - genau die Codes, auf die /v1/search filtern kann (Handbuch Abschnitt 4.5). Keine Parameter.

Parameter

Antworten

POST /v1/search

Buchbare Hotels mit Ab-Preis suchen

Seitenweise (pageSize, Standard 50, hoechstens 100) in Hotel-Code-Reihenfolge; Preis-Sortierung je Seite. Weitere Seiten mit cursor = nextCursor der Vorseite (Handbuch Abschnitt 4.3). destination ohne Hotel fuer diesen Key (erste Seite, ohne cursor) -> 422 ERR_UNKNOWN_DESTINATION (gueltige Codes: GET /v1/destinations).

Parameter

Anfrage

Antworten

POST /v1/search/open

Offene Suche - bestes Angebot je Hotel ueber Anreisefenster und Dauer-Spanne

Ohne Hotelcode und festen Termin: je Hotel das beste Angebot (Preis exakt wie /v1/price mit demselben Tupel, Reihenfolge bewiesen), global sortiert, Seiten per cursor = nextCursor (Handbuch Abschnitt 4a). Recht je Key (sonst 403 ERR_OPEN_SEARCH_NOT_ALLOWED), Grenzen aus dem Suchprofil des Keys (422 am Feld). Jedes unbekannte Feld -> 422 ERR_UNKNOWN_FIELD. Unter Last wird nur die Seite kuerzer (coverage.complete=false), nie der Preis ungenauer; kann die Suche ein Ergebnis nicht beweisen, 500 ERR_INTERNAL.

Parameter

Anfrage

Antworten

POST /v1/search/open/dates

Termin-Matrix eines Hotels - Anreise x Dauer ueber dasselbe Fenster wie die offene Suche

Stufe 2 der offenen Suche (Handbuch Abschnitt 4b): ein Hotel, Zellen dicht in der Ordnung checkIn, nights (mit perBoard zusaetzlich je Verpflegung). Zelle offer = guenstigstes verkaufbares Zimmer/Verpflegung, Preis exakt wie /v1/price mit diesem Tupel; none mit reason; unchecked nur, wenn das Zeitbudget ablief (nie als none). Das beste Angebot der offenen Suche ist bei gleichem Filter und Stand die erste offer-Zelle mit minimalem Kriterium. Recht und Grenzen aus dem Suchprofil des Keys (Fenster matrixMaxWindowDays, Zellen matrixMaxCells). Jedes unbekannte Feld -> 422 ERR_UNKNOWN_FIELD; nicht beweisbar -> 500 ERR_INTERNAL.

Parameter

Anfrage

Antworten

GET /v1/limits

Wirksame Grenzen des eigenen Keys (Takt, Export-Recht, Inhalts-Zugang, Suchprofil)

Das effektive Suchprofil des Keys (Minimum aus Plattform-Deckel, Veranstalter-Obergrenze und Key-Profil) - dieselben Werte, die /v1/search/open und /v1/search/open/dates anwenden; ohne Recht nur openSearch.allowed=false. Keine Interna (weder Ebene noch Grund); Ziele nur im Bestand des Keys. Dazu der Takt aller Anfragen des Keys, das Export-Recht und der Zugang zur Content-API (content.allowed, dieselbe Regel wie /v1/content/*; Handbuch Abschnitt 4c). Keine Parameter (jeder -> 422 ERR_UNKNOWN_FIELD).

Parameter

Antworten

POST /v1/book

Buchen (idempotent ueber idemKey)

Lehnt jedes unbekannte Feld ab (ERR_UNKNOWN_FIELD). Ein schon verbuchter idemKey wird vor Stichtag, Grenzen und priceCheck beantwortet (alreadyBooked), nur ein neuer idemKey durchlaeuft diese Pruefungen.

Parameter

Anfrage

Antworten

GET /v1/booking

Buchung ueber TourAPI-Referenz oder eigene Referenz lesen

Parameter

Antworten

POST /v1/cancel

Stornieren (idempotent)

Lehnt jedes unbekannte Feld ab (ERR_UNKNOWN_FIELD). Der Storno wird beim Veranstalter mit Zeitpunkt und key_id des Keys protokolliert (Wiederholung ohne zweiten Eintrag).

Parameter

Anfrage

Antworten

GET /v1/health

Gesundheit des Knotens (ohne Key)

200 nur, wenn die Lese-Sicht geladen und der letzte Abgleich mit der Datenbank frisch ist; sonst 503 mit Grund. Keine Mandanten- oder Bestandsdaten. Mehr als 10 Aufrufe je Sekunde (Burst 50) von einer Absender-IP werden verzoegert beantwortet (hoechstens 1 s).

Ohne API-Key erreichbar.

Antworten

GET /v1/export/edf/full

EDF-Lieferung, Vollstand zum aktuellen Stand (Zip, Seitenkette)

Zuschnitt nur ueber den Key (Veranstalter, Kundengruppe), kein Parameter dafuer. Braucht das Export-Recht am Key. Ohne epoch/since/until beginnt eine Kette (hoechstens einmal je Stunde und Key; 400, 422 und 503 ERR_EXPORT_NOT_READY zaehlen nicht, Handbuch 10.3) - passt der Vollstand auf eine Seite (10.000 Dateien, 1 GiB entpackt, max_bytes), ist sie der ganze Vollstand (more false); sonst traegt sie more true und den Kettenschluessel in X-Export-Until. Folgeseiten mit epoch, since (to der Vorseite) und until (X-Export-Until der Vorseite) laufen im Seiten-Takt; nach kurzem Fehler dieselbe Folgeseite wiederholen statt neu beginnen. Angewendet wird am Kettenende. Scheitert das Paket nach dem ersten Byte, bricht der Server die Verbindung ab (Transportfehler); jedes Paket vor dem Anwenden gegen das Manifest pruefen (Dateien vollstaendig, bytes, sha256). Das Zip enthaelt manifest.json (Schema ExportManifest) und je Hotel eine Preis- und eine Allotment-Datei (Handbuch Abschnitt 10).

Parameter

Antworten

GET /v1/export/edf/changes

EDF-Lieferung, Aenderungen nach einem Stand (Zip, 204 wenn nichts neu)

Objekte und Tombstones nach since bis zum Ziel der Kette. Ohne until beginnt eine Kette (hoechstens einmal je Minute und Key; 400, 422 und 503 ERR_EXPORT_NOT_READY zaehlen nicht, 200, 204 und 409 zaehlen; die Takt-Pruefung kommt vor der epoch-Pruefung, Handbuch 10.3) und der Server gibt ihren versiegelten Kettenschluessel in X-Export-Until aus; nur Folgeseiten mit diesem Schluessel als until laufen im Seiten-Takt (nach kurzem Fehler dieselbe Folgeseite wiederholen). Angewendet wird am Kettenende (more false). Scheitert das Paket nach dem ersten Byte, bricht der Server die Verbindung ab; jedes Paket vor dem Anwenden gegen das Manifest pruefen.

Parameter

Antworten

POST /v1/export/edf/ack

EDF-Lieferung, Stand als verarbeitet quittieren

Nur fuer die Ueberwachung beim Veranstalter; aendert nichts an der Lieferung. Lehnt jedes unbekannte Feld ab (ERR_UNKNOWN_FIELD).

Parameter

Anfrage

Antworten

GET /v1/content/hotels

Verzeichnis der Hotels des Keys (Content-API)

Hotels des Keys aufsteigend nach code, seitenweise (dasselbe Universum wie /v1/destinations, unabhaengig von der Verfuegbarkeit). feedToken = Stand fuer /v1/content/changes (alle Seiten eines Durchlaufs tragen den Stand der ersten Seite); scopeHash wechselt mit der Hotelmenge des Keys (Handbuch 12.2). Unbekannte Parameter -> warnings.

Parameter

Antworten

GET /v1/content/hotels/{code}

Inhalt eines Hotels (Content-API)

Stamm, Lage, Kategorien, Fakten, sichtbare Texte, fertige sichtbare Bilder und Ausstattung eines Hotels des Keys. Nie Kontaktdaten. Ohne lang alle Inhaltssprachen ohne Rueckfall; mit lang je Texttyp genau ein Eintrag je Sprache, fehlend ueber die Rueckfallkette (Standardsprache des Veranstalters, dann en) mit fallbackFrom (Handbuch 12.3). ETag; mit If-None-Match 304 ohne Koerper.

Parameter

Antworten

GET /v1/content/changes

Aenderungen der Hotelinhalte nach einem Stand

Aenderungen nach since in der Reihenfolge, in der sie gespeichert wurden, lueckenlos, je Hotel hoechstens einmal je Seite (mit seinem letzten Stand), nur Hotels des Keys. more true = sofort mit next weiterlesen. Stand vor dem Horizont (30 Tage) -> 410, dann Verzeichnis neu holen (Handbuch 12.4).

Parameter

Antworten

GET /v1/content/catalog

Kataloge der Hotelinhalte mit Beschriftungen

Objektarten, Kategorieskalen, Text- und Bildtypen, Ausstattungsgruppen und -merkmale mit Beschriftungen; languages = Inhaltssprachen des Veranstalters. ETag; mit If-None-Match 304 (Handbuch 12.5).

Parameter

Antworten

Schemata

Date

Kalendertag JJJJ-MM-TT

Typ

string (date)

Regeln

pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

Cents

Betrag in ganzen Cent der Vertragswaehrung

Typ

integer (int64)

Warnings

Hinweise zur Anfrage (ignorierte Felder, Waehrung, now). Bitte loggen.

Typ

array<string>

Traveller

Occupancy

Availability

PriceRequest

PricesRequest

SearchRequest

PriceCheck

BookRequest

CancelRequest

Rounding

Rundungsregel aller Cent-Betraege der Antwort (dieselbe, die der EDF-Export deklariert)

BreakdownLine

Ein Posten. Reihenfolge: Nacht aufsteigend (Posten je Aufenthalt, night -1, zuletzt), darin Reisender aufsteigend, darin Rechenschritt (BaseCharge/PhantomBaseCharge, GuestCharge, BoardCharge - jeweils direkt gefolgt von ihrer ApplyToBoard-GuestCharge -, Extra nach SortIndex). Die amountCents eines Reisenden summieren sich exakt zu seinem perTravellerCents.

SeparateExtra

Einzeln ausgewiesenes Extra. amountCents ist die exakte Summe seiner Posten, einmal gerundet; bei inTotal=true kann sie von der Summe seiner breakdown-Zeilen abweichen, auch um mehrere Cent je Reisendem (die Anzeige-Cent der Zeilen verteilen die Rundung des ganzen Personen-Topfs, nicht die des Extras). Massgeblich fuer den Preis sind totalCents, perTravellerCents und breakdown; exakter Wert des Extras = Summe der amountExact seiner Zeilen.

PriceResponse

BoardPrice

RoomPrices

BoardError

PricesResponse

SearchResult

SearchSkip

SearchDiagnostics

SearchResponse

OpenSearchRequest

OpenSearchCategoryFilter

Offizielle Kategorie aus dem Hotelstamm; Grenzen eingeschlossen, 4 Superior zaehlt als 4. Hotels ohne offizielle Kategorie zaehlen mit Grund ERR_NO_CATEGORY

OpenSearchGeoFilter

Umkreis (Haversine, Erdradius 6371 km, Abstand auf ganze Meter gerundet, Rand eingeschlossen). Hotels ohne Koordinaten zaehlen mit Grund ERR_NO_GEO

OpenSearchOffer

OpenSearchAlternatives

Vorpruefung ohne Preis (Obergrenze, keine Preis- oder Trefferaussage)

OpenSearchResult

OpenSearchCoverage

OpenSearchResponse

OpenDatesRequest

OpenDatesCell

OpenDatesCoverage

OpenDatesResponse

LimitsRate

LimitsExport

LimitsContent

Zugang zur Content-API (/v1/content/*) mit diesem Key - Freischaltung des Veranstalters und Inhalts-Recht des Keys; ohne Grund.

LimitsOpenSearch

Ohne Recht nur allowed=false; sonst alle Grenzen. destinations fehlt bei allDestinations=true.

LimitsResponse

ContentDirectoryResponse

ContentDirectoryHotel

ContentCategory

ContentGeo

ContentAddress

ContentFacts

ContentText

ContentLabel

ContentFocus

ContentVariant

ContentMedium

ContentAmenity

ContentHotel

Inhalt eines Hotels. Kein Feld fuer Kontaktdaten.

ContentChangesResponse

ContentChange

ContentCatalogResponse

ContentCatalogEntry

ContentCatalogAmenity

DestinationsResponse

Destination

BookResponse

CancelResponse

Booking

Error

Health

ExportAckRequest

ExportManifest

Inhalt von manifest.json im Paket. Kanonische Form (Reihenfolge, Einrueckung) und Grenzen im Liefervertrag (auf Anfrage beim Betreiber); der Referenz-Empfaenger lehnt jede andere Form ab.

ExportRules

ExportObject

ExportRemoval