발행

1. RegistIssue - 승인 현금영수증 발행

POST https://popbill-test.linkhub.co.kr/Cashbill

작성된 현금영수증 데이터를 팝빌에 저장과 동시에 발행하여 “발행완료” 상태로 처리합니다. [참고] 팝빌 국세청 전송 정책

현금영수증 자진발급분은 소득공제 용도로만 발행 가능합니다. (자진발급 번호 : 010-000-1234)
현금영수증 발행시 구매자 메일주소로 발행 안내 메일이 전송되니 유의하시기 바랍니다.

Request

요청 헤더

순번	변수명	필수	설명
1	`Authorization`	Y	인증 토큰 [참고] 인증 및 헤더 설정
2	`Content-Type`	Y	요청 본문 형식 `application/json`
3	`Accept-Language`	N	응답 언어 설정 `ko-KR` 기본값 `en-US`
4	`Accept-Encoding`	N	응답 압축 방식 `gzip`
5	`X-HTTP-Method-Override`	Y	요청 메서드 재정의 `ISSUE`
6	`X-PB-UserID`	N	팝빌회원 아이디

요청 본문

순번	변수명	타입	길이	필수	설명
1	`mgtKey`	string	24	Y	문서번호 문서 관리를 위해 파트너가 할당하는 식별번호 영문 대소문자, 숫자, 특수문자('-','_')만 이용 가능
2	`tradeDT`	string	14	N	거래일시 전일부터 당일까지 입력 가능 형식 : yyyyMMddHHmmss 기본값 : 발행일시 사용
3	`tradeType`	string	4	Y	문서형태 `승인거래`
4	`tradeUsage`	string	-	Y	거래구분 (택 1) `소득공제용` `지출증빙용`
5	`tradeOpt`	string	4	N	거래유형 `일반` 기본값 `도서공연` `대중교통` 도서공연 : 도서, 공연, 박물관, 미술관, 수영장, 체력단련장, 신문구독료(종이신문), 영화관람료
6	`taxationType`	string	-	Y	과세형태 (택 1) `과세` `비과세`
7	`totalAmount`	string	9	Y	거래금액 (공급가액+부가세+봉사료) 양수만 입력
8	`supplyCost`	string	9	Y	공급가액 양수만 입력
9	`tax`	string	9	Y	부가세 양수 또는 0 입력
10	`serviceFee`	string	9	Y	봉사료 양수 또는 0 입력
11	`franchiseCorpNum`	string	10	Y	가맹점 사업자번호 팝빌회원 사업자번호 ('-' 제외)
12	`franchiseTaxRegID`	string	4	N	가맹점 종사업장 식별번호 종사업장 식별번호는 4자리 숫자로만 구성
13	`franchiseCorpName`	string	200	N	가맹점 상호
14	`franchiseCEOName`	string	100	N	가맹점 대표자 성명
15	`franchiseAddr`	string	400	N	가맹점 주소
16	`franchiseTEL`	string	20	N	가맹점 전화번호
17	`identityNum`	string	19	Y	식별번호 {tradeUsage} 값이 "소득공제용" 경우 주민등록/휴대폰/카드번호/자진발급용 번호(010-000-1234) 입력 {tradeUsage} 값이 "지출증빙용" 경우 사업자번호/휴대폰/카드번호 입력 주민등록번호 13자리, 휴대폰번호 10~11자리, 카드번호 13~19자리, 사업자번호 10자리 입력 가능
18	`customerName`	string	70	N	구매자(고객) 성명
19	`itemName`	string	70	N	주문 상품명
20	`orderNumber`	string	200	N	주문번호
21	`email`	string	100	N	구매자(고객) 메일
22	`hp`	string	20	N	구매자(고객) 휴대폰
23	`smssendYN`	boolean	-	N	구매자 알림문자 전송 여부 `true` 전송 `false` 미전송 : 기본값 수신자 : 구매자 휴대폰번호 {hp} 문자 전송 포인트가 차감(단, 전송실패 건은 환불)
24	`memo`	string	200	N	현금영수증 상태 이력을 관리하기 위한 메모
25	`emailSubject`	string	300	N	현금영수증 발행 안내메일 제목 기본값 : 팝빌에서 설정한 안내메일 제목

