API Docs

Index

1. NTS Crawling – sales/purchase invoices

1.1. RequestJob - Request a data crawling

ㆍRequest a crawling the data of sales/purchase invoices from NTS. (Maximum period for search: 3 months)

String requestJob(String CorpNum, QueryType queryType, String DType, String SDate, String EDate, String UserID) throws PopbillException

Parameters

No. Name Type Length Required Description
1 CorpNum String 10 O Business Registration Number of user (10 digits except '-')
2 queryType QueryType - O Type of the e-Tax invoice
└ Valid Value : SELL
3 DType String - O Date type in search criteria
└ Valid Value : W / I / S
└ W = Date of registration, I = of issuance, S = of filing to NTS(Recommended)
4 SDate String - O Initial date of search scope (Format : yyyyMMdd)
5 EDate String - O Last date of search scope (Format : yyyyMMdd)
6 UserID String 50 - User's POPBiLL ID

Return

String - JobID of request

Throws

PopbillException.

1.2. GetJobState - Check the status of crawling job [Single]

ㆍCheck the status of single crawling job using JobID returned by calling [1.1. RequestJob]

ㆍOnce it’s confirmed as ‘jobState = 3(Completed)’ and ‘errorCode = 1(Succeeded)’, user can check the crawled data by calling [2.1. Search] or [2.2. Summary]

HTTaxinvoiceJobState getJobState(String CorpNum, String JobID, String UserID) throws PopbillException

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O Business Registration Number of user (10 digits except '-')
2 JobID String 18 O JobID returned by [1.1. RequestJob]
3 UserID String 50 - User's POPBiLL ID

Return

HTTaxinvoiceJobState

Throws

PopbillException

1.3. ListActiveJob - Check the status list of crawling job [Multiple]

ㆍCheck the status list of multiple crawling jobs using JobID returned by calling [1.1. RequestJob]

ㆍIt’s not available to check the job have been elapsed over an hour since the time of request. 

HTTaxinvoiceJobState[] listActiveJob(String CorpNum, String UserID) throws PopbillException

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O Business Registration Number of user (10 digits except '-')
2 UserID String 50 - User's POPBiLL ID

Return

HTTaxinvoiceJobState[ ]

Throws

PopbillException

2. Check the result of data crawling

2.1. Search - Search the result of data crawling

ㆍSearch the result of data crawling corresponded to the search criteria.

ㆍDefault of optional fields is to 'search all’.

HTTaxinvoiceSearchResult search(String CorpNum, String JobID, String[] Type, String[] TaxType, String[] PurposeType, String TaxRegIDYN, String TaxRegIDType, String TaxRegID, Integer Page, Integer PerPage, String Order, String UserID, String SearchString) throws PopbillException

ㆍRecommend to use for the list of e-Tax invoices with items related to the page(variable: Page, PerPage, Order)

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O Business Registration Number of user (10 digits except '-')
2 JobID String 18 O JobID returned by [1.1. RequestJob]
3 Type String[ ] - - [Array] Type of e-Tax invoice
└ Valid Value : N / M (multiple choice is available)
└ N = General, M = Revised e-Tax invoice
4 TaxType String[ ] - - [Array] Taxation Type
└ Valid Value : T / N / Z (multiple choice is available)
└ T = Taxable, N = Exempted, Z = Zero-rate
5 PurposeType String[ ] - - [Array] Type of the total amount
└ Valid Value : R / C / N (multiple choice is available)
└ R = Amount paid, C = Amount due, N = None
6 TaxRegIDYN String 1 - Whether the Identification number for minor place of business is enrolled or not
└ Valid Value : null / 0 / 1
└ null = All, 0 = None, 1 = Enrolled
7 TaxRegIDType String - - Type of the Identification number for minor place of business
└ Valid Value : S (Seller)
8 TaxRegID String - - Identification number for minor place of business
└ one more numbers must be separated by comma(',') (e.g. 1234, 1110)
9 Page Integer - - Page number
└ Default = 1
10 PerPage Integer - - The number of list to be displayed per page (Maximum : 1,000)
└ Default = 500
11 Order String 1 - Sort direction (related to {@no.3 DType} used in [1.1. RequestJob])
└ Valid Value : D / A
└ D = Descending(Default), A = Ascending
12 UserID String 50 - User's POPBiLL ID
13 SearchString String - - Name of Buyer Company / Business Registration Number (for company) / Residential Registration Number (for entrepreneur) / 9999999999999 (for foreigner)
└ Do not enter hyphen('-')

