정보확인

1. GetInfo - 상태 확인

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

GET https://popbill.linkhub.co.kr/Cashbill/{MgtKey}

현금영수증 1건의 상태 및 요약정보를 확인합니다.
리턴값 stateCode를 통해 현금영수증의 상태코드를 확인합니다.

Request

요청 헤더

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

Path 파라미터

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

요청 예시

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

Response

응답 본문

변수명	타입	길이	설명
itemKey	string	18	팝빌에서 할당한 식별번호
mgtKey	string	24	문서번호 파트너가 할당하는 식별번호
tradeDate	string	8	거래일자 형식 : yyyyMMdd
tradeDT	string	14	거래일시 형식 : yyyyMMddHHmmss
tradeType	string	4	문서형태 승인거래 취소거래
tradeUsage	string	5	거래구분 소득공제용 지출증빙용
tradeOpt	string	4	거래유형 일반 도서공연 대중교통
taxationType	string	3	과세형태 과세 비과세
totalAmount	string	9	거래금액 (공급가액+부가세+봉사료)
supplyCost	string	9	공급가액 양수만 입력
tax	string	9	부가세 양수 또는 0 입력
serviceFee	string	9	봉사료 양수 또는 0 입력
issueDT	string	14	발행일시 형식 : yyyyMMddHHmmss
regDT	string	14	등록일시 형식 : yyyyMMddHHmmss
stateMemo	string	200	상태메모
stateCode	number	1	상태코드 [참고] 팝빌 상태코드
stateDT	string	14	상태 변경일시 형식 : yyyyMMddHHmmss
identityNum	string	19	식별번호 - {tradeUsage} 값이 "소득공제용" 경우 주민등록/휴대폰/카드번호/자진발급용 번호(010-000-1234) 반환 - {tradeUsage} 값이 "지출증빙용" 경우 사업자번호/휴대폰/카드번호 반환
itemName	string	70	주문상품명
orderNumber	string	200	주문번호
email	string	100	구매자 이메일
hp	string	20	구매자 휴대폰
customerName	string	70	구매자(고객) 성명
confirmNum	string	9	국세청승인번호 현금영수증 발행 시점에 팝빌에서 자동으로 할당
orgConfirmNum	string	9	당초 국세청승인번호 {tradeType}="취소거래" 경우 반환
orgTradeDate	string	8	당초 거래일자 {tradeType}="취소거래" 경우 반환
ntssendDT	string	14	국세청 전송일시 형식 : yyyyMMddHHmmss
ntsresultDT	string	14	국세청 처리결과 수신일시 형식 : yyyyMMddHHmmss
ntsresultCode	string	4	국세청 결과코드 [참고] 국세청 결과코드
ntsresultMessage	string	30	국세청 결과메시지
printYN	boolean	-	인쇄여부 true인쇄 false미인쇄
interOPYN	boolean	-	연동문서 여부 trueAPI를 통해 발행한 연동문서 false팝빌 사이트를 통해 발행한 문서

응답 예시

{
    "itemKey": "025102315531300001",
    "mgtKey": "TEST0001",
    "tradeDate": "20251023",
    "tradeDT": "20251023155313",
    "issueDT": "20251023155313",
    "identityNum": "12****7890",
    "taxationType": "과세",
    "totalAmount": "11000",
    "tradeUsage": "지출증빙용",
    "tradeType": "승인거래",
    "tradeOpt": "일반",
    "stateCode": 304,
    "stateDT": "20251023155313",
    "printYN": false,
    "confirmNum": "TB0000032",
    "ntssendDT": "20251024000000",
    "ntsresultDT": "20251024091509",
    "ntsresultCode": "0000",
    "ntsresultMessage": "더미승인",
    "supplyCost": "10000",
    "tax": "1000",
    "serviceFee": "0",
    "interOPYN": true,
    "regDT": "20251023155314"
}

2. GetInfos - 다수건 상태 확인

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

POST https://popbill.linkhub.co.kr/Cashbill/States

다수건의 현금영수증 상태 및 요약 정보를 확인합니다. (1회 호출에 최대 1,000건 확인 가능)
리턴값 stateCode를 통해 현금영수증의 상태코드를 확인합니다.

문서번호를 통해 현금영수증 목록을 구현하는 경우 활용합니다.

Request

요청 헤더

변수명	필수	설명
Authorization	Y	인증 토큰 [참고] 인증 및 헤더 설정
Content-Type	Y	요청 본문 형식 application/json
Accept-Language	N	응답 언어 설정 ko-KR: 기본값 en-US
Accept-Encoding	N	응답 압축 방식 gzip
X-PB-UserID	N	팝빌회원 아이디

