テンプレート＆フィールド

テンプレートは、ドキュメントから抽出したいフィールド（出力列ごとに1つ）を保存して再利用できるリストです。テンプレートのidをバッチ処理の開始に渡すことで、毎回フィールドを再指定する必要がなくなります。組み込みのプリセットからテンプレートを作成することも、テンプレートを完全にスキップしてアドホックなfieldsを直接processに渡し、1回限りの実行を行うこともできます。

テンプレート一覧

保存済みのテンプレートを、各テンプレートの完全なフィールドリスト（順序付き）とともに返します。

GET /api/v1/templates

パラメータ

名前	場所	型	説明
`limit`	クエリ（省略可）	整数	1～100。デフォルトは50。
`page_token`	クエリ（省略可）	文字列	前回のレスポンスの`next_page_token`から取得するオペークカーソル。ページネーションを参照。

発生するエラー

missing_api_key / invalid_api_key / plan_required — エラーハンドリングを参照してください。
invalid_parameter — limitまたはpage_tokenが不正です。

テンプレートを作成する

1つのエンドポイントでテンプレートを作成する方法は2つあります。ゼロから作成する方法（base_template_idを使用して別のテンプレートのフィールドをオプションで複製）と、preset_idを使用して組み込みプリセットから作成する方法です。

POST /api/v1/templates

パラメータ

名前	場所	型	説明
`name`	body (JSON)	string	`preset_id`が指定されていない場合は必須です（指定された場合はプリセットの名前が使用され、その名前のテンプレートが既に存在する場合はタイムスタンプサフィックスで重複回避されます）。
`preset_id`	body (JSON)	string, オプション	組み込みプリセットからテンプレート（およびそのフィールド）を作成します。有効なIDについてはプリセット一覧を参照してください。
`base_template_id`	body (JSON)	integer, オプション	`preset_id`が指定されていない場合のみ使用されます。既存のテンプレートのフィールドを新しいテンプレートに複製します。

発生するエラー

missing_api_key / invalid_api_key / plan_required — エラーハンドリングを参照してください。
missing_parameter (param: "name") — nameとpreset_idの両方がありません。
invalid_parameter (param: "name") — この名前のテンプレートが既に存在します（プリセット以外の作成パスのみ）。
invalid_parameter (param: "preset_id") — 不明なプリセットIDです。
internal_error

テンプレートの削除

テンプレートとそのすべてのフィールドを削除します（カスケード — 別途クリーンアップ呼び出しは不要）。過去のprocess呼び出しでこのテンプレートを使用したドキュメントには影響しません。既に抽出された結果は変更されません。

DELETE /api/v1/templates/{id}

パラメータ

名前	場所	型	説明
`id`	path	integer	削除するテンプレート。

発生しうるエラー

missing_api_key / invalid_api_key / plan_required — エラーハンドリングを参照。
template_not_found
internal_error

プリセット一覧

一般的なドキュメントタイプ（請求書、領収書、銀行取引明細書など）向けの組み込みフィールドリストです。プリセットのidをテンプレート作成のpreset_idとして渡すと、フィールドを手動で列挙しなくても動作するテンプレートを取得できます。プリセットは静的設定であり、データベース行ではありません。APIを通じて作成、編集、削除することはできません。

GET /api/v1/presets

パラメータ

名前	場所	型	説明
`category`	query, optional	string	カテゴリでフィルタリング（例：`"Finance & Accounting"`）。省略すると全カテゴリを表示。
`limit`	query, optional	integer	1～100。デフォルトは50。
`page_token`	query, optional	string	前回のレスポンスの`next_page_token`から取得したオペークカーソル。

発生しうるエラー

missing_api_key / invalid_api_key / plan_required — エラーハンドリングを参照してください。
invalid_parameter — limitまたはpage_tokenが不正です。

フィールドの一覧取得と作成

fieldsは、製品UIで「マッチルール」と呼ばれるもののv1-public名です。出力列ごとに1つのフィールドが、抽出時に出力される順序で並びます。GETはテンプレート上のすべてのフィールドをsort_orderでソートして返します。POSTは新しいフィールドを末尾に追加します。

GET POST /api/v1/templates/{id}/fields

パラメータ

名前	場所	型	説明
`id`	パス	整数	これらのフィールドが属するテンプレート。
`name`	ボディ（JSON）、POSTのみ	文字列	必須。このテンプレート内で一意である必要があります。以下のエラーを参照してください。
`format_requirement`	ボディ（JSON）、POSTのみ	文字列、オプション	期待される値の形式に関する自由形式のヒント（例：`"YYYY-MM-DD"`、`"Number"`）。

発生しうるエラー

missing_api_key / invalid_api_key / plan_required — エラーハンドリングを参照してください。
template_not_found
missing_parameter（param: "name"） — POSTのみ。
duplicate_field_name — このnameを持つフィールドがすでにこのテンプレートに存在します。
internal_error

フィールドの更新と削除

PUT はフィールド名を変更し（format_requirement も置き換えます）— 部分更新ではなく完全置換のため、1つだけ変更した場合でも両方の値を含める必要があります。DELETE はフィールドを削除します。

PUT DELETE /api/v1/templates/{id}/fields/{field_id}

パラメータ

名前	場所	型	説明
`id`	パス	整数	このフィールドが属するテンプレート。
`field_id`	パス	整数	更新または削除するフィールド。
`name`	ボディ (JSON)、PUTのみ	文字列	必須。新しい名前。
`format_requirement`	ボディ (JSON)、PUTのみ	文字列、オプション	新しい形式ヒント — 省略すると空文字列にクリアされ、変更なしのままにはなりません。

発生しうるエラー

missing_api_key / invalid_api_key / plan_required — エラーハンドリングを参照してください。
template_not_found — テンプレートが存在しないか、あなたのものではありません（または、その旨のメッセージとともに、field_id がこのテンプレートに存在しません）。
missing_parameter (param: "name") — PUTのみ。
duplicate_field_name — PUTのみ。このテンプレート上の別のフィールドがすでに持っている名前に変更しようとした場合。
internal_error

フィールドの並び替え

フィールドの順序を明示的に設定します。これにより、line_items および Excel/Word エクスポートにおける出力列の順序が決まります。リスト内にこのテンプレートに属さない ID が含まれている場合、リクエスト全体を拒否するのではなく、暗黙的に無視されます。

PATCH /api/v1/templates/{id}/fields/order

パラメータ

名前	場所	型	説明
`id`	path	integer	並び替え対象のテンプレート。
`field_ids`	body (JSON)	array of integers	このテンプレート上のすべてのフィールドIDを、表示したい順序で指定します。必須。

発生しうるエラー

missing_api_key / invalid_api_key / plan_required — エラーハンドリングを参照してください。
template_not_found
invalid_parameter (param: "field_ids") — 整数のリストではありません。
internal_error