콘텐츠로 이동

정보확인

1. GetInfo - 상태 확인

섹션 제목: “1. GetInfo - 상태 확인”
GET https://popbill-test.linkhub.co.kr/Taxinvoice/{MgtKeyType}/{MgtKey}
  • 세금계산서 1건의 상태 및 요약정보를 확인합니다.
  • 리턴값 stateCode를 통해 세금계산서의 상태코드를 확인합니다. [참고] 팝빌 상태코드

Request

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

Response

응답 본문
순번 변수명 타입 길이 설명
1itemKeystring18
팝빌에서 할당한 식별번호
2taxTypestring2
과세형태
  • 과세
  • 영세
  • 면세
3writeDatestring8
작성일자
형식 : yyyyMMdd
4regDTstring14
임시저장 일시
형식 : yyyyMMddHHmmss
5issueTypestring3
발행형태
  • 정발행
  • 역발행
  • 위수탁
6supplyCostTotalstring18
공급가액 합계
정수만 입력 가능
마이너스 금액 입력 가능, 소수점 아래 자동 절사
7taxTotalstring18
세액 합계
정수만 입력 가능
마이너스 금액 입력 가능, 소수점 아래 자동 절사
8purposeTypestring2
영수/청구
  • 영수
  • 청구
  • 없음
9issueDTstring14
발행일시
형식 : yyyyMMddHHmmss
10lateIssueYNboolean-
지연발행 여부
  • true 지연발행
  • false 정상발행
11openYNboolean-
개봉 여부
  • true 개봉
  • false 미개봉
{issueType}="정발행" or "위수탁" 경우 공급받는자가 세금계산서 보기 버튼을 클릭한 경우 개봉 처리
{issueType}="역발행" 경우 공급자가 세금계산서 보기 버튼을 클릭한 경우 개봉 처리
12openDTstring14
개봉일시
형식 : yyyyMMddHHmmss
13stateMemostring200
상태메모
14stateCodestring3
상태코드
[참고] 팝빌 상태코드
15stateDTstring14
상태 변경일시
형식 : yyyyMMddHHmmss
16ntsconfirmNumstring18
국세청승인번호
전자세금계산서 발행 시점에 팝빌에서 자동으로 할당
17ntsresultstring6
국세청 전송결과
18ntssendDTstring14
국세청 전송일시
형식 : yyyyMMddHHmmss
19ntsresultDTstring14
국세청 결과 수신일시
형식 : yyyyMMddHHmmss
20ntssendErrCodestring6
국세청 결과코드
[참고] 국세청 결과코드
21modifyCodenumber1
수정세금계산서 발행시 입력한 사유코드
[참고] 수정세금계산서
22interOPYNboolean-
연동문서 여부
  • true API를 통해 발행한 연동문서
  • false 팝빌 사이트를 통해 발행한 문서
23invoicerCorpNamestring200
공급자 상호
24invoicerCorpNumstring10
공급자 사업자번호
25invoicerMgtKeystring24
공급자 문서번호
파트너가 할당한 문서번호
26invoicerPrintYNboolean-
공급자 인쇄여부
  • true 인쇄
  • false 미인쇄
27invoiceeCorpNamestring200
공급받는자 상호
28invoiceeCorpNumstring13
공급받는자 사업자번호
29invoiceeMgtKeystring24
공급받는자 문서번호
파트너가 할당한 문서번호
30invoiceePrintYNboolean-
공급받는자 인쇄여부
  • true 인쇄
  • false 미인쇄
31closeDownStatenumber1
공급받는자 휴폐업상태
  • null 미확인
  • 0 미등록
  • 1 사업중
  • 2 폐업
  • 3 휴업
  • 4 확인실패
32closeDownStateDatestring8
공급받는자 휴폐업일자
형식 : yyyyMMdd
33trusteeCorpNamestring200
수탁자 상호
34trusteeCorpNumstring10
수탁자 사업자번호
35trusteeMgtKeystring24
수탁자 문서번호
파트너가 할당한 문서번호
36trusteePrintYNboolean-
수탁자 인쇄여부
  • true 인쇄
  • 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"
}

2. GetInfos - 다수건 상태 확인

섹션 제목: “2. GetInfos - 다수건 상태 확인”
POST https://popbill-test.linkhub.co.kr/Taxinvoice/{MgtKeyType}
  • 다수건의 세금계산서 상태 및 요약 정보를 확인합니다. (1회 호출에 최대 1,000건 확인 가능)
  • 리턴값의 변수 stateCode를 통해 세금계산서의 상태코드를 확인합니다. [참고] 팝빌 상태코드

