Eigene Geschäftsdaten hochladen

Kaleidr kann Fragen anhand der eigenen Daten deiner Organisation beantworten — deiner Objekte, Angebote, Zimmer, Preise, Öffnungszeiten und Dokumente — zusätzlich zu seinem Grundwissen über die Welt.

Zwei Dinge sollten vor allem anderen klargestellt werden, da sie jede weitere Entscheidung beeinflussen.

Deine Daten werden ausschließlich an deine Organisation zurückgegeben. Sie sind auf Datenbankebene isoliert, nicht durch Anwendungslogik, und gelangen niemals in eine Antwort auf der Kaleidr Map für Verbraucher. Sie sind ausschließlich auf deinen eigenen B2B-Oberflächen verfügbar.

Ein Sprachmodell schreibt niemals deine Daten. Es liest den Header deines Exports und einige Beispielzeilen und schlägt ein Column Mapping vor; deterministischer Code wendet dieses Mapping anschließend auf jede Zeile an. Ein falsches Mapping korrigierst du in einem Formular. Würde ein Modell 500 Zeilen transkribieren, wären das 500 Möglichkeiten, einen Preis zu erfinden, der später mit einem überzeugenden Zeitstempel zurückgegeben wird, und ein erfundener Preis wäre von einem echten nicht zu unterscheiden.

Verfügbarkeit

Der Upload von Vendor-Daten ist eine Funktion des Enterprise-Tiers. Sowohl die Upload-UI als auch die API prüfen VENDOR_UPLOAD_TIERS = {"enterprise"} — ein Owner oder Admin im Pro-Tier erhält bei jedem Upload-Aufruf 403 vendor_data_requires_enterprise.

Die Vendor-Data-UI ist in Production derzeit deaktiviert (vendorDataEnabled Config-Flag). Wende dich an den Kaleidr-Support, wenn du Enterprise nutzt und sie für deine Organisation aktiviert werden soll.

Zusätzlich ist die Rolle Owner oder Admin in Enterprise erforderlich — hierbei handelt es sich um organisationsweite Daten, nicht um projektbezogene Daten.

Zwei Wege

Die Upload-Seite. Melde dich unter kaleidr.com an und öffne Your Data in deinem Kontobereich (Nav-Pfad /vendor-data, neben Billing und API Keys). Sie führt durch dieselben vier Schritte wie die API: Datei auswählen, vorgeschlagenes Mapping prüfen, Vorschau des Erkannten ansehen, veröffentlichen. Dies ist der richtige Weg für eine Tabellenkalkulation.

Die API, unten dokumentiert. Nutze sie, wenn deine Daten bereits in einem System liegen, das pushen kann, oder wenn du Uploads zeitgesteuert durchführen möchtest.

Authentifizierung

Alle Aufrufe verwenden ein Cognito-Access Token als Bearer, dasselbe, das deine Session bereits besitzt:

Authorization: Bearer <access token>

Keinen Platform API Key. Platform Keys identifizieren eine Integration; das Hochladen von Daten ist hingegen eine Aktion der Organisationsverwaltung und authentifiziert sich daher als Person mit einer Rolle. Alle folgenden Pfade liegen unter https://api.kaleidr.com.

Struktur eines Uploads

Ein Upload erzeugt einen Ingest (den Job) und ein Release (das versionierte Ergebnis). Ein Release ist draft, bis es veröffentlicht wird, und beim Veröffentlichen wird das vorherige atomar ersetzt — Leser sehen niemals ein halb angewendetes Update und es gibt kein Zeitfenster, in dem deine Organisation keine Daten hat.

1. Mapping vorschlagen

Sende den Anfang deiner Datei — die Header-Zeile und einige Datenzeilen, nicht den gesamten Export.

Method	Path	Body	Returns
POST	/inference-api/vendor/mapping/propose	{ csv_head }	{ mapping_spec, columns, sample_result, notes, errors[] }

csv_head ist auf 16 KB begrenzt und das Sample wird serverseitig zugeschnitten — das Senden einer größeren Datei erweitert nicht, was das Modell sieht.

