콘텐츠로 이동

정보확인

1. GetInfo - 상태확인

섹션 제목: “1. GetInfo - 상태확인”
GET https://popbill-test.linkhub.co.kr/Cashbill/{MgtKey}
  • 현금영수증 1건의 상태 및 요약정보를 확인합니다.
  • 리턴값 stateCode를 통해 현금영수증의 상태코드를 확인합니다.

Request

요청 헤더
순번 변수명 필수 설명
1AuthorizationY
인증 토큰
[참고] 인증 및 헤더 설정
2Accept-LanguageN
응답 언어 설정
  • ko-KR 기본값
  • en-US
3Accept-EncodingN
응답 압축 방식
  • gzip
4X-PB-UserIDN
팝빌회원 아이디
Path 파라미터
순번 변수명 타입 길이 필수 설명
1MgtKeystring24Y
파트너가 할당한 문서번호
요청 예시 
curl --request GET \
  --url 'https://{domain}/Cashbill/{MgtKey}' \
  --header 'Authorization: Bearer {token}'

Response

응답 본문
순번 변수명 타입 길이 설명
1itemKeystring18
팝빌에서 할당한 식별번호
2mgtKeystring24
문서번호
파트너가 할당하는 식별번호
3tradeDatestring8
거래일자
형식 : yyyyMMdd
4tradeDTstring14
거래일시
형식 : yyyyMMddHHmmss
5tradeTypestring4
문서형태
  • 승인거래
  • 취소거래
6tradeUsagestring5
거래구분
  • 소득공제용
  • 지출증빙용
7tradeOptstring4
거래유형
  • 일반
  • 도서공연
  • 대중교통
8taxationTypestring3
과세형태
  • 과세
  • 비과세
9totalAmountstring9
거래금액
공급가액 + 부가세 + 봉사료
10supplyCoststring9
공급가액
11taxstring9
부가세
12serviceFeestring9
봉사료
13issueDTstring14
발행일시
형식 : yyyyMMddHHmmss
14regDTstring14
등록일시
형식 : yyyyMMddHHmmss
15stateMemostring200
상태메모
16stateCodenumber3
상태코드
[참고] 팝빌 상태코드
17stateDTstring14
상태 변경일시
형식 : yyyyMMddHHmmss
18identityNumstring19
식별번호
{tradeUsage} 값이 "소득공제용" 경우 주민등록/휴대폰/카드번호/자진발급용 번호(010-000-1234) 반환
{tradeUsage} 값이 "지출증빙용" 경우 사업자번호/휴대폰/카드번호 반환
19itemNamestring70
주문상품명
20orderNumberstring200
주문번호
21emailstring100
구매자 이메일
22hpstring20
구매자 휴대폰
23customerNamestring70
구매자(고객) 성명
24confirmNumstring9
국세청승인번호
현금영수증 발행 시점에 팝빌에서 자동으로 할당
25orgConfirmNumstring9
당초 국세청승인번호
26orgTradeDatestring8
당초 거래일자
27ntssendDTstring14
국세청 전송일시
형식 : yyyyMMddHHmmss
28ntsresultDTstring14
국세청 처리결과 수신일시
형식 : yyyyMMddHHmmss
29ntsresultCodestring4
국세청 결과코드
[참고] 국세청 결과코드
30ntsresultMessagestring30
국세청 결과메시지
31printYNboolean-
인쇄여부
  • true 인쇄
  • false 미인쇄
32interOPYNboolean-
연동문서 여부
  • true API를 통해 발행한 연동문서
  • 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 - 다수건 상태 확인

섹션 제목: “2. GetInfos - 다수건 상태 확인”
POST https://popbill-test.linkhub.co.kr/Cashbill/States
  • 다수건의 현금영수증 상태 및 요약 정보를 확인합니다. (1회 호출에 최대 1,000건 확인 가능)
  • 리턴값 stateCode를 통해 현금영수증의 상태코드를 확인합니다.

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

