POPBill Developers
SDK Reference
e-Tax Invoice
Java
SDK Reference e-Tax Invoice Java Issue

Issue

1. RegistIssue - Issue an e-Tax invoice

  • This API issues(digitally signs) the generated e-Tax invoice data and process it as “issued”. 
IssueResponse registIssue(String CorpNum, Taxinvoice taxinvoice, Boolean WriteSpecification, String Memo, Boolean ForceIssue, String DealInvoiceKey, String EmailSubject, String UserID) throws PopbillException
  • The seller’s certificate must be pre-registered in POPBiLL server to issue a tax invoice.
  • When issuing a tax invoice, service points will be charged, and a notification mail will be sent to the buyer.
Parameters
Parameters
No.FieldTypeLengthMandatoryDescription
CorpNum String 10 Y Business registration number
10-digits except (‘-’)
taxinvoice Taxinvoice - Y Object of an e-Tax invoice
Taxinvoice
No. Field Type Length Mandatory Description
issueType String 3 Y Issuance type
정발행general issuance
taxType String 2 Y Taxation type
과세taxable
영세zero-rated
면세exempted
chargeDirection String 3 Y Charging Direction
정과금Paid by seller
serialNum String 30 N Serial number
item to manage the list of e-Tax invoice
kwon Short 4 N Volume of a book
item to manage the list of e-Tax invoice
ho Short 4 N Number of a book
item to manage the list of e-Tax invoice
writeDate String 8 Y Date of preparation
format : yyyyMMdd
purposeType String 2 Y Payments received or not
영수payment received
청구payment not received
없음none
supplyCostTotal String 18 Y Sum of supply values
integer values(+/-) only
decimals will be automatically truncated
taxTotal String 18 Y Sum of tax amount
integer values(+/-) only
decimals will be automatically truncated
totalAmount String 18 Y Total amount
integer values(+/-) only
decimals will be automatically truncated
cash String 18 N Payment method – ‘cash’
chkBill String 18 N Payment method – ‘check’
credit String 18 N Payment method – ‘credit’
note String 18 N Payment method – ‘note’
remark1 String 150 Conditional 1st Remark
foreign registration number
passport number
this field is mandatory if {invoiceeType} = “외국인(foreigner)”
remark2 String 150 N 2nd Remark
remark3 String 150 N 3rd Remark
invoicerMgtKey String 24 Ｙ [Seller] document ID
a unique value that can be entered with alphanumeric values and special characters(‘-’, ‘_’)
invoicerCorpNum String 10 Y [Seller] business registration number
10 digits except a hyphen(‘-’)
invoicerTaxRegID String 4 N [Seller] identification number of a branch place
4 digits
invoicerCorpName String 200 Y [Seller] company name
invoicerCEOName String 100 Y [Seller] CEO name
invoicerAddr String 300 N [Seller] company address
invoicerBizType String 100 N [Seller] type of business
invoicerBizClass String 100 N [Seller] items of business
invoicerContactName String 100 N [Seller] name of the person in charge
invoicerDeptName String 100 N [Seller] department of the person in charge
invoicerTEL String 20 N [Seller] contact number of the person in charge
invoicerHP String 20 N [Seller] cell phone number of the person in charge
invoicerEmail String 100 N [Seller] email of the person in charge
invoiceeType String - Y [Buyer] type of customer
사업자business proprietor
개인individual
외국인foreigner
invoiceeCorpNum String - Y [Buyer] business registration number
- if {invoiceeType} = 사업자(business proprietor type) : business registration number, 10 digits except a hyphen(‘-’)
- if {invoiceeType} = 개인(individual type) : resident registration number, 13 digits except a hyphen(‘-’)
- if {invoiceeType} = 외국인(foreigner type) : 9999999999999
invoiceeTaxRegID String 4 N [Buyer] identification number of a branch place
4 digits
invoiceeCorpName String 200 Y [Buyer] company name
invoiceeCEOName String 100 Y [Buyer] CEO name
invoiceeAddr String 300 N [Buyer] company address
invoiceeBizType String 100 N [Buyer] type of business
invoiceeBizClass String 100 N [Buyer] items of business
invoiceeContactName1 String 100 N [Buyer] name of the person in charge
invoiceeDeptName1 String 100 N [Buyer] department of the person in charge
invoiceeTEL1 String 20 N [Buyer] contact number of the person in charge
invoiceeHP1 String 20 N [Buyer] telephone number of the person in charge
invoiceeEmail1 String 100 N [Buyer] email of the person in charge
modifyCode Short 1 Conditional Reason for revocation
Refer to [Revised Invoice]
mandatory when writing a revised invoice
orgNTSConfirmNum String 24 Conditional NTS confirmation number of the original tax invoice
mandatory when writing a revised invoice
detailList List<TaxinvoiceDetail> N Detailed list of items
maximum : 99
TaxinvoiceDetail
No. Field Type Length Mandatory Description
serialNum Short 2 Y Serial number
write sequentially starting from 1
maximum : 99
purchaseDT String 8 N Date of trade
format : yyyyMMdd
itemName String 100 N Item name
spec String 60 N Specification
qty String 12 N Quantity
-99999999.99 ~ 999999999.99
allowed to enter two decimal places
unitCost String 18 N Unit price
-99999999999999.99 ~ 999999999999999.99
allowed to enter two decimal places
supplyCost String 18 N Supply values
integer values(+/-) only
decimals will be automatically truncated
tax String 18 N Tax amount
integer values(+/-) only
decimals will be automatically truncated
remark String 100 N Remark
addContactList List<TaxinvoiceAddContact> N Additional person in charge information of the buyer
use this when sending notification mails to multiple persons in charge
maximum : 5
TaxinvoiceAddContact
No. Field Type Length Mandatory Description
serialNum int 1 Y Serial number
write sequentially starting from 1
maximum value : 5
contactName String 100 N Name of the person in charge
email String 100 Y Email of the person in charge
memo String 200 N Memo for user's convenience
this field is used for individual e-Tax invoices within a Bulk submission only
WriteSpecification Boolean - N Whether a user uses concurrent creation of a transaction details or not
true do
false do not (default)
Memo String 200 N Memo for user’s convenience
ForceIssue Boolean - N Whether a user permits to issue an overdue e-Tax invoice or not
true do
false do not (default)
DealInvoiceKey String 24 N If {WriteSpecification} = true, a document ID can be assigned by a user for an invoice
if not entered, the same document ID of an original e-Tax invoice will be assigned
EmailSubject String 300 N Title of a notification mail sent to a buyer
default : title assigned by POPBiLL
UserID String 50 N User’s POPBiLL ID
Return
IssueResponse
No. Field Type Length Description
code long - API response code
message String - API response message
ntsConfirmNum String 24 NTS confirmation number
POPBiLL automatically assigns this when issuing a tax invoice.
Throws
PopbillException
No. Field Type Length Description
code long - API response code
8 digits code that starts with (‘-’) [Error Code]
message String - Error message for any failed API process

