수정세금계산서 API로 환불, 반품, 기재 오류, 중복 발행을 정정하는 방법

환불, 정산 차액, 중복 발행을 수정 사유와 볼타 API 요청으로 연결하는 개발자 가이드
진태양's avatar
Nov 18, 2026
수정세금계산서 API로 환불, 반품, 기재 오류, 중복 발행을 정정하는 방법

수정세금계산서 API는 이미 발행한 세금계산서의 issuanceKey를 경로에 넣고, 수정 사유별 엔드포인트를 골라 호출하는 방식입니다. 볼타 API가 지원하는 수정발행 사유는 계약의 해제, 공급가액 변동, 착오에 의한 이중발급, 환입, 기재사항 착오정정 다섯 가지입니다. 용역 거래의 전액 취소는 계약의 해제, 부분 환불과 단가 조정은 공급가액 변동, 재화를 돌려받은 반품은 환입으로 연결됩니다. 같은 거래를 두 번 발행했다면 이중발급, 공급받는자 정보나 품목을 잘못 적었다면 기재사항 착오정정을 씁니다.

이 글은 서비스에서 일어나는 환불, 반품, 정산 차액, 기재 오류, 중복 발행 이벤트를 어떤 수정 사유와 어떤 요청으로 바꿀지 정리합니다. 볼타 API 동작은 2026년 11월 볼타 개발자 문서 기준이고, 법령은 2026년 11월 법제처에서 조회한 부가가치세법 시행령 제70조 현행 원문을 따랐습니다.

서비스 이벤트별 수정 사유와 API 호출

한 분기점에서 여러 갈래 컨베이어로 서로 다른 모양의 토큰이 나뉘어 이동하는 장면
서비스 이벤트는 수정 사유별 엔드포인트 가운데 하나로 연결됩니다.

결제 시스템이나 정산 배치가 만드는 이벤트는 세법의 수정 사유와 이름이 다릅니다. 연동을 설계할 때 먼저 이벤트 목록을 만들고, 각 이벤트를 아래 표의 한 줄에 대응시키세요. 다섯 엔드포인트 모두 POST이고 서버 주소는 https://xapi.bolta.io입니다.

서비스 이벤트

수정 사유

엔드포인트

요청 본문

계약 전체 취소, 서비스 미제공 전액 환불

계약의 해제

/v1/taxInvoices/{issuanceKey}/amend/termination

date만

부분 환불(반품 제외), 단가 인하, 사용량 정산 차감

공급가액 변동(감액)

/v1/taxInvoices/{issuanceKey}/amend/changeSupplyCost

date, taxType, 음수 품목

추가 과금, 단가 인상

공급가액 변동(증액)

/v1/taxInvoices/{issuanceKey}/amend/changeSupplyCost

date, taxType, 양수 품목

재화 반품(전부 또는 일부)

환입

/v1/taxInvoices/{issuanceKey}/amend/return

date(환입일), 음수 품목, taxType 없음

공급받는자 정보, 품목 등 기재 오류

기재사항 착오정정

/v1/taxInvoices/{issuanceKey}/amend/misspell

trustee와 description을 뺀 정발행 형식

같은 거래를 두 번 발행(재시도 오류 등)

착오에 의한 이중발급

/v1/taxInvoices/{issuanceKey}/amend/doubleIssuance

없음

경로의 issuanceKey는 수정할 원본 세금계산서의 발행 요청 식별번호입니다. 원본은 같은 API 키로 발행해 발행에 성공한 건이어야 합니다. 원본이 발행 성공 상태가 아니면 400 ISSUANCE_MUST_BE_SUCCESS, 다른 API 키로 발행한 원본이면 403 FORBIDDEN, 없는 issuanceKey면 404 NOT_FOUND가 옵니다. 볼타 웹 화면에서 발행한 건에는 API의 issuanceKey가 없어 API로 수정발행하지 못합니다(2026년 11월 기준 볼타 동작).

