headless

// api guide / polling

폴링 패턴

데이터 수집은 비동기다. 요청 생성 응답의 suggestedPollIntervalMs 간격으로 status 가 SUCCEEDED/FAILED 가 될 때까지 GET 한다.

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 (정규화된 enum), current.errorMessage (사용자 메시지),
  // current.retryable (true 면 자동 재시도 안전) 로 다음 액션 결정
  throw new Error(`${current.errorCode}: ${current.errorMessage}`);
}
const { data } = await getDataJobResults(job.id);

실패 시 다음 액션

  • errorCode — 정규화된 enum (예: AUTH_FAILED, RATE_LIMITED)
  • errorMessage — 사용자에게 보일 한국어 메시지
  • retryable — true 면 같은 요청 재시도 안전, false 면 자격증명 확인 등 사람 개입 필요
  • maxWaitSeconds 가 지나도 종료 안 되면 서버가 자동 FAILED 처리 — 클라이언트도 같은 시간을 hard timeout 으로 둔다.

다음 단계