Tutorial

Following is an example to implement e-Tax invoice issuance (RegistIssue) API by adding the POPBiLL SDK within Java setting.

1. Add POPBiLL SDK

To add POPBiLL SpringBoot Starter, enter dependency information on “build.gradle” file of SpringBoot project, then Refresh it.
※ POPBiLL SpringBoot Starter is compatible with SpringBoot v1.0 and later and it is provided with POPBiLL Java SDK AutoConfiguration.

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

2. POPBiLL SDK Setting

For SDK configuration setting, enter the code below within the application.yml file.

popbill:
  #LinkID
  linkId: TESTER
  #SecretKey
  secretKey: SwWxqU+0TErBXy/9TVjIPEnI0VTUMMSQZtJf3Ed8q3I=
  #Stage setting value , true(TEST), false(PRODUCTION)
  isTest: true
  #Whether to recommend use of authentication token IP restriction function or not,
  #recommended to use (true), to not use (false)
  isIpRestrictOnOff: true
  #Whether to use POPBiLL API service static IP or not,
  #true – use, false- do not use, default(false)
  useStaticIp: false
  #Whether to use local system time or not,
  #true – use(default – recommended), false – do not use
  useLocalTimeYn: true

3. Implement RegistIssue Function

① To add Service Class Bean object e-Tax Invoice, add @Autowired annotation and RegistIssue API code.

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

        // Tax invoice information object
        Taxinvoice taxinvoice = new Taxinvoice();

        // Date of preparation , format of data(yyyyMMdd)
        taxinvoice.setWriteDate("20211123");

        //Charge direction, select 정과금(Regular-Charge)
        taxinvoice.setChargeDirection("정과금");

        // Issuance type, select 정발행 (General Issuance)
        taxinvoice.setIssueType("정발행");

        // Payments received or not, select either [영수(paid), 청구(charge),없음(none)]
        taxinvoice.setPurposeType("영수");

        // Tax type, [과세(Tax),영세(Zero-taxed),면세(Tax Exemption)]
        taxinvoice.setTaxType("과세");

        /*********************************************************************
        *                      Seller Information
        *********************************************************************/

        // [Seller] business registration number
        taxinvoice.setInvoicerCorpNum("1234567890");

        // [Seller] business registration number
        // for minor business place, optional, 4-digit numbers
        taxinvoice.setInvoicerTaxRegID("");

        // [Seller] company name
        taxinvoice.setInvoicerCorpName("Seller Company Name");

        // [Seller] document ID
        // combination of 1~24 alphanumeric characters(number, alphabet, ‘-’, ‘_’),
        // to avoid duplicates, assign unique values for each business place
        taxinvoice.setInvoicerMgtKey("20211123-001");

        // [Seller] CEO name
        taxinvoice.setInvoicerCEOName("Seller Company's CEO Name");

        // [Seller] company address
        taxinvoice.setInvoicerAddr("Seller Address");

        // [Seller] items of business
        taxinvoice.setInvoicerBizClass("Seller Business Class");

        // [Seller] type of business
        taxinvoice.setInvoicerBizType("Seller Business Type");

        // [Seller] name of the person in charge
        taxinvoice.setInvoicerContactName("Seller Contactor Name");

        // [Seller] email of the person in charge
        taxinvoice.setInvoicerEmail("test@test.com");

        // [Seller] contact number of the person in charge
        taxinvoice.setInvoicerTEL("070-7070-0707");

        // [Seller] cell phone number of the person in charge
        taxinvoice.setInvoicerHP("010-000-2222");

        // Whether to send a notification text message
        // when issuing a tax invoice
        // - If sent, SMS service points will be deducted
        //   and if sending fails, point will be returned.
        taxinvoice.setInvoicerSMSSendYN(false);

        /*********************************************************************
        *                      Buyer Information
        *********************************************************************/

        // [Buyer] type of buyer,
        // select either [사업자(Business Proprietor), 개인(Individual), 외국인(Foreigner)]
        taxinvoice.setInvoiceeType("사업자");

        // [Buyer] business registration number, 10-digits except ‘_’
        taxinvoice.setInvoiceeCorpNum("8888888888");

        // [Buyer] branch number, 4-digits
        taxinvoice.setInvoiceeTaxRegID("");

        // [Buyer] company name
        taxinvoice.setInvoiceeCorpName("Buyer Company Name");

        // [Buyer] CEO name
        taxinvoice.setInvoiceeCEOName("Buyer Company's CEO Name");

        // [Buyer] company address
        taxinvoice.setInvoiceeAddr("Buyer Address");

        // [Buyer] items of business
        taxinvoice.setInvoiceeBizClass("Buyer Business Class");

        // [Buyer] type of business
        taxinvoice.setInvoiceeBizType("Buyer Business Type");

        // [Buyer] name of the person in charge
        taxinvoice.setInvoiceeContactName1("Buyer Contactor Name");

        // [Buyer] email of the person in charge
        // Do not include the email address of an actual customer.
        // POPBiLL sends an instructional email in the TEST stage as well.
        taxinvoice.setInvoiceeEmail1("test@invoicee.com");

        // [Buyer] contact information of the person in charge
        taxinvoice.setInvoiceeTEL1("070-111-222");

        // [Buyer] cell phone number of the person in charge
        taxinvoice.setInvoiceeHP1("010-111-222");

        // Whether to send a notification text message
        // when issuing a requested invoice
        //- If sent, SMS service points will be deducted
        //  and if sending fails, point will be returned.
        taxinvoice.setInvoiceeSMSSendYN(false);

        /*********************************************************************
        *                    Tax Invoice Information
        *********************************************************************/

        // [Mandatory] total amount of supply value
        taxinvoice.setSupplyCostTotal("100000");

        // [Mandatory] total amount of tax
        taxinvoice.setTaxTotal("10000");

        // [Mandatory] total amount, supply value + tax amount
        taxinvoice.setTotalAmount("110000");

        // Serial number
        taxinvoice.setSerialNum("123");

        // Cash
        taxinvoice.setCash("");

        // Bill
        taxinvoice.setChkBill("");

        // Note
        taxinvoice.setNote("");

        // Accounts receivable
        taxinvoice.setCredit("");

        // Remark
        taxinvoice.setRemark1("Remark1");
        taxinvoice.setRemark2("Remark2");
        taxinvoice.setRemark3("Remark3");

        // 권 ‘kwon’(unit to count number of books of tax invoices),
        // maximum value : 32767
        taxinvoice.setKwon((short) 1);

        // 호 ‘ho’(unit to count the number of volumes for each book of tax invoices),
        // maximum value : 32767
        taxinvoice.setHo((short) 1);

        /*********************************************************************
        * Information of revised invoice
        * (write this for a revised invoice)
        * - Refer to the integration manual
        *   or development guide link
        *   for any information related to revised invoice
        *********************************************************************/

        // [mandatory when writing a revised invoice]
        // code for reasons for revocation,
        // select between 1-6 depending on the reason for revocation
        taxinvoice.setModifyCode(null);

        // [mandatory when writing a revised invoice]
        // write the NTS confirmation number of the original tax invoice
        taxinvoice.setOrgNTSConfirmNum("");

        /*********************************************************************
        *               Information of detailed list of items
        *********************************************************************/

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

        // Object of detailed information
        TaxinvoiceDetail detail = new TaxinvoiceDetail();

        detail.setSerialNum((short) 1); // Serial number, write sequentially starting from 1
        detail.setPurchaseDT("20211123"); // Date of trade
        detail.setItemName(""Item name"); // Item name
        detail.setSpec("Specification"); // Specification
        detail.setQty("1"); // Quantity
        detail.setUnitCost("50000"); // Unit price
        detail.setSupplyCost("50000"); // Supply value
        detail.setTax("5000"); // Tax
        detail.setRemark("Item remark"); // Remark for item

        taxinvoice.getDetailList().add(detail);

        detail = new TaxinvoiceDetail();

        detail.setSerialNum((short) 2); // Serial number, write sequentially starting from 1
        detail.setPurchaseDT("20211123"); // Date of trade
        detail.setItemName(""Item name2"); // Item  name
        detail.setSpec("Specification"); // Specification
        detail.setQty("1"); // Quantity
        detail.setUnitCost("50000"); // Unit price
        detail.setSupplyCost("50000"); // Supply value
        detail.setTax("5000"); // Tax
        detail.setRemark("Item remark2"); // Remark

        taxinvoice.getDetailList().add(detail);

        /*********************************************************************
        *           Additional Person In Charge Information
        *********************************************************************/

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

        TaxinvoiceAddContact addContact = new TaxinvoiceAddContact();

        addContact.setSerialNum(1);
        addContact.setContactName("Additional Contactor Name");
        addContact.setEmail("test2@test.com");

        taxinvoice.getAddContactList().add(addContact);


        // Whether to concurrently generate the transaction details or not
        Boolean WriteSpecification = false;

        // Document ID of the transaction details
        String DealInvoiceKey = null;

        // Memo for issuance
        String Memo = "Memo";

        // Option on whether to allow the delayed issuance or not
        // You may be subjected to penalty tax
        // if you issue a tax invoice past the deadline for issuance
        // If you must issue regardless of the penalty tax,
        // set the forceIssue value as true and call the issuance API (Issue API).
        Boolean ForceIssue = false;

        try {
            IssueResponse response = taxinvoiceService.registIssue("1234567890",
                taxinvoice, WriteSpecification, Memo, ForceIssue, DealInvoiceKey);
            m.addAttribute("Response", response);
        } catch (PopbillException e) {
            // If an exception occurs,
            // check an error code with e.gtCode()
            // and error message with e.getMessage()
            System.out.println("Error Code : " + e.getCode());
            System.out.println("Error Message : " + e.getMessage());
        }

        return "response";
    }
}

② Add response.html file that outputs the code and message of the API calling result.

<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. Check the Result

If the API calling is being processed successfully, Response code will be returned as “1” and if it fails, an error code(8-digits that starts with “-”) and error message will be returned to POPBiLL Exception. [Error Code]