역발행 API 연동, 이메일 승인과 간편 승인 URL은 어떻게 다를까

매입하는 쪽 플랫폼이 공급자에게 역발행을 요청하고 승인받는 흐름을 시스템으로 붙이는 방법
진태양's avatar
Nov 20, 2026
역발행 API 연동, 이메일 승인과 간편 승인 URL은 어떻게 다를까

역발행 API는 매입하는 쪽 플랫폼이 세금계산서 내용을 먼저 작성해 공급자에게 발행을 요청하고, 공급자가 승인하면 발행이 진행되는 흐름을 시스템에 붙이는 API입니다. 볼타 역발행 API는 승인 방식을 두 가지 제공합니다. 볼타가 공급자 담당자에게 승인 이메일을 보내는 이메일 승인, 그리고 플랫폼이 10분간 유효한 승인 URL을 받아 공급자에게 띄우는 간편 승인입니다.

이 글은 도매 플랫폼, 프랜차이즈 본사, 정산 플랫폼처럼 공급자에게 대금을 지급하는 쪽이 역발행 자동화를 설계할 때 필요한 내용을 다룹니다. 두 승인 방식의 차이, 요청 상태 조회와 취소, 웹훅 수신, 공급자가 승인하지 않을 때의 운영 처리, 발행 마감일 검증 순서로 설명합니다. 2026년 11월 볼타 개발자 문서 기준입니다.

역발행 API로 붙이는 승인 흐름

다리 한쪽의 사람이 빛나는 작은 토큰을 건네고 반대편 사람이 열쇠를 들고 기다리는 장면
역발행은 매입자가 요청을 건네고 공급자가 자기 인증서로 승인해야 완결됩니다.

역발행에서 세금계산서를 작성하는 쪽은 공급받는자(매입자)입니다. 다만 발행 주체는 여전히 공급자라서, 공급자가 자기 회사 명의 인증서로 승인해야 세금계산서가 발행됩니다. 역발행이 필요한 이유와 발행 방법은 역발행 세금계산서 발행 이유와 방법에서, 정발행과 역발행의 발행 주체 차이는 세금계산서 정발행과 역발행의 발행 주체에서 확인하세요.

플랫폼 입장에서 역발행 연동은 세 단계로 나뉩니다.

  1. 요청: 정산이 끝난 거래 내용으로 역발행 요청 API를 호출하고, 응답의 issuanceKey를 저장합니다.

  2. 승인: 공급자가 이메일 링크나 승인 URL에서 내용을 확인하고 인증서로 승인합니다.

  3. 결과 반영: 발행 결과 웹훅을 받거나 요청 상태 조회 API로 확인해 정산 데이터에 반영합니다.

두 승인 방식 모두 첫 단계는 공급자를 발급자로 등록하는 일입니다. 발급자 등록 API를 호출한 뒤 역발행 요청으로 넘어가세요. 볼타 제품 페이지도 거래 내용은 매입자가 쓰고 발행 승인은 공급자가 맡는 구조로 설명합니다.

이메일 승인과 간편 승인 비교

두 방식의 가장 큰 차이는 공급자 인증서를 언제 준비하느냐와 승인 화면을 누가 띄우느냐입니다. 볼타 문서의 비교 내용을 한 표로 묶으면 다음과 같습니다.

구분

이메일 승인 역발행

간편 승인 역발행

승인 경로

볼타가 보낸 이메일 링크

플랫폼이 발급한 승인 URL

공급자 인증서 사전 등록

불필요

필요(공동인증서)

승인 화면 제어

볼타에 위임

플랫폼이 직접 제어

URL 유효시간

해당 없음

10분

추가 호출 API

없음

인증서 등록 URL 조회, 승인 URL 조회

잘 맞는 경우

공급자 인증서를 미리 받기 어려운 경우

플랫폼 안에서 승인까지 끝내려는 경우

이메일 승인 역발행

역발행 요청 본문의 supplier.manager.email에 공급자 담당자 주소를 넣으면, 볼타가 그 주소로 승인 요청 메일을 보냅니다. 공급자는 메일의 링크로 볼타 승인 화면에 들어가 6자리 인증번호로 이메일을 확인합니다. 이어서 거래 내용을 검토하고 전자세금용 금융인증서나 공동인증서로 승인합니다. 공급자 회사 명의 인증서가 필요하다는 점은 같습니다. 승인 시점에 인증서를 쓰기 때문에 플랫폼이 미리 등록받을 필요가 없을 뿐입니다.

공급자가 받은 요청이 여러 건이면 같은 사업자의 요청 목록에서 한꺼번에 승인할 수 있습니다. 금융인증서로 한 번에 승인하는 대상은 최대 50건입니다. 한 공급자에게 매달 여러 건을 요청하는 도매 플랫폼이라면 이 동작을 공급자 안내문에 적어 두세요.

