튜토리얼 - VB.NET

.NET 개발환경에서 팝빌 SDK를 추가하고, 전자세금계산서 즉시 발행 (RegistIssue) API를 호출하는 기본 과정을 단계별로 따라 해볼 수 있도록 구성된 가이드 입니다.

1. POPBiLL SDK 추가

① 팝빌 연동자료실에서 VB.NET SDK 예제코드 다운로드 후 압축을 해제합니다.

② 다운받은 SDK 예제코드의 Linkhub/, Popbill/ 폴더를 SDK를 적용할 프로젝트 경로에 복사하고, Linkhub.csproj, Popbill.csproj를 각각 기존 프로젝트로 추가합니다.

③ Popbill 프로젝트를 적용할 프로젝트의 참조로 추가합니다.

2. POPBiLL SDK 설정

연동환경 설정값, 전자세금계산서 서비스 클래스를 선언하고 Form1_Load() 함수에 서비스 클래스 초기화 코드를 추가합니다.

Public Class Form1
  'API Key
  '- 연동신청 시 발급받은 인증 정보(LinkID, SecretKey로 구성)
  '• LinkID: 파트너를 식별하기 위한 고유 식별자
  '• SecretKey: API 인증토큰 발급에 사용되는 키
  '
  'TODO: 아래 LinkID, SecretKey를 발급받은 정보로 교체해 주세요.
  Private Const LinkID As String = "TESTER"
  Private SecretKey As String = "SwWxqU+0TErBXy/9TVjIPEnI0VTUMMSQZtJf3Ed8q3I="

  ' 전자세금계산서 서비스 객체 선언
  Private taxinvoiceService As TaxinvoiceService

  Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load

    ' 전자세금계산서 서비스 객체 초기화
    taxinvoiceService = New TaxinvoiceService(LinkID, SecretKey)

    ' 연동환경(테스트/운영) 설정
    ' - 연동환경을 테스트 또는 운영으로 설정합니다.
    ' • true: 테스트 환경으로 설정
    ' • false(default) : 운영 환경으로 설정
    '
    ' ※ 운영전환 이후부터 IsTest 설정 변경만으로 자유롭게  환경 전환(테스트<->운영)이 가능합니다.
    taxinvoiceService.IsTest = True

    ' 인증토큰 IP 일치 검증 사용 여부
    ' - 인증토큰을 발급받은 IP와, 그 토큰을 사용하여 API를 호출하는 IP가 같은지를 검사합니다.
    '   (토큰이 외부로 유출되어도 다른 IP에서는 사용하지 못하도록 막는 보안 장치)
    ' • true(사용, default) : 두 IP가 일치할 때만 API 호출 허용
    ' • false(미사용) : IP 일치 검사를 생략
    '
    ' ※ false는 토큰 발급 시점의 IP와 API 호출 시점의 IP가 달라질 수 있는 환경에서 사용
    '   예) 오토스케일링, 로드밸런서, NAT 등으로 호출 IP가 유동적인 클라우드 환경
    taxinvoiceService.IPRestrictOnOff = True

    ' 통신 IP 고정 여부
    ' - 고객사의 보안 정책 또는 방화벽으로 인해 고정 IP로 Outbound 통신을 해야 하는 경우 사용합니다.
    ' • true(사용) : 고정(Static) IP 사용
    ' • false(미사용, default) : 가변(Elastic) IP 사용
    '
    ' ※ true 설정 시, 고정된 IP 또는 도메인을 고객사 방화벽 Outbound 목록에 등록이 필요합니다.
    '   (개발자센터 “가이드 > 공통 > 통신” 페이지에서 확인 가능)
    taxinvoiceService.UseStaticIP = False

    ' 로컬시스템 시간 사용 여부
    ' - 현재시각 기준을 설정합니다.
    ' • true(사용) : 로컬시스템 시간 사용
    ' • false(미사용, default) : 팝빌 서버의 시간을 사용
    '
    ' ※ 현재시각은 주로 인증토큰 발급 및 만료 판단 등에 사용됩니다.
    ' ※ 이 설정은 홈택스 수집 기간, 세금계산서 작성일자, 발행일자 같은 업무 데이터의 날짜값을 변경하는 옵션이 아닙니다.
    ' ※ 로컬 서버 시간이 정상 동기화되어 있으면 일반적으로 true를 사용하고 서버 시간 오차로 인증 실패가 의심되거나
    '   서버 시간을 신뢰하기 어려운 환경이면 false를 사용합니다.
    taxinvoiceService.UseLocalTimeYN = False

  End Sub
End Class

3. RegistIssue 기능 구현

Windows Form에 버튼을 생성하고 버튼의 Click Event 코드에 전자세금계산서 즉시 발행 (RegistIssue) 함수 호출 코드를 추가합니다.

Imports Popbill
Imports Popbill.Taxinvoice
Imports System.ComponentModel