응답으로 받는 issuanceKey는 새로 만든 수정세금계산서의 값이라서 원본과 다릅니다. 기재사항 착오정정은 수정분 issuanceKey와 취소분 cancelIssuanceKey를 함께 돌려주니 두 키를 모두 저장하세요. 원본 키와 묶어 두면 원본과 수정본을 나중에 한눈에 대조합니다.

이벤트가 어느 사유에 해당하는지는 거래의 실제 내용으로 판단합니다. 계약 자체가 없어져 공급이 일어나지 않았는지, 공급한 재화가 돌아왔는지, 공급은 했지만 금액만 달라졌는지가 갈림길입니다. 판단이 애매한 이벤트는 세무 담당자와 기준을 정한 뒤 코드에 넣으세요. 사유별 마감일과 가산세는 세금계산서 수정발행 사유별 마감일과 가산세에서 더 자세히 다룹니다.

부가가치세법 시행령 제70조의 수정 사유와 작성일자

시행령 제70조 제1항은 수정세금계산서 발급 사유를 아홉 가지로 나누고, 사유마다 작성일과 표기 방식을 정합니다. 아래 표는 조문 문구를 줄여 옮긴 것이며, 마지막 열은 볼타 API 문서에 해당 엔드포인트가 있는지 보여 줍니다.

호

사유

작성일자와 발급 방식(시행령 문구)

볼타 API

1

처음 공급한 재화가 환입된 경우

환입된 날을 작성일로, 비고에 처음 작성일, 음(陰)의 표시

환입(/amend/return)

2

계약의 해제로 공급되지 않은 경우

계약해제일을 작성일로, 비고에 처음 작성일, 음(陰)의 표시

계약의 해제

3

계약의 해지 등으로 공급가액이 늘거나 줄어든 경우

증감 사유가 발생한 날을 작성일로, 추가분은 검은색, 차감분은 음(陰)의 표시

공급가액 변동

4

과세기간 종료 후 25일 이내 내국신용장 개설, 구매확인서 발급

처음 작성일을 작성일로, 영세율분 발급과 처음 내용의 음(陰)의 표시분 발급

엔드포인트 없음

5

필요적 기재사항 등이 착오로 잘못 적힌 경우

처음 내용대로 음(陰)의 표시분 발급, 수정분은 검은색으로 발급

기재사항 착오정정(/amend/misspell), 취소분과 수정분 두 장 발행

6

필요적 기재사항 등이 착오 외의 사유로 잘못 적힌 경우

확정신고기한 다음 날부터 1년 이내 작성, 음(陰)의 표시분과 수정분 발급

엔드포인트 없음

7

착오로 전자세금계산서를 이중으로 발급한 경우

처음 내용대로 음(陰)의 표시를 하여 발급

착오에 의한 이중발급

8

면세 등 발급대상이 아닌 거래에 발급한 경우

처음 내용대로 음(陰)의 표시를 하여 발급

엔드포인트 없음

9

세율을 잘못 적용하여 발급한 경우

처음 내용대로 음(陰)의 표시분 발급, 수정분은 검은색으로 발급

엔드포인트 없음

5호, 6호, 9호는 세무조사 통지를 받는 등 과세표준이나 세액의 경정을 미리 알고 있는 경우를 제외합니다. 4호, 6호, 8호, 9호는 2026년 11월 기준 볼타 API 문서에 수정발행 경로가 없습니다. 이 사유에 해당하는 거래는 처리 방법을 세무 담당자와 먼저 정하세요.

수정발행 요청에는 세금계산서 비고를 넣는 필드가 없습니다. 2026년 11월 기준 볼타 동작으로는 볼타가 세금계산서 비고를 사유별 고정 문구로 채웁니다. 계약의 해제와 공급가액 변동은 당초 작성일자와 당초 승인번호, 환입은 당초 작성일자, 이중발급과 기재사항 착오정정은 당초 승인번호가 들어갑니다. 품목 비고(items[].description)는 품목을 보내는 사유에서 따로 적습니다.

