POPBill Developers
API Reference
e-Tax Invoice
API Reference e-Tax Invoice Webhook Event

Webhook Event

Webhook Header

Field Mandatory Description Example
Pb-Webhook-Type Y Webhook type TAXINVOICE.STATE
Pb-Webhook-MID Y Identification value for Event 016120000002-1777d55c2c41492ab06826d
Pb-Webhook-Corpnum Y POPBiLL business registration number 6798700433
Content-Type Y Body type for Webhook message application/json
Authorization N Based 64-encoded BASIC authentication information Basic VEVTVDoxMjM=
└ additional item if using HTTP authentication
X-Api-Key N API Key authentication information TESTAPIKEY
└ additional item if using HTTP authentication
Pb-Webhook-EventType N Event type of Webhook message Event type
└ Issue / CancelIssue / CLOSEDOWN / NTS / OPEN

Depending on the partner’s operational environment, POPBiLL additionally provides custom field other than the default Header field. If you need to request one, please contact the partner center.

Docs State - Single

This Event will be initiated when a seller issues a single e-Tax invoice.
Each event time can be checked [How to Issue].

Event Type Description
Issue a seller issues(digitally signs) an e-Tax invoice
CancelIssue a seller cancels the issuance of an e-Tax invoice
CLOSEDOWN a buyer completes the business status check
NTS the status of a document changes into 301 (before filing), 304 (succeeded) and 305(failed)
OPEN a buyer clicks the ‘전자세금계산서 보기(view the e-Tax invoice)’ button on the notification mail

Issuance

This Event will be initiated when a seller issues(digitally signs) an e-Tax invoice.

Event body
No. Field Type Length Mandatory Description
corpNum string 10 Y Business registration number of a seller
itemKey string 18 Y Document ID assigned by POPBiLL
ntsConfirmNum string 24 Y NTS confirmation number
ntssendDT string 14 N Date and time of the NTS filing
format : yyyyMMddHHmmss
ntsresultDT string 14 N Date and time of receiving NTS filing result
format : yyyyMMddHHmmss
ntssendErrCode string 6 N NTS filing error code
[ntssendErrCode]
stateCode number 3 Y Status code
[stateCode]
stateDT string 14 Y Date and time of the status change
format : yyyyMMddHHmmss
issueDT string 14 Y Date and time of issuance
format : yyyyMMddHHmmss
invoicerMgtKey string 24 N [Seller] document ID
invoiceeMgtKey string 24 N [Buyer] document ID
eventDT string 14 Y Date and time of the initiation of an Event
format : yyyyMMddHHmmss
eventType string 30 Y Event type
Issue
closeDownState number 1 N [Buyer] business status
nullprocessing
0unregistered
1in business
2closed (date of the business shutdown is available)
3suspended (date of the business closure is available)
4failed to check
closeDownStateDate string 8 N [Buyer] date of the business closure/shutdown
check this information if the value of closeDownState is “2(closed)” or “3(suspended)”
format : yyyyMMdd
interOPYN boolean - Y Whether e-Tax invoice is issued by API or not
trueissued via API
falseissued via POPBiLL service website
stateMemo string 200 N Memo about status information
Example of Event
{
  "corpNum": "1234567890",
  "itemKey": "022101816220700001",
  "ntsconfirmNum": "202210188888888800000019",
  "stateCode": 300,
  "stateDT": "20221018162207",
  "issueDT": "20221018162207",
  "invoicerMgtKey": "20221018-001",
  "eventDT": "20221018162207",
  "eventType": "Issue",
  "interOPYN": true,
  "stateMemo": "memo"
}

Issuance Cancelled

This Event will be initiated when a seller cancels the issuance of an e-Tax invoice.

