共通の約束

すべての操作に共通する取り決めです。個別の操作の詳細は API リファレンスを参照してください。

エラー

失敗の応答は共通の封筒で返ります。code は次の 21 種類です。

VALIDATION_ERROR
INVALID_CURSOR
METHOD_NOT_ALLOWED
AUTHENTICATION_REQUIRED
INVALID_CREDENTIAL
FORBIDDEN
NOT_FOUND
DATA_TYPE_NOT_FOUND
DATA_NOT_FOUND
CONFLICT
IDEMPOTENCY_KEY_REUSED
PRECONDITION_FAILED
PAYLOAD_TOO_LARGE
UNPROCESSABLE_ENTITY
RATE_LIMITED
SINGLE_PENDING
INTERNAL_ERROR
BAD_GATEWAY
SERVICE_UNAVAILABLE
GATEWAY_TIMEOUT
PRECONDITION_REQUIRED

一覧取得とページング

ページングする一覧が共通して受け取るのはlimit cursor です。絞り込みの引数は operation ごとに違うので、API リファレンスの各 operation を参照してください。

ページングを持たず、全件をまとめて返す operation もあります。そのうちいくつかは深さの上限などで打ち切ることがあります。どちらなのかは各 operation の説明に書いてあります。

続きは応答に含まれるカーソルを cursor へ渡して取得します。カーソルは不透明な文字列で、組み立てたり分解したりしないでください。古いカーソルや改変したカーソルは INVALID_CURSOR になります。

冪等性

ほとんどの状態変更操作で Idempotency-Key ヘッダが必須です。同じキーで同じ内容を送り直すと、二重に実行されず最初の結果が返ります。同じキーで違う内容を送ると IDEMPOTENCY_KEY_REUSED になります。リトライではキーを変えないでください——変えると二重起票になります。

次の操作は Idempotency-Key を受け取りません:POST /v1/qa/chat

レート制限

上限に達すると RATE_LIMITED が返ります。応答のヘッダに従って待ってから再試行してください。待たずに再試行し続けると、回復が遅くなります。

フォームの選択肢・既定値・入力連動

フォームのoptionsSource、effects[].source、defaultValueSourceは、値そのものではなくクライアントが解決する取得元を表します。取得には各操作の権限が必要です。権限不足や取得失敗を「選択肢が存在しない」と扱わず、入力を保ったままエラーを表示してください。

フォームの指定	公開APIと設定方法
`optionsSource: banks`	`GET /v1/banks`の全ページから`code`を値、`name`を表示名にする
`effects[].source: bank_branches`	選択した銀行コードで`GET /v1/banks/{bankCode}/branches`を全ページ取得する。銀行変更時は支店の値と候補をクリアする
`effects[].source: bank_name`	選択した銀行の`name`（または`GET /v1/banks/{code}`の`name`）を効果の対象フィールドへ入れる。非表示フィールドも送信データに含める
`effects[].source: postal`	`GET /v1/postal-addresses/{postalCode}`の住所情報を、フォームが指定する対象フィールドへ対応付ける
`optionsQuery`	`GET /v1/application-types/{code}/form-options?fieldKey={fieldKey}`を使う。`optionsSource: banks`の取得には使わない
`defaultValueSource: me:legal_name_kana`	`GET /v1/me`の`user.id`で`GET /v1/employees/{id}`を取得し、`values.seiKana`と`values.meiKana`の非空値を半角スペースで結合して初期値の候補にする。取得できない値を推測で補わない

給与口座のaccountHolderなどの既定値は、クライアントがdataに設定して送ります。必須値を省略すると提出時に検証エラーになります。現在の給与口座フォームでは口座名義を編集できるため、本人が口座の表記に合わせて確認・修正できます。既定値候補は戸籍名・口座名義の一致を保証しません。 readOnlyがあるフィールドでは編集UIを抑止しますが、送信を省略する指定ではなく、サーバーが自動補完したり任意の値の送信を一律に拒否したりする指定でもありません。

GET /v1/application-types/{code}/field-effect-values/{targetId}は、申請の対象選択で得た対象IDに紐づく値を取得する操作です。銀行から支店候補を取得する操作には使いません。上表にない取得元を、名前から推測したURLへ変換しないでください。

申請フォームのdataに対する検証エラーでは、fieldErrors[].pathはdata内を基準にしたJSON Pointerです。例えば/accountHolderはdata.accountHolderを指し、/data/accountHolderではありません。