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 Java SDK, input POPBiLL Java SDK dependency information on “pom.xml” file of Spring project and update the Maven.

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

2. POPBiLL SDK Setting

Add e-Commercial Invoice class into Spring Bean. By referring to the code below, edit “servlet-context.xml” file.

<?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"/>

    <util:properties id="EXAMPLE_CONFIG">
        <!-- LinkID -->
        <beans:prop key="LinkID">TESTER</beans:prop>
        <!-- SecretKey -->
        <beans:prop key="SecretKey">SwWxqU+0TErBXy/9TVjIPEnI0VTUMMSQZtJf3Ed8q3I=</beans:prop>
        <!-- Stage setting value , true(TEST), false(PRODUCTION) -->
        <beans:prop key="IsTest">true</beans:prop>
        <!-- Whether to recommend use of authentication token IP restriction function or not, -->
        <!-- recommended to use (true) -->
        <beans:prop key="IsIPRestrictOnOff">true</beans:prop>
        <!-- Whether to use POPBiLL API service static IP or not, -->
        <!-- true – use, false- do not use, default(false) -->
        <beans:prop key="UseStaticIP">false</beans:prop>
        <!-- Whether to use local system time or not, -->
        <!-- true – use(default – recommended), false – do not use -->
        <beans:prop key="UseLocalTimeYN">true</beans:prop>
    </util:properties>

    <beans:beans>
        <!-- e-Commercial Invoice Service Implementation Bean registration.  -->
        <beans:bean id="statementService"
            class="com.popbill.api.statement.StatementServiceImp">
            <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. Implement RegistIssue Function

① To add Service Class Bean object, 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.Response;
import com.popbill.api.StatementService;
import com.popbill.api.statement.Statement;
import com.popbill.api.statement.StatementDetail;

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

    @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] item 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 {
            Response 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.jsp file that outputs the code and message of the API calling result.

<%@ 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>Response code (Response.code) : ${Response.code}</p>
    <p>Response message (Response.message) : ${Response.message}</p>
    <li>POPBiLL confirm number (Response.invoiceNum) : ${Response.invoiceNum}</p>
  </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]