제2항(일반과세자에서 간이과세자로 전환, 선택)과 제3항(간이과세자에서 일반과세자로 전환, 의무)은 전환 전 공급분에 1~3호 사유가 생기면 처음 작성일을 작성일로 적고 비고에 사유 발생일을 덧붙이게 합니다. 볼타가 채우는 비고 문구에는 사유 발생일이 들어가지 않습니다. 과세유형 전환에 걸린 거래는 처리 방법을 세무 담당자와 먼저 정하세요.

원본을 그대로 상계하는 계약의 해제와 이중발급

계약의 해제는 작성일자 하나만 보냅니다

계약의 해제 수정발행은 요청 본문에 date(작성일자) 하나만 보냅니다. 볼타가 원본 세금계산서를 그대로 상계 처리하므로 품목이나 금액을 다시 적을 필요가 없습니다. 문서의 예시에서는 50,000원짜리 원본에 계약의 해제 수정발행을 하면 -50,000원 세금계산서가 나갑니다.

curl -X POST "https://xapi.bolta.io/v1/taxInvoices/{issuanceKey}/amend/termination" \
  -u "{API_KEY}:" \
  -H "Content-Type: application/json" \
  -H "Bolta-Client-Reference-Id: {요청자_관리번호}" \
  -d '{ "date": "2026-11-13" }'

# 200 응답
{ "issuanceKey": "{수정세금계산서_issuanceKey}" }

date의 문서 설명은 "계약 해제 날짜"입니다. 시행령 2호도 계약해제일을 작성일로 적게 하니, 결제 취소 시각이 아니라 계약이 해제된 날을 넘기세요.

  • 원본 품목의 공급가액이 음수이면 계약의 해제 수정발행을 할 수 없습니다.

  • 공급이 일부라도 이뤄졌고 금액만 줄었다면 계약의 해제가 아니라 공급가액 변동을 검토하세요.

  • 인증은 API 키 뒤에 콜론을 붙여 Base64로 인코딩한 Basic 인증입니다.

중복 발행은 이중발급 API를 본문 없이 호출합니다

재시도 로직이 같은 주문으로 세금계산서를 두 번 만들었다면, 중복으로 나간 건의 issuanceKey로 이중발급 엔드포인트를 부르세요. 요청 본문은 보내지 않습니다. 볼타가 기존 발행건을 상계하고, 작성일자에는 당초 세금계산서의 작성일자를 자동으로 넣습니다.

curl -X POST "https://xapi.bolta.io/v1/taxInvoices/{issuanceKey}/amend/doubleIssuance" \
  -u "{API_KEY}:" \
  -H "Bolta-Client-Reference-Id: {요청자_관리번호}"

시행령 7호는 처음 발급한 내용대로 음(陰)의 표시를 하여 발급하라고 정합니다. 문서 예시에서도 50,000원 원본에 이중발급 수정발행을 하면 -50,000원 세금계산서가 나갑니다.

중복 발행 자체를 줄이려면 정발행 요청에 Bolta-Client-Reference-Id 헤더를 붙이세요. 같은 API 키로 이미 쓴 값이 다시 오면 API가 400과 INVALID_REQUEST를 돌려주고 요청을 받지 않습니다. 응답을 받지 못한 요청은 다시 보내지 말고 GET /v1/taxInvoices/issue/status?clientReferenceId=...로 접수 여부부터 확인하세요. 이 헤더는 수정발행 요청에도 쓸 수 있습니다.

공급가액 변동은 늘거나 줄어든 차액만 보냅니다

공급가액 변동 수정발행에는 최종 금액이 아니라 원본 대비 증감액을 품목으로 보냅니다. 금액이 줄면 음수, 늘면 양수입니다. 필수 필드는 date(공급가액 변동 날짜), taxType, items이고, 품목마다 date(공급일자), name, supplyCost가 필요합니다.