Request

요청 헤더
순번 변수명 필수 설명
1AuthorizationY
인증 토큰
[참고] 인증 및 헤더 설정
2Content-TypeY
요청 본문 형식
  • application/json
3Accept-LanguageN
응답 언어 설정
  • ko-KR 기본값
  • en-US
4Accept-EncodingN
응답 압축 방식
  • gzip
5X-PB-UserIDN
팝빌회원 아이디
요청 본문
순번 변수명 타입 길이 필수 설명
1-array1,000Y
문서번호 목록
최대 : 1,000건
요청 예시 
curl --request POST \
--url 'https://{domain}/Cashbill/States' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data '["MGTKEY-0001"]'

Response

응답 본문
순번 변수명 타입 길이 설명
1itemKeystring18
팝빌에서 할당한 식별번호
2mgtKeystring24
문서번호
파트너가 할당하는 식별번호
3tradeDatestring8
거래일자
형식 : yyyyMMdd
4tradeDTstring14
거래일시
형식 : yyyyMMddHHmmss
5tradeTypestring4
문서형태
  • 승인거래
  • 취소거래
6tradeUsagestring5
거래구분
  • 소득공제용
  • 지출증빙용
7tradeOptstring4
거래유형
  • 일반
  • 도서공연
  • 대중교통
8taxationTypestring3
과세형태
  • 과세
  • 비과세
9totalAmountstring9
거래금액
공급가액 + 부가세 + 봉사료
10supplyCoststring9
공급가액
양수만 입력
11taxstring9
부가세
양수만 입력
12serviceFeestring9
봉사료
양수 또는 0 입력
13issueDTstring14
발행일시
형식 : yyyyMMddHHmmss
14regDTstring14
등록일시
형식 : yyyyMMddHHmmss
15stateMemostring200
상태메모
16stateCodenumber3
상태코드
[참고] 팝빌 상태코드
17stateDTstring14
상태 변경일시
형식 : yyyyMMddHHmmss
18identityNumstring19
식별번호
{tradeUsage} 값이 "소득공제용" 경우 주민등록/휴대폰/카드번호/자진발급용 번호(010-000-1234) 반환
{tradeUsage} 값이 "지출증빙용" 경우 사업자번호/휴대폰/카드번호 반환
19itemNamestring70
주문상품명
20orderNumberstring200
주문번호
21emailstring100
구매자 이메일
22hpstring20
구매자 휴대폰
23customerNamestring70
구매자(고객) 성명
24confirmNumstring9
국세청승인번호
현금영수증 발행 시점에 팝빌에서 자동으로 할당
25orgConfirmNumstring9
당초 국세청승인번호
26orgTradeDatestring8
당초 거래일자
27ntssendDTstring14
국세청 전송일시
형식 : yyyyMMddHHmmss
28ntsresultDTstring14
국세청 처리결과 수신일시
형식 : yyyyMMddHHmmss
29ntsresultCodestring4
국세청 결과코드
[참고] 국세청 결과코드
30ntsresultMessagestring30
국세청 결과메시지
31printYNboolean-
인쇄여부
  • true 인쇄
  • false 미인쇄
32interOPYNboolean-
연동문서 여부
  • true API를 통해 발행한 연동문서
  • 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"
    }
]

3. GetDetailInfo - 상세정보 확인

섹션 제목: “3. GetDetailInfo - 상세정보 확인”
GET https://popbill-test.linkhub.co.kr/Cashbill/{MgtKey}
  • 현금영수증 1건의 상세정보를 확인합니다.

Request

요청 헤더
순번 변수명 필수 설명
1AuthorizationY
인증 토큰
[참고] 인증 및 헤더 설정
2Accept-LanguageN
응답 언어 설정
  • ko-KR 기본값
  • en-US
3Accept-EncodingN
응답 압축 방식
  • gzip