요청 본문

순번	변수명	타입	길이	필수	설명
	-	array	-	Y	문서번호 목록 최대 : 1,000건

요청 예시

curl --request POST \
  --url 'https://{domain}/Cashbill/States' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '["MGTKEY-0001"]'

Response

응답 본문

변수명	타입	길이	설명
itemKey	string	18	팝빌에서 할당한 식별번호
mgtKey	string	24	문서번호 파트너가 할당하는 식별번호
tradeDate	string	8	거래일자 형식 : yyyyMMdd
tradeDT	string	14	거래일시 형식 : yyyyMMddHHmmss
tradeType	string	4	문서형태 승인거래 취소거래
tradeUsage	string	5	거래구분 소득공제용 지출증빙용
tradeOpt	string	4	거래유형 일반 도서공연 대중교통
taxationType	string	3	과세형태 과세 비과세
totalAmount	string	9	거래금액 (공급가액+부가세+봉사료)
supplyCost	string	9	공급가액 양수만 입력
tax	string	9	부가세 양수 또는 0 입력
serviceFee	string	9	봉사료 양수 또는 0 입력
issueDT	string	14	발행일시 형식 : yyyyMMddHHmmss
regDT	string	14	등록일시 형식 : yyyyMMddHHmmss
stateMemo	string	200	상태메모
stateCode	number	1	상태코드 [참고] 팝빌 상태코드
stateDT	string	14	상태 변경일시 형식 : yyyyMMddHHmmss
identityNum	string	19	식별번호 - {tradeUsage} 값이 "소득공제용" 경우 주민등록/휴대폰/카드번호/자진발급용 번호(010-000-1234) 반환 - {tradeUsage} 값이 "지출증빙용" 경우 사업자번호/휴대폰/카드번호 반환
itemName	string	70	주문상품명
orderNumber	string	200	주문번호
email	string	100	구매자 이메일
hp	string	20	구매자 휴대폰
customerName	string	70	구매자(고객) 성명
confirmNum	string	9	국세청승인번호 현금영수증 발행 시점에 팝빌에서 자동으로 할당
orgConfirmNum	string	9	당초 국세청승인번호 {tradeType}="취소거래" 경우 반환
orgTradeDate	string	8	당초 거래일자 {tradeType}="취소거래" 경우 반환
ntssendDT	string	14	국세청 전송일시 형식 : yyyyMMddHHmmss
ntsresultDT	string	14	국세청 처리결과 수신일시 형식 : yyyyMMddHHmmss
ntsresultCode	string	4	국세청 결과코드 [참고] 국세청 결과코드
ntsresultMessage	string	30	국세청 결과메시지
printYN	boolean	-	인쇄여부 true인쇄 false미인쇄
interOPYN	boolean	-	연동문서 여부 trueAPI를 통해 발행한 연동문서 false팝빌 사이트를 통해 발행한 문서

응답 예시

[
    {
        "invoiceePrintYN": false,
        "openYN": false,
        "taxType": "과세",
        "invoicerCorpNum": "1234567890",
        "invoicerMgtKey": "MKGTKEY-0002",
        "invoicerCorpName": "공급자 상호",
        "invoicerPrintYN": false,
        "invoiceeCorpName": "공급받는자 상호",
        "trusteePrintYN": false,
        "taxTotal": "1000",
        "supplyCostTotal": "10000",
        "purposeType": "영수",
        "ntsconfirmNum": "202510168888888800000002",
        "closeDownState": 0,
        "lateIssueYN": false,
        "stateCode": 300,
        "interOPYN": true,
        "itemKey": "025102114360700001",
        "issueDT": "20251021143607",
        "stateDT": "20251021143608",
        "regDT": "20251021143608",
        "invoiceeCorpNum": "1234567890",
        "issueType": "정발행",
        "writeDate": "20251016"
    }
]

3. GetDetailInfo - 상세정보 확인

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

GET https://popbill.linkhub.co.kr/Cashbill/{MgtKey}

현금영수증 1건의 상세정보를 확인합니다.

Request

요청 헤더

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

Path 파라미터

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

Query 파라미터

순번	변수명	타입	길이	필수	설명
	Detail	-	-	Y	상세 정보 빈값으로 입력

요청 예시

curl --request GET \
  --url 'https://{domain}/Cashbill/{MgtKey}?Detail' \
  --header 'Authorization: Bearer {token}'

Response

응답 본문