sample_result ist der relevante Teil. Das vorgeschlagene Mapping wird als Dry-Run auf deinen eigenen Beispielzeilen ausgeführt, bevor du es überhaupt siehst, und sample_result zeigt, was es pro Abschnitt produziert hat. Ein Mapping, das plausibel aussieht, aber nichts liefert, würdest du sonst möglicherweise erst nach dem Upload entdecken.

Wenn der Vorschlag nicht angewendet werden kann, erhältst du trotzdem 200 mit gefülltem errors, keinen 5xx-Fehler. Das Mapping ist bearbeitbar und eine einzelne Spalte zu korrigieren ist die gesamte Interaktion. errors meldet außerdem alles, was in einem Durchgang erkannt werden kann — ein fehlendes Pflichtfeld und ein Spaltenname, den dein Sheet nicht besitzt, kommen gemeinsam statt in getrennten Round Trips.

Was bereits vor dem Upload erkannt wird: ein Abschnitt ohne ein Feld, das jede Zeile benötigt (stay_date, price_amount, units_available, name oder timezone eines Ortes), eine {"const": …}-Zeitzone, die keine echte IANA-Zone ist, eine Currency- Const, die nicht drei Buchstaben enthält, und jede Objektregel, die kein const- Container ist. Andernfalls würde jeder dieser Fälle einmal pro Zeile nach dem Upload fehlschlagen.

Begrenzt auf 30 Vorschläge pro Benutzer und Stunde.

2. Vorschau vorbereiten

Method	Path	Body	Returns
POST	/shared-api/vendor-data/ingests	{ filename, artifact, source, mapping_spec?, preview?, org_id? }	{ ingest_id, release_id, status, status_url, dispatched }

• filename muss mit .json oder .csv enden.
• artifact ist der rohe Dateitext.
• source ist csv, json oder manual.
• mapping_spec ist die Rückgabe aus Schritt 1 und kann optional bearbeitet werden. Lass es weg, wenn du ein bereits normalisiertes JSON-Bundle oder eine Nur-Orte-CSV sendest.
• preview: true bereitet vor, ohne zu veröffentlichen — dringend empfohlen für einen ersten Upload und jede Mapping-Änderung.
• org_id ist optional; standardmäßig wird die Organisation verwendet, die du administrierst.

Idempotency-Key ist bei diesem Aufruf erforderlich (8–128 Zeichen) und gilt pro Organisation. Ein erneuter Versuch mit demselben Schlüssel gibt den vorhandenen Ingest zurück, statt einen zweiten anzulegen. Verwende einen neuen Schlüssel, wenn du nach einer Mapping-Änderung bewusst erneut vorbereitest — das ist tatsächlich eine andere Anfrage, und ein aus der Datei abgeleiteter Schlüssel würde dir den mit dem alten Mapping erstellten Ingest zurückgeben.

3. Status beobachten

Method	Path	Returns
GET	/shared-api/vendor-data/ingests/{ingest_id}	{ status, attempts, row_counts, error_report, created_at, started_at, finished_at }

status bewegt sich von pending → running → succeeded oder failed. Bei Erfolg enthält row_counts, was erkannt wurde — "47 places, 312 rates" — und error_report enthält die Zeilen, die nicht gelesen werden konnten, jeweils mit Begründung.

4. Veröffentlichen

Method	Path	Returns
POST	/shared-api/vendor-data/ingests/{ingest_id}/publish	{ ingest_id, release_id, status, status_url, dispatched }

Nur für einen Ingest, der mit preview: true vorbereitet wurde und erfolgreich war.

Beim Veröffentlichen wird der Job erneut ausgeführt, statt nur ein Flag umzuschalten. Derselbe Artifact wird erneut gelesen und dasselbe Mapping angewendet, sodass Counts und Identifiers konstruktionsbedingt übereinstimmen — Geocoding ist jedoch ein Live-Aufruf, daher kann eine Koordinate abweichen, wenn der Provider sie seit deiner Vorschau korrigiert hat.

