headless

// local

처음이라면 — 한 번 받아보기

무엇이 어떻게 오는지 먼저 보고 싶을 때. 가장 작은 범위로 한 번 받아 응답 모양과 자격증명 상태를 확인합니다.

// 상황

이런 상황이라면

뭐가 오는지 모르겠다

붙이기 전에 응답이 어떤 모양인지 먼저 보고 싶습니다.

자격증명이 맞는지 불안

등록한 자격증명이 제대로 동작하는지 확인하고 싶습니다.

크게 시작하기 부담

처음부터 넓은 범위를 받기보다 작게 한 번 시험해 보고 싶습니다.

// 흐름

어떻게 동작하나

  1. 01

    자격증명 등록

    받아 볼 기관의 자격증명을 등록합니다.

  2. 02

    가장 작게 한 번

    짧은 기간으로 한 번 수집 요청을 보냅니다.

  3. 03

    응답 확인

    온 결과의 모양과 자격증명 상태를 확인합니다.

// schemas

사용 데이터 형식

이 시나리오에서 받는 데이터입니다. 기관이 달라도 같은 모양으로 옵니다. 필드 전체 명세는 각 데이터 형식 문서에서 확인할 수 있습니다.

// 결과물

손에 남는 것

  • 응답 데이터 형식을 눈으로 확인
  • 자격증명 동작 여부 확인
  • 작은 범위로 부담 없는 첫 시도
  • 다음 시나리오로 넘어갈 감

// 실행 가이드

그대로 따라 하면 됩니다

사전 점검부터 검증까지 이 페이지에서 끝납니다. 실행 방식이 여럿이면 하나만 고르면 됩니다.

01사전 점검

아래 명령을 붙여 넣어 현재 환경이 준비됐는지 확인합니다.

  • CLI가 설치돼 있다

    h6s --version

    버전 문자열이 출력됩니다

    대안으로 npm i -g @h6s-ai/cli

  • 로그인(또는 API Key)이 돼 있다

    h6s whoami

    워크스페이스와 사용량이 출력된다

    대안으로 h6s init # 또는 export H6S_API_KEY=h6s_live_...

  • 홈택스 자격증명(공동인증서)이 등록돼 있다

    h6s credentials list

    홈택스에 매칭되는 공동인증서가 1건 이상 보입니다

    대안으로 h6s credentials create --interactive --cert

02실행

실행 방식실행 방식 하나만 고르면 됩니다. 결과 형식은 같습니다.

한 달치 매출 세금계산서를 CSV 한 건으로.

terminal
h6s fetch hometax.tax-invoices.sales.v1 --provider HOMETAX --from 2026-04-01 --to 2026-04-30 --output csv --save sales-invoices-2026-04.csv

이렇게 보이면 성공

✓ 24건 수신  (2026-04-01 ~ 2026-04-30)
→ sales-invoices-2026-04.csv 저장

03검증

  • CSV에 거래처·공급가액·세액·발행일 컬럼이 있고 행이 N개다.
  • 명령 종료 후 echo $? 가 0.
  • 건수가 0 이면 기간 내 발행분이 없는 것입니다. 기간을 넓혀 다시 확인합니다.

04흔한 에러

CREDENTIAL_INSUFFICIENT_FOR_PROVIDER

홈택스에 매칭되는 자격증명이 없습니다.

해결 h6s credentials create --interactive --cert 로 공동인증서 등록.

CERT_EXPIRED · CERT_BIZNO_MISMATCH

공동인증서가 만료됐거나 사업자번호가 일치하지 않는다.

해결 h6s credentials update 로 올바른 인증서 재등록 후 재실행.

DATE_RANGE_EXCEEDED

조회 기간이 홈택스 허용 범위를 넘었다.

해결 월 단위 등 더 짧은 --from/--to 로 나눠 호출.

NO_API_KEY

API Key 가 설정되어 있지 않습니다.

해결 h6s init 또는 export H6S_API_KEY=h6s_live_...

05변형

같은 사례에서 자주 바꾸는 옵션. 다른 사례는 아래 이전/다음에서.

매입 세금계산서

terminal
h6s fetch hometax.tax-invoices.purchase.v1 --provider HOMETAX --from 2026-04-01 --to 2026-04-30 --output csv --save purchase-invoices-2026-04.csv

분기 전체 (부가세 신고 자료)

terminal
h6s fetch hometax.tax-invoices.sales.v1 --provider HOMETAX --from 2026-01-01 --to 2026-03-31 --output csv --save vat-sales-Q1.csv
전체 가이드 페이지로 보기

// 더 보기

관련 시나리오

terminal
$ h6s fetch bank.transactions.cb.v1 --provider CB_KB --month 2026-04✓ 132건 수신 (2026-04-01 ~ 2026-04-30)거래일 적요 금액 잔액2026-04-29 ㈜에이클라이언트 +1,540,000 8,420,300▍

은행 입출금내역 1개월 받기

터미널에 4월 입출금 거래 N건이 표 형태로 출력됩니다. 적요 · 금액 · 잔액 컬럼은 그대로 유지됩니다.

CLIClaude Code·임의 (한 번)

// faq

자주 묻는 질문

처음에 뭘 받아 보면 좋나요?

세금계산서나 은행 입출금내역을 짧은 기간으로 한 번 받아 응답 모양을 보는 것을 권합니다.

자격증명이 맞는지 어떻게 아나요?

작은 수집을 한 번 돌려 결과가 오면 자격증명이 동작하는 것입니다. 실패하면 자격증명 상태를 확인합니다.

그다음은요?

응답을 확인했다면 제품 임베드, 내부 적재, 자동 리포팅 같은 다음 시나리오로 넘어가면 됩니다.

// related

함께 보면 좋은 흐름

같은 데이터를 제품 연동, 내부 시스템, 자동화 작업 중 어디에 둘지에 따라 구현 방식이 달라집니다.

headless

첫 수집은 작게 시작합니다

가입하고 API 키를 만드세요. 짧은 기간의 데이터로 응답 형식을 먼저 확인할 수 있습니다.

무료로 첫 수집 시작