변수명	타입	길이	설명
mgtKey	string	24	문서번호 문서 관리를 위해 파트너가 할당하는 식별번호
confirmNum	string	9	국세청승인번호 현금영수증 발행 시점에 팝빌에서 자동으로 할당
orgConfirmNum	string	9	당초 국세청승인번호 {tradeType}="취소거래" 경우 반환
orgTradeDate	string	8	당초 거래일자 {tradeType}="취소거래" 경우 반환
tradeDate	string	8	거래일자 현금영수증 발행 시점에 팝빌에서 자동으로 할당 {tradeDT}의 yyyyMMdd
tradeDT	string	14	거래일시 형식 : yyyyMMddHHmmss
tradeType	string	4	문서형태 승인거래 취소거래
tradeUsage	string	5	거래구분 소득공제용 지출증빙용
tradeOpt	string	4	거래유형 일반 도서공연 대중교통
taxationType	string	3	과세형태 과세 비과세
totalAmount	string	9	거래금액 (공급가액+부가세+봉사료)
supplyCost	string	9	공급가액
tax	string	9	부가세
serviceFee	string	9	봉사료
franchiseCorpNum	string	10	가맹점 사업자번호
franchiseTaxRegID	string	4	가맹점 종사업장 식별번호
franchiseCorpName	string	200	가맹점 상호
franchiseCEOName	string	100	가맹점 대표자 성명
franchiseAddr	string	400	가맹점 주소
franchiseTEL	string	20	가맹점 전화번호
identityNum	string	19	식별번호 - {tradeUsage} 값이 "소득공제용" 경우 주민등록/휴대폰/카드번호/자진발급용 번호(010-000-1234) 반환 - {tradeUsage} 값이 "지출증빙용" 경우 사업자번호/휴대폰/카드번호 반환
customerName	string	70	구매자(고객) 성명
itemName	string	70	주문 상품명
orderNumber	string	200	주문번호
email	string	100	구매자(고객) 메일
hp	string	20	구매자(고객) 휴대폰
smssendYN	boolean	-	구매자 알림문자 전송 여부 true전송 false미전송 : 기본값 수신자 : 구매자 휴대폰번호 {hp}
cancelType	string	test	취소사유 1거래취소 2오류발급취소 3기타 {tradeType}="취소거래" 경우 입력

응답 예시

{
    "mgtKey": "TEST0001",
    "tradeDate": "20251023",
    "tradeDT": "20251023155313",
    "tradeUsage": "지출증빙용",
    "tradeType": "승인거래",
    "tradeOpt": "일반",
    "taxationType": "과세",
    "supplyCost": "10000",
    "tax": "1000",
    "serviceFee": "0",
    "totalAmount": "11000",
    "franchiseCorpNum": "1234567890",
    "identityNum": "12****7890",
    "printYN": false,
    "smssendYN": false,
    "faxsendYN": false,
    "confirmNum": "TB0000032"
}

4. CheckMgtKeyInUse - 문서번호 사용 여부 확인

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

GET https://popbill.linkhub.co.kr/Cashbill/{MgtKey}

파트너가 현금영수증 관리 목적으로 할당하는 문서번호 사용여부를 확인합니다.
응답 본문의 itemKey 필드에 값이 존재하면 사용 중인 문서번호이며, 값이 존재하지 않으면 사용 가능한 문서번호 입니다.
이미 사용 중인 문서번호는 중복 사용이 불가하고, 현금영수증이 삭제된 경우에만 문서번호의 재사용이 가능합니다.

Request

요청 헤더

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

Path 파라미터

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

요청 예시

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

Response

응답 본문