문서번호를 통해 세금계산서 목록을 구현하는 경우 활용합니다.

Request

요청 헤더
순번 변수명 필수 설명
1AuthorizationY
인증 토큰
[참고] 인증 및 헤더 설정
2Accept-LanguageN
응답 언어 설정
  • ko-KR 기본값
  • en-US
3Accept-EncodingN
응답 압축 방식
  • gzip
4X-PB-UserIDN
팝빌회원 아이디
Path 파라미터
순번 변수명 타입 길이 필수 설명
1MgtKeyTypestring-Y
문서번호 유형 (택 1)
  • SELL 매출
  • BUY 매입
  • TRUSTEE 위수탁
요청 본문
순번 변수명 타입 길이 필수 설명
1-array1,000Y
문서번호 목록
최대 : 1,000건
요청 예시 
curl --request POST \
  --url 'https://{domain}/Taxinvoice/{MgtKeyType}' \
  --header 'Authorization: Bearer {token}' \
  --data '["TEST0001", "TEST0002"]'

Response

응답 본문
순번 변수명 타입 길이 설명
1itemKeystring18
팝빌에서 할당한 식별번호
2taxTypestring2
과세형태
  • 과세
  • 영세
  • 면세
3writeDatestring8
작성일자
형식 : yyyyMMdd
4regDTstring14
임시저장 일시
형식 : yyyyMMddHHmmss
5issueTypestring3
발행형태
  • 정발행
  • 역발행
  • 위수탁
6supplyCostTotalstring18
공급가액 합계
정수만 입력 가능
마이너스 금액 입력 가능, 소수점 아래 자동 절사
7taxTotalstring18
세액 합계
정수만 입력 가능
마이너스 금액 입력 가능, 소수점 아래 자동 절사
8purposeTypestring2
영수/청구
  • 영수
  • 청구
  • 없음
9issueDTstring14
발행일시
형식 : yyyyMMddHHmmss
10lateIssueYNboolean-
지연발행 여부
  • true 지연발행
  • false 정상발행
11openYNboolean-
개봉 여부
  • true 개봉
  • false 미개봉
{issueType}="정발행" or "위수탁" 경우 공급받는자가 세금계산서 보기 버튼을 클릭한 경우 개봉 처리
{issueType}="역발행" 경우 공급자가 세금계산서 보기 버튼을 클릭한 경우 개봉 처리
12openDTstring14
개봉일시
형식 : yyyyMMddHHmmss
13stateMemostring200
상태메모
14stateCodestring3
상태코드
[참고] 팝빌 상태코드
15stateDTstring14
상태 변경일시
형식 : yyyyMMddHHmmss
16ntsconfirmNumstring18
국세청승인번호
전자세금계산서 발행 시점에 팝빌에서 자동으로 할당
17ntsresultstring6
국세청 전송결과
18ntssendDTstring14
국세청 전송일시
형식 : yyyyMMddHHmmss
19ntsresultDTstring14
국세청 결과 수신일시
형식 : yyyyMMddHHmmss
20ntssendErrCodestring6
국세청 결과코드
[참고] 국세청 결과코드
21modifyCodenumber1
수정세금계산서 발행시 입력한 사유코드
[참고] 수정세금계산서
22interOPYNboolean-
연동문서 여부
  • true API를 통해 발행한 연동문서
  • false 팝빌 사이트를 통해 발행한 문서
23invoicerCorpNamestring200
공급자 상호
24invoicerCorpNumstring10
공급자 사업자번호
25invoicerMgtKeystring24
공급자 문서번호
파트너가 할당한 문서번호
26invoicerPrintYNboolean-
공급자 인쇄여부
  • true 인쇄
  • false 미인쇄
27invoiceeCorpNamestring200
공급받는자 상호
28invoiceeCorpNumstring13
공급받는자 사업자번호
29invoiceeMgtKeystring24
공급받는자 문서번호
파트너가 할당한 문서번호
30invoiceePrintYNboolean-
공급받는자 인쇄여부
  • true 인쇄
  • false 미인쇄
31closeDownStatenumber1
공급받는자 휴폐업상태
  • null 미확인
  • 0 미등록
  • 1 사업중
  • 2 폐업
  • 3 휴업
  • 4 확인실패