간편 승인 역발행

간편 승인은 공급자의 공동인증서를 먼저 등록받아야 시작됩니다. 발급자 등록 응답의 issuerId로 인증서 등록 URL 조회 API(GET /v1/issuers/{issuerId}/certificates/url)를 호출하고, 공급자가 그 URL에서 공동인증서를 등록하게 하세요. 이후 역발행을 요청하고 승인 URL 조회 API로 승인 페이지 주소를 받습니다.

curl "https://xapi.bolta.io/v1/taxInvoices/{issuanceKey}/issueRequest/grant" \
  -u "{API_KEY}:"

# 응답
{ "url": "{승인_페이지_URL}" }

받은 URL은 10분간 유효합니다. 플랫폼 화면에서 새 탭 열기나 페이지 이동으로 공급자에게 보여 주세요. 유효시간이 짧으니 요청 직후 받아 쌓아 두기보다 공급자가 승인 버튼을 누르는 시점에 호출하는 편이 안전합니다.

역발행 요청 보내기와 중복 방지

역발행 요청 API는 POST /v1/taxInvoices/issueRequest입니다. 필수 필드는 date(작성일자), purpose(영수 RECEIPT 또는 청구 CLAIM), taxType, supplier, supplied, items입니다. 품목은 1개 이상 16개 이하로 보내고, 전체 품목의 금액 합이 발행 금액이 됩니다. 인증은 API 키를 Username으로, Password를 비운 Basic 인증으로 합니다.

curl -X POST "https://xapi.bolta.io/v1/taxInvoices/issueRequest" \
  -u "{API_KEY}:" \
  -H "Content-Type: application/json" \
  -H "Bolta-Client-Reference-Id: {정산건번호-요청회차}" \
  -d '{
    "date": "YYYY-MM-DD",
    "purpose": "CLAIM",
    "taxType": "TAXABLE",
    "supplier": {
      "identificationNumber": "{공급자_사업자등록번호_10자리}",
      "organizationName": "{공급자_상호}",
      "representativeName": "{공급자_대표자명}",
      "manager": { "email": "{공급자_담당자_메일주소}", "name": "{담당자명}" }
    },
    "supplied": {
      "identificationNumber": "{우리_사업자등록번호_10자리}",
      "organizationName": "{우리_상호}",
      "representativeName": "{우리_대표자명}",
      "managers": [ { "email": "{우리_담당자_메일주소}", "name": "{담당자명}" } ]
    },
    "items": [
      { "date": "YYYY-MM-DD", "name": "{품목명}", "supplyCost": 100000, "tax": 10000 }
    ]
  }'

# 응답
{ "issuanceKey": "{발행_요청_식별번호}" }

taxType별 세액 규칙도 확인하세요. 과세(TAXABLE)는 품목 세액이 null이면 안 되고, 영세율(ZERO_RATE)은 모든 품목 세액이 0이어야 합니다. 면세(TAX_FREE)는 세액을 생략하거나 null로 보냅니다. 금액 검증도 있습니다. 품목 공급가액 합계는 0이면 안 되고, 세액 합계가 0이나 null이 아니면 공급가액 합계와 부호가 같아야 합니다. 수량을 넣는다면 양수만 받습니다. 어기면 API가 400 INVALID_REQUEST를 반환합니다. 공급받는자 담당자는 1명 이상 2명 이하입니다.

응답의 issuanceKey는 이후 상태 조회, 승인 URL 조회, 취소에 모두 쓰는 키입니다. 형식과 길이가 바뀔 수 있으니 문자열 전체를 그대로 저장하세요.

중복 발행을 막으려면 선택 헤더 Bolta-Client-Reference-Id에 1~255자의 고유값을 넣으세요. 정산 건 번호에 요청 회차를 붙인 값(예: settle-1024-1)을 쓰면 재요청 때도 겹치지 않습니다. 같은 API 키로 이미 접수된 값을 다시 보내면 본문이 같아도 API가 400과 INVALID_REQUEST("이미 접수된 요청입니다")를 반환합니다. 네트워크 오류로 응답을 받지 못했거나 5xx를 받았다면 같은 요청을 다시 보내지 마세요. 관리번호 조회 API로 접수 여부부터 확인하는 것이 순서입니다. 2026년 11월 기준 볼타 동작에서 5xx는 접수 전후 어느 쪽에서 났는지 응답만으로 알 수 없습니다.

요청 상태 조회와 웹훅으로 결과 받기

