headless

// api guide / polling

폴링 패턴

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

3단계 흐름

terminal — curl
# 1. 수집 요청 생성 → status: PENDING + 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>", "status": "PENDING", "suggestedPollIntervalMs": 5000, "maxWaitSeconds": 600 }

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

# 3. status == 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.status === "PENDING" || current.status === "RUNNING") {
  await sleep(current.suggestedPollIntervalMs ?? 5000);
  current = await getDataJob(job.id);
}
if (current.status === "FAILED") {
  // current.errorCode 로 분기 (예: LOGIN_FAILED, JOB_TIMEOUT),
  // current.errorMessage 는 사용자에게 그대로 노출 가능,
  // current.retryable === true 면 같은 요청 재시도가 안전합니다
  throw new Error(`${current.errorCode}: ${current.errorMessage}`);
}
const { data } = await getDataJobResults(job.id);

실패 시 다음 액션

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

다음 단계