32closeDownStateDatestring8
공급받는자 휴폐업일자
형식 : yyyyMMdd
33trusteeCorpNamestring200
수탁자 상호
34trusteeCorpNumstring10
수탁자 사업자번호
35trusteeMgtKeystring24
수탁자 문서번호
파트너가 할당한 문서번호
36trusteePrintYNboolean-
수탁자 인쇄여부
  • true 인쇄
  • 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 - 상세정보 확인

섹션 제목: “3. GetDetailInfo - 상세정보 확인”
GET https://popbill-test.linkhub.co.kr/Taxinvoice/{MgtKeyType}/{MgtKey}
  • 세금계산서 1건의 상세정보를 확인합니다.

Request

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

Response

응답 본문
순번 변수명 타입 길이 설명
1ntsconfirmNumstring24
국세청승인번호
전자세금계산서 발행 시점에 팝빌에서 자동으로 할당
2issueTypestring3
발행형태
  • 정발행
  • 역발행
  • 위수탁
3taxTypestring2
과세형태
  • 과세
  • 영세
  • 면세
4chargeDirectionstring3
과금방향
  • 정과금 공급자 과금
  • 역과금 공급받는자 과금
5serialNumstring30
일련번호
6kwonnumber4
책번호 "권" 항목
7honumber4
책번호 "호" 항목
8writeDatestring8
작성일자
형식 : yyyyMMdd
9purposeTypestring2
영수/청구
  • 영수
  • 청구
  • 없음
10supplyCostTotalstring18
공급가액 합계
11taxTotalstring18
세액 합계
12totalAmountstring18
합계금액
13cashstring18
현금
14chkBillstring18
수표
15creditstring18
외상
16notestring18
어음
17remark1string150
비고1
{invoiceeType}="외국인"
경우 외국인등록번호 또는 여권번호 필수 입력
18remark2string150
비고2
19remark3string150
비고3
20invoicerMgtKeystring24
공급자 문서번호
문서 관리를 위해 파트너가 할당하는 고유 식별번호
21invoicerCorpNumstring10
공급자 사업자번호
22invoicerTaxRegIDstring4
공급자 종사업장 식별번호
23invoicerCorpNamestring200
공급자 상호
24invoicerCEONamestring100
공급자 대표자 성명
25invoicerAddrstring300
공급자 주소
26invoicerBizTypestring100
공급자 업태
27invoicerBizClassstring100
공급자 종목
28invoicerContactNamestring100
공급자 담당자 성명
29invoicerDeptNamestring100
공급자 담당자 부서명
30invoicerTELstring20
공급자 담당자 연락처
31invoicerHPstring20
공급자 담당자 휴대폰
32invoicerEmailstring100
공급자 담당자 메일
33invoicerSMSSendYNboolean-
공급자 알림문자 전송 여부
  • true 전송
  • false 미전송
수신자 : 공급받는자 휴대폰번호 {invoiceeHP1}
34invoiceeMgtKeystring24
공급받는자 문서번호
문서 관리를 위해 파트너가 할당하는 고유 식별번호
35invoiceeTypestring3
공급받는자 유형
  • 사업자
  • 개인
  • 외국인
36invoiceeCorpNumstring13
공급받는자 등록번호
{invoiceeType}="사업자" 경우 사업자번호
{invoiceeType}="개인" 경우 주민등록번호
{invoiceeType}="외국인" 경우 "9999999999999"
37invoiceeTaxRegIDstring4
공급받는자 종사업장 식별번호
38invoiceeCorpNamestring200
공급받는자 상호
39invoiceeCEONamestring100
공급받는자 대표자 성명
40invoiceeAddrstring300
공급받는자 주소
41invoiceeBizTypestring100
공급받는자 업태
42invoiceeBizClassstring100
공급받는자 종목
43closeDownStatenumber1
공급받는자 휴폐업상태
  • null 미확인
  • 0 미등록
  • 1 사업중
  • 2 폐업
  • 3 휴업
  • 4 확인실패
세금계산서 발행시 거래처 사업자등록 상태를 조회하여 결과값 반환
44closeDownStateDatestring8
공급받는자 휴폐업일자
형식 : yyyyMMdd
45invoiceeContactName1string100
공급받는자 담당자 성명
46invoiceeDeptName1string100
공급받는자 담당자 부서명
47invoiceeTEL1string20
공급받는자 담당자 연락처
48invoiceeHP1string20
공급받는자 담당자 휴대폰
49invoiceeEmail1string100
공급받는자 담당자 메일
50invoiceeSMSSendYNboolean-
공급받는자 알림문자 전송 여부
  • true 전송
  • false 미전송