Return

HTTaxinvoiceSearchResult

Throws

PopbillException

2.2. Summary - Check the summarized information

ㆍCheck the summarized information of crawled data.

ㆍDefault of optional fields is to 'search all’.

HTTaxinvoiceSummary summary(String CorpNum, String JobID, String[] Type, String[] TaxType, String[] PurposeType, String TaxRegIDYN, String TaxRegIDType, String TaxRegID, String UserID, String SearchString) throws PopbillException

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O Business Registration Number of user (10 digits except '-')
2 JobID String 18 O JobID returned by [1.1. RequestJob]
3 Type String[ ] - - [Array] Type of e-Tax invoice
└ Valid Value : N / M (multiple choice is available)
└ N = General, M = Revised e-Tax invoice
4 TaxType String[ ] - - [Array] Taxation Type
└ Valid Value : T / N / Z (multiple choice is available)
└ T = Taxable, N = Exempted, Z = Zero-rate
5 PurposeType String[ ] - - [Array] Type of the total amount
└ Valid Value : R / C / N (multiple choice is available)
└ R = Amount paid, C = Amount due, N = None
6 TaxRegIDYN String 1 - Whether the Identification number for minor place of business is enrolled or not
└ Valid Value : null / 0 / 1
└ null = All, 0 = None, 1 = Enrolled
7 TaxRegIDType String - - Type of the Identification number for minor place of business
└ Valid Value : S (Seller)
8 TaxRegID String - - Identification number for minor place of business
└ one more numbers must be separated by comma(',') (e.g. 1234, 1110)
9 UserID String 50 - User's POPBiLL ID
10 SearchString String - - Name of Buyer Company / Business Registration Number (for company) / Residential Registration Number (for entrepreneur) / 9999999999999 (for foreigner)
└ Do not enter hyphen('-')

Return

HTTaxinvoiceSummary

Throws

PopbillException

2.3. GetTaxinvoice - Check the detailed information (JSON)

ㆍCheck the detailed information of single e-Tax invoice using NTS confirm number.

HTTaxinvoice getTaxinvoice(String CorpNum, String NTSConfirmNum, String UserID) throws PopbillException

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O Business Registration Number of user (10 digits except '-')
2 NTSConfirmNum String 24 O NTS Confirm Number
3 UserID String 50 - User's POPBiLL ID

Return

HTTaxinvoice

Throws

PopbillException

2.4. GetXML - Check the detailed information (XML)

ㆍCheck the detailed information of single e-Tax invoice using NTS confirm number.

ㆍThe result is returned as a XML-formatted string.

HTTaxinvoiceXMLResponse getXML(String CorpNum, String NTSConfirmNum, String UserID) throws PopbillException

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O Business Registration Number of user (10 digits except '-')
2 NTSConfirmNum String 24 O NTS Confirm Number
3 UserID String 50 - User's POPBiLL ID

Return

HTTaxinvoiceXMLResponse

Throws

PopbillException

2.5 GetPopUpURL - URL to view a single e-Tax invoice crawled

ㆍGet the popup URL to view a single e-Tax invoice crawled.

ㆍReturned URL is valid for 30 seconds and after the valid time, page is not opened.

String getPopUpURL(String CorpNum, String NTSConfirmNum, String UserID) throws PopbillException

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O Business Registration Number of user (10 digits except '-')
2 NTSConfirmNum String 24 O NTS Confirm Number
3 UserID String 50 - User's POPBiLL ID

Return

String - Returned URL to response about the request

Throws

PopbillException

2.6 GetPrintURL - URL to print a single e-Tax invoice crawled

ㆍGet the popup URL to print a single e-Tax invoice crawled.

ㆍReturned URL is valid for 30 seconds and after the valid time, page is not opened.

String getPrintURL(String CorpNum, String NTSConfirmNum, String UserID) throws PopbillException

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O Business Registration Number of user (10 digits except '-')
2 NTSConfirmNum String 24 O NTS Confirm Number
3 UserID String 50 - User's POPBiLL ID

Return

String - Returned URL to response about the request

Throws

PopbillException

3. Manage HomeTax Authentication

3.1. GetCertificatePopUpURL - URL to manage HomeTax Authentication