2. BulkSubmit - Submit an issuance of bulk invoices

  • This API submits the issuance of bulk invoices. A single request processes maximum 100 invoices at once.
BulkResponse bulkSubmit(String CorpNum, String SubmitID, List <Taxinvoice> taxinvoiceList, Boolean ForceIssue, String UserID) throws PopbillException
  • The seller’s certificate must be pre-registered in POPBiLL server to issue a tax invoice.
  • When issuing a tax invoice, service points will be charged, and a notification mail will be sent to the buyer.
Parameters
Parameters
No.FieldTypeLengthMandatoryDescription
CorpNum String 10 Y Business registration number
10-digits except (‘-’)
SubmitID String 36 Y Submission ID
a user assigns this ID to identify each bulk submission
a unique value combined with alphabets, numeric values, and a hyphen(‘-’)
taxinvoiceList List<Taxinvoice> Y List of objects of an e-Tax invoice
maximum 100 invoices
Taxinvoice
No. Field Type Length Mandatory Description
issueType String 3 Y Issuance type
정발행general issuance
taxType String 2 Y Taxation type
과세taxable
영세zero-rated
면세exempted
chargeDirection String 3 Y Charging Direction
정과금Paid by seller
serialNum String 30 N Serial number
item to manage the list of e-Tax invoice
kwon Short 4 N Volume of a book
item to manage the list of e-Tax invoice
ho Short 4 N Number of a book
item to manage the list of e-Tax invoice
writeDate String 8 Y Date of preparation
format : yyyyMMdd
purposeType String 2 Y Payments received or not
영수payment received
청구payment not received
없음none
supplyCostTotal String 18 Y Sum of supply values
integer values(+/-) only
decimals will be automatically truncated
taxTotal String 18 Y Sum of tax amount
integer values(+/-) only
decimals will be automatically truncated
totalAmount String 18 Y Total amount
integer values(+/-) only
decimals will be automatically truncated
cash String 18 N Payment method – ‘cash’
chkBill String 18 N Payment method – ‘check’
credit String 18 N Payment method – ‘credit’
note String 18 N Payment method – ‘note’
remark1 String 150 Conditional 1st Remark
foreign registration number
passport number
this field is mandatory if {invoiceeType} = “외국인(foreigner)”
remark2 String 150 N 2nd Remark
remark3 String 150 N 3rd Remark
invoicerMgtKey String 24 Ｙ [Seller] document ID
a unique value that can be entered with alphanumeric values and special characters(‘-’, ‘_’)
invoicerCorpNum String 10 Y [Seller] business registration number
10 digits except a hyphen(‘-’)
invoicerTaxRegID String 4 N [Seller] identification number of a branch place
4 digits
invoicerCorpName String 200 Y [Seller] company name
invoicerCEOName String 100 Y [Seller] CEO name
invoicerAddr String 300 N [Seller] company address
invoicerBizType String 100 N [Seller] type of business
invoicerBizClass String 100 N [Seller] items of business
invoicerContactName String 100 N [Seller] name of the person in charge
invoicerDeptName String 100 N [Seller] department of the person in charge
invoicerTEL String 20 N [Seller] contact number of the person in charge
invoicerHP String 20 N [Seller] cell phone number of the person in charge
invoicerEmail String 100 N [Seller] email of the person in charge
invoiceeType String - Y [Buyer] type of customer
사업자business proprietor
개인individual
외국인foreigner
invoiceeCorpNum String - Y [Buyer] business registration number
- if {invoiceeType} = 사업자(business proprietor type) : business registration number, 10 digits except a hyphen(‘-’)
- if {invoiceeType} = 개인(individual type) : resident registration number, 13 digits except a hyphen(‘-’)
- if {invoiceeType} = 외국인(foreigner type) : 9999999999999
invoiceeTaxRegID String 4 N [Buyer] identification number of a branch place
4 digits
invoiceeCorpName String 200 Y [Buyer] company name
invoiceeCEOName String 100 Y [Buyer] CEO name
invoiceeAddr String 300 N [Buyer] company address
invoiceeBizType String 100 N [Buyer] type of business
invoiceeBizClass String 100 N [Buyer] items of business
invoiceeContactName1 String 100 N [Buyer] name of the person in charge
invoiceeDeptName1 String 100 N [Buyer] department of the person in charge
invoiceeTEL1 String 20 N [Buyer] contact number of the person in charge
invoiceeHP1 String 20 N [Buyer] telephone number of the person in charge
invoiceeEmail1 String 100 N [Buyer] email of the person in charge
modifyCode Short 1 Conditional Reason for revocation
Refer to [Revised Invoice]
mandatory when writing a revised invoice
orgNTSConfirmNum String 24 Conditional NTS confirmation number of the original tax invoice
mandatory when writing a revised invoice
detailList List<TaxinvoiceDetail> N Detailed list of items
maximum : 99
TaxinvoiceDetail
No. Field Type Length Mandatory Description
serialNum Short 2 Y Serial number
write sequentially starting from 1
maximum : 99
purchaseDT String 8 N Date of trade
format : yyyyMMdd
itemName String 100 N Item name
spec String 60 N Specification
qty String 12 N Quantity
-99999999.99 ~ 999999999.99
allowed to enter two decimal places
unitCost String 18 N Unit price
-99999999999999.99 ~ 999999999999999.99
allowed to enter two decimal places
supplyCost String 18 N Supply values
integer values(+/-) only
decimals will be automatically truncated
tax String 18 N Tax amount
integer values(+/-) only
decimals will be automatically truncated
remark String 100 N Remark
addContactList List<TaxinvoiceAddContact> N Additional person in charge information of the buyer
use this when sending notification mails to multiple persons in charge
maximum : 5
TaxinvoiceAddContact
No. Field Type Length Mandatory Description
serialNum int 1 Y Serial number
write sequentially starting from 1
maximum value : 5
contactName String 100 N Name of the person in charge
email String 100 Y Email of the person in charge
memo String 200 N Memo for user's convenience
this field is used for individual e-Tax invoices within a Bulk submission only
ForceIssue Boolean - Y Whether a user permits to issue an overdue e-Tax invoice or not
true do
false do not
‘false’ if not entered
UserID String 50 N User’s POPBiLL ID
Return
BulkResponse
No. Field Type Length Description
code long - API response code
message String - API response message
receiptID String 24 Receipt ID
POPBiLL automatically assigns when submission is processed.
Throws
PopbillException
No. Field Type Length Description
code long - API response code
8 digits code that starts with (‘-’) [Error Code]
message String - Error message for any failed API process