수신자 : 공급자 휴대폰번호 {invoicerHP}
51trusteeMgtKeystring24
수탁자 문서번호
수탁자의 문서 관리를 위해 파트너가 할당하는 식별번호
52trusteeCorpNumstring10
수탁자 사업자번호
53trusteeTaxRegIDstring4
수탁자 종사업장 식별번호
54trusteeCorpNamestring200
수탁자 상호
55trusteeCEONamestring100
수탁자 대표자 성명
56trusteeAddrstring300
수탁자 주소
57trusteeBizTypestring100
수탁자 업태
58trusteeBizClassstring100
수탁자 종목
59trusteeContactNamestring100
수탁자 담당자 성명
60trusteeDeptNamestring100
수탁자 담당자 부서명
61trusteeTELstring20
수탁자 담당자 연락처
62trusteeHPstring20
수탁자 담당자 휴대폰
63trusteeEmailstring100
수탁자 담당자 메일
64trusteeSMSSendYNboolean-
수탁자 알림문자 전송 여부
  • true 전송
  • false 미전송
수신자 : 공급받는자 휴대폰번호 {invoiceeHP1}
65modifyCodenumber1
수정 사유코드
수정세금계산서 작성시 필수 [참고] 수정세금계산서
66orgNTSConfirmNumstring24
당초 국세청승인번호
수정세금계산서 작성시 반환
67businessLicenseYNboolean-
팝빌에 등록된 사업자등록증 첨부 여부
  • true 첨부
  • false 미첨부
68bankBookYNboolean-
팝빌에 등록된 통장사본 첨부 여부
  • true 첨부
  • false 미첨부
69array-
품목 상세정보
최대 : 99개
detailList
순번변수명타입길이설명
1serialNumnumber2
일련번호
2purchaseDTstring8
거래일자
형식 : yyyyMMdd
3itemNamestring100
품명
4specstring60
규격
5qtystring12
수량
-99999999.99 ~ 999999999.99
소수점 아래 2번째 자리까지 입력 가능
6unitCoststring18
단가
-99999999999999.99 ~ 999999999999999.99
소수점 아래 2번째 자리까지 입력 가능
7supplyCoststring18
공급가액
정수만 입력 가능
마이너스 금액 입력 가능, 소수점 자동 절사
8taxstring18
세액
정수만 입력 가능
마이너스 금액 입력 가능, 소수점 자동 절사
9remarkstring100
비고
70array-
공급받는자 추가담당자 정보
최대 : 5명
addContactList
순번변수명타입길이설명
1serialNumnumber1
일련번호
2contactNamestring100
담당자 성명
3emailstring100
메일
응답 예시 
{
    "writeSpecification": false,
    "writeDate": "20251016",
    "chargeDirection": "정과금",
    "issueType": "정발행",
    "issueTiming": "직접발행",
    "taxType": "과세",
    "invoicerCorpNum": "1234567890",
    "invoicerMgtKey": "MKGTKEY-0002",
    "invoicerTaxRegID": "0001",
    "invoicerCorpName": "공급자 상호",
    "invoicerCEOName": "공급자 대표자 성명",
    "invoicerAddr": "공급자 주소",
    "invoicerBizClass": "공급자 종목",
    "invoicerBizType": "공급자 업태",
    "invoicerContactName": "공급자 담당자 성명",
    "invoicerDeptName": "공급자 담당자 부서명",
    "invoicerTEL": "010-1234-5678",
    "invoicerHP": "010-1234-5678",
    "invoicerEmail": "test@test.com",
    "invoicerSMSSendYN": false,
    "invoiceeCorpNum": "1234567890",
    "invoiceeType": "사업자",
    "invoiceeTaxRegID": "0001",
    "invoiceeCorpName": "공급받는자 상호",
    "invoiceeCEOName": "공급받는자 대표자 성명",
    "invoiceeAddr": "공급받는자 주소",
    "invoiceeBizType": "공급받는자 업태",
    "invoiceeBizClass": "공급받는자 종목",
    "invoiceeContactName1": "공급받는자 담당자 성명",
    "invoiceeDeptName1": "공급받는자 담당자 부서명",
    "invoiceeTEL1": "010-1234-5678",
    "invoiceeHP1": "010-1234-5678",
    "invoiceeEmail1": "test@test.com",
    "invoiceeSMSSendYN": false,
    "trusteeSMSSendYN": false,
    "taxTotal": "1000",
    "supplyCostTotal": "10000",
    "totalAmount": "11000",
    "purposeType": "영수",
    "businessLicenseYN": false,
    "bankBookYN": false,
    "faxsendYN": false,
    "ntsconfirmNum": "202510168888888800000002",
    "detailList": [
        {
            "serialNum": 1,
            "purchaseDT": "20251016",
            "itemName": "품명",
            "spec": "규격",
            "qty": "1",
            "unitCost": "10000",
            "supplyCost": "10000",
            "tax": "1000",
            "remark": "비고"
        }
    ],
    "addContactList": [
      {
        "serialNum": 1,
        "contactName": "담당자 성명",
        "email": "test@test.com"
      }
    ],
    "closeDownState": 0
}

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

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