ㆍGet the popup URL to access the management page of HomeTax Authentication.

ㆍReturned URL is valid for 30 seconds and after the valid time, page is not opened.

String getCertificatePopUpURL(String CorpNum, String UserID) throws PopbillException

Parameters

순번 변수명 타입 길이 필수 설명
1 CorpNum String 10 O Business Registration Number of user (10 digits except '-')
2 UserID String 50 - User's POPBiLL ID

Return

String - Returned URL to response about the request

Throws

PopbillException

A. Object Information

A.1. Response

No. Name Type Length Description
1 code long - Response code for API processing
2 message String - Response message for API processing

A.2. PopbillException

No. Name Type Length Description
1 code long - Error code for failure of API process (8 digits starting with ‘-’)
└ [Reference] Error codes
2 message String - Error message for failure of API processing

A.3. QueryType (enum)

No. Name Type Length Description
1 SELL enum -
2 BUY enum -
3 TRUSTEE enum -

A.4. HTTaxinvoiceJobState

No. Name Type Length Description
1 jobID String 18 JobID of data crawling requested
2 jobState String - The status of data crawling
└ Valid Value : 1 / 2 / 3
└ 1 = Waiting, 2 = In progress, 3 = Completed
3 queryType String - The type of crawled data
└Valid Value : 매출
└ 매출 = Sales invoices
4 queryDateType String - Date type in search criteria
└ Valid Value : W / I / S
└ W = Date of registration, I = of issuance, S = of filing to NTS
5 queryStDate String 8 Initial date of search scope (Format : yyyyMMdd)
6 queryEnDate String 8 Last date of search scope (Format : yyyyMMdd)
7 errorCode long - Result code for data crawling
└ Valid Value : 1 / -********(8-digit number)
└ 1 = Succeeded, -******** = Failed(e.g. -99999999)
8 errorReason String - Error message
└ Returned when {@no.7 errorCode} = -********(8-digit number)
9 jobStartDT String 14 Initial date and time of data crawling (Format : yyyyMMddHHmmss)
10 jobEndDT String 14 End date and time of data crawling (Format : yyyyMMddHHmmss)
11 collectCount Integer - The number of crawled data
12 regDT String 14 The date and time of request to crawl data (Format : yyyyMMddHHmmss)

A.5. HTTaxinvoice