4X-PB-UserIDN
팝빌회원 아이디
Path 파라미터
순번 변수명 타입 길이 필수 설명
1MgtKeystring24Y
파트너가 할당한 문서번호
Query 파라미터
순번 변수명 타입 길이 필수 설명
1Detail-Y
상세 정보
빈값으로 입력
요청 예시 
curl --request GET \
  --url 'https://{domain}/Cashbill/{MgtKey}?Detail' \
  --header 'Authorization: Bearer {token}'

Response

응답 본문
순번 변수명 타입 길이 설명
1mgtKeystring24
문서번호
문서 관리를 위해 파트너가 할당하는 식별번호
2confirmNumstring9
국세청승인번호
현금영수증 발행 시점에 팝빌에서 자동으로 할당
3orgConfirmNumstring9
당초 국세청승인번호
{tradeType}="취소거래" 경우 반환
4orgTradeDatestring8
당초 거래일자
{tradeType}="취소거래" 경우 반환
5tradeDatestring8
거래일자
현금영수증 발행 시점에 팝빌에서 자동으로 할당
{tradeDT}의 yyyyMMdd
6tradeDTstring14
거래일시
형식 : yyyyMMddHHmmss
7tradeTypestring4
문서형태
  • 승인거래
  • 취소거래
8tradeUsagestring5
거래구분
  • 소득공제용
  • 지출증빙용
9tradeOptstring4
거래유형
  • 일반
  • 도서공연
  • 대중교통
10taxationTypestring3
과세형태
  • 과세
  • 비과세
11totalAmountstring9
거래금액 (공급가액+부가세+봉사료)
12supplyCoststring9
공급가액
13taxstring9
부가세
14serviceFeestring9
봉사료
15franchiseCorpNumstring10
가맹점 사업자번호
16franchiseTaxRegIDstring4
가맹점 종사업장 식별번호
17franchiseCorpNamestring200
가맹점 상호
18franchiseCEONamestring100
가맹점 대표자 성명
19franchiseAddrstring400
가맹점 주소
20franchiseTELstring20
가맹점 전화번호
21identityNumstring19
식별번호
{tradeUsage} 값이 "소득공제용" 경우 주민등록/휴대폰/카드번호/자진발급용 번호(010-000-1234) 반환
{tradeUsage} 값이 "지출증빙용" 경우 사업자번호/휴대폰/카드번호 반환
22customerNamestring70
구매자(고객) 성명
23itemNamestring70
주문 상품명
24orderNumberstring200
주문번호
25emailstring100
구매자(고객) 메일
26hpstring20
구매자(고객) 휴대폰
27smssendYNboolean-
구매자 알림문자 전송 여부
  • true 전송
  • false 미전송 : 기본값
수신자 : 구매자 휴대폰번호 {hp}
28cancelTypestring-
취소사유
  • 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 - 문서번호 사용 여부 확인

섹션 제목: “4. CheckMgtKeyInUse - 문서번호 사용 여부 확인”
GET https://popbill-test.linkhub.co.kr/Cashbill/{MgtKey}
  • 파트너가 현금영수증 관리 목적으로 할당하는 문서번호 사용여부를 확인합니다.
  • 응답 본문의 itemKey 필드에 값이 존재하면 사용 중인 문서번호이며, 값이 존재하지 않으면 사용 가능한 문서번호 입니다.
  • 이미 사용 중인 문서번호는 중복 사용이 불가하고, 현금영수증이 삭제된 경우에만 문서번호의 재사용이 가능합니다.

Request

요청 헤더
순번 변수명 필수 설명
1AuthorizationY
인증 토큰
[참고] 인증 및 헤더 설정
2Accept-LanguageN
응답 언어 설정
  • ko-KR 기본값
  • en-US
3Accept-EncodingN
응답 압축 방식
  • gzip
4X-PB-UserIDN
팝빌회원 아이디
Path 파라미터
순번 변수명 타입 길이 필수 설명
1MgtKeystring24Y
파트너가 할당한 문서번호
요청 예시 
curl --request GET \
  --url 'https://{domain}/Cashbill/{MgtKey}' \
  --header 'Authorization: Bearer {token}'