Request

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

Response

응답 본문
순번 변수명 타입 길이 설명
1itemKeystring18
팝빌에서 할당한 식별번호
응답 예시 
{
    "itemKey": "025102114360700001"
}

5. GetXML - 상세정보 확인(XML)

섹션 제목: “5. GetXML - 상세정보 확인(XML)”
GET https://popbill-test.linkhub.co.kr/Taxinvoice/{MgtKeyType}/{MgtKey}
  • 세금계산서 1건의 상세정보를 XML로 반환합니다.

Request

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

Response

응답 본문
순번 변수명 타입 길이 설명
1codenumber-
API 처리에 대한 응답코드
  • 1 성공
2messagestring-
API 처리에 대한 응답메시지
3retObjectstring-
전자세금계산서 XML 문서
응답 예시 
{
    "code": 1,
    "message": "확인완료",
    "retObject": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?>\n<TaxInvoice..."
}
섹션 제목: “6. Search - 목록 조회”
GET https://popbill-test.linkhub.co.kr/Taxinvoice/{MgtKeyType}
  • 검색조건에 해당하는 세금계산서를 조회합니다. (최대 조회기간 : 6개월)

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

Request

요청 헤더
순번 변수명 필수 설명
1AuthorizationY
인증 토큰
[참고] 인증 및 헤더 설정
2Accept-LanguageN
응답 언어 설정
  • ko-KR 기본값
  • en-US
3Accept-EncodingN
응답 압축 방식
  • gzip
4X-PB-UserIDN
팝빌회원 아이디
Path 파라미터
순번 변수명 타입 길이 필수 설명
1MgtKeyTypestring-Y
문서번호 유형 (택 1)
  • SELL 매출
  • BUY 매입
  • TRUSTEE 위수탁
Query 파라미터
순번 변수명 타입 길이 필수 설명
1DTypestring1Y
검색일자 유형 (택 1)
  • R 등록일자
  • W 작성일자
  • I 발행일자
2SDatestring8Y
검색 시작일자
형식 : yyyyMMdd
3EDatestring8Y
검색 종료일자
형식 : yyyyMMdd
4Statestring-N
세금계산서 상태코드
2, 3번째 자리에 와일드카드(*) 사용가능. 예) 3**,60* [참고] 팝빌 상태코드
기본값 : 전체조회
5Typestring-N
세금계산서 문서 유형 (다중 선택 가능)
  • N 세금계산서
  • M 수정세금계산서
다중 선택시 콤마(',')로 구분. 예) N,M
기본값 : 전체조회
6TaxTypestring-N
과세형태 (다중 선택 가능)
  • T 과세
  • N 면세
  • Z 영세
다중 선택시 콤마(',')로 구분. 예) T,N
기본값 : 전체조회
7IssueTypestring-N
발행형태 (다중 선택 가능)
  • N 정발행
  • R 역발행
  • T 위수탁
다중 선택시 콤마(',')로 구분. 예) N,R
기본값 : 전체조회
8LateOnlyboolean-N
지연발행 여부
  • true 지연발행
  • false 정상발행
기본값 : 전체조회
9TaxRegIDTypestring1N
종사업장번호의 주체 (택 1)
  • S 공급자
  • B 공급받는자
  • T 수탁자
