Tutorial

Following is an example to implement e-Commercial 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-Commercial Invoice, add @Autowired annotation and RegistIssue API code.

import java.util.ArrayList;
import java.util.HashMap;
import java.util.Map;

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.PopbillException;
import com.popbill.api.SMTIssueResponse;
import com.popbill.api.StatementService;
import com.popbill.api.statement.Statement;
import com.popbill.api.statement.StatementDetail;

@Controller
@RequestMapping(value = "StatementService")
public class StatementServiceController {

    @Autowired
    private StatementService statementService;

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

        // [Seller] business registration number
        String corpNum = "1234567890";

        // [Seller] POPBiLL ID
        String testUserID = "testkorea";

        // Title of a notification mail ( default if not entered )
        String emailSubject = "Email Subject";

        // Memo
        String Memo = "Memo";

        // E-Commercial invoice information object
        Statement statement = new Statement();

        // [Mandatory] date of preparation, format : yyyyMMdd
        statement.setWriteDate("20220101");

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

        // [Mandatory] tax type, enter either {과세,영세,면세}
        // *과세 : taxable, 영세 : zero-rated, 면세 : exempted
        statement.setTaxType("과세");

        // Custom form code, default if not entered.
        statement.setFormCode("");

        // [Mandatory] types of invoice,
        // [121 – transaction details], [122- bill],
        // [123 – estimate], [124 – purchase order],
        // [125 – deposit slip], [126 – receipt]
        statement.setItemCode((short) 121);

        // [Mandatory] document ID,
        // combination of 1~24 alphanumeric characters(number, alphabet, ‘-’, ‘_’)
        statement.setMgtKey("20220101-001");

        /*********************************************************************
        *                       Sender Information
        *********************************************************************/

        // [Mandatory] sender’s business registration number
        statement.setSenderCorpNum(corpNum);

        // [Mandatory] sender’s company name
        statement.setSenderCorpName("Sender Company Name");

        // [Mandatory] sender’s company address
        statement.setSenderAddr("Sender Address");

        // [Mandatory] sender’s CEO name
        statement.setSenderCEOName("Sender Company's CEO Name");

        // [Sender] branch number, 4-digits, optional entry
        statement.setSenderTaxRegID("");

        // [Sender] items of business
        statement.setSenderBizClass("Sender Business Class");

        // [Sender] type of business
        statement.setSenderBizType(Sender Business Type");

        // [Sender] name of the person in charge
        statement.setSenderContactName("Sender Contactor Name");

        // [Sender] email of the person in charge
        statement.setSenderEmail("test@test.com");

        // [Sender] contact number of the person in charge
        statement.setSenderTEL("070-7070-0707");

        // [Sender] cell phone number of the person in charge
        statement.setSenderHP("010-000-2222");

        /*********************************************************************
        *                      Receiver Information
        *********************************************************************/

        // [Mandatory] receiver's business registration number
        statement.setReceiverCorpNum("8888888888");

        // [Mandatory] receiver's company name
        statement.setReceiverCorpName("Receiver Company Name");

        // [Mandatory] receiver's CEO name
        statement.setReceiverCEOName("Receiver Company's CEO Name");

        // [Receiver] company address
        statement.setReceiverAddr("Receiver Address");

        // [Receiver] items of business
        statement.setReceiverBizClass("Receiver Business Class");

        // [Receiver] type of business
        statement.setReceiverBizType("Receiver Business Type");

        // [Receiver] name of the person in charge
        statement.setReceiverContactName("Receiver Contactor Name");

        // [Receiver] email
        // Do not include the email address of an actual customer
        // POPBiLL sends an instructional email in the TEST stage as well
        statement.setReceiverEmail("test@receiver.com");

        /*********************************************************************
        *                 Information of e-Commercial Invoice
        *********************************************************************/

        // Total amount of supply value
        statement.setSupplyCostTotal("400000");

        // Total amount of tax
        statement.setTaxTotal("40000");

        // Total amount. supply value + tax
        statement.setTotalAmount("440000");

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

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

        /*********************************************************************
        *              Item Information of e-Commercial Invoice
        *********************************************************************/

        // Array of list of detailed item information
        statement.setDetailList(new ArrayList<StatementDetail>());

        StatementDetail detail = new StatementDetail();

        detail.setSerialNum((short) 1);  // Serial number, write sequentially starting from 1
        detail.setItemName("Item1");  // Item name
        detail.setPurchaseDT("20211125");  // Date of trade
        detail.setQty("1");  // Quantity
        detail.setSupplyCost("200000");  // Supply value
        detail.setTax("20000");  // Tax

        statement.getDetailList().add(detail);

        detail = new StatementDetail();
        detail.setSerialNum((short) 2);  // Serial number, write sequentially starting from 1
        detail.setItemName("Item2");  // Item name
        detail.setPurchaseDT("20211125");  // Date of trade
        detail.setQty("1");  // Quantity
        detail.setSupplyCost("200000");  // Supply value
        detail.setTax("20000");  // Tax

        statement.getDetailList().add(detail);

        /*********************************************************************
        *            Additional properties of e-Commercial Invoice
        *********************************************************************/

        Map<String, String> propertyBag = new HashMap<String, String>();

        propertyBag.put("Balance", "15000");  // Amount before deposit
        propertyBag.put("Deposit", "5000");   // Deposit amount
        propertyBag.put("CBalance", "20000"); // Remaining amount

        statement.setPropertyBag(propertyBag);

        try {
            SMTIssueResponse response = statementService.registIssue(corpNum, statement, Memo, testUserID, emailSubject);

            m.addAttribute("Response", response);

        } catch (PopbillException e) {
            // If an exceptional error occurs,
            // check the error code with e.getCode( )
            // and check the 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>
    <ul>
      <li>Response Code (Response.code) : <span th:text="${Response.code}"></span></li>
      <li>Response Message (Response.message) : <span th:text="${Response.message}"></span></li>
      <li>POPBiLL confirm number (Response.invoiceNum) : <span th:text="${Response.invoiceNum}"></span></li>
    </ul>
  </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]