オブジェクト・フィールド・レコード

データモデル。14 個の標準オブジェクト、5 系統 19 種類のフィールド、レコードが保持するもの、そして稼働中のオブジェクトの何が変えられるかを扱います。

オブジェクトはワークスペースが扱う物の種類です（取引先、見積、タスク）。フィールドはそのオブジェクトのレコードが保持する 1 つの情報です。レコードはその 1 件です。/objects 配下のすべてのエンドポイントはこの 3 つのいずれかを扱います。

標準オブジェクト

標準オブジェクトは 14 個あり、それぞれモジュールに属します。POST /bootstrap はワークスペースで有効なモジュールが所有するものを設置するため、ワークスペースがどのオブジェクトを持つかは何を有効にしているかで決まります。 再実行しても既に設置済みのものはそのまま残ります。

一覧を前提にせず GET /objects を読んでください。marketing にはこの API のエンドポイントが 1 つもないため、その 2 つのオブジェクトは存在しますがこの API からは到達できません。

ラベルは表示用の文字列であり、リクエストごとに翻訳するのではなく一度保存されます。キーで照合し、ラベルで照合しないでください。

activity（活動）と event（行動）は別のオブジェクトで、よく混同されます。activity は記録された接触で、経由したチャネル、結果、そしてリードの温度を持ちます。event は予定された打ち合わせで、種別とカレンダー上の表示を持ちます。

フィールドの種類

19 種類が 5 系統に分かれます。どの系統かが、書き込めるか、フィルターできるか、設定できるかを決めます。

13 のスカラー種類は 1 つの列に保存され、型以外の設定を持ちません。text、longtext、decimal、currency、percent、boolean、date、datetime、email、url、phone、user、address です。

2 つの選択種類 select と multi_select はフィールドが定義する一覧から値を取ります。multi_select は最大 200 個で、重複を拒否します。

relation は別のオブジェクトのレコードを指します。作成時に targetObjectId と cardinality を指定します。

formula は式ではなく 1 つの算術ステップを計算します。left、add・subtract・multiply・divide のいずれかの演算子、right で、両辺はキーで別のフィールドを指します。

2 つの仮想種類 rollup と days_since には列がありません。クライアントが他のレコードやフィールドから計算します。保存されず書き込めないため、これを含むレコード書き込みは field_not_scalar で拒否されます。

レコードが保持するもの

レコードは id、objectId、name、revision、createdAt、updatedAt、archivedAt、フィールドごとに 1 件の values、そしてオブジェクトがリレーションフィールドを持つ場合は relations を返します。

name と updated_at は予約されたフィルター・ソートキーで、上のレスポンスの形とは別の一覧です。ビューは updated_at で並び替え、レスポンスは updatedAt を返します。

空は 5 種類ではなく 1 つの状態です。 キーの不在、null、空文字列、空の multi_select、全部分が空白の住所はすべて同じもので、すべて値なしとして保存されます。どの形で送っても読み戻すと null になります。

select の選択肢はそれ自体が保存値です。 そのためフィールドが提供しない選択肢を書き込むと field_value_invalid で拒否されます。標準フィールドではこれは、選択肢一覧は追加されるだけで名称変更されないことを意味します。古い文字列が既存のレコードが保持している値だからです。

フィールドの作成と変更

オブジェクトやフィールドの追加には custom_objects モジュールが必要です。レコードの読み書きには不要です。

POST /objects/{objectId}/fields は系統ごとに異なる本文を取り、全部で 7 つの形があります。どれも key、label、required、visibleByDefault を持ち、選択系統は options（最大 200 個、各 1〜120 文字）を、リレーションは targetObjectId を追加します。

選択肢はフィールド作成時に決まります。 PATCH は key、label、required、targetObjectId、type を受け付け、options は受け付けません。つまりこの API を通して後から一覧を変える方法はありません。フィールドにレコードが入る前に決めてください。

visibleByDefault は一覧のメタデータです。誰も列を選んでいない状態で一覧がそのフィールドを表示するかどうかを決めます。誰がそのフィールドを読めるかとは無関係で、それは権限の話です。

リードの転換

リードは取引先と取引先責任者になります。GET /objects/{objectId}/records/{recordId}/conversion-matches は重複を作らず統合する候補を探します。

スキャンには上限があります。 partial: true はレコードを見尽くす前にスキャンが止まったことを意味するため、何も見つからないことは何も証明しません。partial の下での空の結果は「一致なし」ではなく「不明」として扱ってください。