기본값 : 전체조회
10TaxRegIDstring-N
종사업장번호
다수건 검색시 콤마(',')로 구분. 예) 1234,1000
기본값 : 전체조회
11TaxRegIDYNstring1N
종사업장번호 유무
  • 0 없음
  • 1 있음
기본값 : 전체조회
12QStringstring-N
조회 검색어 ('-' 제외)
상호명 조회시 거래처상호 입력
사업자 조회시 사업자번호 입력
개인 조회시 주민등록번호 입력
외국인 조회시 "9999999999999" 입력
기본값 : 전체조회
13Pagenumber-N
목록 페이지번호
기본값 : 1
14PerPagenumber-N
페이지당 표시할 목록 건수
최대 : 1,000건
기본값 : 500건
15Orderstring1N
조회 기준일자 유형을 기준으로 하는 목록 정렬 방향
  • D 내림차순 : 기본값
  • A 오름차순
16InterOPYNstring1N
세금계산서 작성유형
  • 0 팝빌 사이트를 통해 작성한 세금계산서
  • 1 API로 작성한 세금계산서
기본값 : 전체조회
17RegTypestring-N
전자세금계산서 등록 유형 (다중 선택 가능)
  • P 팝빌에서 등록(발행)
  • H 홈택스 또는 ASP에서 등록(발행)
다중 선택시 콤마(',')로 구분. 예) P,H
기본값 : 전체조회
18CloseDownStatestring-N
휴폐업상태 (다중 선택 가능)
  • N 미확인
  • 0 미등록
  • 1 사업중
  • 2 폐업
  • 3 휴업
  • 4 확인실패
다중 선택시 콤마(',')로 구분. 예) N,0
기본값 : 전체조회
19MgtKeystring-N
문서번호
세금계산서의 문서번호 또는 국세청승인번호 중 검색하고자 하는 정보 입력
기본값 : 전체조회
요청 예시 
curl --request GET \
  --url 'https://{domain}/Taxinvoice/{MgtKeyType}?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
팝빌에서 할당한 식별번호
2taxTypestring2
과세형태
  • 과세
  • 영세
  • 면세
3writeDatestring8
작성일자
형식 : yyyyMMdd
4regDTstring14
임시저장 일시
형식 : yyyyMMddHHmmss
5issueTypestring3
발행형태
  • 정발행
  • 역발행
  • 위수탁
6supplyCostTotalstring18
공급가액 합계
정수만 입력 가능
마이너스 금액 입력 가능, 소수점 아래 자동 절사
7taxTotalstring18
세액 합계
정수만 입력 가능
마이너스 금액 입력 가능, 소수점 아래 자동 절사
8purposeTypestring2
영수/청구
  • 영수
  • 청구
  • 없음
9issueDTstring14
발행일시
형식 : yyyyMMddHHmmss
10lateIssueYNboolean-
지연발행 여부
  • true 지연발행
  • false 정상발행
11openYNboolean-
개봉 여부
  • true 개봉
  • false 미개봉
{issueType}="정발행" or "위수탁" 경우 공급받는자가 세금계산서 보기 버튼을 클릭한 경우 개봉 처리
{issueType}="역발행" 경우 공급자가 세금계산서 보기 버튼을 클릭한 경우 개봉 처리
12openDTstring14
개봉일시
형식 : yyyyMMddHHmmss
13stateMemostring200
상태메모
14stateCodestring3
상태코드
[참고] 팝빌 상태코드
15stateDTstring14
상태 변경일시
형식 : yyyyMMddHHmmss
16ntsconfirmNumstring18
국세청승인번호
전자세금계산서 발행 시점에 팝빌에서 자동으로 할당
17ntsresultstring6
국세청 전송결과
18ntssendDTstring14
국세청 전송일시
형식 : yyyyMMddHHmmss
19ntsresultDTstring14
국세청 결과 수신일시
형식 : yyyyMMddHHmmss
20ntssendErrCodestring6
국세청 결과코드
[참고] 국세청 결과코드
21modifyCodenumber1
수정세금계산서 발행시 입력한 사유코드
[참고] 수정세금계산서
22interOPYNboolean-
연동문서 여부
  • true API를 통해 발행한 연동문서
  • false 팝빌 사이트를 통해 발행한 문서
23invoicerCorpNamestring200
공급자 상호
24invoicerCorpNumstring10
공급자 사업자번호
25invoicerMgtKeystring24
공급자 문서번호
파트너가 할당한 문서번호
26invoicerPrintYNboolean-
공급자 인쇄여부
  • true 인쇄
  • false 미인쇄