변수명	타입	길이	설명
itemKey	string	18	팝빌에서 할당한 식별번호
mgtKey	string	24	문서번호 파트너가 할당하는 식별번호
tradeDate	string	8	거래일자 형식 : yyyyMMdd
tradeDT	string	14	거래일시 형식 : yyyyMMddHHmmss
tradeType	string	4	문서형태 승인거래 취소거래
tradeUsage	string	5	거래구분 소득공제용 지출증빙용
tradeOpt	string	4	거래유형 일반 도서공연 대중교통
taxationType	string	3	과세형태 과세 비과세
totalAmount	string	9	거래금액 (공급가액+부가세+봉사료)
supplyCost	string	9	공급가액 양수만 입력
tax	string	9	부가세 양수 또는 0 입력
serviceFee	string	9	봉사료 양수 또는 0 입력
issueDT	string	14	발행일시 형식 : yyyyMMddHHmmss
regDT	string	14	등록일시 형식 : yyyyMMddHHmmss
stateCode	number	1	상태코드 [참고] 팝빌 상태코드
stateDT	string	14	상태 변경일시 형식 : yyyyMMddHHmmss
identityNum	string	19	식별번호 - {tradeUsage} 값이 "소득공제용" 경우 주민등록/휴대폰/카드번호/자진발급용 번호(010-000-1234) 반환 - {tradeUsage} 값이 "지출증빙용" 경우 사업자번호/휴대폰/카드번호 반환
itemName	string	70	주문상품명
orderNumber	string	200	주문번호
email	string	100	구매자 이메일
hp	string	20	구매자 휴대폰
customerName	string	70	구매자(고객) 성명
confirmNum	string	9	국세청승인번호 현금영수증 발행 시점에 팝빌에서 자동으로 할당
orgConfirmNum	string	9	당초 국세청승인번호 {tradeType}="취소거래" 경우 반환
orgTradeDate	string	8	당초 거래일자 {tradeType}="취소거래" 경우 반환
ntssendDT	string	14	국세청 전송일시 형식 : yyyyMMddHHmmss
ntsresultDT	string	14	국세청 처리결과 수신일시 형식 : yyyyMMddHHmmss
ntsresultCode	string	4	국세청 결과코드 [참고] 국세청 결과코드
ntsresultMessage	string	30	국세청 결과메시지
printYN	boolean	-	인쇄여부 true인쇄 false미인쇄
interOPYN	boolean	-	연동문서 여부 trueAPI를 통해 발행한 연동문서 false팝빌 사이트를 통해 발행한 문서

응답 예시

{
    "itemKey": "025102315531300001",
}

5. Search - 목록 조회

GET https://popbill-test.linkhub.co.kr/Cashbill/Search

GET https://popbill.linkhub.co.kr/Cashbill/Search

검색조건에 해당하는 현금영수증을 조회합니다. (최대 조회기간 : 6개월)

매개변수 Page, PerPage, Order를 이용하여 페이징 기능을 구현할 수 있습니다.

Request

요청 헤더

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

Query 파라미터

변수명	타입	길이	필수	설명
DType	string	1	Y	검색일자 유형 (택 1) R등록일자 T작성일자 I발행일시
SDate	string	8	Y	검색 시작일자 형식 : yyyyMMdd
EDate	string	8	Y	검색 종료일자 형식 : yyyyMMdd
State	string	-	N	현금영수증 상태코드 2, 3번째 자리에 와일드카드() 사용가능. 예) 3* [참고] 팝빌 상태코드 기본값 : 전체조회
TradeType	string	-	N	현금영수증 문서형태 (다중 선택 가능) N승인 현금영수증 C취소 현금영수증 다중 선택시 콤마(',')로 구분. 예) N,C 기본값 : 전체조회
TradeUsage	string	-	N	거래구분 (다중 선택 가능) P소득공제용 C지출증빙용 다중 선택시 콤마(',')로 구분. 예) P,C 기본값 : 전체조회
TradeOpt	string	-	N	거래유형 (다중 선택 가능) N일반 B도서공연 T대중교통 다중 선택시 콤마(',')로 구분. 예) N,B 기본값 : 전체조회
TaxationType	string	-	N	과세형태 (다중 선택 가능) T과세 N비과세 다중 선택시 콤마(',')로 구분. 예) T,N 기본값 : 전체조회
QString	string	-	N	조회 검색어(식별번호) 기본값 : 전체조회
Page	number	-	Y	목록 페이지번호 기본값 : 1
PerPage	number	-	N	페이지당 표시할 목록 건수 최대 : 1,000건 기본값 : 500건
Order	string	1	N	조회 기준일자 유형을 기준으로 하는 목록 정렬 방향 D내림차순 : 기본값 A오름차순
FranchiseTaxRegID	string	-	N	가맹점 종사업장번호 다수건 검색시 콤마(',')로 구분. 예) 1234,1000 기본값 : 전체조회

요청 예시

curl --request GET \
  --url 'https://{domain}/Cashbill/}/Search?DType={DType}&SDate={SDate}&EDate={EDate}' \
  --header 'Authorization: Bearer {token}'

Response

응답 본문

순번

변수명

타입

길이

설명

code

number

API 처리에 대한 응답코드

1성공

message

string

API 처리에 대한 응답메시지

total

string

총 검색결과 건수

perPage

string

페이지당 목록 건수

pageNum

string

페이지 번호

pageCount

string

페이지 개수

list

array

현금영수증 상태/요약정보