역발행 요청의 현재 단계는 요청 상태 조회 API(GET /v1/taxInvoices/{issuanceKey}/issueRequest)로 확인합니다. 응답에는 status, 공급자 승인 기한 approvalDueDate, 실패 사유 failure가 들어 있습니다.

status

의미

플랫폼 처리

REQUESTED

접수 완료, 공급자 승인 대기

승인 기한 안내, 공급자 독려

APPROVED

공급자 승인 완료, 국세청 전송 중

발행 결과 대기

ISSUED

발행 완료

정산 건에 발행 완료 반영

REJECTED

공급자 거절

내용 확인 후 새 요청

CANCELED

요청 취소

필요하면 새 요청

EXPIRED

승인 기한 만료

작성일자 유지, 세무 담당자와 지연발급 절차 확인

FAILED

접수 또는 발행 실패

failure.stage로 원인 구분

REQUESTED에는 볼타가 요청을 공급자에게 전달하기 전 구간도 포함됩니다. 그래서 전달 전이거나 전달하지 못하고 끝난 요청은 approvalDueDate가 null입니다. 다른 API 키나 다른 발급자의 요청을 조회하면 403, 없는 키면 404가 돌아옵니다.

상태를 계속 조회하는 대신 웹훅을 기본 경로로 두세요. 세금계산서 웹훅 이벤트는 TAX_INVOICE_ISSUANCE_SUCCESS(발행 성공)와 TAX_INVOICE_ISSUANCE_FAILURE(발행 실패) 두 가지입니다. 공급자가 승인해 발행이 끝나면 성공 이벤트의 data.taxInvoiceUrl에 세금계산서 URL이 담겨 옵니다. 실패 이벤트에는 data.cause.code와 data.cause.message가 옵니다. 거절, 만료, 승인 대기 여부는 볼타 문서가 요청 상태 조회 API로 확인하라고 안내합니다.

웹훅 수신 서버는 다음 조건을 맞추세요.

  • 웹훅 URL은 공개 도메인의 HTTPS 주소로 등록하세요. 볼타는 IP 주소나 내부망 주소로 보내지 않고, 리다이렉트도 따라가지 않습니다.

  • 10초 안에 2xx로 응답하고, 오래 걸리는 처리는 응답 뒤 비동기로 돌리세요.

  • 전송에 실패하면 최초 전송을 포함해 최대 8번 시도하고, 마지막 시도는 첫 시도 후 약 44시간 36분 뒤입니다.

  • 같은 이벤트가 두 번 이상 오거나 순서가 바뀔 수 있으니 webhook-id와 eventType, issuanceKey 기준으로 중복을 막으세요.

  • Standard Webhooks 규격 서명을 검증한 뒤 처리하세요.

8번째 시도까지 실패하면 자동 재시도가 멈춥니다. 웹훅을 받지 못한 건은 요청 상태 조회 API로 메우는 보정 작업을 따로 두세요.

공급자가 승인하지 않을 때 운영 처리

볼타 제품 페이지는 운영팀의 역할을 "승인 대기, 거절, 발행 결과를 구분해 후속 업무를 진행"하는 일로 정의합니다. 상태별로 처리 규칙을 미리 정해 두세요.

승인 대기가 길어질 때

REQUESTED 상태에서 approvalDueDate를 정산 화면에 보여 주고, 기한이 가까워지면 플랫폼의 알림 채널로 공급자에게 승인을 안내하세요. 간편 승인이라면 알림 안의 링크가 승인 URL 조회 API를 호출하는 플랫폼 화면으로 가게 만드세요. 그래야 10분 유효시간에 걸리지 않습니다.

내용이 틀렸거나 거래가 바뀌었을 때

공급자가 승인하기 전이라면 요청 취소 API(PUT /v1/taxInvoices/{issuanceKey}/issueRequest/cancel)로 요청을 거두세요. 정상 취소되면 API가 HTTP 200과 취소한 issuanceKey를 반환합니다. 이미 승인, 취소, 발행된 요청이면 API가 에러를 반환하므로, 취소 전에 상태 조회로 단계를 확인하세요. 취소 뒤에는 고친 내용으로 새로 요청합니다. 이때 Bolta-Client-Reference-Id도 새 값을 써야 합니다.

거절, 만료, 실패가 났을 때

  • REJECTED: 공급자에게 거절 사유를 확인한 뒤 내용을 고쳐 새로 요청하세요.

  • EXPIRED: 승인 기한이 지난 요청입니다. 볼타 승인 안내도 기한이 지난 요청은 거래처에 새 요청을 받으라고 설명합니다.

  • FAILED + SUBMISSION: 요청이 공급자에게 전달되지 않았습니다. 사용하지 않은 새 Bolta-Client-Reference-Id로 다시 요청하세요.

  • FAILED + ISSUANCE: 공급자는 승인했지만 발행에 실패했습니다. failure.code와 failure.message로 원인을 보세요. 이 코드는 보통 발행 실패 웹훅의 data.cause.code와 같고, 사유를 알 수 없으면 ISSUANCE_FAILED입니다.

