POPBill Developers
가이드

튜토리얼

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

1. POPBiLL SDK 추가

Popbill SpringBoot Starter 추가를 위해 SpringBoot 프로젝트 "build.gradle" 파일에 dependency를 추가 후 Refresh 합니다.
※ Popbill SpringBoot Starter는 SpringBoot v1.0 이상에서 사용 가능하며 Popbill Java SDK AutoConfiguration을 지원합니다.

dependencies {
    implementation 'kr.co.linkhub:popbill-spring-boot-starter:1.14.4'
}

2. POPBiLL SDK 설정

SDK 설정을 위해 아래의 코드를 application.yml 파일에 추가합니다.

popbill:
  #링크아이디
  linkId: TESTER
  #비밀키
  secretKey: SwWxqU+0TErBXy/9TVjIPEnI0VTUMMSQZtJf3Ed8q3I=
  #연동환경 설정, true-테스트, false-운영(Production), (기본값:false)
  isTest: true
  #인증토큰 IP 검증 설정, true-사용, false-미사용, (기본값:true)
  isIpRestrictOnOff: true
  #통신 IP 고정, true-사용, false-미사용, (기본값:false)
  useStaticIp: false
  #로컬시스템 시간 사용여부, true-사용, false-미사용, (기본값:true)
  useLocalTimeYn: true

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 TaxinvoiceServiceController {

    @Autowired
    private TaxinvoiceService taxinvoiceService;

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

        // 세금계산서 정보 객체
        Taxinvoice taxinvoice = new Taxinvoice();

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

        // 과금방향, [정과금, 역과금] 중 선택기재, "역과금"은 역발행세금계산서 발행에만 가능
        taxinvoice.setChargeDirection("정과금");

        // 발행유형, [정발행, 역발행, 위수탁] 중 기재
        taxinvoice.setIssueType("정발행");

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

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


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

        // 공급자 사업자번호
        taxinvoice.setInvoicerCorpNum("1234567890");

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

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

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

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

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

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

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

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

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

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

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

        // 발행 안내문자메시지 전송여부
        // - 전송시 포인트 차감되며, 전송실패시 환불처리
        taxinvoice.setInvoicerSMSSendYN(false);


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

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

        // 공급받는자 사업자번호, '-' 제외 10자리
        taxinvoice.setInvoiceeCorpNum("8888888888");

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

        // [역발행시 필수] 공급받는자 문서번호, 1~24자리까지 사업자번호별 중복없는 고유번호 할당
        taxinvoice.setInvoiceeMgtKey("");

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

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

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

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

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

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

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

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

        // 역발행시 안내문자메시지 전송여부
        // - 전송시 포인트 차감되며, 전송실패시 환불처리
        taxinvoice.setInvoiceeSMSSendYN(false);


        /*********************************************************************
        *                           세금계산서 기재정보
        *********************************************************************/

        // [필수] 공급가액 합계
        taxinvoice.setSupplyCostTotal("100000");

        // [필수] 세액 합계
        taxinvoice.setTaxTotal("10000");

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

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

        // 기재 상 현금
        taxinvoice.setCash("");

        // 기재 상 수표
        taxinvoice.setChkBill("");

        // 기재 상 어음
        taxinvoice.setNote("");

        // 기재 상 외상미수금
        taxinvoice.setCredit("");

        // 기재 상 비고
        taxinvoice.setRemark1("비고1");
        taxinvoice.setRemark2("비고2");
        taxinvoice.setRemark3("비고3");
        taxinvoice.setKwon((short) 1);
        taxinvoice.setHo((short) 1);

        // 사업자등록증 이미지 첨부여부
        taxinvoice.setBusinessLicenseYN(false);

        // 통장사본 이미지 첨부여부
        taxinvoice.setBankBookYN(false);

        /*********************************************************************
        *               수정세금계산서 정보 (수정세금계산서 작성시 기재)
        * - 수정세금계산서 관련 정보는 연동매뉴얼 또는 개발가이드 링크 참조
        & - [참고] 수정세금계산서 작성방법 안내 [http://blog.linkhubcorp.com/650]
        *********************************************************************/

        // [수정세금계산서 작성시 필수] 수정사유코드, 수정사유에 따라 1~6 중 선택기재.
        taxinvoice.setModifyCode(null);

        // [수정세금계산서 작성시 필수] 당초승인번호 기재
        taxinvoice.setOrgNTSConfirmNum("");


        /*********************************************************************
        *                       상세항목(품목) 정보
        *********************************************************************/

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

        // 상세항목 객체
        TaxinvoiceDetail detail = new TaxinvoiceDetail();

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

        taxinvoice.getDetailList().add(detail);


        /*********************************************************************
        *                       추가담당자 정보
        *********************************************************************/

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

        TaxinvoiceAddContact addContact = new TaxinvoiceAddContact();

        addContact.setSerialNum(1);
        addContact.setContactName("추가 담당자명");
        addContact.setEmail("test2@test.com");

        taxinvoice.getAddContactList().add(addContact);


        // 거래명세서 동시작성여부
        Boolean WriteSpecification = false;

        // 거래명세서 문서번호
        String DealInvoiceKey = null;

        // 즉시 발행 메모
        String Memo = "즉시 발행 메모";

        // 지연발행 강제여부
        // 발행마감일이 지난 세금계산서를 발행하는 경우, 가산세가 부과될 수 있습니다.
        // 가산세가 부과되더라도 발행을 해야하는 경우에는 forceIssue의 값을
        // true로 선언하여 발행(Issue API)를 호출하시면 됩니다.
        Boolean ForceIssue = false;

        try {

                IssueResponse response = taxinvoiceService.registIssue("1234567890",
                    taxinvoice, WriteSpecification, Memo, ForceIssue, DealInvoiceKey);

                m.addAttribute("Response", response);

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

            return "response";
}
}

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

<html xmlns:th="http://www.thymeleaf.org"">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <title>Popbill SDK Response</title>
  </head>

  <body>
    <fieldset>
      <ul>
        <li>응답코드 (Response.code) : <span th:text="${Response.code}"></span></li>
        <li>응답메시지 (Response.message) : <span th:text="${Response.message}"></span></li>
        <li>국세청승인번호 (Response.ntsConfirmNum) : <span th:text="${Response.ntsConfirmNum}"></span></li>
      </ul>
    </fieldset>
  </body>
</html>

4. 결과 확인

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