上傳您的業務資料
Kaleidr 可以結合您組織自己的資料 — 包括房產、listing、room、rate、營業時間與 document — 以及其對世界的基礎知識來回答問題。
在其他內容之前，有兩點值得先說明，因為它們會影響下面的每一個 決定。
您的資料只會提供給您的組織。 它們在 database level，而不是 application logic 層面進行隔離，並且絕不會進入面向消費者的 Kaleidr Map 回答中。它們只會出現在您自己的 B2B surface。
語言模型絕不會寫入您的資料。 它會 讀取 export 的 header 與少量 sample rows，並提出一個 column mapping；接著由 deterministic code 將該 mapping 套用到每一 row。錯誤的 mapping 只需要您在 form 中 修正即可。讓模型轉錄 500 row，相當於提供 500 次機會去虛構一個 price， 而這個 price 之後可能帶著看似可信的 timestamp 被引用，並且無法與真實 price 區分。
可用性
Vendor data upload 是 Enterprise-tier 功能。upload UI 與
API 都會檢查 VENDOR_UPLOAD_TIERS = {"enterprise"} — Pro-tier 的 owner
或 admin 發起任何 upload call 時都會收到 403 vendor_data_requires_enterprise。
vendor-data UI 目前在 production 中處於停用狀態（vendorDataEnabled
config flag）。如果您使用 Enterprise 並需要為組織啟用它，請聯絡
Kaleidr 支援。
此外，還需要 Enterprise owner 或 admin role — 這是 organization-level data，而不是每個 project 單獨的資料。
兩種方式
上傳頁面。 登入 kaleidr.com，在帳戶區域開啟
Your Data（nav path /vendor-data，位於 Billing
與 API keys 旁邊）。它會按照與 API 相同的四個步驟進行：選擇 file、檢查
建議的 mapping、preview 系統理解的內容，然後 publish。這是
spreadsheet 最適合的方式。
API 說明如下。若資料已存在於可以 push 的 system 中，或您希望依排程進行 upload，請使用 API。
身分驗證
所有 call 都使用 Cognito access token 作為 bearer，也就是您的 session 已經持有的同一個 token：
Authorization: Bearer <access token>
不是 platform API key。Platform key 用於識別 integration；上傳資料則是
organization administration 操作，因此以擁有 role 的個人身分
進行驗證。下面所有 path 都位於 https://api.kaleidr.com。
Upload 的結構
一次 upload 會產生一個 ingest（job）與一個 release（versioned
result）。release 在 publish 前為 draft，publish 時會
atomically supersede 上一個 release — reader 永遠不會看到只套用一半的 update，也不會存在
組織完全沒有資料的時間窗口。
1. 提議 mapping
只傳送 file 的開頭 — header row 與少量 data rows，而不是整個 export。
| Method | Path | Body | Returns |
|---|---|---|---|
| POST | /inference-api/vendor/mapping/propose | { csv_head } | { mapping_spec, columns, sample_result, notes, errors[] } |
csv_head 上限為 16 KB，且 sample 在 server-side 進行截取 — 傳送
更大的 file 不會增加 model 所看到的內容。
sample_result 是最值得檢查的部分。系統會先對您自己的
sample rows 執行 proposed mapping 的 dry-run，再顯示給您；sample_result 會報告每個 section
實際產生了什麼。否則，一個看起來合理但沒有任何產出的 mapping
可能要到 upload 後才會被發現。
如果 proposal 無法套用，您仍會取得帶有 errors 的 200，
而不是 5xx。mapping 可以編輯，整個互動只需要修正一個 column。
errors 還會一次回報所有可以判斷的問題 — 例如 missing required field 與
sheet 中不存在的 column name 會一起出現，
而不是每次 round trip 只出現一個。
在 upload 前即可發現的問題包括：section 缺少每一 row 都需要的 field
（stay_date, price_amount, units_available, place 的 name 或
timezone）、{"const": …} timezone 不是有效 IANA zone、currency
const 不是三個字母，以及任何不是 const container 的 object rule。
否則這些問題會在 upload 後每 row 失敗一次。
限制為每位使用者每小時 30 個 proposal。
2. Stage preview
| 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必須以.json或.csv結尾。artifact是 raw file text。source為csv、json或manual。mapping_spec是步驟 1 的傳回值，也可以進行編輯。如果傳送的是已 normalized 的 JSON bundle 或僅包含 places 的 CSV， 可以省略它。preview: true會只 stage 而不 publish — 強烈建議用於首次 upload， 以及任何 mapping 變更。org_id為選用；預設使用您所管理的 organization。
此 call 必須提供 Idempotency-Key（8–128 個字元），而且會依
organization 限定。使用相同 key 重試會傳回既有 ingest，
而不是建立第二個。如果您在修改 mapping 後有意重新 stage，請使用一個新的 key —
因為這是真正不同的 request，而從 file 派生的 key 會將使用舊 mapping
建立的 ingest 傳回給您。
3. 查看狀態
| Method | Path | Returns |
|---|---|---|
| GET | /shared-api/vendor-data/ingests/{ingest_id} | { status, attempts, row_counts, error_report, created_at, started_at, finished_at } |
status 會從 pending → running → succeeded 或 failed。成功時，
row_counts 會包含系統理解的內容 — "47 places, 312 rates" — 而
error_report 會列出無法讀取的 row 與各自原因。
4. Publish
| Method | Path | Returns |
|---|---|---|
| POST | /shared-api/vendor-data/ingests/{ingest_id}/publish | { ingest_id, release_id, status, status_url, dispatched } |
僅適用於使用 preview: true stage 且成功完成的 ingest。
Publish 會重新執行 job，而不是只切換一個 flag。 它會重新讀取同一個 artifact，並重新套用同一個 mapping，因此 counts 與 identifiers 從結構上保持一致 — 但 geocoding 是 live call，因此如果 provider 在 preview 之後修正了某個 coordinate，它可能會不同。
不要在這裡傳送 Idempotency-Key。 此 endpoint 不接受該值，
也不需要它：相同 ingest 不可能 publish 兩次。如果第一個 request 在您這邊
逾時，但在我們這邊已成功，重試會傳回 409 —
ingest_is_not_a_preview，或者當兩次嘗試完全重疊時傳回 publish_already_in_progress。
兩者都表示您的 publish 已經在進行。
應將它們視為成功，而不是需要重試的錯誤。
列出 releases
| Method | Path | Returns |
|---|---|---|
| GET | /shared-api/vendor-data/releases | [{ id, status, published_at, superseded_at, created_at }] |
可使用 ?status= 選擇性篩選。每個 organization 同一時間只能有一個 release
處於 published。
Preview 會過期
從 staging 完成開始計算，未被批准的 preview 會在 14 天後退役。
它會被標記為 superseded，而不是刪除，因此 upload 仍保留在歷史中 —
但不能再 publish，需要重新 upload。publish 已過期 preview 會傳回
409 no_previewed_release_to_publish。
欄位說明
每個 place 都必須提供 timezone，而且它很重要。 Rate 與 availability
回答是根據房產所在地的 local calendar 計算 — Sydney 飯店的 "tonight"
可能與 server 上的 "tonight" 是不同日期。如果您的 export 確實
沒有 timezone column，請明確 map 一個 constant：
{ "timezone": { "const": "UTC" } }
請刻意指定，而不是讓它使用 default。對依 UTC 時間營運的 property 而言，UTC 是正確答案， 但對不是如此的 property 則會產生細微錯誤；這種錯誤通常只會出現在 stay window 的 邊界。
省略 timezone 或指定不存在的 zone，會在 upload 前的
propose step 就被拒絕。
如果有 coordinates，請提供。 帶有 lat/lng 的 place 會按原值
使用 — 您的 coordinates 是 authoritative，我們不會重新推導。
只有 address 的 place 會進行 geocode；如果我們對 match 沒有足夠信心，就會
拒絕而不是猜測：把 property 錯誤放置在地圖上，比回報無法解析更糟。
只有一半 coordinate 時，會被視為 typo，而不是缺少資料。
重新 upload 成本低而且安全。 Identifiers 根據 mapping 指定為 identifying 的 columns 產生，因此相同 export 會取得相同 reference — 重新 upload 會更新，而不是產生 duplicate。
錯誤
| Status | Meaning |
|---|---|
| 401 | Access token 缺少或 expired |
403 vendor_data_requires_enterprise | org 不屬於 Enterprise tier |
| 403 | 您的 organization 未啟用 data upload |
| 404 | 您的 organization 中不存在該 ingest |
| 409 | ingest 目前 state 不允許此 call — 請參閱上方 publish 說明 |
| 413 | file 超過 upload limit |
| 422 | 無法讀取 file 或 mapping；body 會列出 row 與原因 |
| 429 | Rate limited — 暫停後重試 |
即將推出
目前 API 接受完整 bundle。一旦 mapping 成為已儲存、可重複使用的
object，它還會接受您自己的 export 加 mapping id，如此
integration 就能直接傳送既有輸出的 file，而不需要先 reshape。
之後還會沿用相同路徑推出 delta API — 依 natural key 進行 upsert 與 delete，並帶有 since cursor。