요청 예시

curl --request POST \
  --url 'https://{domain}/Cashbill' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --header 'X-HTTP-Method-Override: ISSUE' \
  --data '{
    "mgtKey": "TEST0001",
    "tradeType": "승인거래",
    "tradeUsage": "지출증빙용",
    "taxationType": "과세",
    "totalAmount": "11000",
    "supplyCost": "10000",
    "tax": "1000",
    "serviceFee": "0",
    "franchiseCorpNum": "1234567890",
    "identityNum": "1234567890"
  }'

Response

응답 본문

순번	변수명	타입	길이	설명
1	`code`	number	-	API 처리에 대한 응답코드 `1` 성공
2	`message`	string	-	API 처리에 대한 응답메시지
3	`confirmNum`	string	9	국세청승인번호 현금영수증 발행 시점에 팝빌에서 자동으로 할당
4	`tradeDate`	string	8	거래일자 현금영수증 발행 시점에 팝빌에서 자동으로 할당 형식 : yyyyMMdd

응답 예시

{
    "code": 1,
    "message": "발행 완료",
    "confirmNum": "TB0000032",
    "tradeDate": "20251023"
}

2. RevokeRegistIssue - 취소 현금영수증 발행

POST https://popbill-test.linkhub.co.kr/Cashbill

당초 승인 현금영수증의 취소거래 발행 API 입니다.
작성된 취소 현금영수증 데이터를 팝빌에 저장과 동시에 발행하여 “발행완료” 상태로 처리합니다. [참고] 팝빌 국세청 전송 정책
부분 취소 현금영수증을 발행하는 경우 isPartCancel 값을 true 로 설정하여 주시기 바랍니다.
당초 국세청승인번호와 거래일자는 [GetInfo – 상태확인]함수를 통해 확인 가능합니다.

당초 승인 현금영수증의 거래일시보다 과거의 거래일시를 입력할 수 없습니다.
취소 현금영수증의 거래금액의 합은 당초 승인 현금영수증의 거래금액을 넘을 수 없습니다.
취소 현금영수증 발행시 구매자 메일주소로 발행 안내 메일이 전송되니 유의하시기 바랍니다.

Request

요청 헤더

순번	변수명	필수	설명
1	`Authorization`	Y	인증 토큰 [참고] 인증 및 헤더 설정
2	`Content-Type`	Y	요청 본문 형식 `application/json`
3	`Accept-Language`	N	응답 언어 설정 `ko-KR` 기본값 `en-US`
4	`Accept-Encoding`	N	응답 압축 방식 `gzip`
5	`X-HTTP-Method-Override`	Y	요청 메서드 재정의 `REVOKEISSUE`
6	`X-PB-UserID`	N	팝빌회원 아이디

요청 본문

순번	변수명	타입	길이	필수	설명
1	`mgtKey`	string	24	Y	파트너가 할당한 문서번호 영문 대소문자, 숫자, 특수문자('-','_')만 이용 가능
2	`orgConfirmNum`	string	9	Y	당초 국세청승인번호 [GetInfo - 상태 확인] API의 리턴값 confirmNum을 통해 내용 확인 가능
3	`orgTradeDate`	string	8	Y	당초 거래일자 [GetInfo - 상태 확인] API의 리턴값 tradeDate를 통해 내용 확인 가능
4	`smssendYN`	boolean	-	N	현금영수증 발행시 알림문자 전송 여부 `true` 전송 `false` 미전송 : 기본값 당초 승인 현금영수증의 구매자(고객)의 휴대폰번호 문자 전송
5	`memo`	string	200	N	현금영수증 상태 이력을 관리하기 위한 메모
6	`isPartCancel`	boolean	-	N	현금영수증 취소유형 `true` 부분 취소 `false` 전체 취소 : 기본값
7	`cancelType`	number	1	N	현금영수증 취소사유 `1` 거래취소 : 기본값 `2` 오류발급취소 `3` 기타
8	`supplyCost`	string	9	조건부	부분 취소 공급가액 양수만 입력 {isPartCancel}=true 경우 필수
9	`tax`	string	9	조건부	부분 취소 부가세 양수 또는 0 입력 {isPartCancel}=true 경우 필수
10	`serviceFee`	string	9	조건부	부분 취소 봉사료 양수 또는 0 입력 {isPartCancel}=true 경우 필수
11	`totalAmount`	string	9	조건부	부분 취소 거래금액 양수만 입력 거래금액 = 공급가액 + 부가세 + 봉사료 {isPartCancel}=true 경우 필수
12	`emailSubject`	string	300	N	현금영수증 발행 안내메일 제목 기본값 : 팝빌에서 설정한 안내메일 제목
13	`tradeDT`	string	14	N	거래일시 전일부터 당일까지 입력 가능 형식 : yyyyMMddHHmmss 기본값 : 발행일시 사용