Public Class Form1

    Private Sub btnRegistIssue_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) _
        Handles btnRegistIssue.Click
        Dim taxinvoice As Taxinvoice = New Taxinvoice

        '작성일자,yyyyMMdd( 표시형식 )
        taxinvoice.writeDate = "20250314"

        '발행형태, [정발행, 역발행, 위수탁] 중 기재
        taxinvoice.issueType = "정발행"

        ' 과금방향, {정과금, 역과금} 중 기재
        ' └ 정과금 = 공급자 과금 , 역과금 = 공급받는자 과금
        ' -'역과금'은 역발행 세금계산서 발행 시에만 이용가능
        taxinvoice.chargeDirection = "정과금"

        '영수/청구, [영수, 청구, 없음] 중 기재
        taxinvoice.purposeType = "영수"

        '과세형태, [과세, 영세, 면세] 중 기재
        taxinvoice.taxType = "과세"

        '=========================================================================
        '                              공급자 정보
        '=========================================================================

        '공급자 사업자번호, '-' 제외 10자리
        taxinvoice.invoicerCorpNum = txtCorpNum.Text

        '공급자 종사업장 식별번호. 필요시 숫자 4자리 기재
        taxinvoice.invoicerTaxRegID = ""

        '공급자 상호
        taxinvoice.invoicerCorpName = "공급자 상호"

        '공급자 문서번호, 최대 24자리, 영문, 숫자 '-', '_'를 조합하여 사업자별로 중복되지 않도록 구성
        taxinvoice.invoicerMgtKey = txtMgtKey.Text

        '공급자 대표자 성명
        taxinvoice.invoicerCEOName = "공급자 대표자 성명"

        '공급자 주소
        taxinvoice.invoicerAddr = "공급자 주소"

        '공급자 종목
        taxinvoice.invoicerBizClass = "공급자 업종"

        '공급자 업태
        taxinvoice.invoicerBizType = "공급자 업태,업태2"

        '공급자 담당자명
        taxinvoice.invoicerContactName = "공급자 담당자명"

        '공급자 담당자 메일주소
        taxinvoice.invoicerEmail = ""

        '공급자 담당자 연락처
        taxinvoice.invoicerTEL = ""

        '공급자 담당자 휴대폰번호
        taxinvoice.invoicerHP = ""

        ' 발행 안내 문자 전송여부 (true / false 중 택 1)
        ' └ true = 전송 , false = 미전송
        ' └ 공급받는자 (주)담당자 휴대폰번호 {invoiceeHP1} 값으로 문자 전송
        ' - 전송 시 포인트 차감되며, 전송실패시 환불처리
        taxinvoice.invoicerSMSSendYN = False

        '=========================================================================
        '                            공급받는자 정보
        '=========================================================================

        '공급받는자 유형, [사업자, 개인, 외국인] 중 기재
        taxinvoice.invoiceeType = "사업자"

        ' 공급받는자 사업자번호
        ' - {invoiceeType}이 "사업자" 인 경우, 사업자번호 (하이픈 ('-') 제외 10자리)
        ' - {invoiceeType}이 "개인" 인 경우, 주민등록번호 (하이픈 ('-') 제외 13자리)
        ' - {invoiceeType}이 "외국인" 인 경우, "9999999999999" (하이픈 ('-') 제외 13자리)
        taxinvoice.invoiceeCorpNum = "8888888888"

        '공급받는자 상호
        taxinvoice.invoiceeCorpName = "공급받는자 상호"

        '공급받는자 대표자 성명
        taxinvoice.invoiceeCEOName = "공급받는자 대표자 성명"

        '공급받는자 주소
        taxinvoice.invoiceeAddr = "공급받는자 주소"

        '공급받는자 종목
        taxinvoice.invoiceeBizClass = "공급받는자 종목"

        '공급받는자 업태
        taxinvoice.invoiceeBizType = "공급받는자 업태"

        '공급받는자 담당자명
        taxinvoice.invoiceeContactName1 = "공급받는자 담당자명"

        '공급받는자 담당자 메일주소
        '팝빌 테스트 환경에서 테스트하는 경우에도 안내 메일이 전송되므로,
        '실제 거래처의 메일주소가 기재되지 않도록 주의
        taxinvoice.invoiceeEmail1 = ""

        '공급받는자 담당자 연락처
        taxinvoice.invoiceeTEL1 = ""

        '공급받는자 담당자 휴대폰번호
        taxinvoice.invoiceeHP1 = ""


        '=========================================================================
        '                            세금계산서 정보
        '=========================================================================

        '공급가액 합계
        taxinvoice.supplyCostTotal = "100000"

        '세액 합계
        taxinvoice.taxTotal = "10000"

        '합계금액, 공급가액 합계 + 세액합계
        taxinvoice.totalAmount = "110000"

        '기재 상 '일련번호' 항목
        taxinvoice.serialNum = "123"

        '기재상 권 항목, 최대값 32767
        '미기재시 taxinvoice.kwon = Nothing
        taxinvoice.kwon = Nothing

        '기재상 호 항목, 최대값 32767
        '미기재시 taxinvoice.ho = Nothing
        taxinvoice.ho = Nothing

        '기재 상 '현금' 항목
        taxinvoice.cash = ""

        '기재 상 '수표' 항목
        taxinvoice.chkBill = ""

        '기재 상 '어음' 항목
        taxinvoice.note = ""

        '기재 상 '외상미수금' 항목
        taxinvoice.credit = ""

        ' 비고
        ' {invoiceeType}이 "외국인" 이면 remark1 필수
        ' - 외국인 등록번호 또는 여권번호 입력
        taxinvoice.remark1 = "비고1"
        taxinvoice.remark2 = "비고2"
        taxinvoice.remark3 = "비고3"

        ' 사업자등록증 이미지 첨부여부 (true / false 중 택 1)
        ' └ true = 첨부 , false = 미첨부(기본값)
        ' - 팝빌 사이트 또는 인감 및 첨부문서 등록 팝업 URL (GetSealURL API) 함수를 이용하여 등록
        taxinvoice.businessLicenseYN = False

        ' 통장사본 이미지 첨부여부 (true / false 중 택 1)
        ' └ true = 첨부 , false = 미첨부(기본값)
        ' - 팝빌 사이트 또는 인감 및 첨부문서 등록 팝업 URL (GetSealURL API) 함수를 이용하여 등록
        taxinvoice.bankBookYN = False


        '=========================================================================
        '         수정세금계산서 정보 (수정세금계산서 작성시에만 기재)
        '========================================================================='

        ' 수정사유코드, 수정사유에 따라 1~6중 선택기재
        taxinvoice.modifyCode = Nothing

        ' 원본세금계산서의 국세청승인번호
        taxinvoice.orgNTSConfirmNum = ""


        '=========================================================================
        '                            상세항목(품목) 정보
        '=========================================================================

        taxinvoice.detailList = New List(Of TaxinvoiceDetail)

        Dim detail As TaxinvoiceDetail = New TaxinvoiceDetail

        detail.serialNum = 1                            '일련번호, 1부터 순차기재
        detail.purchaseDT = "20250314"                 '거래일자, yyyyMMdd
        detail.itemName = "품목명"                      '품목명
        detail.spec = "규격"                            '규격
        detail.qty = "1"                                '수량
        detail.unitCost = "100000"                      '단가
        detail.supplyCost = "100000"                    '공급가액
        detail.tax = "10000"                            '세액
        detail.remark = "품목비고"                      '비고

        taxinvoice.detailList.Add(detail)

        detail = New TaxinvoiceDetail

        detail.serialNum = 2
        detail.itemName = "품목명"

        taxinvoice.detailList.Add(detail)

        '=========================================================================
        '                              추가담당자 정보
        ' - 세금계산서 발행안내 메일을 수신받을 공급받는자 담당자가 다수인 경우
        ' 담당자 정보를 추가하여 발행안내메일을 다수에게 전송할 수 있습니다.
        '=========================================================================

        taxinvoice.addContactList = New List(Of TaxinvoiceAddContact)

        Dim addContact As TaxinvoiceAddContact = New TaxinvoiceAddContact

        addContact.serialNum = 1                    '일련번호, 1부터 순차기재
        addContact.contactName = "추가담당자명"        '담당자 성명
        addContact.email = ""                       '담당자 메일주소

        taxinvoice.addContactList.Add(addContact)

        ' 지연발행 강제여부  (true / false 중 택 1)
        ' └ true = 가능 , false = 불가능
        ' - 미입력 시 기본값 false 처리
        ' - 발행마감일이 지난 세금계산서를 발행하는 경우, 가산세가 부과될 수 있습니다.
        ' - 가산세가 부과되더라도 발행을 해야하는 경우에는 forceIssue의 값을
        '   true로 선언하여 발행(Issue API)를 호출하시면 됩니다.
        Dim forceIssue As Boolean = False

        '발행시 메모
        Dim memo As String = "즉시발행 메모"

        ' 거래명세서 동시작성여부 (true / false 중 택 1)
        ' └ true = 사용 , false = 미사용
        ' - 미입력 시 기본값 false 처리
        Dim writeSpecification As Boolean = False

        ' {writeSpecification} = true인 경우, 거래명세서 문서번호 할당
        ' - 미입력시 기본값 세금계산서 문서번호와 동일하게 할당
        Dim dealInvoiceMgtKey As String = ""

        ' 발행안내메일 제목, 미기재시 기본양식으로 전송
        Dim emailSubject As String = ""

        Try
            Dim response As IssueResponse = taxinvoiceService.RegistIssue(txtCorpNum.Text, taxinvoice, forceIssue, memo, writeSpecification, dealInvoiceMgtKey, emailSubject)

            MsgBox("code(응답코드) : " + response.code.ToString + vbCrLf + "message(응답메시지) : " + response.message + vbCrLf + "ntsConfirmNum(국세청승인번호) : " + response.ntsConfirmNum)
        Catch ex As PopbillException
            MsgBox("code(응답코드) : " + ex.code.ToString + vbCrLf + "message(응답메시지) : " + ex.Message)
        End Try
    End Sub
End Class

4. API 응답결과 확인

API 호출 응답결과는 다음과 같습니다.

구분	응답
성공	code : 1
실패	code : 오류코드 (8자리 음의 정수) [오류코드] message : 오류메시지