curl -X POST "https://xapi.bolta.io/v1/taxInvoices/{issuanceKey}/amend/changeSupplyCost" \
  -u "{API_KEY}:" \
  -H "Content-Type: application/json" \
  -H "Bolta-Client-Reference-Id: {요청자_관리번호}" \
  -d '{
    "date": "2026-11-13",
    "taxType": "TAXABLE",
    "items": [
      {
        "date": "2026-11-13",
        "name": "부분 환불",
        "unitPrice": null,
        "quantity": null,
        "supplyCost": -200000,
        "tax": -20000,
        "specification": null,
        "description": null
      }
    ]
  }'

세액 입력은 정발행과 같은 규칙을 따릅니다. taxType에 맞춰 품목 세액을 아래처럼 채우세요.

taxType

의미

items[].tax

TAXABLE

과세(전자세금계산서)

null이 아닌 값

ZERO_RATE

영세율(전자세금계산서)

모든 품목 0

TAX_FREE

면세(계산서)

모든 품목 null 또는 생략

볼타 문서의 계산 예시는 품목 두 개의 단가를 각각 1,000원씩 낮추는 경우입니다. 원본이 공급가액 50,000원과 150,000원이면 수정분은 단가 -1,000원에 원본 수량 10개와 50개를 그대로 적어 공급가액 -10,000원과 -50,000원, 세액 -1,000원과 -5,000원이 됩니다. 최종 거래 금액은 공급가액 40,000원과 100,000원으로 남습니다.

요청을 보내기 전에 아래 검증 규칙을 코드에서 먼저 확인하세요.

  • 품목은 1개 이상 16개 이하, 품목명은 최대 100자, 규격은 최대 60자입니다.

  • 품목 공급가액 합계는 0이 될 수 없습니다. 세액 합계가 0이나 null이 아니면 공급가액 합계와 부호가 같아야 합니다.

  • 수량(quantity)에는 0을 넣을 수 없고, 공급가액 변동에서는 양수만 받습니다.

  • 단가(unitPrice)는 음수도 받습니다. 단가를 함께 적는다면 위 예시처럼 음수 단가에 양수 수량을 쓰세요.

  • 보이지 않는 제어 문자는 볼타가 지우고, 이모지처럼 U+FFFF를 넘는 문자는 400으로 거부합니다. 환불 사유 문구를 사용자 입력에서 그대로 가져온다면 먼저 걸러 두세요.

반품은 환입, 잘못 적은 내용은 기재사항 착오정정으로 보냅니다

환입은 돌려받은 금액을 음수 품목으로 보냅니다

재화를 돌려받았다면 환입 엔드포인트를 부르세요. 요청 본문은 date와 items 두 필드뿐입니다. date에는 실제 환입일을 적고, 품목에는 돌려받은 금액을 음수 공급가액으로 적습니다. taxType은 보내지 않습니다. API가 원본의 과세유형, 영수/청구 구분, 공급자, 공급받는자, 수탁자를 그대로 쓰기 때문입니다. 세액은 원본 과세유형에 맞춰 입력하세요.

curl -X POST "https://xapi.bolta.io/v1/taxInvoices/{issuanceKey}/amend/return" \
  -u "{API_KEY}:" \
  -H "Content-Type: application/json" \
  -H "Bolta-Client-Reference-Id: {요청자_관리번호}" \
  -d '{
    "date": "2026-11-13",
    "items": [
      {
        "date": "2026-11-13",
        "name": "반품 품목",
        "unitPrice": null,
        "quantity": null,
        "supplyCost": -30000,
        "tax": -3000,
        "specification": null,
        "description": null
      }
    ]
  }'
  • 품목 공급가액 합계는 음수여야 합니다. 문서 예시처럼 50,000원 원본 가운데 일부를 반품하면 -20,000원 수정세금계산서가 나갑니다.

  • 품목 세액은 모두 정수이거나 모두 null(또는 생략)이어야 하고, 세액 합계가 0이나 null이 아니면 음수여야 합니다.

  • 수량에는 0을 넣을 수 없고, 환입은 음수 수량도 받습니다.

  • date는 오늘이나 이전 날짜이고 과거 하한이 없습니다. 품목 공급일자는 시작일부터 date까지 넣습니다. date가 전월 작성분의 발행 마감일 당일이나 이전이면 전월 1일, 이후면 당월 1일이 시작일입니다.