함수 [GetInfo - 상태 확인]의 리턴값 구성과 동일
최대 1,000건

변수명	타입	길이	설명
itemKey	string	18	팝빌에서 할당한 식별번호
mgtKey	string	24	문서번호 파트너가 할당하는 식별번호
tradeDate	string	8	거래일자 형식 : yyyyMMdd
tradeDT	string	14	거래일시 형식 : yyyyMMddHHmmss
tradeType	string	4	문서형태 승인거래 취소거래
tradeUsage	string	5	거래구분 소득공제용 지출증빙용
tradeOpt	string	4	거래유형 일반 도서공연 대중교통
taxationType	string	3	과세형태 과세 비과세
totalAmount	string	9	거래금액 (공급가액+부가세+봉사료)
supplyCost	string	9	공급가액 양수만 입력
tax	string	9	부가세 양수 또는 0 입력
serviceFee	string	9	봉사료 양수 또는 0 입력
issueDT	string	14	발행일시 형식 : yyyyMMddHHmmss
regDT	string	14	등록일시 형식 : yyyyMMddHHmmss
stateMemo	string	200	상태메모
stateCode	number	1	상태코드 [참고] 팝빌 상태코드
stateDT	string	14	상태 변경일시 형식 : yyyyMMddHHmmss
identityNum	string	19	식별번호 - {tradeUsage} 값이 "소득공제용" 경우 주민등록/휴대폰/카드번호/자진발급용 번호(010-000-1234) 반환 - {tradeUsage} 값이 "지출증빙용" 경우 사업자번호/휴대폰/카드번호 반환
itemName	string	70	주문상품명
orderNumber	string	200	주문번호
email	string	100	구매자 이메일
hp	string	20	구매자 휴대폰
customerName	string	70	구매자(고객) 성명
confirmNum	string	9	국세청승인번호 현금영수증 발행 시점에 팝빌에서 자동으로 할당
orgConfirmNum	string	9	당초 국세청승인번호 {tradeType}="취소거래" 경우 반환
orgTradeDate	string	8	당초 거래일자 {tradeType}="취소거래" 경우 반환
ntssendDT	string	14	국세청 전송일시 형식 : yyyyMMddHHmmss
ntsresultDT	string	14	국세청 처리결과 수신일시 형식 : yyyyMMddHHmmss
ntsresultCode	string	4	국세청 결과코드 [참고] 국세청 결과코드
ntsresultMessage	string	30	국세청 결과메시지
printYN	boolean	-	인쇄여부 true인쇄 false미인쇄
interOPYN	boolean	-	연동문서 여부 trueAPI를 통해 발행한 연동문서 false팝빌 사이트를 통해 발행한 문서

응답 예시

{
    "code": 1,
    "total": 4,
    "perPage": 500,
    "pageNum": 1,
    "pageCount": 1,
    "list": [
        {
            "itemKey": "025102315531300001",
            "mgtKey": "TEST0001",
            "tradeDate": "20251023",
            "tradeDT": "20251023155313",
            "issueDT": "20251023155313",
            "identityNum": "12****7890",
            "taxationType": "과세",
            "totalAmount": "11000",
            "tradeUsage": "지출증빙용",
            "tradeType": "승인거래",
            "tradeOpt": "일반",
            "stateCode": 304,
            "stateDT": "20251023155313",
            "printYN": false,
            "confirmNum": "TB0000032",
            "ntssendDT": "20251024000000",
            "ntsresultDT": "20251024091509",
            "ntsresultCode": "0000",
            "ntsresultMessage": "더미승인",
            "supplyCost": "10000",
            "tax": "1000",
            "serviceFee": "0",
            "interOPYN": true,
            "regDT": "20251023155314"
        }
    ],
    "message": "검색 완료"
}

6. GetURL - 문서함 팝업 URL

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

GET https://popbill.linkhub.co.kr/Cashbill

Request

요청 헤더

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

Query 파라미터

순번	변수명	타입	길이	필수	설명
	TG	string	-	Y	접근 메뉴 (택 1) TBOX임시 문서함 PBOX발행 문서함 WRITE현금영수증 작성

요청 예시

curl --request GET \
  --url 'https://{domain}/Cashbill?TG={TG}' \
  --header 'Authorization: Bearer {token}'

Response

응답 본문

순번	변수명	타입	길이	설명
	url	string	-	현금영수증 문서함 팝업 URL

응답 예시

{
    "url": "https://test.popbill.com/App/API?T=IRXSGITDREOTPOIRLPUHCB4BSBC4...NX7BMAR3="
}