# 비동기 작업 모델 — 문서 및 배치 처리 상태

> v1 API에서 문서 및 배치 처리가 비동기로 작동하는 방식 — 대기 중/처리 중/성공/실패/취소 상태 머신과 created_at/started_at/completed_at 타임스탬프 체인.

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

## 상태 생애 주기

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

```text
queued → processing → succeeded | failed | canceled
```

- `queued` — 업로드되었거나 작업자가 가져가길 기다리는 중입니다.
- `processing` — 작업자가 문서를 가져가 데이터를 적극적으로 추출하고 있습니다.
- `succeeded` — 추출이 완료되었습니다. 결과 응답의 `line_items`가 채워집니다.
- `failed` — 이 문서에 대해 추출을 완료할 수 없습니다(이는 *문서 수준*의 결과이며 API 호출 오류가 아닙니다. [오류 처리](/developers/guides/errors)의 `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 로 유지됩니다. 일부 문서가 이미 완료되었더라도 아직 진행 중인 문서가 있는 배치는 아직 '완료'되지 않은 것입니다. |

## 폴링 vs. 웹훅

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

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

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

---

Source: https://imagetotable.ai/ko/developers/guides/async-model