Tutorial

Following is an example to implement cash receipt 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 Cash Receipt, add @Autowired annotation and RegistIssue API code.

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.CashbillService;
import com.popbill.api.PopbillException;
import com.popbill.api.CBIssueResponse;
import com.popbill.api.cashbill.Cashbill;

@Controller
@RequestMapping(value = "CashbillService")
public class CashbillServiceController {

    @Autowired
    private CashbillService cashbillService;

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

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

        // Memo
        String Memo = "Memo";

        // Cash receipt information object
        Cashbill cashbill = new Cashbill();

        // Document ID
        // combination of 1~24 alphanumeric characters(number, alphabet, ‘-’, ‘_’)
        cashbill.setMgtKey("20211125-001");

        // Document type, enter either {승인거래, 취소거래}
        // *승인거래 : general cash receipt,
        // *취소거래 : cash receipt for revocation
        cashbill.setTradeType("승인거래");

        // Original NTS confirmation number
        // – enter the value of confirmNum via getInfo API.
        //   It is mandatory to enter for cash receipt for revocation.
        cashbill.setOrgConfirmNum("");

        // Date of trade on the original cash receipt
        // – enter the value of tradeDate via getInfo API.
        //   It is mandatory to enter for cash receipt for revocation.
        cashbill.setOrgTradeDate("");

        // Taxation type, enter either {과세, 비과세}.
        // *과세 : taxable, 비과세 : exempted
        cashbill.setTaxationType("과세");

        // [Buyer] identification number,
        // enter according to the purpose of issuance.
        // Income decduction usage
        // – enter either resident registration number/phone number/card number.
        // Proof of purchase usage
        // – enter either business registration number/ resident registration number/phone number/card number.
        cashbill.setIdentityNum("0101112222");

        // Taxation type, enter either {소득공제용, 지출증빙용}.
        // *소득공제용 : income deduction usage
        // *지출증빙용 : proof of purchase usage
        cashbill.setTradeUsage("소득공제용");

        //Trade type, enter either {일반, 도서공연, 대중교통}.
        // *일반 : general,
        // *도서공연 : book/performance,
        // *대중교통 : public transportation
        cashbill.setTradeOpt("대중교통");

        // Supply value, enter digits only
        cashbill.setSupplyCost("10000");

        // Tax amount, enter digits only
        cashbill.setTax("1000");

        // Service fee, enter digits only
        cashbill.setServiceFee("0");

        // Total amount, enter digits only,
        // sum of service fee + supply value + tax
        cashbill.setTotalAmount("11000");

        // [Seller] business registration number
        // (10-digits except ‘-’)
        cashbill.setFranchiseCorpNum(corpNum);

        // [Seller] branch number
        cashbill.setFranchiseTaxRegID("");

        // [Seller] company name
        cashbill.setFranchiseCorpName("Company Name");

        // [Seller] CEO name
        cashbill.setFranchiseCEOName("Company's CEO Name");

        // [Seller] company address
        cashbill.setFranchiseAddr("Company Address");

        // [Seller] contact number
        cashbill.setFranchiseTEL("07043042991");

        // [Seller] whether to send a notification mail or not
        cashbill.setSmssendYN(false);

        // [Buyer] customer name
        cashbill.setCustomerName("Customer Name");

        // [Buyer] item name
        cashbill.setItemName("Item Name");

        // [Buyer] order number
        cashbill.setOrderNumber("Order Number");

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

        // [Buyer] phone number
        cashbill.setHp("010111222");

        try {
            CBIssueResponse response = cashbillService.registIssue(corpNum, cashbill, Memo);
            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>
    <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>
        <li>TradeDate (Response.tradeDate) : <span th:text="${Response.tradeDate}"></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]