참조

템플릿 및 필드

템플릿은 문서에서 추출하려는 필드의 저장된 재사용 가능 목록입니다(출력 열당 하나의 필드). 템플릿의 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이 잘못되었습니다.

템플릿 생성

한 엔드포인트에서 템플릿을 만드는 두 가지 방법이 있습니다: 처음부터 만들거나(base_template_id로 다른 템플릿의 필드를 선택적으로 복제), preset_id로 내장 프리셋에서 생성하는 것입니다. 계정당 템플릿은 30개로 제한되며, 한도에 도달하면 새 템플릿을 만들기 전에 기존 템플릿을 삭제하세요.

POST /api/v1/templates

매개변수

이름위치유형설명
name본문 (JSON)문자열preset_id가 주어지지 않으면 필수입니다(주어진 경우 프리셋의 자체 이름으로 대체되며, 이미 같은 이름의 템플릿이 있으면 타임스탬프 접미사로 구분됩니다).
preset_id본문 (JSON)문자열, 선택 사항내장 프리셋에서 템플릿(및 해당 필드)을 생성합니다 — 유효한 ID는 프리셋 목록을 참조하세요.
base_template_id본문 (JSON)정수, 선택 사항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입니다.
  • template_limit_reached — 이 계정의 템플릿 30개 한도에 도달했습니다.
  • internal_error

템플릿 설정 업데이트

템플릿의 전역 형식 요구 사항(각 필드의 자체 요구 사항 위에 적용됨)과 다중 페이지 병합 구성을 설정합니다. 동일한 논리적 레코드(다중 페이지 임대 계약서, 스테이플로 묶인 영수증 묶음)에 속하는 여러 업로드 페이지를 페이지당 하나의 행으로 유지하는 대신 단일 출력 행으로 접어야 하는지 여부를 결정합니다. 여기에서 활성화하면 병합은 이 템플릿이 처리 및 결과 모두에 사용되는 모든 곳에서 자동으로 적용됩니다. ?merge=true on Get batch results 및 Export a batch를 참조하세요(항상 적용되며, 거기서는 별도 동의가 필요 없습니다). 아래 요청 본문의 모든 필드는 선택 사항입니다. 보내는 키만 업데이트되고 나머지는 그대로 유지됩니다(확인할 별도의 초안/미리보기 상태는 없음 — 이 호출은 웹 앱의 템플릿 설정 대화상자와 동일하게 즉시 적용됩니다).

PUT /api/v1/templates/{id}/settings

매개변수

이름위치유형설명
idpathinteger업데이트할 템플릿입니다.
global_format_requirementbody (JSON), 선택 사항string각 필드의 자체 format_requirement 위에 적용되는 추가 지침입니다.
merge_enabledbody (JSON), 선택 사항boolean다중 페이지 병합을 켜거나 끕니다. 이 값이 false인 동안 아래의 모든 merge_* 필드는 의미가 없습니다.
merge_modebody (JSON), 선택 사항string 또는 null"sequential"(데이터 열의 값이 변경될 때 새 레코드 생성), "key_match"(업로드 순서와 관계없이 일치하는 데이터 열 값으로 그룹화), 또는 "fixed_count"(N개 업로드마다 그룹화).
merge_field_namebody (JSON), 선택 사항string 또는 nullsequential의 값 기반 트리거와 key_match의 그룹화 키에 사용되는 데이터 열(필드 이름)입니다.
merge_trigger_typebody (JSON), 선택 사항string 또는 nullsequential 전용: "value_change", "blank", "has_value" 또는 "equals_value".
merge_trigger_valuebody (JSON), 선택 사항string 또는 nullmerge_trigger_type: "equals_value" 전용 — 일치시킬 텍스트 또는 정규식입니다.
merge_fixed_countbody (JSON), 선택 사항integer 또는 nullmerge_mode: "fixed_count" 전용 — 그룹 크기, 최소 1.
merge_conflict_policybody (JSON), 선택 사항string 또는 null그룹화된 페이지가 필드 값에 대해 일치하지 않을 때: "split"(병합 대신 페이지당 출력 행 하나 생성), "first", "last" 또는 "concat"(기본값).
merge_conflict_separatorbody (JSON), 선택 사항string 또는 nullmerge_conflict_policy: "concat"일 때 사용되며, 최대 20자입니다. null은 기본값 " / "으로 대체되고, ""은 의도적인 "구분자 없음" 선택으로 그대로 저장됩니다.
merge_skip_previewbody (JSON), 선택 사항boolean웹 앱 전용 사항(내보내기 미리보기 확인 화면을 제어) — API에는 건너뛸 대화형 미리보기 단계가 없으므로 API 동작에는 영향을 미치지 않습니다. 템플릿의 전체 구성이 이 단일 엔드포인트를 통해 왕복할 수 있도록 여기서 설정할 수 있습니다.

가능한 오류

  • missing_api_key / invalid_api_key / plan_required — 오류 처리 참조.
  • template_not_found
  • invalid_parameter — 잘못된 merge_mode / merge_trigger_type / merge_fixed_count / merge_conflict_policy / merge_conflict_separator.
  • internal_error

템플릿 삭제

템플릿과 해당 템플릿의 모든 필드를 삭제합니다(연쇄 삭제 — 별도의 정리 호출 불필요). 과거 process 호출에서 이 템플릿을 사용한 문서에는 영향을 주지 않으며, 이미 추출된 결과는 그대로 유지됩니다.

DELETE /api/v1/templates/{id}

매개변수

이름위치유형설명
idpathinteger삭제할 템플릿입니다.

가능한 오류

  • missing_api_key / invalid_api_key / plan_required — 오류 처리 참조.
  • template_not_found
  • internal_error

프리셋 목록

일반적인 문서 유형(인보이스, 영수증, 은행 명세서 등)에 대한 기본 제공 필드 목록입니다. 프리셋의 id를 템플릿 만들기의 preset_id로 전달하면 필드를 직접 나열하지 않고도 작동하는 템플릿을 얻을 수 있습니다. 프리셋은 데이터베이스 행이 아닌 정적 구성이므로 API를 통해 생성, 편집 또는 삭제할 수 없습니다.

GET /api/v1/presets

매개변수

이름위치유형설명
categoryquery, 선택 사항string하나의 카테고리로 필터링합니다 (예: "Finance & Accounting"). 생략하면 모든 카테고리를 나열합니다.
limitquery, 선택 사항integer1–100. 기본값 50.
page_tokenquery, 선택 사항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

매개변수

이름위치유형설명
idpathinteger이 필드들이 속한 템플릿입니다.
namebody (JSON), POST 전용string필수. 이 템플릿 내에서 고유해야 합니다 — 아래 오류를 참조하세요.
format_requirementbody (JSON), POST 전용string, 선택 사항예상 값 형식에 대한 자유 텍스트 힌트입니다 (예: "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를 대체합니다) — 전체 교체이며 부분 패치가 아니므로 하나만 변경되었더라도 두 값을 모두 포함해야 합니다. 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

매개변수

이름위치유형설명
idpathinteger순서를 변경할 템플릿입니다.
field_idsbody (JSON)array of integers표시하려는 순서대로 이 템플릿의 모든 필드 ID입니다. 필수입니다.

가능한 오류

  • missing_api_key / invalid_api_key / plan_required — 오류 처리를 참조하세요.
  • template_not_found
  • invalid_parameter (param: "field_ids") — 정수 목록이 아닙니다.
  • internal_error
📮 contact email: [email protected]