No. Name Type Length Description
1 writeDate String 8 Date of preparation
└ Format : yyyyMMdd
2 issueDT String 14 Date and Time of issuance
└ Format : yyyyMMddHHmmss
3 invoiceType Short 3 Type of invoice
└ 101 : e-Tax invoice, 102 : Zero-rate invoice
└ 103 : Consigned invoice, 104 : e-Tax invoice on import
└ 105 : Consigned zero-rated invoice
└ 201 : Revised invoice, 202 : Revised zero-rated invoice
└ 203 : Revised consigned invoice, 204 : Revised invoice on import
└ 205 : Revised consigned zero-rated invoice
└ 301 : e-Invoice, 303 : Consigned e-Invoice, 304 : e-Invoice on import
└ 401 : Revised e-Invoice, 403 : Revised consigned e-Invoice
└ 404 : Reviced e-Invoice on import
4 taxType String 2 Taxation Type
└ Valid Value : 과세 / 영세 / 면세
└ 과세 = Taxable, 영세 = Zero-rate, 면세 = Exempted
5 taxTotal String 18 Sum of tax amount
6 supplyCostTotal String 18 Sum of supply values
7 totalAmount String 18 Total Amount
└ sum of {@no.5 taxTotal} and {@no.6 supplyCostTotal}
8 purposeType String 2 Type of the total amount
└ Valid Value : 영수 / 청구 / 없음
└ 영수 = Amount paid, 청구 = Amount due, 없음 = None
9 serialNum String 30 One of e-Tax invoice's items to manage document – 'Serial number'
10 cash String 18 Payment Method – 'cash'
11 chkBill String 18 Payment Method – 'check'
12 credit String 18 Payment Method – 'credit'
13 note String 18 Payment Method – ‘note'
14 remark1 String 150 1st Remark
15 remark2 String 150 2nd Remark
16 remark3 String 150 3rd Remark
17 ntsconfirmNum String 24 NTS confirm number
18 invoicerCorpNum String 10 [Seller] Business Registration Number
19 invoicerMgtKey String 24 [Seller] Invoice ID
20 invoicerTaxRegID String 4 [Seller] Identification Number for minor place of business
└ 4 digits number
21 공급자 상호 String 200 [Seller] Name of Company
22 invoicerCEOName String 100 [Seller] Name of Representative
23 invoicerAddr String 300 [Seller] Company Address
24 invoicerBizType String 100 [Seller] Business Type
25 invoicerBizClass String 100 [Seller] Business Item
26 invoicerContactName String 100 [Seller] Name of the person in charge
27 invoicerDeptName String 100 [Seller] Department of the person in charge
28 invoicerTEL String 20 [Seller] Telephone of the person in charge
29 invoicerEmail String 100 [Seller] Email address of the person in charge
30 invoiceeCorpNum String 13 [Buyer] Business Registration Number
└ It must be synchronized with {@no. 31 invoiceeType}
└ Company: Business registration number (10 digits except '-')
└ Individual: Resident registration number (13 digits except '-')
└ Foreigner: "9999999999999"(13 digits except '-')
31 invoiceeType String - Buyer Type
└ Valid Value : 사업자 / 개인 / 외국인
└ 사업자 = company, 개인 = individual, 외국인 = foreigner
32 invoiceeMgtKey String 24 It's only requires to 'requested e-Tax invoice'
33 invoiceeTaxRegID String 4 [Buyer] Identification Number for minor place of business
└ 4 digits number
34 invoiceeCorpName String 200 [Buyer] Name of Company
35 invoicerCEOName String 100 [Buyer] Name of Representative
36 invoiceeAddr String 300 [Buyer] Company Address
37 invoiceeBizType String 100 [Buyer] Business Type
38 invoiceeBizClass String 100 [Buyer] Business Item
39 invoiceeContactName1 String 100 [Buyer] Name of the person in charge
40 invoiceeDeptName1 String 100 [Buyer] Department of the person in charge
41 invoiceeTEL1 String 20 [Buyer] Telephone of the person in charge
42 invoiceeEmail1 String 100 [Buyer] Email address of the person in charge
43 invoiceeContactName2 String 30 [Buyer] Name of the 2nd person in charge
44 invoiceeDeptName2 String 40 [Buyer] Department of the 2nd person in charge
45 invoiceeTEL2 String 20 [Buyer] Telephone of the 2nd person in charge
46 invoiceeEmail2 String 70 [Buyer] Email of the 2nd person in charge
47 trusteeCorpNum String 10 [Consignee] Business Registration Number
48 trusteeMgtKey String 24 [Consignee] Invoice ID
49 trusteeTaxRegID String 4 [Consignee] Identification Number for minor place of business
└ 4 digits number
50 trusteeCorpName String 200 [Consignee] Name of Company
51 trusteeCEOName String 100 [Consignee] Name of Representative
52 trusteeAddr String 300 [Consignee] Company Address
53 trusteeBizType String 100 [Consignee] Business Type
54 trusteeBizClass String 100 [Consignee] Business Item
55 trusteeContactName String 100 [Consignee] Name of the person in charge
56 trusteeDeptName String 100 [Consignee] Department of the person in charge
57 trusteeTEL String 20 [Consignee] Telephone of the person in charge
58 trusteeEmail String 100 [Consignee] Email address of the person in charge
59 modifyCode Short 1 Modification Code
└ Valid Value : 1 / 2 / 3 / 4 / 5 / 6
└ 1 = Correction of errors, 2 = Change in supply values, 3 = Return,
└ 4 = Cancellation of contract, 5 = Post opening of local letter of credit, 6 = Duplicated issuance
60 orgNTSConfirmNum String 24 NTS Confirm Number of the Original
61 detailList List<HTTaxinvoiceDetail> [List] Detailed list of items (Maximum : 99)

A.6. HTTaxinvoiceDetail

No. Name Type Length Description
1 serialNum Short 1 Serial Number
2 purchaseDT String 8 Date of preparation
└ Format : yyyyMMdd
3 itemName String 100 Item name
4 spec String 60 Specification
5 qty String 12 Quantity
└ Available to two decimal places
└ Minus(Negative) amount is available
6 unitCost String 18 Unit price
└ Available to two decimal places
└ Minus(Negative) amount is available
7 supplyCost String 18 Unit price
└ Minus(Negative) amount is available
8 tax String 18 Tax amount
└ Minus(Negative) amount is available
9 remark String 100 Remark

