用語集
パス、スコープ、拒否理由に現れる用語を、正確さを保てる最短の定義で。そして同じものに読めてしまう組み合わせを並べます。
API がパス、スコープ名、拒否の reason で使う用語を一度だけ定義します。
モデル
| 用語 | 何か |
|---|---|
| オブジェクト | ワークスペースが扱う物の種類。取引先、見積、タスクなど。標準は 14 個で、custom_objects モジュールがあれば追加できます |
| フィールド | オブジェクトのレコードが保持する 1 つの情報。19 種類のいずれかです |
| レコード | オブジェクトの 1 件 |
| リレーション | 値が別のオブジェクトのレコードであるフィールド |
| リビジョン | 現在の状態を読んだことを証明するために書き込みが返すカウンター |
| ビュー | レコード一覧に適用する条件とソート。それぞれ最大 10 件と 2 件 |
| カーソル | 生成時の順序を運ぶ不透明なページ位置 |
| ワークスペース | トークンの組織が所有するもの。1 トークン、1 ワークスペース |
| モジュール | ワークスペースが有効にできる製品の一部。8 個あり、互いに依存しません |
| アクション | 権限が付与される単位。エンドポイントの OAuth スコープはそのアクションそのものです |
商取引
| 用語 | 何か |
|---|---|
| 商品 | 販売対象。原価とは独立しています |
| 価格表 | 1 つの通貨の名前付き価格一覧。価格は取り込んだエントリとして入ります |
| 価格合意 | 1 つの取引先を 1 つの価格表に期間付きで結び付けるもの。複数該当する場合は priority が高いものが勝ち、最小数量の大きい方が同点を破り、両方同じなら price_agreement_ambiguous で拒否されます |
| 仕入原価 | 事業が支払った額。販売額とは別に記録され、一部の価格決定方式がこれを読みます |
| 見積 | 取引先に対する価格付きの提示。通貨と、ある日付時点の為替レートを持ちます |
| 見積バージョン | 凍結された番号付きの見積改訂。専用のルートから読み戻せます |
| 見積ドラフト | まだ凍結されていないバージョン。開いている間、見積の改訂は quote_draft_open で拒否されます |
| 売上総利益率 | 売上に対して計算される率 |
| マークアップ | 原価に対して計算される率。利益率とは同じ数字になりません |
同じに読めてしまう組み合わせ
| この 2 つは | 同じではありません |
|---|---|
| オブジェクトとレコード | オブジェクトは種類、レコードはその 1 件。/objects/{objectId}/records/{recordId} は両方を指します |
| 活動と行動 | 活動はチャネルと結果を持つ記録された接触、行動は予定された打ち合わせ |
| リビジョンとバージョン | リビジョンはほぼすべてが持つ同時実行制御のカウンター、バージョンは見積の意図的に凍結されたスナップショット |
| 価格表と価格合意 | 価格表は価格を持ち、価格合意はどの取引先がいつどの価格表を使うかを決めます |
| モジュールとスコープ | モジュールはワークスペースに設定され要求できません。スコープはトークンに付与され設定できません |
| アーカイブと削除 | アーカイブは id とリンクを残すため、読み取りはそのレコードを指せます。この API はレコードを削除しません |
field_required と permission_required |
前者は値の欠落、後者はスコープまたは役割の欠落 |
見覚えておくべき拒否
拒否はサーバーが名前を付けられるとき reason を伴います。よく出るものは次のとおりです。
| reason | 意味 |
|---|---|
record_stale、settings_stale、quote_stale |
送ったリビジョンが現在のものではない |
cursor_ordering_mismatch |
カーソルが別の順序の下で生成された |
filter_unsupported_for_field |
その演算子はそのフィールドの種類に適用できない |
order_field_unsupported |
そのフィールドには並び替えの基準になる単一の値がない |
field_not_scalar |
列を持たない種類に対して書き込みが値を含んでいた |
feature_disabled |
ワークスペースがそのモジュールを有効にしていない |
permission_required |
トークンのスコープかメンバーの役割が許可していない |
workspace_not_initialized |
標準オブジェクトがまだ設置されていない |
workspace_session_required |
そのパスはこの API ではなく Web アプリケーションのもの |
エラーが拒否の形と、再試行の価値があるものを扱います。