세금계산서·현금영수증 발행 API가 필요할 때 — headless는 조회, 발행은 볼타

headless로 세금계산서나 현금영수증을 발행할 수 있느냐는 문의를 종종 받습니다. headless는 발행하지 않습니다. headless는 홈택스에 이미 신고된 세금계산서·현금영수증을 받아 오는 조회·수집 API입니다. 발행이 필요하다면 함께 쓰는 발행 서비스 볼타가 그 자리를 맡습니다.

이 글은 둘의 경계를 정리합니다. 발행이 문제라면 볼타로, 받은 자료를 은행·카드 데이터와 함께 자동화하는 것이 문제라면 headless로 — 어느 쪽이 지금 필요한지 먼저 정하면 길이 갈립니다.

발행은 문서를 만들고 전송하는 일이고, headless는 이미 신고된 데이터를 받아 자동화 흐름에 연결합니다.

조회와 발행은 다른 일입니다

세금계산서 업무는 크게 두 방향입니다. 하나는 거래처에 전자세금계산서를 끊어 국세청에 전송하는 발행이고, 다른 하나는 이미 신고된 자료를 받아 장부·대사·신고 준비에 쓰는 조회입니다. 현금영수증도 마찬가지로 발행과 조회가 나뉩니다.

headless는 두 번째 방향, 조회·수집에 맞춘 API입니다. 홈택스 매출·매입 세금계산서와 현금영수증을 표준 데이터 형식으로 받아, 은행 입출금내역·법인카드 승인내역과 같은 흐름에서 다룹니다.

이 형식들은 모두 받아 오는 쪽입니다. 새 세금계산서를 끊거나 현금영수증을 발행하는 엔드포인트는 headless에 없습니다.

새 문서를 발행하는 흐름과 신고된 자료를 조회하는 흐름은 시작점부터 다릅니다.

조회·자동화가 필요하다면 — headless

headless는 홈택스에 신고된 자료를 data-job 한 번으로 받아, 은행·카드 데이터와 같은 흐름에서 자동화에 연결합니다. 발행은 다루지 않지만, 받은 다음의 일은 headless가 맡습니다.

• 매출·매입 세금계산서, 현금영수증을 표준 형식으로 조회
• 받은 매출 세금계산서를 은행 입금내역과 대사
• 거래처·공급가액·세액을 골라 자동 분개
• Claude Code·Cursor에서 자연어로 조회 (MCP · CLI)

매출 세금계산서를 지난달치로 받는 호출은 이렇게 시작합니다.

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": "HOMETAX",
    "schema": "hometax.tax-invoices.sales.v1",
    "params": { "dateRangeStart": "2026-06-01", "dateRangeEnd": "2026-06-30" }
  }'

data-job 결과를 받는 방법과 35개 고정 필드는 API 빠른시작과 데이터 형식에 정리되어 있습니다.

무엇이 필요하면 어디로 가나

발행이 필요하다면 — 볼타

볼타는 전자세금계산서 발행을 처음부터 끝까지 API로 제공하는 서비스입니다. headless와 함께 쓰도록 설계된 발행 서비스로, headless가 다루지 않는 발행 영역을 맡습니다.

발행 방식은 거래 구조에 따라 갈리는데, 볼타는 그 갈래를 모두 API로 덮습니다.

• 정발행 — 공급자가 직접 끊는 일반 발행
• 역발행 — 공급받는자가 요청하고 공급자가 승인하는 발행
• 수정발행 — 계약 해제, 공급가액 변동, 착오에 의한 이중발급 정정
• 대량발행 · 예약발행 · 정기발행 — 건수가 많거나 매월 반복되는 발행
• 현금영수증 발행

인증은 발급받은 API 키로 합니다. 베이스 URL은 https://xapi.bolta.io이고, HTTP Basic 인증에 공급자를 가리키는 Supplier-Key 헤더를 더합니다. 테스트 키는 test_로 시작해, 국세청 실연동 없이 개발 단계에서 응답을 확인할 수 있습니다.

세금계산서 한 건을 발행하는 호출은 이렇게 시작합니다.

curl -X POST "https://xapi.bolta.io/v1/taxInvoices/issue" \
  -u "$BOLTA_API_KEY:" \
  -H "Supplier-Key: $BOLTA_SUPPLIER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "writeDate": "2026-06-22",
    "purposeType": "RECEIPT",
    "items": [
      { "name": "구독료", "supplyAmount": 1000000, "taxAmount": 100000 }
    ]
  }'

요청·응답 구조와 필드, 역발행 승인 URL, 수정발행 사유 코드, 현금영수증 발행, 웹훅으로 발행 상태를 받는 방법은 볼타 API 문서에 정리되어 있습니다.

발행과 조회를 같이 쓰는 그림

두 제품은 한 흐름으로 이어집니다. 볼타로 세금계산서·현금영수증을 발행하고, 그렇게 신고된 자료를 headless로 받아 은행 입금과 대사하거나 장부에 올립니다. 발행은 볼타가, 받은 다음의 자동화는 headless가 맡는 구성입니다.

예를 들어 월말 정산이라면, 볼타가 거래처별 세금계산서를 끊어 전송하고, headless가 매출 세금계산서와 법인 통장 입금내역을 같은 형식으로 받아 대사 리포트를 만듭니다. 끊는 쪽과 맞춰 보는 쪽이 한 벌로 돕니다.

볼타로 발행한 뒤 홈택스에 반영된 자료를 headless가 받아 은행·장부 데이터와 맞춰 봅니다.

시작 경로

• 발행이 필요하면: 볼타 API 문서에서 API 키 발급과 발행 호출을 확인합니다.
• 조회·자동화가 필요하면: API 빠른시작에서 data-job 흐름을, 데이터 형식에서 홈택스·은행·카드 스키마를 봅니다.
• AI 도구에서 쓰려면: MCP를 연결해 Claude Code·Cursor에서 자연어로 호출합니다.

자주 묻는 질문

Q. headless로 세금계산서를 발행할 수 있나요? 없습니다. headless는 홈택스에 신고된 세금계산서·현금영수증을 받아 오는 조회·수집 API입니다. 발행은 볼타를 씁니다.

Q. 현금영수증도 볼타로 발행하나요? 네. 볼타는 전자세금계산서와 함께 현금영수증 발행도 지원합니다. 연동 방법은 볼타 API 문서에서 확인할 수 있습니다.

Q. 발행과 조회를 둘 다 써야 하면요? 볼타로 발행하고 headless로 받아 자동화하는 구성을 권합니다. 발행한 자료가 홈택스에 반영되면 headless의 매출·매입 스키마로 받아 대사·분개에 바로 씁니다.