Sende hier keinen Idempotency-Key. Dieser Endpoint akzeptiert keinen und benötigt auch keinen: Ein zweites Publish desselben Ingests kann nicht stattfinden. Wenn deine erste Anfrage auf deiner Seite ein Timeout hatte, bei uns aber erfolgreich war, gibt der Retry 409 zurück — ingest_is_not_a_preview, oder publish_already_in_progress, wenn sich zwei Versuche exakt überschneiden. Beides bedeutet, dass dein Publish bereits läuft. Behandle diese Antworten als Erfolg, nicht als Fehler, den du erneut versuchen solltest.

Releases auflisten

Method	Path	Returns
GET	/shared-api/vendor-data/releases	[{ id, status, published_at, superseded_at, created_at }]

Optional mit ?status= filterbar. Pro Organisation ist jeweils genau ein Release published.

Vorschauen laufen ab

Eine Vorschau, die du nie freigibst, wird 14 Tage nach Abschluss des Stagings zurückgezogen. Sie wird als superseded markiert statt gelöscht, sodass der Upload in deiner Historie bleibt — sie kann aber nicht mehr veröffentlicht werden und du müsstest erneut hochladen. Das Veröffentlichen einer abgelaufenen Vorschau gibt 409 no_previewed_release_to_publish zurück.

Hinweise zu Feldern

timezone ist für jeden Ort erforderlich und relevant. Antworten zu Preisen und Verfügbarkeit werden im lokalen Kalender der Unterkunft berechnet — "tonight" in einem Hotel in Sydney ist ein anderer Tag als "tonight" auf dem Server. Wenn dein Export tatsächlich keine Timezone-Spalte hat, mappe ausdrücklich eine Konstante:

{ "timezone": { "const": "UTC" } }

Schreibe dies bewusst, statt einen Default zuzulassen. UTC ist für eine Unterkunft, die mit UTC-Zeiten arbeitet, korrekt, aber subtil falsch für eine Unterkunft, die dies nicht tut; der Fehler zeigt sich erst an den Rändern eines Aufenthaltszeitraums.

Das Weglassen von timezone oder die Angabe einer nicht existierenden Zone wird bereits im Propose-Schritt abgelehnt, nicht erst nach dem Upload.

Gib Koordinaten an, wenn du sie hast. Ein Ort mit lat/lng wird genauso verwendet — deine Koordinaten gelten als maßgeblich und werden nicht neu bestimmt. Ein Ort nur mit Adresse wird geokodiert, und wenn wir einem Treffer nicht vertrauen, wird er abgelehnt statt geraten: Eine Unterkunft falsch auf einer Karte zu platzieren ist schlimmer, als sie als nicht auflösbar zu melden. Eine halbe Koordinate wird als Tippfehler behandelt, nicht als Lücke.

Erneutes Hochladen ist kostengünstig und sicher. Identifiers werden aus den Spalten abgeleitet, die dein Mapping als identifizierend markiert. Derselbe Export erzeugt daher dieselben Referenzen — erneutes Hochladen aktualisiert statt zu duplizieren.

Fehler

Status	Bedeutung
401	Access Token fehlt oder ist abgelaufen
403 vendor_data_requires_enterprise	Die Organisation befindet sich nicht im Enterprise-Tier
403	Deine Organisation ist nicht für Daten-Uploads aktiviert
404	Kein solcher Ingest für deine Organisation
409	Der Ingest befindet sich nicht in einem Zustand, der diesen Aufruf erlaubt — siehe Publish-Hinweise oben
413	Die Datei überschreitet das Upload-Limit
422	Datei oder Mapping konnten nicht gelesen werden; der Body nennt Zeilen und Gründe
429	Rate Limited — nach einer Pause erneut versuchen

Was als Nächstes kommt

Die API akzeptiert heute ein vollständiges Bundle. Sobald ein Mapping ein gespeichertes, wiederverwendbares Objekt ist, akzeptiert sie auch deinen eigenen Export plus eine Mapping-ID, sodass eine Integration die bereits erzeugte Datei senden kann, ohne sie vorher umzuformen. Eine Delta-API — Upsert und Delete per Natural Key mit einem since-Cursor — folgt demselben Weg.