Event body
No. Field Type Length Mandatory Description
corpNum string 10 Y Business registration number of a seller
itemKey string 18 Y Document ID assigned by POPBiLL
ntsConfirmNum string 24 Y NTS confirmation number
ntssendDT string 14 N Date and time of the NTS filing
format : yyyyMMddHHmmss
ntsresultDT string 14 N Date and time of receiving NTS filing result
format : yyyyMMddHHmmss
ntssendErrCode string 6 N NTS filing error code
[ntssendErrCode]
stateCode number 3 Y Status code
[stateCode]
stateDT string 14 Y Date and time of the status change
format : yyyyMMddHHmmss
issueDT string 14 Y Date and time of issuance
format : yyyyMMddHHmmss
invoicerMgtKey string 24 N [Seller] document ID
invoiceeMgtKey string 24 N [Buyer] document ID
eventDT string 14 Y Date and time of the initiation of an Event
format : yyyyMMddHHmmss
eventType string 30 Y Event type
CancelIssue
closeDownState number 1 N [Buyer] business status
nullprocessing
0unregistered
1in business
2closed (date of the business shutdown is available)
3suspended (date of the business closure is available)
4failed to check
closeDownStateDate string 8 N [Buyer] date of the business closure/shutdown
check this information if the value of closeDownState is “2(closed)” or “3(suspended)”
format : yyyyMMdd
interOPYN boolean - Y Whether e-Tax invoice is issued by API or not
trueissued via API
falseissued via POPBiLL service website
stateMemo string 200 N Memo about status information
Example of Event
{
  "corpNum": "1234567890",
  "itemKey": "022101816232400001",
  "ntsconfirmNum": "20221018888888880000001a",
  "stateCode": 600,
  "stateDT": "20221018162332",
  "issueDT": "20221018162324",
  "invoicerMgtKey": "20221018-002",
  "eventDT": "20221018162332",
  "eventType": "CancelIssue",
  "closeDownState": 0,
  "interOPYN": true,
  "stateMemo": "cancelIssue memo"
}

Result of the Business Status Check

This Event will be initiated when a buyer completes the business status check.

Event body
No. Field Type Length Mandatory Description
corpNum string 10 Y Business registration number of a seller
itemKey string 18 Y Document ID assigned by POPBiLL
ntsConfirmNum string 24 Y NTS confirmation number
ntssendDT string 14 N Date and time of the NTS filing
format : yyyyMMddHHmmss
ntsresultDT string 14 N Date and time of receiving NTS filing result
format : yyyyMMddHHmmss
ntssendErrCode string 6 N NTS filing error code
[ntssendErrCode]
stateCode number 3 Y Status code
[stateCode]
stateDT string 14 Y Date and time of the status change
format : yyyyMMddHHmmss
issueDT string 14 Y Date and time of issuance
format : yyyyMMddHHmmss
invoicerMgtKey string 24 N [Seller] document ID
invoiceeMgtKey string 24 N [Buyer] document ID
eventDT string 14 Y Date and time of the initiation of an Event
format : yyyyMMddHHmmss
eventType string 30 Y Event type
Closedown
closeDownState number 1 N [Buyer] business status
nullprocessing
0unregistered
1in business
2closed (date of the business shutdown is available)
3suspended (date of the business closure is available)
4failed to check
closeDownStateDate string 8 N [Buyer] date of the business closure/shutdown
check this information if the value of closeDownState is “2(closed)” or “3(suspended)”
format : yyyyMMdd
interOPYN boolean - Y Whether e-Tax invoice is issued by API or not
trueissued via API
falseissued via POPBiLL service website
stateMemo string 200 N Memo about status information
Example of Event
{
  "corpNum": "1234567890",
  "itemKey": "022101816232400001",
  "ntsconfirmNum": "20221018888888880000001a",
  "stateCode": 300,
  "stateDT": "20221018162325",
  "issueDT": "20221018162324",
  "invoicerMgtKey": "20221018-002",
  "eventDT": "20221018162324",
  "eventType": "CLOSEDOWN",
  "closeDownState": 0,
  "interOPYN": true,
  "stateMemo": "memo"
}

NTS Filing Status

This Event will be initiated when the status of a document changes into 301 (before filing), 304 (succeeded) and 305(failed).