요청 예시

curl --request POST \
  --url 'https://{domain}/Cashbill' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --header 'X-HTTP-Method-Override: REVOKEISSUE' \
  --data '{
    "mgtKey": "TEST0002",
    "orgConfirmNum": "TB0000032",
    "orgTradeDate": "20251023"
  }'

Response

응답 본문

순번	변수명	타입	길이	설명
1	`code`	number	-	API 처리에 대한 응답코드 `1` 성공
2	`message`	string	-	API 처리에 대한 응답메시지
3	`confirmNum`	string	9	국세청승인번호 현금영수증 발행 시점에 팝빌에서 자동으로 할당
4	`tradeDate`	string	8	거래일자 현금영수증 발행 시점에 팝빌에서 자동으로 할당 형식 : yyyyMMdd

응답 예시

{
    "code": 1,
    "message": "발행 완료",
    "confirmNum": "TB0000032",
    "tradeDate": "20251023"
}

3. BulkSubmit - 초대량 발행 접수

POST https://popbill-test.linkhub.co.kr/Cashbill

최대 100건의 현금영수증 발행을 한번의 요청으로 접수합니다.

Request

요청 헤더

순번	변수명	필수	설명
1	`Authorization`	Y	인증 토큰 [참고] 인증 및 헤더 설정
2	`Content-Type`	Y	요청 본문 형식 `application/json`
3	`Accept-Language`	N	응답 언어 설정 `ko-KR` 기본값 `en-US`
4	`Accept-Encoding`	N	응답 압축 방식 `gzip`
5	`X-PB-Submit-ID`	Y	제출아이디 영문, 숫자, '-' 조합으로 최대 36자 길이로 구성
6	`X-HTTP-Method-Override`	Y	요청 메서드 재정의 `BULKISSUE`
7	`X-PB-Message-Digest`	Y	Message Digest 요청 본문의 무결성을 검증하는데 사용 [참고] X-PB-Message-Digest
8	`X-PB-UserID`	N	팝빌회원 아이디

요청 본문

순번 변수명 타입 길이 필수 설명

array

현금영수증 목록

최대 : 100건

cashbills

