비동기 작업 모델

문서를 업로드한다고 바로 처리되는 것이 아니며, 처리를 시작한다고 같은 요청 내에서 완료되는 것도 아닙니다. 모든 문서와 배치는 고정된 닫힌 상태 집합을 따라 이동합니다. 이 페이지에서는 그 생애 주기를 처음부터 끝까지 설명합니다.

상태 생애 주기

모든 문서는 항상 다섯 가지 상태 중 정확히 하나에 있습니다:

queued → processing → succeeded | failed | canceled

queued — 업로드되었거나 작업자가 가져가길 기다리는 중입니다.
processing — 작업자가 문서를 가져가 데이터를 적극적으로 추출하고 있습니다.
succeeded — 추출이 완료되었습니다. 결과 응답의 line_items가 채워집니다.
failed — 이 문서에 대해 추출을 완료할 수 없습니다(이는 문서 수준의 결과이며 API 호출 오류가 아닙니다. 오류 처리의 processing_error 참고 사항을 확인하세요).
canceled — 처리가 시작되기 전에 문서가 대기열에서 제거되었습니다.

이 다섯 값 집합은 공개 계약으로, 시스템이 내부적으로 사용하는 상태와 의도적으로 분리되어 있습니다. 새로운 내부 중간 상태가 나중에 도입되더라도 여기에 여섯 번째 값을 추가할 필요가 없습니다. 오늘 파싱하는 모든 v1 응답은 계속 작동합니다.

문서(GET /documents/{id})와 배치(GET /batches/{batch_name}/results) 응답 모두 동일한 세 가지 필드를 제공하므로, '대기 중이지만 멈춤', '실행 중', '실제로 완료됨'을 구분할 수 있습니다:

필드	설정 시점
`created_at`	문서가 업로드된 시점.
`started_at`	작업자가 문서를 할당받아 처리를 시작한 시점. `status`가 여전히 `queued`인 동안은 `null`로 유지됩니다.
`completed_at`	문서가 최종 상태에 도달한 시점. `queued` 또는 `processing` 상태인 동안은 `null`로 유지됩니다. 배치 수준에서는 배치 내 모든 문서가 이 값을 가질 때까지 `null`로 유지됩니다. 일부 문서가 이미 완료되었더라도 아직 진행 중인 문서가 있는 배치는 아직 '완료'되지 않은 것입니다.

배치 완료를 확인하는 두 가지 방법이 있습니다:

폴링 — GET /batches/{batch_name}을 주기적으로 호출하여 all_done을 확인합니다. 간단하며 서버 측 인프라가 필요 없지만, 너무 자주 폴링하면 요청이 낭비되거나(상태 엔드포인트의 분당 120회 제한은 속도 제한 참조), 너무 느리게 폴링하면 완료를 인지하는 데 지연이 발생합니다.
웹훅 — PUT /batches/{batch_name}/webhook으로 콜백 URL을 한 번 등록하면, 반복적으로 요청하지 않고도 배치가 완료되는 즉시 알림을 받습니다. 자세한 내용은 웹훅 가이드를 참조하세요. 배치에 문서를 추가하고 이미 알림을 받은 후 다시 처리할 경우 어떻게 되는지도 다룹니다.

한 번 처리하는 소규모 배치의 경우 몇 번의 폴링이 가장 간단합니다. 대용량 처리나 요청 루프를 계속 유지하고 싶지 않은 경우에는 웹훅이 더 적합합니다.