Event body
No. Field Type Length Mandatory Description
corpNum string 10 Y Business registration number of a seller
itemKey string 18 Y Document ID assigned by POPBiLL
ntsConfirmNum string 24 Y NTS confirmation number
ntssendDT string 14 N Date and time of the NTS filing
format : yyyyMMddHHmmss
ntsresultDT string 14 N Date and time of receiving NTS filing result
format : yyyyMMddHHmmss
ntssendErrCode string 6 N NTS filing error code
[ntssendErrCode]
stateCode number 3 Y Status code
[stateCode]
stateDT string 14 Y Date and time of the status change
format : yyyyMMddHHmmss
issueDT string 14 Y Date and time of issuance
format : yyyyMMddHHmmss
invoicerMgtKey string 24 N [Seller] document ID
invoiceeMgtKey string 24 N [Buyer] document ID
eventDT string 14 Y Date and time of the initiation of an Event
format : yyyyMMddHHmmss
eventType string 30 Y Event type
NTS
closeDownState number 1 N [Buyer] business status
nullprocessing
0unregistered
1in business
2closed (date of the business shutdown is available)
3suspended (date of the business closure is available)
4failed to check
closeDownStateDate string 8 N [Buyer] date of the business closure/shutdown
check this information if the value of closeDownState is “2(closed)” or “3(suspended)”
format : yyyyMMdd
interOPYN boolean - Y Whether e-Tax invoice is issued by API or not
trueissued via API
falseissued via POPBiLL service website
stateMemo string 200 N Memo about status information
Example of Event
{
  "corpNum": "1234567890",
  "itemKey": "022101816220700001",
  "ntsconfirmNum": "202210188888888800000019",
  "ntssendDT": "20221018162207",
  "ntsresultDT": "20221018162707",
  "ntssendErrCode": "SUC001",
  "stateCode": 304,
  "stateDT": "20221018162207",
  "issueDT": "20221018162207",
  "invoicerMgtKey": "20221018-001",
  "eventDT": "20221018162707",
  "eventType": "NTS",
  "closeDownState": 0,
  "interOPYN": true,
  "stateMemo": "memo"
}

Check the Notification Mail

This Event will be initiated when a buyer clicks the ‘전자세금계산서 보기(view the e-Tax invoice)’ button on the notification mail.

Event body
No. Field Type Length Mandatory Description
corpNum string 10 Y Business registration number of a seller
itemKey string 18 Y Document ID assigned by POPBiLL
ntsConfirmNum string 24 Y NTS confirmation number
ntssendDT string 14 N Date and time of the NTS filing
format : yyyyMMddHHmmss
ntsresultDT string 14 N Date and time of receiving NTS filing result
format : yyyyMMddHHmmss
ntssendErrCode string 6 N NTS filing error code
[ntssendErrCode]
stateCode number 3 Y Status code
[stateCode]
stateDT string 14 Y Date and time of the status change
format : yyyyMMddHHmmss
issueDT string 14 Y Date and time of issuance
format : yyyyMMddHHmmss
invoicerMgtKey string 24 N [Seller] document ID
invoiceeMgtKey string 24 N [Buyer] document ID
eventDT string 14 Y Date and time of the initiation of an Event
format : yyyyMMddHHmmss
eventType string 30 Y Event type
OPEN
closeDownState number 1 N [Buyer] business status
nullprocessing
0unregistered
1in business
2closed (date of the business shutdown is available)
3suspended (date of the business closure is available)
4failed to check
closeDownStateDate string 8 N [Buyer] date of the business closure/shutdown
check this information if the value of closeDownState is “2(closed)” or “3(suspended)”
format : yyyyMMdd
interOPYN boolean - Y Whether e-Tax invoice is issued by API or not
trueissued via API
falseissued via POPBiLL service website
stateMemo string 200 N Memo about status information
Example of Event
{
  "corpNum": "1234567890",
  "itemKey": "022102113485500001",
  "ntsconfirmNum": "20221021888888880000000d",
  "stateCode": 300,
  "stateDT": "20221021134858",
  "issueDT": "20221021134858",
  "eventDT": "20221021135006",
  "eventType": "OPEN",
  "closeDownState": 0,
  "interOPYN": false
}