Response

응답 본문
순번 변수명 타입 길이 설명
1itemKeystring18
팝빌에서 할당한 식별번호
응답 예시 
{
    "itemKey": "025102114360700001"
}
섹션 제목: “5. Search - 목록 조회”
GET https://popbill-test.linkhub.co.kr/Cashbill/Search
  • 검색조건에 해당하는 현금영수증을 조회합니다. (최대 조회기간 : 6개월)

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

Request

요청 헤더
순번 변수명 필수 설명
1AuthorizationY
인증 토큰
[참고] 인증 및 헤더 설정
2Accept-LanguageN
응답 언어 설정
  • ko-KR 기본값
  • en-US
3Accept-EncodingN
응답 압축 방식
  • gzip
4X-PB-UserIDN
팝빌회원 아이디
Query 파라미터
순번 변수명 타입 길이 필수 설명
1DTypestring1Y
검색일자 유형 (택 1)
  • R 등록일자
  • T 작성일자
  • I 발행일시
2SDatestring8Y
검색 시작일자
형식 : yyyyMMdd
3EDatestring8Y
검색 종료일자
형식 : yyyyMMdd
4Statestring-N
현금영수증 상태코드
2, 3번째 자리에 와일드카드(*) 사용가능. 예) 3**
[참고] 팝빌 상태코드
기본값 : 전체조회
5TradeTypestring-N
현금영수증 문서형태 (다중 선택 가능)
  • N 승인 현금영수증
  • C 취소 현금영수증
다중 선택시 콤마(',')로 구분. 예) N,C
기본값 : 전체조회
6TradeUsagestring-N
거래구분 (다중 선택 가능)
  • P 소득공제용
  • C 지출증빙용
다중 선택시 콤마(',')로 구분. 예) P,C
기본값 : 전체조회
7TradeOptstring-N
거래유형 (다중 선택 가능)
  • N 일반
  • B 도서공연
  • T 대중교통
다중 선택시 콤마(',')로 구분. 예) N,B
기본값 : 전체조회
8TaxationTypestring-N
과세형태 (다중 선택 가능)
  • T 과세
  • N 비과세
다중 선택시 콤마(',')로 구분. 예) T,N
기본값 : 전체조회
9QStringstring-N
조회 검색어(식별번호)
기본값 : 전체조회
10Pagenumber-N
목록 페이지번호
기본값 : 1
11PerPagenumber-N
페이지당 표시할 목록 건수
최대 : 1,000건
기본값 : 500건
12Orderstring1N
조회 기준일자 유형을 기준으로 하는 목록 정렬 방향
  • D 내림차순 : 기본값
  • A 오름차순
13FranchiseTaxRegIDstring-N
가맹점 종사업장번호
다수건 검색시 콤마(',')로 구분. 예) 1234,1000
기본값 : 전체조회
요청 예시 
curl --request GET \
  --url 'https://{domain}/Cashbill/Search?DType={DType}&SDate={SDate}&EDate={EDate}' \
  --header 'Authorization: Bearer {token}'

Response

응답 본문
순번 변수명 타입 길이 설명
1codenumber-
API 처리에 대한 응답코드
  • 1 성공
2messagestring-
API 처리에 대한 응답메시지
3totalnumber-
총 검색결과 건수
4perPagenumber-
페이지당 목록 건수
5pageNumnumber-
페이지 번호
6pageCountnumber-
페이지 개수
7array-
현금영수증 상태/요약정보
함수 [GetInfo – 상태 확인]의 리턴값 구성과 동일
최대 : 1,000건
list
순번변수명타입길이설명
1itemKeystring18
팝빌에서 할당한 식별번호
2mgtKeystring24
문서번호
파트너가 할당하는 식별번호
3tradeDatestring8
거래일자
형식 : yyyyMMdd
4tradeDTstring14
거래일시
형식 : yyyyMMddHHmmss
5tradeTypestring4
문서형태
  • 승인거래
  • 취소거래