A.7. HTTaxinvoiceSearchResult

No. Name Type Length Description
1 code long - Response code for API processing
2 message String - Response message for API processing
3 total long - The total number of search results
4 perPage long - The number of search result per page
5 pageNum long - Page number
6 pageCount long - The number of pages
7 list List<HTTaxinvoiceAbbr> [List] Summarized information of e-Tax invoices (Maximum : 1,000 invoices)

A.8. HTTaxinvoiceAbbr

No. Name Type Length Description
1 ntsconfirmNum String 24 NTS Confirm Number
2 writeDate String 8 Date of preparation
└ Format : yyyyMMdd
3 issueDate String 8 Date of issuance
└ Format : yyyyMMdd
4 sendDate String 8 Date of filing to NTS
└ Format : yyyyMMdd
5 taxType String 2 Taxation Type
└ Valid Value : 과세 / 영세 / 면세
└ 과세 = Taxable, 영세 = Zero-rate, 면세 = Exempted
6 purposeType String 2 Type of the total amount
└ Valid Value : 영수 / 청구 / 없음
└ 영수 = Amount paid, 청구 = Amount due, 없음 = None
7 supplyCostTotal String 18 Sum of supply values
8 taxTotal String 18 Sum of tax amount
9 totalAmount String 18 Total Amount
└ sum of {@no.7 supplyCostTotal} and {@no.8 taxTotal}
10 remark1 String 150 Remark
11 invoiceType String 2 Valid Value : 매입 / 매출
└ 매입 = purchase invoices, 매출 = sales invoices
12 modifyYN Boolean - Whether it’s a revised invoice or not
└ true = Revised invoice, false = (general) invoice
13 orgNTSConfirmNum String 24 NTS Confirm Number of the Original
14 purchaseDate String 8 [Line item] Date of preparation
15 itemName String 100 [Line item] Item name
16 spec String 60 [Line item] Specification
17 qty String 12 [Line item] Quantity
18 unitCost String 18 [Line item] Unit price
19 supplyCost String 18 [Line item] Unit price
20 tax String 18 [Line item] Tax amount
21 remark String 100 [Line item] Remark
22 invoicerCorpNum String 10 [Seller] Business Registration Number
23 invoicerTaxRegID String 4 [Seller] Identification Number for minor place of business
└ 4 digits number
24 invoicerCorpName String 200 [Seller] Name of Company
25 invoicerCEOName String 100 [Seller] Name of Representative
26 invoicerEmail String 100 [Seller] Email address of the person in charge
27 invoiceeCorpNum String 13 [Buyer] Business Registration Number
└ It must be synchronized with {@no. 28 invoiceeType}
└ Company: Business registration number (10 digits except '-')
└ Foreigner: "9999999999999"(13 digits except '-')
└ Individual: Resident registration number (13 digits except
28 invoiceeType String - Buyer Type
└ Valid Value : 사업자 / 개인 / 외국인
└ 사업자 = company, 개인 = individual, 외국인 = foreigner
29 invoiceeTaxRegID String 4 [Buyer] Identification Number for minor place of business
└ 4 digits number
30 invoiceeCorpName String 200 [Buyer] Name of Company
31 invoiceeCEOName String 100 [Buyer] Name of Representative
32 invoiceeEmail1 String 100 [Buyer] Email address of the 1st person in charge
33 invoiceeEmail2 String 70 [Buyer] Email address of the 2nd person in charge
34 trusteeCorpNum String 10 [Consignee] Business Registration Number
35 trusteeTaxRegID String 4 [Consignee] Identification Number for minor place of business
└ 4 digits number
36 trusteeCorpName String 200 [Consignee] Name of Company
37 trusteeCEOName String 100 [Consignee] Name of Representative
38 trusteeEmail String 100 [Consignee] Email address of the person in charge

A.9. HTTaxinvoiceSummary

No. Name Type Length Description
1 count long - The total number of search results
2 supplyCostTotal long - Sum of supply values
3 taxTotal long - Sum of tax amount
4 amountTotal long - Total Amount
└ sum of {@no.2 supplyCostTotal} and {@no.3 taxTotal}

A.10. HTTaxinvoiceXMLResponse

No. Name Type Length Description
1 ResultCode long - Response code for API processing
2 Message String 24 NTS Confirm Number
3 retObject String - XML document of e-Tax invoice