Docs State - Bulk

This Event will be initiated when a seller issues bulk e-Tax invoices.
Each event time can be checked [Bulk Issuance].

Event Type Description
BULK.RESULT a seller completes the bulk submission request
BULK.CLOSEDOWN the business status check is completed for all the e-Tax invoices within the bulk submission. The list of up to 500 invoices will be processed sequentially
BULK.NTS the status of a document changes into 301 (before filing), 304 (succeeded) and 305(failed)
CancelIssue a seller cancels the issuance of an e-Tax invoice

Submission Result

This Event will be initiated when a seller completes the bulk submission request.

Event body
No. Field Type Length Mandatory Description
corpNum string 10 Y business registration number of a seller
submitID string 36 Y Submission ID
receiptID string 36 Y Receipt ID
POPBiLL automatically assigns when submission is processed.
receiptDT string 14 Y Date and time of the submission
format : yyyyMMddHHmmss
eventType string - Y Type of Event
BULK.RESULT
eventDT string 14 Y Date and time of the initiation of an Event
format : yyyyMMddHHmmss
submitCount number - Y Number of tax invoice submissions
successCount number - Y Number of succeeded tax invoice issuance
failCount number - Y Number of failed tax invoice issuance
txState number 1 Y Submission status
0submitted
1in progress
2completed
txResultCode number - N Submission result code
txStartDT string 14 N Start date and time of submission process
format : yyyyMMddHHmmss
txEndDT string 14 N End date and time of submission process
format : yyyyMMddHHmmss
issueResult array 100 N Issuance result
issueResult
No. Field Type Length Mandatory Description
code number - Y API response code
returns 1 if the process result is successful
returns error code( 8 digits that start with “-”) if the process result is failed
message string - N API response message
issueDT string 14 N Date and time of issuance
format : yyyyMMddHHmmss
ntsconfirmNum string 24 N NTS confirmation number
POPBiLL automatically assigns this when issuing a tax invoice.
invoicerMgtKey string 24 N [Seller] document ID
Example of Event
{
  "corpNum": "1234567890",
  "submitID": "20221013-TEST-2",
  "receiptID": "0221013-4e1a30b927ab4f88ad3d3f4a7ed9",
  "receiptDT": "20221013154838",
  "eventType": "BULK.RESULT",
  "eventDT": "20221013154839",
  "submitCount": 5,
  "successCount": 5,
  "failCount": 0,
  "txState": 2,
  "txResultCode": 1,
  "txStartDT": "20221013154839",
  "txEndDT": "20221013154839",
  "issueResult":
    [
      {
        "code": 1,
        "issueDT": "20221013154839"
        "ntsconfirmNum": "202210138888888800000068",
        "invoicerMgtKey": "20221013-TEST-2-0",
      },
      {
        "code": 1,
        "issueDT": "20221013154839"
        "ntsconfirmNum": "202210138888888800000069",
        "invoicerMgtKey": "20221013-TEST-2-1",
      },
      ...
    ]
}

Business Status Check Result

This Event will be initiated when the business status check is completed for all the e-Tax invoices within the bulk submission. The list of up to 500 invoices will be processed sequentially.

