headless

// api guide / quickstart

API 빠른시작

API는 수집 요청을 만들고, 완료되면 결과를 가져오는 구조입니다. 콘솔에서 API 키와 자격증명을 준비한 뒤 data-job을 생성하고 결과를 조회합니다.

한눈에 보는 흐름

1

API 키와 자격증명 준비

콘솔에서 금융기관 자격증명을 등록하고 API 키를 발급합니다.

자격증명 등록
2

수집 요청 생성

수집할 기관, 데이터 형식, 기간을 넣어 data-job을 만듭니다.

POST /data-jobs
3

상태 폴링

요청 생성 응답의 id로 진행 상태를 조회합니다.

폴링 패턴
4

결과 조회

상태가 SUCCEEDED가 되면 결과 API 응답에 표준 형식 데이터가 포함됩니다.

GET /results

필수 개념

API 키
모든 Open REST API 호출에 쓰는 인증 값입니다. 워크스페이스는 API 키에서 해석됩니다.
자격증명
은행·홈택스·카드사에 접근하기 위한 인증 정보입니다. 콘솔에서 한 번 등록한 뒤 API 호출에 매칭됩니다.
schemaId
받을 데이터 형식을 고르는 식별자입니다. 같은 schemaId를 쓰면 기관이 달라도 필드 이름과 타입이 같습니다.
data-job
비동기 수집 요청 한 건입니다. 생성 응답의 id로 상태와 결과를 조회합니다.

curl 예제

아래 예제는 국민은행 입출금내역 1개월을 요청합니다. H6S_API_KEY에는 콘솔에서 발급한 라이브 키를 넣습니다.

1. data-job 생성
curl -sS -X POST https://api.h6s.ai/api/v1/data-jobs \
  -H "Authorization: Bearer $H6S_API_KEY" \
  -H "Content-Type: application/json" \
  -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, ... }
2. 상태 조회
curl -sS https://api.h6s.ai/api/v1/data-jobs/<job-id> \
  -H "Authorization: Bearer $H6S_API_KEY"
# 응답: { "id": "<job-id>", "status": "RUNNING", ... }
# status가 SUCCEEDED 또는 FAILED가 될 때까지 suggestedPollIntervalMs 간격으로 조회합니다.
3. 결과 조회
curl -sS https://api.h6s.ai/api/v1/data-jobs/<job-id>/results \
  -H "Authorization: Bearer $H6S_API_KEY"
# 응답: { "schema": "bank.transactions.cb.v1", "totalCount": 247, "data": [ ... ] }

요청·응답 필드는 어디서 보나요?

schemaId별 요청 파라미터와 응답 필드는 데이터 형식 문서에서 확인합니다. 예를 들어 bank.transactions.cb.v1을 쓰면 은행이 달라도 같은 필드 이름과 타입으로 응답됩니다.

데이터 형식 목록은행 입출금내역 필드 보기

LLM으로 개발할 때

AI 코딩 도구에 API 문맥을 넣어 개발한다면 /llms-full.txt를 컨텍스트로 사용하세요. 엔드포인트, 데이터 형식, 에러 코드가 한 문서에 정리되어 있습니다.

다음 링크