Items
品目
GET /api/1/items — 品目一覧の取得
概要 指定した事業所に登録されている品目の一覧を取得します。取引や振替伝票の明細に付与する品目マスタとして参照する用途を想定しています。
注意点 使用設定（available）が false の品目も含めて返します。 start_update_date / end_update_date で品目の更新日を範囲指定して絞り込めます。JST の日付を yyyy-mm-dd で指定してください（どちらも指定日を含みます）。 品目コード（code）は、事業所の設定で品目コードを使用する設定にしている場合のみレスポンスに含まれます。設定が無効の場合は code キー自体が返りません。
パラメータ
- company_id*: integer(int64) - 事業所ID。取得対象の事業所を指定します。
- start_update_date: string - 更新日で絞り込む開始日 (yyyy-mm-dd, JST)。指定日を含む、それ以降に更新された品目を対象にします。
- end_update_date: string - 更新日で絞り込む終了日 (yyyy-mm-dd, JST)。指定日を含む、それ以前に更新された品目を対象にします。
- offset: integer(int64) - 取得レコードのオフセット (デフォルト: 0)。ページング用に、スキップする件数を指定します。
- limit: integer(int64) - 取得レコードの件数 (デフォルト: 50, 最小: 1, 最大: 3000)。1 回のリクエストで取得する上限件数を指定します。
レスポンス
品目一覧の取得に成功しました。
- items*: array[object] - 品目の一覧
POST /api/1/items — 品目の作成
概要 指定した事業所に新しい品目を作成します。作成された品目は使用設定（available）が true の状態で登録され、取引作成時などに指定できるようになります。
注意点 品目名（name）は事業所内で重複できません。既に同名の品目が存在する場合は 400 エラーになります。 品目コード（code）を利用するには、事業所の設定で品目コードを使用する設定にする必要があります。設定が無効の場合、code を指定しても無視され保存されません。 品目コード（code）は事業所内で重複できません。
リクエストボディ
- company_id*: integer(int64) - 事業所ID。品目を作成・更新する対象の事業所を指定します。 例:
1(最小: 1) - name*: string - 品目名 (30文字以内)。事業所内で重複できません。既に同名の品目が存在する場合は 400 エラーになります。 例:
新しい品目 - shortcut1: string - ショートカット１ (20文字以内)。Web画面などで品目を検索する際のキーワードとして使用します。更新時に省略した場合は未設定（null）に更新されます。 例:
NEWITEM - shortcut2: string - ショートカット２ (20文字以内)。Web画面などで品目を検索する際のキーワードとして使用します。更新時に省略した場合は未設定（null）に更新されます。 例:
202 - code: string - 品目コード (20文字以内、半角英数字・ハイフン・アンダースコアのみ)。事業所内で重複できません。事業所の設定で品目コードを使用する設定にしている場合のみ保存され、設定が無効の場合は指定しても無視されます。更新時に省略した場合は未設定（null）に更新されます。 例:
code001(パターン: ^[0-9a-zA-Z_-]+$)
レスポンス
品目の作成に成功しました。作成された品目を返します。
- item*: object
GET /api/1/items/{id} — 品目の取得
概要 指定した事業所の品目を 1 件取得します。品目ID（id）は品目一覧の取得 API で確認できます。
注意点 品目コード（code）は、事業所の設定で品目コードを使用する設定にしている場合のみレスポンスに含まれます。設定が無効の場合は code キー自体が返りません。 存在しないか既に削除された品目IDを指定した場合は 404 を返します。
パラメータ
- company_id*: integer(int64) - 事業所ID。取得対象の事業所を指定します。
- id* (path): integer(int64) - 品目ID。品目一覧の取得 API のレスポンスに含まれる id を指定します。
レスポンス
品目の取得に成功しました。
- item*: object
PUT /api/1/items/{id} — 品目の更新
概要 指定した事業所の品目を更新します。この API は品目の作成は行いません。品目コードをキーに更新（存在しない場合は作成）したい場合は PUT /api/1/items/code/upsert を利用してください。
注意点 リクエストボディで省略した任意項目（shortcut1・shortcut2・code）は未設定（null）に更新されます。値を維持したい場合は、現在の値も含めてすべての項目を指定してください。 品目名（name）は事業所内で重複できません。別の品目と同名になる更新は 400 エラーになります。 品目コード（code）は、事業所の設定で品目コードを使用する設定にしている場合のみ更新されます。設定が無効の場合、code を指定しても無視されます。 存在しない品目IDを指定した場合はエラーになります。品目IDは品目一覧の取得 API で事前に確認してください。
パラメータ
- id* (path): integer(int64) - 品目ID。品目一覧の取得 API のレスポンスに含まれる id を指定します。
リクエストボディ
POST /api/1/items と同じ
レスポンス
品目の更新に成功しました。更新後の品目を返します。
- item*: object
DELETE /api/1/items/{id} — 品目の削除
概要 指定した事業所の品目を削除します。
注意点 取引などで既に使用されている品目は削除できず、400 エラーになります。品目を無効にしたい場合は、Web 画面から使用設定（available）を「使用しない」に変更してください。 存在しないか既に削除された品目IDを指定した場合は 404 を返します。
パラメータ
- id* (path): integer(int64) - 品目ID。品目一覧の取得 API のレスポンスに含まれる id を指定します。
- company_id*: integer(int64) - 事業所ID。削除対象の品目が属する事業所を指定します。
レスポンス
品目の削除に成功しました。レスポンスボディはありません。
PUT /api/1/items/code/upsert — 品目の更新（存在しない場合は作成）
概要 品目コード（code）をキーに、指定した品目の情報を更新します。該当する品目が存在しない場合は新規作成します（upsert）。外部システムとの連携で、品目マスタを一括で登録・更新する用途を想定しています。
注意点 本 API を利用するには、事業所の設定で品目コードを使用する設定にする必要があります。設定が無効な事業所への呼び出しは 400 エラーになります。 item オブジェクト内で code を指定することはできません（品目コードは変更不可）。指定した場合は 400 エラーになります。リクエストボディ直下の code のみが有効です。 更新レスポンスは 200 OK、新規作成レスポンスは 201 Created で返ります。作成・更新のどちらが行われたかは HTTP ステータスコードで判別してください。 更新時、item オブジェクト内で省略した任意項目（shortcut1・shortcut2）は未設定（null）に更新されます。値を維持したい場合は、現在の値も含めてすべての項目を指定してください。 品目名（name）は事業所内で重複できません。別の品目と同名になる場合は ...
リクエストボディ
- code*: string - 品目コード (20文字以内、半角英数字・ハイフン・アンダースコアのみ)。更新・作成対象の品目を特定するキーです。このコードを持つ品目が存在する場合は更新し、存在しない場合は新規作成します。 例:
code001(パターン: ^[0-9a-zA-Z_-]+$) - company_id*: integer(int64) - 事業所ID。品目を更新・作成する対象の事業所を指定します。 例:
1(最小: 1) - item*: object - 品目に設定する内容。code（品目コード）はこのオブジェクト内には指定できません（品目コードは変更不可のため、指定すると 400 エラーになります）。
- name*: string - 品目名 (30文字以内)。事業所内で重複できません。既に同名の品目が存在する場合は 400 エラーになります。 例:
新しい品目 - shortcut1: string - ショートカット１ (20文字以内)。Web画面などで品目を検索する際のキーワードとして使用します。更新時に省略した場合は未設定（null）に更新されます。 例:
NEWITEM - shortcut2: string - ショートカット２ (20文字以内)。Web画面などで品目を検索する際のキーワードとして使用します。更新時に省略した場合は未設定（null）に更新されます。 例:
202
- name*: string - 品目名 (30文字以内)。事業所内で重複できません。既に同名の品目が存在する場合は 400 エラーになります。 例:
レスポンス
PUT /api/1/items/{id} と同じ