Event body
No. Field Type Length Mandatory Description
header object - Y header
header
No. Field Type Length Mandatory Description
QMNum string 24 Y NTS confirmation number
POPBiLL automatically assigns this when issuing a tax invoice.
CORPNUM string 10 Y business registration number of a seller
TYPE string - Y Webhook type
TAXINVOICE.STATE
body object - Y body
body
No. Field Type Length Mandatory Description
corpNum string 10 Y Business registration number of a seller
itemKey string 18 Y Document ID assigned by POPBiLL
ntsConfirmNum string 24 Y NTS confirmation number
stateCode number 3 Y Status code
[stateCode]
stateDT string 14 Y Date and time of the status change
format : yyyyMMddHHmmss
issueDT string 14 Y Date and time of issuance
format : yyyyMMddHHmmss
invoicerMgtKey string 24 N [Seller] document ID
eventDT string 14 Y Date and time of the initiation of an Event
format : yyyyMMddHHmmss
eventType string 30 Y Event type
CLOSEDOWN
closeDownState number 1 Y [Buyer] business status
nullprogressing
0unregistered
1in business
2closed (date of the business shutdown is available)
3suspended (date of the business closure is available)
4failed to check
closeDownStateDate string 8 N [Buyer] date of the business closure/shutdown
check this information if the value of closeDownState is “2(closed)” or “3(suspended)”
format: yyyy-MM-dd
interOPYN boolean - Y Whether e-Tax invoice is issued by API or not
trueissued via API
falseissued via POPBiLL service website
Example of Event
[
  {
    "header": {
      "QMNum": "202210138888888800000068",
      "CORPNUM": "1234567890",
      "TYPE": "TAXINVOICE.STATE"
    },
    "body": {
      "corpNum": "1234567890",
      "itemKey": "022101315483900001",
      "ntsconfirmNum": "202210138888888800000068",
      "ntssendDT": "20221013154839",
      "stateCode": 303,
      "stateDT": "20221013154839",
      "issueDT": "20221013154839"
      "invoicerMgtKey": "20221013-TEST-2-0",
      "eventDT": "20221013154839",
      "eventType": "CLOSEDOWN",
      "closeDownState": 0,
      "interOPYN": true,
    }
  },
  {
    "header": {
      "QMNum": "202210138888888800000069",
      "CORPNUM": "1234567890",
      "TYPE": "TAXINVOICE.STATE"
    },
    "body": {
      "invoicerMgtKey": "20221013-TEST-2-1",
      "stateDT": "20221013154839",
      "eventType": "CLOSEDOWN",
      "closeDownState": 0,
      "itemKey": "022101315483900002",
      "ntsconfirmNum": "202210138888888800000069",
      "corpNum": "1234567890",
      "interOPYN": true,
      "ntssendDT": "20221013154839",
      "stateCode": 303,
      "eventDT": "20221013154839",
      "issueDT": "20221013154839"
    }
  },
  ...
]

NTS Filing Result

This Event will be initiated when the NTS filing process is completed for the bulk submission. The list of up to 500 invoices will be processed sequentially.

