headless
전체 블로그

// quickstart

첫 API 호출: headless 시작 체크리스트

처음 headless API를 호출하는 개발자를 위한 가이드. 자격증명 등록부터 은행 거래내역 data-job 생성·결과 조회까지 필요한 순서를 따라갑니다.

·headless

첫 호출에서는 큰 연동보다 자격증명이 정상인지와 거래내역 응답이 필요한 형식으로 오는지부터 확인합니다. 이 가이드는 자격증명을 등록한 뒤 curl 두 단계로 은행 입출금내역 JSON을 받는 가장 짧은 경로를 보여 줍니다.

권한과 인증서 준비 상태에 따라 시간은 달라집니다. 결과를 확인한 뒤에야 서비스 연동 범위와 오류 처리를 설계하는 편이 안전합니다.

누가 이 글을 읽으면 좋을까

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

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

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

여기까지 네 단계입니다.

1. 계정과 API 키

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

2. 자격증명 등록 (콘솔)

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

  • 콘솔 → 자격증명에서 기관을 고르고 자격증명을 입력합니다.
  • 공동인증서(GLOBAL)라면 PFX를 한 번만 등록해도 기관을 따로 고르지 않고 거의 모든 홈택스·은행에서 함께 씁니다.

3. 수집 요청 생성

  • 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. 결과 조회

  • 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는 표준 형식 배열입니다. 어느 은행에서 받아도 identifier 포함 같은 9개 필드라, 받는 코드를 기관마다 새로 짤 필요가 없습니다.

받은 데이터를 파일로 확인

여기까지 진행하면 한국 금융 데이터를 내 터미널에서 받게 됩니다. 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건해당 기간 거래 없음·계좌 미매칭기간을 넓히거나 계좌 파라미터 명시

다음 단계