🌐
カスタムオプション管理API
概要
本APIにより、外部システムの人事マスタの変更（例: 役職名の改称・廃止・追加）を人手を介さずYESODの選択肢に自動反映できます。
対象は各テナントで追加したカスタムオプションのみです。YESOD標準で用意されている選択肢（標準オプション）や、標準オプションの名称を上書きしたもの（標準オプションの上書き）は対象外です。
📋 関連記事リクエストヘッダの共通仕様は「APIリクエストヘッダ」を、APIトークンの発行手順は「APIトークンの発行手順・削除手順」を参照してください。標準オプションを含めて選択肢の全体像を参照したい場合は「項目オプションAPI」（）を利用してください。全パラメータ・全エラーコードなどの正確な仕様は OPEN APIリファレンス を参照してください。本記事では実際に使う際によく参照する内容に絞って説明します。
⚠️ 注意（画面と同時に操作する場合）YESODの画面（オプション管理）を開いたまま本APIで作成・変更・無効化・有効化・一括置換を行い、その後に画面から保存すると、画面を開いた時点の内容で全体が上書きされます。その間にAPIで行った変更のうち、既存の選択肢への変更（名称変更・無効化など）は画面を開いた時点の状態に戻り（APIを再実行すれば元に戻せます）、APIで新規に追加した選択肢は削除されます（同じIDでは復元できません）。連携の実行中は、YESODの画面でのオプション編集は控えてください。
詳細
以降の例では、ID・コード値・名称はすべてサンプルです（役職項目に 001 部長・002 課長・003 係長 があるものとして記載しています）。
一覧の取得（コード値での検索を含む）
リクエスト（項目IDでの絞り込みは任意）
レスポンス（200）
コード値で検索する場合は のように指定します（レスポンスの形は同じ。attributeId と併用すると AND 条件）。無効化済みの選択肢（selectable=false）も含まれます。
💡 ポイントはコード値検索だけで使うと、別の項目や無効化済みの選択肢まで含めて横断的にヒットします。項目を特定して検索したい場合は も併せて指定してください。
1件取得
リクエスト
レスポンス（200）
追加
リクエスト（コード値・並び順・序列は任意。並び順を省略すると末尾に追加）
レスポンス（201。選択肢IDが採番され、並び順は末尾＝4 になった例）
変更（部分更新）
リクエスト（変えたい項目だけを送る。省略した項目は変更されない）
レスポンス（200。名称だけ変わり、コード値・並び順・序列は維持）
💡 ポイントは指定するとオブジェクト全体が置き換わります（ だけ送ると は未設定になります）。維持したい言語も含めて送ってください。
無効化
無効化は物理削除ではなく「選択不可」への切り替えです。データは削除されず、 が になります。
リクエスト（ボディ不要）
レスポンス（200。selectable が false になる）
無効化すると、YESODの各ロールに設定されているグループのデフォルトフィルタ（雇用形態・在籍状況の初期絞り込み条件）から該当オプションが除去されます。この除去は有効化しても元には戻りません（フィルタ設定はYESODの画面で付け直してください）。
有効化
無効化済みのカスタムオプションを再度選択可能な状態に戻します。
リクエスト（ボディ不要）
レスポンス（200。selectable が true に戻る）
有効化した結果、同一項目内で他の有効な選択肢と が重複する場合は400になります。どちらの操作も既にその状態であれば何も変更せず200を返します（冪等）。
一括置換（洗い替え）
項目単位で「あるべき全量リスト」を送り、突合キー（コードまたは選択肢ID）をもとに、「あれば更新・なければ作成・リストにないものは無効化」を一度に実行します（外部システムのマスタ全量インポート用）。
リクエスト（key=code。残したい選択肢の全量リストを送る）
001 を「部長」から「部課長」に改称・002 を廃止・004 係長補佐を追加の例
レスポンス（200。各選択肢に result が付く。リストに載せた順に並び、リスト外＝無効化されたものが後続）
- 並び順（order）・序列（hierarchy）は省略したため既存の値が維持されています（新規の 004 は末尾＝4）。リストの並びを反映したい場合は各要素の order に 1 から連番を指定します
- 001 の en_US が消えているのは、labels がオブジェクト全体で置き換わるためです（維持したい言語も含めて送ってください）。002 はリスト外のため名称は変わらず無効化だけされています
- コード値未設定の選択肢（画面から手動作成したものを含む）も含めて置換したい場合は、 を指定します。この場合は対象項目のすべての選択肢が置換の対象になり、リクエストの各要素で を省略すると新規作成、 を指定するとその値へ更新（省略時は既存値を維持）されます
💡 ポイントリストを組み立ててから本APIを実行するまでの間にYESODの画面で新しいカスタムオプションが追加された場合、そのカスタムオプションはリストに載っていない扱いとなり無効化されます（ で判別でき、再度リストに含めて実行すれば元に戻せます）。また、空リストを送ると管理対象の有効な選択肢が全件無効化されるため、実行前にリクエスト内容をよく確認してください。
どちらのkeyを使うか迷ったら：外部システムのマスタが唯一の正で、画面から手動作成した選択肢を許容しない（すべてAPI管理にしたい）場合は 。画面からの手動作成分と共存させたい場合は を選んでください。
エラーレスポンス
エラー時は （エラー種別を表す値、例：、）と （エラー内容の説明）を含むJSON形式でレスポンスが返却されます。個別のエラーコード・発生条件の一覧は OPEN APIリファレンス を参照してください。
主な仕様
- 無効化は物理削除ではなく「選択不可」への切り替え。無効化した選択肢はAPIで有効化できます
- 無効化時は画面操作と同じく、グループのデフォルトフィルタ（雇用形態・在籍状況）からも該当選択肢が外れます
- 操作対象はカスタムオプションのみ。YESOD標準の選択肢は参照・操作とも対象外（標準を含む全体像が必要な場合は既存の「項目オプションAPI」を利用）
- 一括置換は、項目単位で「あるべき全量リスト」を受け取り、突合キー（コードまたは選択肢ID）をもとに、「あれば更新・なければ作成・リストにないものは無効化」を一度に実行します（外部システムのマスタ全量インポート用）。突合キーがコードの場合、コード未設定の選択肢（画面で手動作成したもの）は影響を受けません
- 一括置換で省略した項目（コード・並び順・序列）は既存の値をそのまま維持します（外部システムが管理していない項目が置換のたびに消えないようにするため）
- 各選択肢について「追加・更新・再有効化・無効化・変更なしのどれになったか」がレスポンスで返るため、外部システム側で取り込み結果を確認できます