튜토리얼

Java 개발환경에서 팝빌 SDK를 추가하여 전자세금계산서 즉시 발행 (RegistIssue) 함수를 구현하는 예시입니다.

1. POPBiLL SDK 추가

팝빌 Java SDK를 추가하기 위해 Spring 프로젝트 "pom.xml" 파일에 팝빌 Java SDK dependency 정보를 추가하고 Maven 업데이트합니다.

<dependency>
    <groupId>kr.co.linkhub</groupId>
    <artifactId>popbill-sdk</artifactId>
    <version>1.67.4</version>
</dependency>

2. POPBiLL SDK 설정

전자세금계산서 클래스를 Spring 빈으로 추가합니다. 아래의 코드를 참조하여 "servlet-context.xml" 파일을 수정합니다.

<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns="http://www.springframework.org/schema/mvc"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:beans="http://www.springframework.org/schema/beans"
  xmlns:context="http://www.springframework.org/schema/context"
  xmlns:util="http://www.springframework.org/schema/util"
  xsi:schemaLocation="http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc.xsd
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd
http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd">

  <annotation-driven/>

  <resources mapping="/resources/**" location="/resources/"/>

  <beans:bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
    <beans:property name="prefix" value="/WEB-INF/views/"/>
    <beans:property name="suffix" value=".jsp"/>
  </beans:bean>

  <context:component-scan base-package="com.popbill.example"/>

  <!--
  <테스트 연동개발 준비사항>
    1) API Key 변경 (연동신청 시 메일로 전달된 정보)
      - LinkID : 링크허브에서 발급한 링크아이디
      - SecretKey : 링크허브에서 발급한 비밀키
    2) SDK 환경설정 옵션 설정
      - IsTest : 연동환경 설정, true-테스트, false-운영(Production), (기본값:false)
      - IPRestrictOnOff : 인증토큰 IP 검증 설정, true-사용, false-미사용, (기본값:true)
      - UseStaticIP : 통신 IP 고정, true-사용, false-미사용, (기본값:false)
      - UseLocalTimeYN : 로컬시스템 시간 사용여부, true-사용, false-미사용, (기본값:true)
  -->
  <util:properties id="EXAMPLE_CONFIG">
    <beans:prop key="LinkID">TESTER</beans:prop>
    <beans:prop key="SecretKey">SwWxqU+0TErBXy/9TVjIPEnI0VTUMMSQZtJf3Ed8q3I=</beans:prop>
    <beans:prop key="IsTest">true</beans:prop>
    <beans:prop key="IsIPRestrictOnOff">true</beans:prop>
    <beans:prop key="UseStaticIP">false</beans:prop>
    <beans:prop key="UseLocalTimeYN">true</beans:prop>
  </util:properties>

  <beans:beans>
    <!-- 전자세금계산서 서비스 객체 초기화  -->
    <beans:bean id="taxinvoiceService" class="com.popbill.api.taxinvoice.TaxinvoiceServiceImp">
      <beans:property name="linkID" value="#{EXAMPLE_CONFIG.LinkID}"/>
      <beans:property name="secretKey" value="#{EXAMPLE_CONFIG.SecretKey}"/>
      <beans:property name="test" value="#{EXAMPLE_CONFIG.IsTest}"/>
      <beans:property name="IPRestrictOnOff" value="#{EXAMPLE_CONFIG.IsIPRestrictOnOff}"/>
      <beans:property name="useStaticIP" value="#{EXAMPLE_CONFIG.UseStaticIP}"/>
      <beans:property name="useLocalTimeYN" value="#{EXAMPLE_CONFIG.UseLocalTimeYN}"/>
    </beans:bean>
  </beans:beans>
</beans:beans>

3. RegistIssue 기능 구현

① 서비스 클래스 빈 객체 추가를 위해 @Autowired 어노테이션과 RegistIssue 함수 호출 코드를 추가합니다.

import java.util.ArrayList;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;

import com.popbill.api.IssueResponse;
import com.popbill.api.PopbillException;
import com.popbill.api.TaxinvoiceService;
import com.popbill.api.taxinvoice.Taxinvoice;
import com.popbill.api.taxinvoice.TaxinvoiceAddContact;
import com.popbill.api.taxinvoice.TaxinvoiceDetail;

@Controller
public class TaxinvoiceServiceExample {

    @Autowired
    private TaxinvoiceService taxinvoiceService;