시행령 1호는 비고에 처음 작성일을 적게 합니다. 2026년 11월 기준 볼타 동작으로는 볼타가 환입분 비고에 당초 작성일자를 자동으로 넣습니다.

기재사항 착오정정은 고친 내용 전체를 보냅니다

공급받는자 정보나 품목을 잘못 적었다면 기재사항 착오정정 엔드포인트에 고친 세금계산서 내용을 보내세요. API가 원본을 상계하는 취소분과 고친 내용의 수정분, 두 장을 함께 발행합니다. 문서 예시에서 50,000원 원본을 고치면 취소분 -50,000원과 수정분 55,000원이 나갑니다.

요청 본문은 trustee와 description을 뺀 정발행 형식입니다. 필수 필드는 date(수정분 작성일자), purpose, taxType, supplied, items입니다. supplier를 생략하면 원본 공급자를 씁니다. 보낼 때는 사업자등록번호(identificationNumber)와 종사업장번호(taxRegistrationId)가 원본과 같아야 합니다.

curl -X POST "https://xapi.bolta.io/v1/taxInvoices/{issuanceKey}/amend/misspell" \
  -u "{API_KEY}:" \
  -H "Content-Type: application/json" \
  -H "Bolta-Client-Reference-Id: {요청자_관리번호}" \
  -d '{
    "date": "2026-11-13",
    "purpose": "CLAIM",
    "taxType": "TAXABLE",
    "supplied": {
      "identificationNumber": "{공급받는자_사업자등록번호}",
      "taxRegistrationId": null,
      "organizationName": "공급받는자 상호",
      "representativeName": "공급받는자대표",
      "managers": [{ "email": "{공급받는자_담당자_이메일}" }]
    },
    "items": [
      { "date": "2026-11-13", "name": "정정 품목", "supplyCost": 100000, "tax": 10000 }
    ]
  }'

# 200 응답
{ "issuanceKey": "{수정분_issuanceKey}", "cancelIssuanceKey": "{취소분_issuanceKey}" }
  • 과세와 영세율 사이는 바꿀 수 있지만, 과세나 영세율을 면세로 바꾸거나 그 반대로 바꾸지는 못합니다.

  • 품목 공급가액 합계는 0만 아니면 양수와 음수를 모두 받습니다. 세액 합계가 0이나 null이 아니면 공급가액 합계와 부호가 같아야 합니다.

  • 위수탁 세금계산서와 공급받는자 식별번호가 외국인등록번호인 세금계산서는 지원하지 않습니다.

  • 포인트는 취소분과 수정분 장마다 차감합니다. Bolta-Client-Reference-Id는 수정분에만 저장됩니다.

수정발행 결과는 새 issuanceKey로 추적합니다

수정발행 API의 200 응답은 요청 접수 결과입니다. 최종 발행 결과는 발행 결과 웹훅이나 내용 조회로 확인하세요. 세금계산서 웹훅 이벤트는 TAX_INVOICE_ISSUANCE_SUCCESS와 TAX_INVOICE_ISSUANCE_FAILURE 두 가지이고, data.issuanceKey로 어떤 요청의 결과인지 구분합니다.

확인 수단

내용

발행 성공 웹훅

issuanceKey, taxInvoiceUrl

발행 실패 웹훅

issuanceKey, cause.code, cause.message

웹훅 도착 시간

