規約

冪等性キー、カーソルページネーション、楽観的リビジョン、リクエスト制限。文書のための保証ではなく、サーバーが実際にどう振る舞うかを記述します。

すべてのエンドポイントがこれらを共有します。以下はサーバーが実際に行うことであり、文書のために作られた保証ではありません。保証が想像より狭い箇所は、そのことを明記します。

冪等性

ほとんどの変更操作には Idempotency-Key ヘッダー（8〜128 文字）が必要で、付けないリクエストは 400 で拒否されます。必要なエンドポイントはリファレンスに記載されています。4 つの POST エンドポイントは必要としません。何も書き込まない 2 つの価格プレビュー、ダウンロードリンク、そして POST /api/v1/bootstrap です。後者は標準オブジェクトをインストールしますが、すでにインストール済みのオブジェクトはそのまま残されるため繰り返しても安全です。

同じキーと同じボディを送ると、処理が二重に実行されることなく最初の応答が再生されます。同じキーで異なるボディを送ると、409 と理由 idempotency_key_reused で拒否されます。

この保証には知っておくべき 2 つの限界があります。

レシートは利用者とアクションごとのスコープです。 グローバルではありません。利用者、アクション、キーの 3 つを合わせたキーで管理されるため、別の人が使った同じキー、あるいは自分が別のエンドポイントに対して使った同じキーは、別のコマンドになります。キーは自分が行っていることの範囲で一意であれば十分です。

再生は保存された本文を返します。 リリースでエンドポイントのレスポンス形状が変わった場合、それ以前に発行されたキーは古い本文を再生します。これは保存された応答を再生することに内在する性質であり、キーをセッション全体で使い回すのではなく 1 つのリクエストに属させる理由です。

ページネーション

一覧には 2 種類あり、ページングの方法が異なります。

ほとんどの一覧（商品、価格表、見積）は limit と after を取り、nextCursor を返します。次のページには nextCursor を after として渡し、null になったら終了します。

レコードの一覧はより多くを取ります。limit、dir、orderBy または view、relatedTo と via、そして cursor または after です。4 つの組み合わせは 400 で拒否され、これらはパラメータ一覧では表現できません。

• via には relatedTo が必要
• orderBy と view は併用できない
• cursor には orderBy か view のいずれかが必要
• after はそのどちらとも併用できない。順序付きのクエリは cursor でページングする

カーソルはそれを生成した順序に属します。 順序 — ソート、方向、関連レコードのフィルター、ビュー — はカーソルの内部に入っています。ビューが変わった後にカーソルを再利用すると、正しそうに見えて実際は違うページを返すのではなく、cursor_ordering_mismatch で明示的に失敗します。順序が変わったら最初のページから取り直してください。

total は最初のページでのみ数えられます。 after も cursor もないリクエストは件数を返し、以降のページは total: null を返します。件数は毎ページではなく一度だけ支払われるため、表示したい場合は最初のページの値を保持してください。

リビジョン

レコード、オブジェクト、項目、保存済みレポート、商取引ポリシーは revision を持ちます。更新は読み取った時点のリビジョンを送り、古いものは 409 で拒否されます。

これはロックではなく楽観的同時実行制御です。考えている間、何も保持されません。読み取り、読み取ったリビジョンを送り、拒否されたら読み直してください。

リクエスト制限

リクエストボディは 1 MB までです。例外はノート画像のアップロードで、こちらは 4 MB です。この制限はルートの実行前に適用されるため、過大なリクエストはどのエンドポイント宛てであっても 413 で拒否されます。

ヘッダー

X-CRM-CSRF は送る必要がありません。これは Web アプリケーションが自身の Cookie セッションでの書き込みに使うものです。Bearer トークンのリクエストはその経路を通らず、これを必要としません。資格情報付き CORS も同様にアプリケーション自身のオリジンのみを許可しており、ブラウザのオリジンを送らないサーバー間呼び出しには関係しません。

日付と金額

タイムスタンプは UTC の ISO 8601 文字列です。日付のみの項目 — 仕入日、スケジュールの開始日と終了日 — は YYYY-MM-DD です。

金額は常に文字列で、数値ではありません。 合計、単価、税、割引は "1234.56" のような文字列で届きます。どの値も二進浮動小数点を通らないようにするためです。十進数を扱うライブラリで解析し、数値として加算しないでください。