발행 마감일 검증과 테스트 준비

역발행 요청 API는 요청을 받을 때 작성일자가 발행 마감일 안인지 검증합니다. 마감일을 넘긴 작성일자로 요청하면 API가 400과 INVALID_REQUEST를 반환합니다. 2026년 11월 기준 볼타 동작에서 이 거부는 접수 전 요청 검증 단계에서 끝나 요청자 관리번호를 소모하지 않습니다. 작성일자를 잘못 입력한 경우에는 실제 거래에 맞게 정정한 요청에 같은 관리번호를 써도 됩니다. 볼타 API가 쓰는 마감일은 작성일자가 속한 달의 다음 달 10일이고, 10일이 주말이나 공휴일이면 다음 영업일로 늦춰집니다. 국세청이 기한을 연장한 달은 연장된 날짜를 따릅니다.

승인 단계에서도 마감일이 걸립니다. 이메일 승인은 마감일이 지나면 공급자가 승인할 수 없고, 간편 승인은 승인 URL을 조회할 때 API가 400 에러를 반환합니다. 실제 거래에 맞는 작성일자로 접수했는데 승인 대기 중 기한이 지났다면, 마감일 검증을 통과하려고 날짜를 바꾸지 마세요. 부가가치세법 제34조의 공급시기와 실제 거래일 기준을 유지하고, 공급자의 세무 담당자와 지연발급 처리 절차를 확인하세요. 별도 확인을 거쳐 새로 요청할 때는 원래 요청이 이미 접수된 상태라 관리번호도 새 값을 써야 합니다. 정산 마감 직후 요청을 몰아 보내는 플랫폼이라면 요청 전에 발행 마감일 조회 API로 남은 날짜를 확인하세요.

curl "https://xapi.bolta.io/v1/taxInvoiceIssueDueDates?date=YYYY-MM-DD" \
  -u "{API_KEY}:"

# 응답
{ "date": "YYYY-MM-DD", "issueDueDate": "YYYY-MM-DD" }

이 API는 발급자 등록이나 공동인증서 없이 API 키만으로 호출하고, 포인트를 차감하지 않습니다. 호출 시점의 마감일을 돌려주므로 결과를 오래 저장하지 말고 필요할 때 다시 조회하세요.

개발 단계에서는 테스트 키(test_)로 흐름을 먼저 검증하세요. 테스트 키 요청은 공급자 승인 단계를 거치지 않고, 포인트도 차감하지 않습니다. 요청 취소 API로 취소한 테스트 요청은 상태 조회에서 CANCELED를 반환합니다. 라이브 전환 뒤 역발행 요금은 1건당 200원이며, 서비스 구독 요금과 별도로 사전 충전한 포인트에서 차감합니다(1포인트는 1원). 승인 방식별 준비 조건과 요금은 볼타 세금계산서 역발행 API 소개 페이지에서, 인증서 등록부터 웹훅까지 이어지는 순서는 간편 승인 역발행 개발자 문서에서 확인하세요.

자주 묻는 질문

공급자가 볼타에 가입해야 역발행을 승인할 수 있나요?

이메일 승인은 볼타 계정이 없어도 이메일 인증으로 진행됩니다. 공급자는 요청 메일의 링크로 들어가 이메일 인증번호를 입력하고, 회사 명의 인증서로 승인합니다. 간편 승인은 공급자가 인증서 등록 URL에서 공동인증서를 미리 등록해야 합니다.

승인에 쓸 수 있는 인증서는 무엇인가요?

공급자 회사 명의의 전자세금용 금융인증서, 전자세금용 공동인증서, 사업자 범용 공동인증서 중 하나입니다. 개인 명의 인증서, 은행 거래 전용 인증서, 홈택스 보안카드로는 승인할 수 없습니다.

공급자가 이미 승인한 역발행 요청을 취소할 수 있나요?

취소할 수 없습니다. 요청 취소 API는 이미 승인, 취소, 발행된 요청에 에러를 반환합니다. 취소는 REQUESTED 상태일 때 하세요.

웹훅이 오지 않으면 어떻게 확인하나요?

요청 상태 조회 API에 저장해 둔 issuanceKey를 넣어 호출하세요. 승인 대기, 거절, 만료, 실패 여부까지 함께 확인됩니다. 전송 성공과 실패 이력은 개발자센터의 웹훅 전송 이력에서 볼 수 있습니다.

Share article