27invoiceeCorpNamestring200
공급받는자 상호
28invoiceeCorpNumstring13
공급받는자 사업자번호
29invoiceeMgtKeystring24
공급받는자 문서번호
파트너가 할당한 문서번호
30invoiceePrintYNboolean-
공급받는자 인쇄여부
  • true 인쇄
  • false 미인쇄
31closeDownStatenumber1
공급받는자 휴폐업상태
  • null 미확인
  • 0 미등록
  • 1 사업중
  • 2 폐업
  • 3 휴업
  • 4 확인실패
32closeDownStateDatestring8
공급받는자 휴폐업일자
형식 : yyyyMMdd
33trusteeCorpNamestring200
수탁자 상호
34trusteeCorpNumstring10
수탁자 사업자번호
35trusteeMgtKeystring24
수탁자 문서번호
파트너가 할당한 문서번호
36trusteePrintYNboolean-
수탁자 인쇄여부
  • true 인쇄
  • false 미인쇄
응답 예시 
{
    "code": 1,
    "total": 14,
    "perPage": 500,
    "pageNum": 1,
    "pageCount": 1,
    "list": [
        {
            "invoicerPrintYN": false,
            "invoiceeCorpName": "공급받는자 상호",
            "invoiceePrintYN": false,
            "trusteePrintYN": false,
            "taxTotal": "10000",
            "supplyCostTotal": "100000",
            "lateIssueYN": false,
            "stateCode": 100,
            "taxType": "과세",
            "purposeType": "영수",
            "itemKey": "025102220380000001",
            "interOPYN": true,
            "writeDate": "20251022",
            "issueType": "정발행",
            "openYN": false,
            "invoicerCorpNum": "1234567890",
            "invoicerMgtKey": "20251022-10",
            "invoicerCorpName": "공급자 상호",
            "invoiceeCorpNum": "8888888888",
            "regDT": "20251022203801",
            "stateDT": "20251022203801"
        }
    ],
    "message": "검색 완료"
}

7. GetLogs - 상태 변경이력 확인

섹션 제목: “7. GetLogs - 상태 변경이력 확인”
GET https://popbill-test.linkhub.co.kr/Taxinvoice/{MgtKeyType}/{MgtKey}/Logs
  • 세금계산서의 상태에 대한 변경이력을 확인합니다.

Request

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

Response

응답 본문
순번 변수명 타입 길이 설명
1docLogTypenumber3
로그타입
  • 100 임시저장
  • 101 수정
  • 102 개봉
  • 103 수신확인
  • 111 메일 재전송
  • 112 문자 재전송
  • 113 팩스 재전송
  • 122 문자 전송결과
  • 123 팩스 전송결과
  • 124 사업자등록상태 확인
  • 125 문서번호 할당
  • 220 역발행요청
  • 221 역발행요청 거부
  • 222 역발행요청 취소
  • 230 발행
  • 240 발행취소
  • 250 국세청전송 요청
  • 251 국세청전송 대기중
  • 252 국세청전송 진행중
  • 253 국세청전송 접수
  • 254 국세청전송 성공
  • 255 국세청전송 실패
2logstring2000
이력정보
3procTypestring3
처리형태
  • 연동 API를 통해 처리함
  • 일반 팝빌 사이트를 통해 처리함
  • 시스템 팝빌이 처리함
4procCorpNamestring70
처리회사명
5procContactNamestring30
처리담당자
6procMemostring200
처리메모
7regDTstring14
등록일시
형식 : yyyyMMddHHmmss
8ipstring39
아이피
응답 예시 
[
    {
        "ip": "192.***.*.104",
        "log": "임시저장 되었습니다.",
        "regDT": "20251021143608",
        "docLogType": 100,
        "procType": "연동",
        "procCorpName": "회사명",
        "procContactName": "담당자 성명2"
    }
]

8. GetURL - 문서함 팝업 URL

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

문서함 팝업 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 임시 문서함
  • SWBOX 매출 발행 대기함
  • SBOX 매출 문서함
  • PWBOX 매입 발행 대기함
  • PBOX 매입 문서함
  • WRITE 정발행 작성
요청 예시 
curl --request GET \
  --url 'https://{domain}/Taxinvoice?TG={TG}' \
  --header 'Authorization: Bearer {token}'

Response

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