템플릿 및 필드

템플릿은 문서에서 추출하려는 필드의 저장된 재사용 가능 목록입니다. 템플릿의 id를 배치 처리 시작에 전달하면 매 호출마다 필드를 다시 나열할 필요가 없습니다. 또한 프리셋에서 템플릿을 빌드하거나, 템플릿을 완전히 건너뛰고 일회성 실행을 위해 임시 fields를 process에 직접 전달할 수도 있습니다.

템플릿 목록

저장된 템플릿을 각각의 전체 정렬된 필드 목록과 함께 반환합니다.

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.

템플릿 생성

한 엔드포인트에서 템플릿을 생성하는 두 가지 방법: 처음부터 생성 또는 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, 선택 사항	string	하나의 카테고리로 필터링합니다. 생략하면 모든 카테고리를 나열합니다.
`limit`	query, 선택 사항	integer	1–100. 기본값 50.
`page_token`	query, 선택 사항	string	이전 응답의 `next_page_token`에서 가져온 불투명 커서입니다.

가능한 오류

missing_api_key / invalid_api_key / plan_required — 오류 처리를 참조하세요.
invalid_parameter — 잘못된 limit 또는 page_token.

필드 목록 및 생성

fields는 제품 UI에서 "일치 규칙"이라고 부르는 것의 v1-public 이름입니다. 각 출력 열당 하나의 필드이며, 추출이 출력하는 순서대로 정렬됩니다. GET은 템플릿의 모든 필드를 sort_order로 이미 정렬된 상태로 반환합니다. POST는 새 필드를 끝에 추가합니다.

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

매개변수

이름	위치	유형	설명
`id`	path	integer	이 필드들이 속한 템플릿입니다.
`name`	body (JSON), POST 전용	string	필수. 이 템플릿 내에서 고유해야 합니다. 아래 오류를 참조하세요.
`format_requirement`	body (JSON), POST 전용	string, 선택 사항	예상 값 형식에 대한 자유 텍스트 힌트입니다.

가능한 오류

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를 교체합니다. 전체 교체이므로 부분 패치가 아니며, 하나만 변경되더라도 두 값을 모두 포함해야 합니다. DELETE는 필드를 제거합니다.

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

매개변수

이름	위치	유형	설명
`id`	path	integer	이 필드가 속한 템플릿입니다.
`field_id`	path	integer	업데이트 또는 삭제할 필드입니다.
`name`	body (JSON), PUT 전용	string	필수. 새 이름입니다.
`format_requirement`	body (JSON), PUT 전용	string, 선택 사항	새 형식 힌트입니다. 생략하면 빈 문자열로 설정되며, 변경되지 않은 상태로 남지 않습니다.

가능한 오류

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 중 이 템플릿에 속하지 않는 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