Event body
No. Field Type Length Mandatory Description
header object - Y header
header
No. Field Type Length Mandatory Description
QMNum string 24 Y NTS confirmation number
POPBiLL automatically assigns this when issuing a tax invoice.
CORPNUM string 10 Y business registration number of a seller
TYPE string - Y Webhook type
TAXINVOICE.STATE
body object - Y body
body
No. Field Type Length Mandatory Description
corpNum string 10 Y Business registration number of a seller
itemKey string 18 Y Document ID assigned by POPBiLL
ntsconfirmNum string 24 Y NTS confirmation number
ntssendDT string 14 N Date and time of the NTS filing
format : yyyyMMddHHmmss
ntsresultDT string 14 N Date and time of receiving NTS filing result
format : yyyyMMddHHmmss
ntssendErrCode string - N NTS filing result code
[ntssendErrCode]
stateCode number 3 Y Status code
[stateCode]
stateDT string 14 Y Date and time of the status change
format : yyyyMMddHHmmss
issueDT string 14 Y Date and time of issuance
format : yyyyMMddHHmmss
invoicerMgtKey string 24 N [Seller] document ID
eventDT string 14 Y Date and time of the initiation of an Event
format : yyyyMMddHHmmss
eventType string 30 Y Event type
NTS
closeDownState number 1 Y [Buyer] business status
nullprogressing
0unregistered
1in business
2closed (date of the business shutdown is available)
3suspended (date of the business closure is available)
4failed to check
closeDownStateDate string 8 N [Buyer] date of the business closure/shutdown
check this information if the value of closeDownState is “2(closed)” or “3(suspended)”
format : yyyyMMdd
interOPYN boolean - Y Whether e-Tax invoice is issued by API or not
trueissued via API
falseissued via POPBiLL service website
Example of Event
[
  {
    "header": {
      "QMNum": "20221013888888880000006b",
      "CORPNUM": "1234567890",
      "TYPE": "TAXINVOICE.STATE"
    },
    "body": {
      "corpNum": "1234567890",
      "itemKey": "022101315483900004",
      "ntsconfirmNum": "20221013888888880000006b",
      "ntssendDT": "20221013154839",
      "ntsresultDT": "20221013155339",
      "ntssendErrCode": "SUC001",
      "stateCode": 304,
      "stateDT": "20221013154839",
      "issueDT": "20221013154839"
      "invoicerMgtKey": "20221013-TEST-2-3",
      "eventDT": "20221013155339",
      "eventType": "NTS",
      "closeDownState": 0,
      "interOPYN": true,
    }
  },
  {
    "header": {
      "QMNum": "20221013888888880000006c",
      "CORPNUM": "1234567890",
      "MEMBERCODE": "014070000004",
    },
    "body": {
      "invoicerMgtKey": "20221013-TEST-2-4",
      "stateDT": "20221013154840",
      "eventType": "NTS",
      "closeDownState": 0,
      "itemKey": "022101315483900005",
      "ntsconfirmNum": "20221013888888880000006c",
      "corpNum": "1234567890",
      "ntssendErrCode": "SUC001",
      "interOPYN": true,
      "ntssendDT": "20221013154840",
      "stateCode": 304,
      "ntsresultDT": "20221013155339",
      "eventDT": "20221013155339",
      "issueDT": "20221013154839"
    }
  },
  ...
]

Issuance Cancelled

This Event will be initiated when a seller cancels the issuance of an e-Tax invoice.

Event body
No. Field Type Length Mandatory Description
corpNum string 10 Y Business registration number of a seller
itemKey string 18 Y Document ID assigned by POPBiLL
ntsConfirmNum string 24 Y NTS confirmation number
ntssendDT string 14 N Date and time of the NTS filing
format : yyyyMMddHHmmss
ntsresultDT string 14 N Date and time of receiving NTS filing result
format : yyyyMMddHHmmss
ntssendErrCode string 6 N NTS filing error code
[ntssendErrCode]
stateCode number 3 Y Status code
[stateCode]
stateDT string 14 Y Date and time of the status change
format : yyyyMMddHHmmss
issueDT string 14 Y Date and time of issuance
format : yyyyMMddHHmmss
invoicerMgtKey string 24 N [Seller] document ID
invoiceeMgtKey string 24 N [Buyer] document ID
eventDT string 14 Y Date and time of the initiation of an Event
format : yyyyMMddHHmmss
eventType string 30 Y Event type
CancelIssue
closeDownState number 1 N [Buyer] business status
nullprocessing
0unregistered
1in business
2closed (date of the business shutdown is available)
3suspended (date of the business closure is available)
4failed to check
closeDownStateDate string 8 N [Buyer] date of the business closure/shutdown
check this information if the value of closeDownState is “2(closed)” or “3(suspended)”
format : yyyyMMdd
interOPYN boolean - Y Whether e-Tax invoice is issued by API or not
trueissued via API
falseissued via POPBiLL service website
stateMemo string 200 N Memo about status information
Example of Event
{
  "corpNum": "1234567890",
  "itemKey": "022101816232400001",
  "ntsconfirmNum": "20221018888888880000001a",
  "stateCode": 600,
  "stateDT": "20221018162332",
  "issueDT": "20221018162324",
  "invoicerMgtKey": "20221018-002",
  "eventDT": "20221018162332",
  "eventType": "CancelIssue",
  "closeDownState": 0,
  "interOPYN": true,
  "stateMemo": "cancelIssue memo"
}