6tradeUsagestring5
거래구분
  • 소득공제용
  • 지출증빙용
7tradeOptstring4
거래유형
  • 일반
  • 도서공연
  • 대중교통
8taxationTypestring3
과세형태
  • 과세
  • 비과세
9totalAmountstring9
거래금액
공급가액 + 부가세 + 봉사료
10supplyCoststring9
공급가액
양수만 입력
11taxstring9
부가세
양수만 입력
12serviceFeestring9
봉사료
양수 또는 0 입력
13issueDTstring14
발행일시
형식 : yyyyMMddHHmmss
14regDTstring14
등록일시
형식 : yyyyMMddHHmmss
15stateMemostring200
상태메모
16stateCodenumber3
상태코드
[참고] 팝빌 상태코드
17stateDTstring14
상태 변경일시
형식 : yyyyMMddHHmmss
18identityNumstring19
식별번호
{tradeUsage} 값이 "소득공제용" 경우 주민등록/휴대폰/카드번호/자진발급용 번호(010-000-1234) 반환
{tradeUsage} 값이 "지출증빙용" 경우 사업자번호/휴대폰/카드번호 반환
19itemNamestring70
주문상품명
20orderNumberstring200
주문번호
21emailstring100
구매자 이메일
22hpstring20
구매자 휴대폰
23customerNamestring70
구매자(고객) 성명
24confirmNumstring9
국세청승인번호
현금영수증 발행 시점에 팝빌에서 자동으로 할당
25orgConfirmNumstring9
당초 국세청승인번호
26orgTradeDatestring8
당초 거래일자
27ntssendDTstring14
국세청 전송일시
형식 : yyyyMMddHHmmss
28ntsresultDTstring14
국세청 처리결과 수신일시
형식 : yyyyMMddHHmmss
29ntsresultCodestring4
국세청 결과코드
[참고] 국세청 결과코드
30ntsresultMessagestring30
국세청 결과메시지
31printYNboolean-
인쇄여부
  • true 인쇄
  • false 미인쇄
32interOPYNboolean-
연동문서 여부
  • true API를 통해 발행한 연동문서
  • 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

섹션 제목: “6. GetURL - 문서함 팝업 URL”
GET https://popbill-test.linkhub.co.kr/Cashbill

문서함 팝업 URL 미리보기

문서함 팝업 URL 미리보기

현금영수증 문서함의 팝업 URL을 반환합니다.

  • 권장 사이즈 : width = 1,280px (최소 1,000px) / height = 800px
  • 반환되는 URL은 30초 동안만 사용이 가능합니다.
  • 반환되는 URL은 팝빌회원의 로그인 세션을 포함하고 있으니 사용에 유의하여 주시기 바랍니다.

Request

요청 헤더
순번 변수명 필수 설명
1AuthorizationY
인증 토큰
[참고] 인증 및 헤더 설정
2Accept-LanguageN
응답 언어 설정
  • ko-KR 기본값
  • en-US
3Accept-EncodingN
응답 압축 방식
  • gzip
4X-PB-UserIDN
팝빌회원 아이디
Query 파라미터
순번 변수명 타입 길이 필수 설명
1TGstring-Y
접근 메뉴 (택 1)
  • TBOX 임시 문서함
  • PBOX 발행 문서함
  • WRITE 현금영수증 작성
요청 예시 
curl --request GET \
  --url 'https://{domain}/Cashbill?TG={TG}' \
  --header 'Authorization: Bearer {token}'

Response

응답 본문
순번 변수명 타입 길이 설명
1urlstring-
현금영수증 문서함 팝업 URL
응답 예시 
{
    "url": "https://test.popbill.com/App/API?T=IRXSGITDREOTPOIRLPUHCB4BSBC4...NX7BMAR3="
}