순번	변수명	타입	길이	필수	설명
1	`mgtKey`	string	24	Y	문서번호 문서 관리를 위해 파트너가 할당하는 식별번호 영문 대소문자, 숫자, 특수문자('-','_')만 이용 가능
2	`tradeDT`	string	14	N	거래일시 전일부터 당일까지 입력 가능 형식 : yyyyMMddHHmmss 기본값 : 발행일시 사용
3	`tradeType`	string	4	Y	문서형태 `승인거래`
4	`tradeUsage`	string	-	Y	거래구분 (택 1) `소득공제용` `지출증빙용`
5	`tradeOpt`	string	4	N	거래유형 `일반` 기본값 `도서공연` `대중교통` 도서공연 : 도서, 공연, 박물관, 미술관, 수영장, 체력단련장, 신문구독료(종이신문), 영화관람료
6	`taxationType`	string	-	Y	과세형태 (택 1) `과세` `비과세`
7	`totalAmount`	string	9	Y	거래금액 (공급가액+부가세+봉사료) 양수만 입력
8	`supplyCost`	string	9	Y	공급가액 양수만 입력
9	`tax`	string	9	Y	부가세 양수 또는 0 입력
10	`serviceFee`	string	9	Y	봉사료 양수 또는 0 입력
11	`franchiseCorpNum`	string	10	Y	가맹점 사업자번호 팝빌회원 사업자번호 ('-' 제외)
12	`franchiseTaxRegID`	string	4	N	가맹점 종사업장 식별번호 종사업장 식별번호는 4자리 숫자로만 구성
13	`franchiseCorpName`	string	200	N	가맹점 상호
14	`franchiseCEOName`	string	100	N	가맹점 대표자 성명
15	`franchiseAddr`	string	400	N	가맹점 주소
16	`franchiseTEL`	string	20	N	가맹점 전화번호
17	`identityNum`	string	19	Y	식별번호 {tradeUsage} 값이 "소득공제용" 경우 주민등록/휴대폰/카드번호/자진발급용 번호(010-000-1234) 입력 {tradeUsage} 값이 "지출증빙용" 경우 사업자번호/휴대폰/카드번호 입력 주민등록번호 13자리, 휴대폰번호 10~11자리, 카드번호 13~19자리, 사업자번호 10자리 입력 가능
18	`customerName`	string	70	N	구매자(고객) 성명
19	`itemName`	string	70	N	주문 상품명
20	`orderNumber`	string	200	N	주문번호
21	`email`	string	100	N	구매자(고객) 메일
22	`hp`	string	20	N	구매자(고객) 휴대폰
23	`smssendYN`	boolean	-	N	구매자 알림문자 전송 여부 `true` 전송 `false` 미전송 : 기본값 수신자 : 구매자 휴대폰번호 {hp} 문자 전송 포인트가 차감(단, 전송실패 건은 환불)
24	`memo`	string	200	N	현금영수증 상태 이력을 관리하기 위한 메모
25	`emailSubject`	string	300	N	현금영수증 발행 안내메일 제목 기본값 : 팝빌에서 설정한 안내메일 제목

요청 예시

curl --request POST \
  --url 'https://{domain}/Cashbill' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --header 'X-HTTP-Method-Override: BULKISSUE' \
  --header 'X-PB-Submit-ID: {submitID}' \
  --header 'X-PB-Message-Digest: {messageDigest}' \
  --data '{
    "cashbills": [
        {
            "mgtKey": "TEST0004",
            "tradeType": "승인거래",
            "tradeUsage": "지출증빙용",
            "taxationType": "과세",
            "totalAmount": "11000",
            "supplyCost": "10000",
            "tax": "1000",
            "serviceFee": "0",
            "franchiseCorpNum": "1234567890",
            "identityNum": "1234567890"
        }
    ]
  }'

Response

응답 본문

순번	변수명	타입	길이	설명
1	`code`	number	-	API 처리에 대한 응답코드 `1` 성공
2	`message`	string	-	API 처리에 대한 응답메시지
3	`receiptID`	string	36	접수아이디

응답 예시

{
  "code": 1,
  "message": "접수 완료",
  "receiptID": "0251024-f842ed73b6004518bf5bc73c1d9f"
}

4. GetBulkResult - 초대량 접수결과 확인

GET https://popbill-test.linkhub.co.kr/Cashbill/BULK/{submitID}/State

접수시 기재한 SubmitID를 사용하여 현금영수증 접수결과를 확인합니다.
개별 현금영수증 처리상태는 접수상태(txState)가 완료(2) 시 반환됩니다.

Request

요청 헤더

순번	변수명	필수	설명
1	`Authorization`	Y	인증 토큰 [참고] 인증 및 헤더 설정
2	`Accept-Language`	N	응답 언어 설정 `ko-KR` 기본값 `en-US`
3	`Accept-Encoding`	N	응답 압축 방식 `gzip`
4	`X-PB-UserID`	N	팝빌회원 아이디

