# 대량발행 (Bulk API)
Bulk(대량발행) API는 한 번 호출로 최대 100건의 전자세금계산서를 일괄 처리하여, 건별로 발행할 때 발생하는 오버헤드를 최소화 합니다. 또한 전자서명(발행) 과정을 팝빌에서 B/G 프로세스로 처리함으로써, 전체 발행 소요 시간을 기존 대비 1/40 수준으로 단축할 수 있습니다.
> 팝빌에서는 동시에 1만건 이상 전자세금계산서를 발행하는 경우 Bulk API 이용을 권장합니다.
## 대량발행 vs 단건발행
| 발행건수 | 대량발행 | 단건발행 |
| ---- | ---- | ------ |
| 1만 | 0.4분 | 0.67시간 |
| 10만 | 4분 | 7시간 |
| 25만 | 10분 | 16시간 |
| 50만 | 20분 | 1일 4시간 |
| 100만 | 45분 | 2일 8시간 |
※ 대량발행(Bulk API) 처리 소요시간은 접수를 기준으로 측정되며, 발행은 팝빌 B/G 프로세스로 처리됩니다.\
(발행 소요시간 = 접수시간\*2.5)
## 프로세스
프로그램 공급사가 팝빌에 전자세금계산서를 대량으로 접수하면, 팝빌은 B/G에서 이를 순차적으로 비동기 처리하여 발행합니다. [\[BulkSubmit - 대량발행 접수\]](https://developers.popbill.com/api-reference/taxinvoice/api/issue#BulkSubmit)
**대량발행**
```mermaid
flowchart LR
WriteInvoicer("공급자 작성")
ReceiptSuccess("접수성공")
Issue("발행")
Issued("발행완료
(300)")
Canceled("발행취소
(600)")
SendNTS{"국세청 전송"}
SendFail("전송실패
(305)")
SendSuccess("전송성공
(304)")
WriteInvoicer -- BulkSubmit
(대량발행 접수) --> ReceiptSuccess
ReceiptSuccess --> Issue
Issue -- 팝빌 B/G에서 순차 처리 --> Issued
Issued -- CancelIssue
(발행취소) --> Canceled("발행취소
(600)")
Issued --> SendNTS
SendNTS --> SendFail
SendNTS --> SendSuccess
classDef invoicer stroke-width:1px,font-weight:bold;
classDef popbill stroke-width:1px,font-weight:bold;
class WriteInvoicer,ReceiptSuccess,Issued,Canceled invoicer
class SendNTS,Issue,SendFail,SendSuccess popbill
```
## 문서번호 관리체계
문서번호란 전자세금계산서의 중복 발행을 방지하고 내부 관리를 위해 프로그램 공급사가 직접 생성하고 할당하는 고유번호 입니다. Bulk 접수 단위로 제출아이디(submitID)를 할당하고, Bulk에 포함된 개별 전자세금계산서 단위로 문서번호를 할당합니다.\
단, 한번 사용된 제출아이디는 재사용할 수 없습니다.
| 관리주체 | 유형 | 변수명 | 길이 | 설명 |
| -------- | -------- | -------------- | :-: | --------------------------------------------------------------- |
| 프로그램 공급사 | 제출아이디 | submitID | 36 | 접수 시점에 고객사에서 할당한 제출아이디 |
| 프로그램 공급사 | 공급자 문서번호 | invoicerMgtKey | 24 | 문서 관리를 위해 파트너가 할당하는 고유 식별번호 영문 대소문자, 숫자, 특수문자(’-’, ’\_‘)만 입력 가능 |
| 프로그램 공급사 | 수탁자 문서번호 | trusteeMgtKey | 24 | 문서 관리를 위해 파트너가 할당하는 고유 식별번호 영문 대소문자, 숫자, 특수문자(’-’, ’\_‘)만 입력 가능 |
| 팝빌 | 접수아이디 | receiptID | 36 | 접수 시점에 팝빌에서 자동으로 할당 |
| 팝빌 | 국세청승인번호 | ntsConfirmNum | 24 | 전자세금계산서 발행 시점에 팝빌에서 자동으로 할당 |
> “국세청승인번호”는 국세청 신고를 위해 팝빌이 생성하고 할당한 전자세금계산서의 식별값(Unique Value) 입니다.
## 상태확인
팝빌 Bulk API로 발행된 전자세금계산서의 상태 확인을 위해 2가지 방법을 제공합니다. Bulk API는 비동기 B/G 프로세스로 처리결과가 응답되므로, 상태 변경시점을 실시간으로 확인할 수 있는 ‘Webhook’ 방식을 권장합니다.
- **Webhook(Push)**\
팝빌에서 전자세금계산서 상태가 변경된 시점에 파트너가 지정한 Callback URL로 이벤트 전송 [\[Webhook\]](https://developers.popbill.com/api-reference/taxinvoice/webhook/introduction)
- **API(Polling)**\
프로그램 공급사가 주기적으로 API를 호출하여 전자세금계산서 상태 확인
**Webhook(Push)**
```mermaid
sequenceDiagram
participant 공급자
participant Webhook Receiver
participant POPBiLL
공급자->>POPBiLL: Callback URL 등록
공급자->>POPBiLL: BulkSubmit - 대량발행 접수
POPBiLL-->>공급자: receiptID(접수아이디) 반환
POPBiLL->>POPBiLL: 전자세금계산서
대량 발행
POPBiLL->>Webhook Receiver: Webhook 실행
Event Type = "BULKRESULT"
POPBiLL->>POPBiLL: 공급받는자
휴폐업조회
loop 최대 500건씩 묶어서 웹훅으로 전달
POPBiLL->>Webhook Receiver: Webhook 실행
Event Type = "CLOSEDOWN"
Webhook Receiver->>Webhook Receiver: 결과 업데이트
POPBiLL->>POPBiLL: 국세청 전송 처리 완료
POPBiLL->>Webhook Receiver: Webhook 실행
Event Type = "NTS"
stateCode = 304(전송성공)
stateCode = 305(전송실패)
Webhook Receiver->>Webhook Receiver: 결과 업데이트
end
```
**API(Polling)**
```mermaid
sequenceDiagram
participant 공급자
participant POPBiLL
공급자->>POPBiLL: BulkSubmit - 대량발행 접수
POPBiLL-->>공급자: receiptID(접수아이디) 반환
POPBiLL->>POPBiLL: 전자세금계산서
대량발행
공급자->>POPBiLL: GetBulkResult - 대량 접수결과 확인
POPBiLL-->>공급자: txState(접수상태) 반환
0 : 접수
1 : 처리중
2 : 처리완료
POPBiLL->>POPBiLL: 국세청 전송 및 결과반영
POPBiLL-->>공급자: stateCode(상태코드) 반환
stateCode = 304(전송성공)
stateCode = 305(전송실패)
공급자->>공급자: 결과 업데이트
```