headless
전체 블로그

// quickstart

5분 안에 첫 API 호출 — headless 시작 체크리스트

가입부터 첫 거래내역 응답까지 5분. 콘솔에서 자격증명을 한 번 등록한 뒤 curl 두 단계로 한국 금융 데이터를 코드로 받아올 수 있는 최소 경로입니다.

·headless

가입에서 첫 거래내역 응답까지 5분입니다. 콘솔에서 자격증명을 한 번 등록한 뒤 복붙 가능한 curl 두 단계면 끝납니다. 손에 쥐는 결과물은 내 화면에서 바로 열어볼 수 있는 한국 은행 입출금내역 JSON 한 덩어리입니다.

거창한 연동을 짜기 전에, 데이터가 정말 내 손에 들어오는지 가장 작게 한 번 확인해 보는 경로입니다.

누가 이 글을 읽으면 좋을까

  • 한국 은행·홈택스 데이터를 코드로 처음 받아 보려는 개발자
  • 사전 지식: 터미널, curl, 발급받을 은행/홈택스 자격증명 하나

무엇을 만들 것인가 (5초 미리보기)

bash
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": [ ... ] }

여기까지 네 단계, 약 5분입니다.

1. 계정과 API 키 (1분)

  • h6s.ai 가입 후 콘솔에서 API 키 발급
  • 키를 환경변수에 저장
bash
export H6S_API_KEY=h6s_live_...

2. 자격증명 등록 (1~2분, 콘솔)

자격증명 등록은 콘솔 UI 안내를 따라 진행합니다. 첫 등록 직후 credentialHealth가 표시되어 값 오류를 바로 확인할 수 있습니다.

  • 콘솔 → 자격증명에서 기관을 고르고 자격증명을 입력합니다.
  • 공동인증서(GLOBAL)라면 PFX를 한 번 등록하는 것으로 거의 모든 홈택스·은행에 공유됩니다 — 기관 선택 없이 한 번에.

3. 수집 요청 생성 (1분)

  • API 키 하나로 자격증명이 자동 매칭되어 수집 요청이 만들어집니다 (providerCode만 적으면 등록된 자격증명이 자동 선택됩니다).
bash
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 }

4. 결과 조회 (30초)

  • status가 SUCCEEDED가 될 때까지 suggestedPollIntervalMs(기본 5,000ms) 간격으로 폴링한 뒤 결과를 조회합니다.
bash
curl -sS "https://api.h6s.ai/api/v1/data-jobs/<job-id>/results" \
  -H "Authorization: Bearer $H6S_API_KEY"

응답의 data는 표준 형식 배열입니다. 어느 은행에서 받아도 같은 8개 필드라, 받는 코드를 기관마다 새로 짤 필요가 없습니다.

받은 데이터를 내 손에서 바로

여기까지 왔으면 한국 금융 데이터가 이미 내 터미널에 들어와 있습니다. JSON 한 덩어리를 그대로 파일로 떨어뜨려 두면 스프레드시트로 열거나 차트 라이브러리에 바로 먹일 수 있습니다.

bash
curl -sS "https://api.h6s.ai/api/v1/data-jobs/<job-id>/results" \
  -H "Authorization: Bearer $H6S_API_KEY" > bank-transactions.json

내 화면에 띄울 작은 대시보드든, 주간 캐시플로우 메모든, 출발점은 이 한 덩어리입니다. 흐름이 손에 익으면 받아오는 범위를 넓히거나 다른 스키마로 갈아 끼우기만 하면 됩니다.

자주 만나는 막힘

증상원인대응
401 UnauthorizedAPI 키 누락·오타Authorization: Bearer $H6S_API_KEY 확인
credentialHealth가 VERIFIED 아님자격증명 값 오류·기관 거부콘솔에서 자격증명 갱신
job이 PENDING에서 안 변함폴링이 이른 시점suggestedPollIntervalMs 간격으로 재조회
결과 0건해당 기간 거래 없음·계좌 미매칭기간을 넓히거나 계좌 파라미터 명시

다음 단계