3. GetBulkResult - Check a submission status for bulk issuance

  • This API checks the submission status for bulk issuance using 'SubmitID’.
  • The issuance result(succeeded/failed) is returned when the submission status(variable : txState) is updated as ‘2’(completed).
BulkTaxinvoiceResult getBulkResult(String CorpNum, String SubmitID, String UserID) throws PopbillException
Parameters
Parameters
No.FieldTypeLengthMandatoryDescription
CorpNum String 10 Y Business registration number
10-digits except (‘-’)
SubmitID String 36 Y Submission ID
assigned by a user when registering for a bulk submission
UserID String 50 N User’s POPBiLL ID
Return
BulkTaxinvoiceResult
No. Field Type Length Description
code long - API response code
message String - API response message
submitID String 36 Submission ID
assigned by a user when registering for a bulk submission
submitCount long - Number of tax invoice submissions
successCount long - Number of succeeded tax invoice issuance
failCount long - Number of failed tax invoice issuance
txState long 1 Submission status
0submitted
1in progress
2completed
txResultCode long - Submission result code
txStartDT String 14 Start date and time of B/G issuance process
format : yyyyMMddHHmmss
txEndDT String 14 End date and time of B/G issuance process
format : yyyyMMddHHmmss
receiptDT String 14 Date and time of the submission
format : yyyyMMddHHmmss
issueResult List<BulkTaxinvoiceIssueResult> Issuance result
BulkTaxinvoiceIssueResult
No. Field Type Length Description
invoicerMgtKey String 24 [Seller] document ID
a unique value that can be entered with alphanumeric values and special characters(‘-’, ‘_’)
code long - API response code
message String - API response message
ntsconfirmNum String 24 NTS confirmation number
POPBiLL automatically assigns this when issuing a tax invoice.
issueDT String 14 Date and time of the issuance
format : yyyyMMddHHmmss
receiptID String 36 Receipt ID
POPBiLL automatically assigns when submission is processed
Throws
PopbillException
No. Field Type Length Description
code long - API response code
8 digits code that starts with (‘-’) [Error Code]
message String - Error message for any failed API process

