ビジネスデータをアップロード

Kaleidr は 組織独自のデータ — 物件、listing、room、rate、営業時間、document — と 世界に関する基本知識を組み合わせて質問に回答できます。

以下のすべての判断に影響するため、最初に明確にしておくべきことが 2つあります。

データはあなたの組織にのみ提供されます。 Application logic ではなく database level で分離されており、consumer 向け Kaleidr Map の回答に 利用されることはありません。利用可能なのは自社の B2B surface のみです。

言語モデルがあなたのデータを書き込むことはありません。 モデルは export の header と 少数の sample row を読み、column mapping を提案します。その後 deterministic code が その mapping をすべての row に適用します。mapping が間違っていれば form で 修正できます。モデルに 500 row を転記させると、後から自信に満ちた timestamp 付きで引用される price を捏造する機会が 500 回生まれ、捏造された price と本物を区別できなくなります。

利用条件

Vendor data upload は Enterprise-tier 機能です。upload UI と API はどちらも VENDOR_UPLOAD_TIERS = {"enterprise"} で gate されており、Pro-tier の owner または admin が upload call を行うと 403 vendor_data_requires_enterprise を受け取ります。

vendor-data UI は現在 production では無効 です（vendorDataEnabled config flag）。Enterprise を利用していて組織向けに有効化する必要がある場合は Kaleidr support にお問い合わせください。

さらに Enterprise の owner または admin role が必要です — これは project 単位ではなく organization-level data です。

2つの方法

Upload page。 kaleidr.com にサインインし、account area の Your Data を開きます（nav path /vendor-data、Billing と API keys の隣）。API と同じ4つの step — file 選択、提案された mapping の確認、理解された内容の preview、publish — を進みます。 spreadsheet ではこちらが適しています。

API は以下に記載しています。データがすでに push 可能な system に存在する場合や、upload を schedule したい場合に使用してください。

認証

すべての call は Cognito access token を bearer として受け取ります。session が すでに保持しているものと同じです：

Authorization: Bearer <access token>

platform API key ではありません。Platform key は integration を識別しますが、data upload は organization administration の操作であるため、role を持つ person として 認証されます。以下のすべての path は https://api.kaleidr.com 配下です。

Upload の構造

1つの upload は1つの ingest（job）と1つの release（versioned result）を生成します。release は publish されるまで draft で、publish 時には previous release が atomically supersede されます — reader が半分だけ適用された update を見ることはなく、 organization に data が存在しない時間もありません。

1. Mapping を提案

file の先頭 — header row と数行の data row のみを送信し、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 で slice されます — 大きい file を投稿しても model が見られる範囲は広がりません。

確認すべきなのは sample_result です。提案 mapping は表示される前に 自分の sample row に対して dry-run され、sample_result は section ごとに 何を produced したかを示します。もっともらしく見えるのに何も生成しない mapping は、 そうでなければ upload 後に初めて気付く可能性があります。

提案を適用できない場合でも errors 入りの 200 が返り、 5xx にはなりません。mapping は編集可能で、1つの column を直すだけで済みます。 errors は1回で分かるすべてを報告するため、missing required field と sheet に存在しない column name が、round trip ごとに1つずつではなく 同時に返されます。

upload 前に検出されるもの：すべての row に必要な field が欠けた section （stay_date, price_amount, units_available, place の name または timezone）、実在する IANA zone ではない {"const": …} timezone、3文字でない currency const、const container ではない object rule。これらは本来、upload 後に row ごとに1回失敗します。

ユーザー1人あたり1時間30 proposal に制限されています。

2. Preview を stage

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 は step 1 の返り値で、必要に応じて編集できます。すでに normalized 済みの JSON bundle または places-only CSV を 送る場合は省略してください。
• preview: true は publish せずに stage します — 初回 upload、および mapping を変更した場合には 強く推奨されます。
• org_id は任意で、default は自分が管理する organization です。

この call では Idempotency-Key が必須 です（8～128文字）。scope は organization ごとです。同じ key で retry すると2つ目を作らず、既存の 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 は flag を切り替えるのではなく job を再実行します。 同じ artifact を再度読み込み、同じ mapping を再適用するため、count と identifier は構造上 一致します — ただし geocoding は live call のため、preview 後に provider が coordinate を修正していれば異なる可能性があります。

ここでは Idempotency-Key を送らないでください。 この endpoint は受け付けず、 必要もありません。同じ ingest を2回 publish することはできません。最初の request が 手元では timeout したもののこちらで成功していた場合、retry は 409 — ingest_is_not_a_preview、または2つの試行が完全に重なった場合は publish_already_in_progress を返します。どちらも publish がすでに進行中であることを意味します。 retry すべき error ではなく success として扱ってください。

Release の一覧

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

?status= で任意に filter できます。同時に published となる release は organization ごとに必ず1つです。

Preview の期限切れ

承認されない preview は staging 完了時から 14日後 に retire されます。 delete ではなく superseded として mark されるため upload history には残りますが、 それ以降 publish はできず、再 upload が必要です。期限切れ preview を publish すると 409 no_previewed_release_to_publish を返します。

Field に関する注意

timezone はすべての place で必須で、重要です。 Rate と availability の回答は property の local calendar で計算されます — Sydney の hotel における "tonight" は server 上の "tonight" とは別の日になる可能性があります。export に本当に timezone column がない場合は、 constant を明示的に map してください：

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

default に任せず、意図的に指定してください。UTC 時間で運用する property では UTC が正しい一方、 そうでない property では微妙に誤りになります。そしてその誤りは stay window の端でしか 現れません。

timezone を省略した場合、または存在しない zone を指定した場合は、upload 後ではなく propose step で拒否されます。

coordinates がある場合は必ず提供してください。 lat/lng を持つ place はそのまま 使用されます — あなたの coordinates が authoritative であり、再計算はしません。 address のみの place は geocode され、confidence が低い match は guess するのではなく拒否 されます。property が map 上の誤った場所に配置されることは、 unresolvable と報告されるより悪いからです。coordinate が片方だけの場合は missing ではなく typo として扱います。

再 upload は低コストで安全です。 identifier は mapping が identifying として指定した column から 導出されるため、同じ export は同じ reference を生成します — 再 upload は duplicate ではなく update になります。

エラー

Status	Meaning
401	Access token がない、または expired
403 vendor_data_requires_enterprise	org が Enterprise tier ではない
403	organization で data upload が有効化されていない
404	organization に該当 ingest が存在しない
409	ingest がこの call を許可する state ではない — 上記 publish note を参照
413	file が upload limit を超えている
422	file または mapping を読み取れなかった。body に row と reason が含まれる
429	Rate limited — 少し待って retry

今後追加されるもの

現在 API は complete bundle を受け付けます。mapping が保存済みで再利用可能な object になれば、独自 export + mapping id も受け付けるようになり、 integration は現在生成している file を事前に reshaping せずそのまま送信できます。 その後、natural key ごとの upsert/delete と since cursor を持つ delta API が 同じ route に追加されます。