// product
세금계산서
홈택스 매출·매입 세금계산서를 한 스키마로. 분기 부가세 신고 자료를 받는 가장 빠른 길.
// schemas
사용 스키마
hometax.tax-invoices.sales.v1hometax.tax-invoices.purchase.v1hometax.tax-invoice-detail.v1
// scenario
매출 세금계산서 한 번 받기
결산 직전 한 달치 매출 세금계산서를 CSV 한 건으로 — 거래처 · 공급가액 · 세액 그대로.
- 주기
- 임의 (한 번)
- 대상
- 결산 직전 데이터를 한 번 확인하고 싶은 회계담당.
- 채널
- CLI · Claude Code
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 한 건으로.
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 저장
받자마자 거래처별 합계까지 한 번에 정리하고 싶을 때.
4월 매출 세금계산서 한 번 받아서 거래처별 합계까지 정리해줘.
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_KEYAPI Key 가 설정돼 있지 않다.
해결 h6s init 또는 export H6S_API_KEY=h6s_live_...
05변형
같은 사례에서 자주 바꾸는 옵션. 다른 사례는 아래 이전/다음에서.
매입 세금계산서
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분기 전체 (부가세 신고 자료)
h6s fetch hometax.tax-invoices.sales.v1 --provider HOMETAX --from 2026-01-01 --to 2026-03-31 --output csv --save vat-sales-Q1.csv// related