    @RequestMapping(value = "registIssue", method = RequestMethod.GET)
    public String registIssue(Model m) {

        // 팝빌회원 사업자번호
        String CorpNum = "1234567890";

        // 전자세금계산서 정보
        Taxinvoice taxinvoice = new Taxinvoice();

        // 발행형태, {정발행, 역발행, 위수탁} 중 기재
        taxinvoice.setIssueType("정발행");

        // 과세형태, {과세, 영세, 면세} 중 기재
        taxinvoice.setTaxType("과세");

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

        // 일련번호
        taxinvoice.setSerialNum("123");

        // 책번호 '권' 항목
        taxinvoice.setKwon((short) 1);

        // 책번호 '호' 항목
        taxinvoice.setHo((short) 1);

        // 작성일자, 날짜형식(yyyyMMdd)
        taxinvoice.setWriteDate("20250711");

        // 영수/청구, {영수, 청구, 없음} 중 기재
        taxinvoice.setPurposeType("영수");

        // 공급가액 합계
        taxinvoice.setSupplyCostTotal("100000");

        // 세액 합계
        taxinvoice.setTaxTotal("10000");

        // 합계금액, 공급가액 + 세액
        taxinvoice.setTotalAmount("110000");

        // 현금
        taxinvoice.setCash("");

        // 수표
        taxinvoice.setChkBill("");

        // 외상
        taxinvoice.setCredit("");

        // 어음
        taxinvoice.setNote("");

        // 비고
        // {invoiceeType}이 "외국인" 이면 remark1 필수
        // - 외국인 등록번호 또는 여권번호 입력
        taxinvoice.setRemark1("비고1");
        taxinvoice.setRemark2("비고2");
        taxinvoice.setRemark3("비고3");

        /***************************************************************************
         * 공급자 정보
         ****************************************************************************/

        // 공급자 문서번호, 1~24자리 (숫자, 영문, '-', '_') 조합으로 사업자 별로 중복되지 않도록 구성
        taxinvoice.setInvoicerMgtKey("20250711-MVC001");

        // 공급자 사업자번호 (하이픈 '-' 제외 10 자리)
        taxinvoice.setInvoicerCorpNum(CorpNum);

        // 공급자 종사업장 식별번호, 필요시 기재. 형식은 숫자 4자리.
        taxinvoice.setInvoicerTaxRegID("");

        // 공급자 상호
        taxinvoice.setInvoicerCorpName("공급자 상호");

        // 공급자 대표자 성명
        taxinvoice.setInvoicerCEOName("공급자 대표자 성명");

        // 공급자 주소
        taxinvoice.setInvoicerAddr("공급자 주소");

        // 공급자 업태
        taxinvoice.setInvoicerBizType("공급자 업태,업태2");

        // 공급자 종목
        taxinvoice.setInvoicerBizClass("공급자 종목");

        // 공급자 담당자 성명
        taxinvoice.setInvoicerContactName("공급자 담당자 성명");

        // 공급자 담당자 부서명
        taxinvoice.setInvoicerDeptName("공급자 담당자 부서명");

        // 공급자 담당자 연락처
        taxinvoice.setInvoicerTEL("070-7070-0707");

        // 공급자 담당자 휴대폰
        taxinvoice.setInvoicerHP("010-000-2222");

        // 공급자 담당자 메일
        taxinvoice.setInvoicerEmail("test@test.com");

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

        /***************************************************************************
         * 공급받는자 정보
         ****************************************************************************/

        // [역발행시 필수] 공급받는자 문서번호, 1~24자리 (숫자, 영문, '-', '_') 를 조합하여 사업자별로 중복되지 않도록 구성
        taxinvoice.setInvoiceeMgtKey("");

        // 공급받는자 유형, [사업자, 개인, 외국인] 중 기재
        taxinvoice.setInvoiceeType("사업자");

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

        // 공급받는자 종사업장 식별번호, 필요시 숫자4자리 기재
        taxinvoice.setInvoiceeTaxRegID("");

        // 공급받는자 상호
        taxinvoice.setInvoiceeCorpName("공급받는자 상호");

        // 공급받는자 대표자 성명
        taxinvoice.setInvoiceeCEOName("공급받는자 대표자 성명");

        // 공급받는자 주소
        taxinvoice.setInvoiceeAddr("공급받는자 주소");

        // 공급받는자 업태
        taxinvoice.setInvoiceeBizType("공급받는자 업태");

        // 공급받는자 종목
        taxinvoice.setInvoiceeBizClass("공급받는자 종목");

        // 공급받는자 담당자 성명
        taxinvoice.setInvoiceeContactName1("공급받는자 담당자 성명");

        // 공급받는자 담당자 부서명
        taxinvoice.setInvoiceeDeptName1("공급받는자 담당자 부서명");

        // 공급받는자 담당자 연락처
        taxinvoice.setInvoiceeTEL1("070-111-222");

        // 공급받는자 담당자 휴대폰
        taxinvoice.setInvoiceeHP1("010-111-222");

        // 공급받는자 담당자 메일
        // 팝빌 개발환경에서 테스트하는 경우에도 안내 메일이 전송되므로,
        // 실제 거래처의 메일주소가 기재되지 않도록 주의
        taxinvoice.setInvoiceeEmail1("test@invoicee.com");

        // 공급받는자 알림문자 전송 여부 (true / false 중 택 1)
        // └ true = 전송 , false = 미전송
        // └ 공급자 담당자 휴대폰 {invoicerHP} 값으로 문자 전송
        // - 전송 시 포인트 차감되며, 전송실패시 환불처리
        taxinvoice.setInvoiceeSMSSendYN(false);

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

        // 수정 사유코드, 수정사유에 따라 1~6 중 선택기재.
        taxinvoice.setModifyCode(null);

        // 당초 국세청승인번호
        taxinvoice.setOrgNTSConfirmNum(null);

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

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

        /***************************************************************************
         * 품목 상세정보
         ****************************************************************************/

        taxinvoice.setDetailList(new ArrayList<TaxinvoiceDetail>());

        TaxinvoiceDetail detail = new TaxinvoiceDetail();

        detail.setSerialNum((short) 1); // 일련번호, 1부터 순차기재
        detail.setPurchaseDT("20250711"); // 거래일자
        detail.setItemName("품명"); // 품명
        detail.setSpec("규격"); // 규격
        detail.setQty("1"); // 수량
        detail.setUnitCost("50000"); // 단가
        detail.setSupplyCost("50000"); // 공급가액
        detail.setTax("5000"); // 세액
        detail.setRemark("품목비고"); // 비고

        taxinvoice.getDetailList().add(detail);

        detail = new TaxinvoiceDetail();

        detail.setSerialNum((short) 2);
        detail.setPurchaseDT("20250711");
        detail.setItemName("품명2");
        detail.setSpec("규격");
        detail.setQty("1");
        detail.setUnitCost("50000");
        detail.setSupplyCost("50000");
        detail.setTax("5000");
        detail.setRemark("품목비고2");

        taxinvoice.getDetailList().add(detail);

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

        taxinvoice.setAddContactList(new ArrayList<TaxinvoiceAddContact>());

        TaxinvoiceAddContact addContact = new TaxinvoiceAddContact();

        addContact.setSerialNum(1); // 일련번호, (1부터 순차적으로 입력 (최대 5))
        addContact.setContactName("추가 담당자 성명"); // 담당자 성명
        addContact.setEmail("test2@test.com"); // 메일

        taxinvoice.getAddContactList().add(addContact);

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

        // 세금계산서 상태 이력을 관리하기 위한 메모
        String Memo = "즉시발행 메모";

        // 지연발행 가능여부 (true / false 중 택 1)
        // └ true = 가능 , false = 불가능
        // - 미입력 시 기본값 false 처리
        // - 발행마감일이 지난 세금계산서를 발행하는 경우, 가산세가 부과될 수 있습니다.
        Boolean ForceIssue = false;

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

        // 세금계산서 발행 안내메일 제목
        String EmailSubject = "";

        // 팝빌회원 아이디
        String UserID = "testkorea";

        try {

            IssueResponse response = taxinvoiceService.registIssue(CorpNum, taxinvoice,
                WriteSpecification, Memo, ForceIssue, DealInvoiceKey, EmailSubject, UserID);

            m.addAttribute("Response", response);

        } catch (PopbillException e) {
            // 예외 발생 시, e.getCode() 로 오류 코드를 확인하고, e.getMessage()로 오류 메시지를 확인합니다.
            System.out.println("오류 코드" + e.getCode());
            System.out.println("오류 메시지" + e.getMessage());
        }

        return "response";
    }
}

② 함수 호출결과 코드와 메시지를 출력하는 response.jsp 파일을 추가합니다.

<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
<%@ page pageEncoding="UTF-8" contentType="text/html; charset=UTF-8"%>
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <title>Popbill SDK Response</title>
  </head>

  <body>
    <p>code (응답코드) : ${Response.code}</p>
    <p>message (응답메시지) : ${Response.message}</p>
    <p>ntsConfirmNum (국세청승인번호) : ${Response.ntsConfirmNum}</p>
  </body>
</html>

4. 결과 확인

함수 호출 반환 결과는 아래와 같습니다.
- 성공 : Response code 숫자 1 반환
- 실패 : PopbillException 음의 정수 8자리 숫자값 오류코드와 오류메시지 반환 [오류코드]