테스트 키 10~30초, 라이브 키 약 10분

내용 조회 GET /v1/taxInvoices/{issuanceKey}

발행 완료 건의 국세청승인번호, 발행일시, 작성일자, 품목

PDF 조회

정발행, 역발행, 수정세금계산서 PDF 다운로드 주소

기재사항 착오정정은 두 장을 각 키로 따로 조회하고 웹훅도 따로 받습니다. API는 수정분을 먼저 발행합니다. 수정분 발행이 실패하면 취소분도 발행하지 않고 두 키 모두에 실패 웹훅을 보냅니다. 수정분이 국세청에서 거절되면 취소분 웹훅의 cause.code는 PREDECESSOR_FAILED입니다. 수정분만 발행되고 취소분 발행이 실패하면 원본과 수정분이 함께 유효한 상태가 되니, 두 키를 함께 볼타에 문의하세요.

볼타는 웹훅 전송에 실패하면 최초 전송을 포함해 최대 8번 시도합니다. 같은 이벤트가 두 번 오거나 순서가 바뀔 수 있으니 webhook-id를 고유 키로 기록하고, 업무 반영은 eventType과 issuanceKey 기준으로도 중복을 막으세요. 웹훅이 오지 않으면 내용 조회 API로 상태를 확인합니다.

정발행부터 수정발행까지 한 흐름으로 붙이려면 볼타 전자세금계산서 발행 API 소개를 참고하세요. API 연동 전체 그림은 세금계산서 API 가이드에 정리돼 있습니다.

자주 묻는 질문

부분 환불은 계약의 해제와 공급가액 변동 중 무엇으로 처리하나요?

공급이 일부라도 이뤄졌고 금액만 줄었다면 시행령 3호의 공급가액 변동에 가깝습니다. 볼타 API에서는 changeSupplyCost 엔드포인트에 환불액을 음수 품목으로 보내세요. 계약의 해제는 계약이 해제돼 공급이 일어나지 않은 경우의 사유이고, 재화를 돌려받은 반품은 환입 사유입니다.

계약의 해제 수정발행에 품목 금액을 따로 보내야 하나요?

보내지 않습니다. 요청 본문에는 date만 넣고, 볼타가 원본 세금계산서를 그대로 상계 처리합니다. 원본 품목 공급가액이 음수이면 이 사유로 수정발행할 수 없습니다.

반품이나 기재사항 착오도 API로 수정발행할 수 있나요?

할 수 있습니다. 반품은 환입(/amend/return)에 환입일과 음수 품목을 보내고, 기재사항 착오는 기재사항 착오정정(/amend/misspell)에 고친 내용을 정발행 형식으로 보냅니다. 착오정정은 취소분과 수정분 두 장을 발행하며, 위수탁 건과 공급받는자 식별번호가 외국인등록번호인 건은 지원하지 않습니다.

볼타 웹 화면에서 발행한 세금계산서도 API로 수정발행할 수 있나요?

할 수 없습니다. 수정발행 API는 같은 API 키로 발행한 원본의 issuanceKey만 받습니다(2026년 11월 기준 볼타 동작). 웹 화면 발행분은 웹 화면의 [수정발행]에서 처리하고, 다른 API 키로 발행한 원본을 요청하면 403 FORBIDDEN이 옵니다.

수정발행에도 요금이 드나요?

볼타 전자세금계산서 API 제품 페이지는 정발행과 수정발행 모두 1건당 90원으로 안내합니다. 기재사항 착오정정은 요청 한 번에 취소분과 수정분 두 장이 나가고, 포인트도 장마다 차감됩니다. 서비스 구독 요금과 API 이용 요금은 별개이고, API는 사전 충전 방식으로 이용합니다.


수정세금계산서를 언제까지 발급해야 하는지는 사유마다 다릅니다. 기한과 신고 일정은 세금계산서 수정신고 기한 확인 방법에서 이어서 확인하세요.

Share article