上传您的业务数据
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。