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
① Download the Java – JSP SDK exemplary code from POPBiLL library and decompress it.
② Copy 3 jar files from the folder within the WEB-INF/lib/ of SDK exemplary code and paste it to the project library folder.
2. POPBiLL SDK Setting
For e-Tax Invoice service configuration setting, generate “$CATALINA_HOME?webapps/ROOT/common.jsp” file within the file path of the project. Then, complete the setting of the authentication information by referring to the code below.
<%-- Generate e-Tax invoice Service Class Bean --%>
<jsp:useBean id="taxinvoiceService" scope="application" class="com.popbill.api.taxinvoice.TaxinvoiceServiceImp"/>
<%-- LinkID – enter the provided API credentials information --%>
<jsp:setProperty name="taxinvoiceService" property="linkID" value="TESTER"/>
<%-- SecretKey– enter the provided API credentials information --%>
<jsp:setProperty name="taxinvoiceService" property="secretKey" value="SwWxqU+0TExEXy/9TVjKPExI2VTUMMSLZtJf3Ed8q3I="/>
<%-- STAGE configuration setting, true – TEST, false – PRODUCTION --%>
<jsp:setProperty name="taxinvoiceService" property="test" value="true"/>
<%-- Whether to register the Authentication token registration IP or not (On/Off), --%>
<%-- true – On(default-recommended), false - Off – PRODUCTION --%>
<jsp:setProperty name="taxinvoiceService" property="IPRestrictOnOff" value="true"/>
<%-- Whether to use static IP or not, --%>
<%-- true – use static IP, false – do not use static IP(default) --%>
<jsp:setProperty name="taxinvoiceService" property="useStaticIP" value="false"/>
<%-- Whether to use local system time or not, --%>
<%-- true – use (default – recommended), false – do not use --%>
<jsp:setProperty name="taxinvoiceService" property="useLocalTimeYN" value="true"/>3. Implement RegistIssue Function
Generate the “$CATALINA_HOME/webapps/ROOT/RegistIssue.jsp” file. Then, add the code to call API by referring to the example below.
<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%>
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8" />
<title>Popbill Taxinvoice Example</title>
</head>
<%@ include file="common.jsp" %>
<%@page import="java.util.ArrayList"%>
<%@page import="com.popbill.api.IssueResponse"%>
<%@page import="com.popbill.api.PopbillException"%>
<%@page import="com.popbill.api.taxinvoice.Taxinvoice"%>
<%@page import="com.popbill.api.taxinvoice.TaxinvoiceDetail"%>
<%@page import="com.popbill.api.taxinvoice.TaxinvoiceAddContact"%>
<%
// Tax invoice information object
Taxinvoice taxinvoice = new Taxinvoice();
// Date of preparation, format of data(yyyyMMdd)
taxinvoice.setWriteDate("20220101");
// Issuance type, select 정발행 (General Issuance)
taxinvoice.setIssueType("정발행");
// Charge direction, select 정과금(Regular-Charge)
taxinvoice.setChargeDirection("정과금");
// Payments received or not, select either [영수(paid), 청구(charge),없음(none)]
taxinvoice.setPurposeType("영수");
// Tax type, enter either [과세(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("20220101-TEST001");
// [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 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@test.com");
// [Buyer] contract number
taxinvoice.setInvoiceeTEL1("070-1234-1234");
// [Buyer] cell phone number
taxinvoice.setInvoiceeHP1("010-000-1111");
// 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("200000");
// [Mandatory] total amount of tax
taxinvoice.setTaxTotal("20000");
// [Mandatory] total amount, supply value + tax amount
taxinvoice.setTotalAmount("220000");
// 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);
// Whether to attach a copy of business registration certificate or not
taxinvoice.setBusinessLicenseYN(false);
// Whether to attach a copy of bankbook or not
taxinvoice.setBankBookYN(false);
/***************************************************************************
* 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("20220101"); // Date of trade
detail.setItemName(""Item name1"); // Item name
detail.setSpec("Specification"); // Specification
detail.setQty("1"); // Quantity
detail.setUnitCost("100000"); // Unit price
detail.setSupplyCost("100000"); // Supply value
detail.setTax("10000"); // 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;
IssueResponse IssueResponse = null;
try {
IssueResponse = taxinvoiceService.registIssue("1234567890", taxinvoice, writeSpecification,
memo, forceIssue, dealInvoiceKey);
} catch (PopbillException pe) {
// if an exceptional error occurs,
// check the error code with pe.getCode()
// and check the error message with pe.getMessage()
System.out.println("Error Code : " + e.getCode());
System.out.println("Error Message : " + e.getMessage());
throw pe;
}
%>
<body>
<p>Response</p>
<br/>
<fieldset>
<legend>Taxinvoice Issuance</legend>
<ul>
<li>Response code (IssueResponse.code) : <%=IssueResponse.getCode()%></li>
<li>Response message (IssueResponse.message) : <%=IssueResponse.getMessage()%></li>
<li>NTS confirmation number (IssueResponse.ntsConfirmNum) : <%=IssueResponse.getNtsConfirmNum()%></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]