Path 파라미터

순번	변수명	타입	길이	필수	설명
1	`submitID`	string	36	Y	파트너가 할당한 제출아이디

요청 예시

curl --request GET \
  --url 'https://{domain}/Cashbill/BULK/{submitID}/State' \
  --header 'Authorization: Bearer {token}'

Response

응답 본문

순번 변수명 타입 길이 설명

code

number

API 처리에 대한 응답코드

1 성공

message

string

API 처리에 대한 응답메시지

submitID

string

접수 시점에 고객사에서 할당한 제출아이디

submitCount

number

현금영수증 접수 건수

successCount

number

현금영수증 발행 성공 건수

failCount

number

현금영수증 발행 실패 건수

txState

number

접수상태

0 접수
1 처리중
2 처리완료

txResultCode

number

접수 결과코드

성공 : 1

실패 : 음의 정수 8자리 숫자값 [참고] 오류코드

txStartDT

string

발행처리 시작일시

형식 : yyyyMMddHHmmss

txEndDT

string

발행처리 완료일시

형식 : yyyyMMddHHmmss

receiptID

string

접수아이디

접수 시점에 팝빌에서 자동으로 할당

array

발행결과

issueResult

순번	변수명	타입	길이	설명
1	`code`	number	-	API 처리에 대한 응답코드 `1` 성공
2	`message`	string	-	API 처리에 대한 응답메시지
3	`mgtKey`	string	24	문서번호
4	`confirmNum`	string	9	국세청승인번호 현금영수증 발행 시점에 팝빌에서 자동으로 할당
5	`tradeDate`	string	8	거래일자 현금영수증 발행 시점에 팝빌에서 자동으로 할당 {tradeDT}의 yyyyMMdd
6	`issueDT`	string	14	발행일시 형식 : yyyyMMddHHmmss

receiptDT

string

접수일시

형식 : yyyyMMddHHmmss

응답 예시

{
    "code": 1,
    "message": "확인 완료",
    "receiptID": "0251024-bf8026eae6d64e44854593e5fa82",
    "submitID": "20251024-JAVA3",
    "submitCount": 5,
    "successCount": 5,
    "failCount": 0,
    "txState": 2,
    "txStartDT": "20251024140659",
    "txEndDT": "20251024140700",
    "txResultCode": 1,
    "issueResult": [
        {
            "mgtKey": "20251024-0",
            "code": 1,
            "confirmNum": "TB0000048",
            "tradeDate": "20251024",
            "issueDT": "20251024140659"
        }
    ],
    "receiptDT": "20251024140659"
}

5. Delete - 삭제

POST https://popbill-test.linkhub.co.kr/Cashbill/{MgtKey}

삭제 가능한 상태의 현금영수증을 삭제합니다.
※ 삭제 가능한 상태: “전송실패”

삭제 처리된 현금영수증의 문서번호는 재사용이 가능합니다.

Request

요청 헤더

순번	변수명	필수	설명
1	`Authorization`	Y	인증 토큰 [참고] 인증 및 헤더 설정
2	`Accept-Language`	N	응답 언어 설정 `ko-KR` 기본값 `en-US`
3	`Accept-Encoding`	N	응답 압축 방식 `gzip`
4	`X-HTTP-Method-Override`	Y	요청 메서드 재정의 `DELETE`
5	`X-PB-UserID`	N	팝빌회원 아이디

Path 파라미터

순번	변수명	타입	길이	필수	설명
1	`MgtKey`	string	24	Y	파트너가 할당한 문서번호

요청 예시

curl --request POST \
  --url 'https://{domain}/Cashbill/{MgtKey}' \
  --header 'Authorization: Bearer {token}' \
  --header 'X-HTTP-Method-Override: DELETE'

Response

응답 본문

순번	변수명	타입	길이	설명
1	`code`	number	-	API 처리에 대한 응답코드 `1` 성공
2	`message`	string	-	API 처리에 대한 응답메시지

응답 예시

{
    "code": 1,
    "message": "삭제 완료"
}