4. CancelIssue - Cancel the issuance of an e-Tax invoice

  • This API processes an e-Tax invoice of a status “issued” as “cancelled” and exempts it from filing to the NTS.
Response cancelIssue(String CorpNum, MgtKeyType KeyType, String MgtKey, String Memo, String UserID) throws PopbillException

You can reuse a document ID if you delete an “issued” e-Tax invoice via [Delete – Delete a revocable tax invoice] API.

Parameters
Parameters
No.FieldTypeLengthMandatoryDescription
CorpNum String 10 Y Business registration number
10-digits except (‘-’)
KeyType MgtKeyType - Y Type of the e-Tax invoice
SELL sales
MgtKeyType
No. Field Type Length Description
SELL enum - Sales
MgtKey String 24 Y Document ID
Memo String 200 N Memo for user’s convenience
UserID String 50 N User’s POPBiLL ID
Return
Response
No. Field Type Length Description
code long - API response code
message String - API response message
Throws
PopbillException
No. Field Type Length Description
code long - API response code
8 digits code that starts with (‘-’) [Error Code]
message String - Error message for any failed API process

5. Delete - Delete a revocable e-Tax invoice

  • This API deletes a revocable e-Tax invoice.

    ※ available status to delete : “cancelled”, “failed”

Response delete(String CorpNum, MgtKeyType KeyType, String MgtKey, String UserID) throws PopbillException
  • Recommend to implement this API only if you need to reuse a document ID of an e-Tax invoice.
Parameters
Parameters
No.FieldTypeLengthMandatoryDescription
CorpNum String 10 Y Business registration number
10-digits except (‘-’)
KeyType MgtKeyType - Y Type of the e-Tax invoice
SELL sales
MgtKeyType
No. Field Type Length Description
SELL enum - Sales
MgtKey String 24 Y Document ID
UserID String 50 N User’s POPBiLL ID
Return
Response
No. Field Type Length Description
code long - API response code
message String - API response message
Throws
PopbillException
No. Field Type Length Description
code long - API response code
8 digits code that starts with (‘-’) [Error Code]
message String - Error message for any failed API process

6. SendToNTS - File “issued” e-Tax invoice to the NTS

  • This API immediately files an “issued”(stateCode = 300) e-tax invoice to the NTS and once the filing process is completed, the stateCode of an invoice will be returned as “succeeded”(stateCode = 304)or ”failed”(stateCode = 305).
  • This API can be optionally implemented for the users with NTS filing option set as ‘next-day filing’(default).
Response sendToNTS(String CorpNum, MgtKeyType KeyType, String MgtKey, String UserID) throws PopbillException
Parameters
Parameters
No.FieldTypeLengthMandatoryDescription
CorpNum String 10 Y Business registration number
10-digits except (‘-’)
KeyType MgtKeyType - Y Type of the e-Tax invoice
SELL sales
MgtKeyType
No. Field Type Length Description
SELL enum - Sales
MgtKey String 24 Y Document ID
UserID String 50 N User’s POPBiLL ID
Return
Response
No. Field Type Length Description
code long - API response code
message String - API response message
Throws
PopbillException
No. Field Type Length Description
code long - API response code
8 digits code that starts with (‘-’) [Error Code]
message String - Error message for any failed API process