headless

문서

// api guide / polling

폴링 패턴

데이터 수집은 비동기로 처리됩니다. 요청 생성 응답의 suggestedPollIntervalMs 간격으로 kind 를 조회하고 Succeeded/Failed 가 되면 폴링을 종료합니다.

3단계 흐름

terminal curl
# 1. 수집 요청 생성 → kind: InProgress + suggestedPollIntervalMs
curl -sS -X POST https://api.h6s.ai/api/v1/data-jobs \
  -H "Authorization: Bearer $H6S_API_KEY" \
  -d '{ "providerCode": "CB_KB", "schema": "bank.transactions.cb.v1",
        "params": { "dateRangeStart": "2026-03-01", "dateRangeEnd": "2026-03-31" } }'
# → { "id": "<job-id>", "kind": "InProgress", "phase": "PENDING", "suggestedPollIntervalMs": 5000, "maxWaitSeconds": 3600 }

# 2. kind 가 Succeeded / Failed 가 될 때까지 suggestedPollIntervalMs 간격으로 GET
curl -sS https://api.h6s.ai/api/v1/data-jobs/<job-id> -H "Authorization: Bearer $H6S_API_KEY"
# → { "kind": "InProgress", "phase": "RUNNING" }       # 진행 중
# → { "kind": "Succeeded", "recordCount": 42 }          # 종료, results 호출

# 3. kind 가 Succeeded 이면 결과 받기
curl -sS https://api.h6s.ai/api/v1/data-jobs/<job-id>/results -H "Authorization: Bearer $H6S_API_KEY"

폴링 루프 예시

typescript
// TypeScript fetch loop
const job = await postDataJob({ providerCode, schema, params });
let current = job;
while (current.kind === "InProgress") {
  await sleep(current.suggestedPollIntervalMs ?? 5000);
  current = await getDataJob(job.id);
}
if (current.kind === "Failed") {
  // current.error.code 로 분기 (예: LOGIN_FAILED, JOB_TIMEOUT),
  // current.error.message 는 사용자에게 그대로 노출 가능,
  // current.error.retryable === true 면 같은 요청 재시도가 안전합니다
  throw new Error(`${current.error.code}: ${current.error.message}`);
}
const { data } = await getDataJobResults(job.id);

실패 시 다음 액션

  • error.code는 오류 유형 식별자 (예: AUTH_FAILED, RATE_LIMITED)
  • error.message는 사용자에게 보일 한국어 메시지
  • error.retryable은 true 면 같은 요청 재시도 안전, false 면 자격증명 확인 등 사람 개입 필요
  • maxWaitSeconds 를 넘기면 작업이 Failed 로 표시될 수 있습니다. 클라이언트도 같은 시간을 hard timeout 기준으로 잡기를 권장합니다.

다음 단계