{"openapi":"3.0.3","info":{"title":"APICK 사업자 국세 통합 조회 인증 요청","version":"1.0.0","description":"사업자 국세 통합 자료를 조회하기 위한 인증 요청입니다. 사용자에게 간편인증을 요청하고, 결과 조회에 쓸 transactionId 를 바로 돌려줍니다. 요청 본문의 products 로 받을 조회를 고르며, 고른 조회만 실행하고 그 단가의 합으로 과금합니다."},"servers":[{"url":"https://apick.app"}],"paths":{"/rest/req_hometax_biz_bundle":{"post":{"summary":"사업자 국세 통합 조회 인증 요청","description":"사업자 국세 통합 자료를 조회하기 위한 인증 요청입니다. 사용자에게 간편인증을 요청하고, 결과 조회에 쓸 transactionId 를 바로 돌려줍니다. 요청 본문의 products 로 받을 조회를 고르며, 고른 조회만 실행하고 그 단가의 합으로 과금합니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"schemaVersion":{"type":"string","description":"결과 스키마 버전 (고정값: \"1.0\")"},"transactionId":{"type":"string","description":"결과 조회에 사용하는 트랜잭션 ID"},"product":{"type":"string","description":"조회 항목 코드. 결과조회에도 같은 값이 오므로 어느 항목의 결과인지 대조할 수 있습니다."},"status":{"type":"string","description":"처리 상태 (AUTH_REQUESTED: 인증 요청 완료)"},"resultAvailable":{"type":"boolean","description":"결과 데이터 포함 여부. 인증 요청 응답은 항상 false 입니다."},"charged":{"type":"boolean","description":"이번 호출의 과금 발생 여부. 실제 발송에 성공하면 true 입니다."},"sources":{"type":"array","items":{}},"message":{"type":"string","description":"상태 메시지 (고정값: \"인증 대기중입니다.\")"},"approvals":{"type":"integer","description":"사용자가 휴대폰에서 승인해야 하는 횟수. 같은 인증으로 처리되는 조회는 묶음이어도 1회입니다."},"expiresAt":{"type":"string","description":"인증 유효 기한(ISO 8601). 이 시각까지 승인하지 못하면 인증 실패 처리됩니다."},"success":{"type":"integer","description":"과금 여부0: 실패 또는 재사용(무과금)1: 발송 성공(과금)"}},"description":"인증 요청 결과"},"api":{"type":"object","properties":{"success":{"type":"boolean","description":"API 서버 정상 응답 여부"},"cost":{"type":"integer","description":"API 호출 요금"},"ms":{"type":"integer","description":"API 응답 시간"},"pl_id":{"type":"integer","description":"API 결제 로그 ID"}},"description":"API 호출 공통 데이터"}}}}}},"default":{"description":"HTTP 상태 및 서비스 오류코드 확인","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"조회 대상의 이름입니다. 개인 조회에서는 성명, 기업 조회에서는 법인명·상호를 뜻합니다. 같은 요청의 생년월일·전화번호 또는 사업자등록번호와 함께 확인하세요. (string)","example":"홍길동"},"birthDate":{"type":"string","description":"대상자의 생년월일 8자리입니다. 예: 19900101. 하이픈 없이 숫자만 보내며, 인증 대상자와 정확히 일치해야 합니다. (string)","example":"19900101"},"phone":{"type":"string","description":"본인 명의 휴대전화 번호입니다. 하이픈 없이 숫자만 입력하며, 인증 문자를 받을 수 있는 번호여야 합니다. (string)","example":"01011112222"},"authProvider":{"type":"string","description":"사용할 간편인증 수단의 식별자입니다. 예: kakao, naver, toss, pass. 지원 값은 이 문서의 간편인증 목록을 확인하세요. pass(통신사 PASS)를 고르면 telco(통신사 코드)를 반드시 함께 보냅니다. 가능한 값은 13가지입니다. kakao = kakao 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. naver = naver 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. toss = toss 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. pass = pass 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. samsung = samsung 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. kb = kb 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. shinhan = shinhan 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. hana = hana 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. woori = woori 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. ibk = ibk 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. nh = nh 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. kakaobank = kakaobank 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. banksalad = banksalad 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. (string)","enum":["kakao","naver","toss","pass","samsung","kb","shinhan","hana","woori","ibk","nh","kakaobank","banksalad"],"example":"kakao"},"telco":{"type":"string","description":"통신사 코드. authProvider=pass(통신사 PASS)일 때 필수이며, 빠지거나 허용값이 아니면 인증 요청 없이 400으로 거절합니다. S SKT·K KT·L LGU+·SA SKT알뜰폰·KA KT알뜰폰·LA LGU+알뜰폰 가능한 값은 6가지입니다. S = S 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. K = K 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. L = L 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. SA = SA 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. KA = KA 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. LA = LA 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. (string)","enum":["S","K","L","SA","KA","LA"]},"businessNo":{"type":"string","description":"사업자등록번호 10자리 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)","example":"1234567890"},"businessYear":{"type":"string","description":"사업자 매출·매입 조회 연도 4자리 (생략 시 최근) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"business_type":{"type":"string","description":"사업자 구분. corporate(법인)는 공동인증서가 필수, personal(개인)은 간편인증·공동인증서 모두 가능. 없으면 personal (string)"},"certificate_id":{"type":"string","description":"등록한 공동인증서 ID. 없으면 기본 인증서를 쓴다 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"auth_type":{"type":"string","description":"인증 방식. certificate(공동인증서) 또는 simple(간편인증). 없으면 business_type·certificate_id 로 정한다 (string)"},"cert_file":{"type":"string","description":"공동인증서 인증서 파일(signCert.der)을 base64 로 보낸다. key_file·cert_password 와 함께 보내면 인증서를 등록하지 않고 바로 인증하며, certificate_id 보다 우선한다 (string)"},"key_file":{"type":"string","description":"공동인증서 개인키 파일(signPri.key)을 base64 로 보낸다. cert_file 과 함께 보낸다 (string)"},"cert_password":{"type":"string","description":"공동인증서 비밀번호. 이번 인증에만 쓰고 보관하지 않는다 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"business_no":{"type":"string","description":"사업자등록번호 10자리 (숫자만) 문자열로 보내며, 빼거나 빈 값으로 보내면 요청이 거부됩니다. (string)","example":"1234567890"},"engl_yn":{"type":"string","description":"영문 증명 여부 (Y/N, 생략 시 N) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. 가능한 값은 2가지입니다. Y = 이 항목을 사용(포함)하는 경우입니다. N = 이 항목을 사용(포함)하지 않는 경우입니다. (string)","enum":["Y","N"]},"use_purpose":{"type":"string","description":"사용용도 코드 2자리 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)","example":"99"},"submit_to":{"type":"string","description":"제출처 코드 2자리 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)","example":"99"},"delivery":{"type":"string","description":"교부방법 (06 프린터·10 화면·04 팩스·12 전자문서지갑) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. 가능한 값은 4가지입니다. 06 = 06 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. 10 = 10 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. 04 = 04 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. 12 = 12 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. (string)","enum":["06","10","04","12"],"example":"06"},"quantity":{"type":"string","description":"발급 희망 수량 (1~5, 생략 시 1) 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다. (integer)"},"email":{"type":"string","description":"검증·발송할 이메일 주소입니다. @와 도메인을 포함한 전체 주소를 보내며, 형식이 맞지 않으면 조회 전에 거부됩니다. (string)"},"fax_no":{"type":"string","description":"팩스번호(팩스 발송 시 필수) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"wallet_address":{"type":"string","description":"전자문서지갑 주소(지갑 발급 시 필수) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"format":{"type":"string","description":"증명 응답 형식 (생략 시 both) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. 가능한 값은 3가지입니다. pdf = pdf 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. json = json 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. both = both 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. (string)","enum":["pdf","json","both"]},"year":{"type":"string","description":"증명·전자세금계산서 귀속연도 4자리 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)","example":"2025"},"period":{"type":"string","description":"부가가치세 과세기간 (1=1기·2=2기·all=연간) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. 가능한 값은 3가지입니다. 1 = 1 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. 2 = 2 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. all = all 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. (string)","enum":["1","2","all"]},"cert_type":{"type":"string","description":"납세증명서 종류 (서버 공통코드) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)","example":"B0006"},"start_month":{"type":"string","description":"조회 시작 월 (01~12) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"end_month":{"type":"string","description":"조회 종료 월 (01~12) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"itrf_cd":{"type":"string","description":"증명 발급 사유 코드 (서버 공통코드) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)","example":"10"},"issuance":{"type":"string","description":"증명 발급 구분 (서버 공통코드) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"from":{"type":"string","description":"조회 시작 연월입니다. YYYY-MM 형식(예: 1995-01)으로 보내며, 종료 연월보다 늦으면 빈 결과가 옵니다. (string)","example":"2025-01"},"to":{"type":"string","description":"조회 종료 연월입니다. YYYY-MM 형식(예: 2025-12)으로 보내며, 시작 연월보다 빠르면 빈 결과가 옵니다. (string)","example":"2025-12"},"bind_id":{"type":"string","description":"이전 사업자 조회 결과의 bind_id (같은 계정·같은 사업자등록번호, 90일 이내면 agreed 없이 접수) (string)"},"agreed":{"type":"string","description":"대표자 본인 확인 동의. bind_id 가 없으면 true 여야 접수되며, 빠지면 인증을 보내지 않고 무과금으로 거절 true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. (boolean)"},"keyword":{"type":"string","description":"거래처·품목 검색어 (선택) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"}},"required":["name","birthDate","phone","authProvider","business_no"]}}}}}}},"x-code-tables":[{"title":"공통 오류 응답","columns":["상황","확인할 값","대응"],"rows":[["인증키 누락·오류","api.success=false","Header Authorization: Bearer 를 확인하세요. 과금되지 않습니다."],["입력값 누락·형식 오류","오류 메시지에 어느 항목이 잘못됐는지 표시됩니다.","이름·생년월일·휴대전화번호·인증방식을 다시 확인하세요."],["조회 항목에 필요한 추가 입력 누락","오류 메시지에 필요한 입력 이름이 표시됩니다.","아래 요청 표의 추가 입력 항목을 채우세요."],["없는 transactionId · 만료된 요청","요청을 찾을 수 없다는 응답 또는 status AUTH_EXPIRED","인증요청부터 다시 하세요."],["처리 중 재요청","HTTP 424 · 요청 처리 중 또는 처리 잠금 획득 실패 · api.cost=0","같은 사용자·같은 조회 항목의 접수는 서버가 한 건씩 처리합니다. 앞선 요청이 끝난 뒤 같은 transactionId 로 다시 조회하세요."],["결과 재조회 기한 만료","errorCode=RESULT_EXPIRED","24시간이 지났습니다. 인증요청부터 다시 하세요."],["사용자 인증 거부","errorCode=AUTH_REJECTED","사용자에게 다시 시도할지 안내하세요. 과금되지 않습니다."],["정보 조회 실패","errorCode=COLLECT_FAILED · status FAILED","잠시 후 인증요청부터 다시 시도하세요. 결과 단가는 과금되지 않습니다."],["기관 서비스 점검·중지","errorCode=SERVICE_MAINTENANCE · maintenance=true · status FAILED","요청 오류가 아니므로 입력값을 고칠 필요가 없습니다. 점검이 끝난 뒤 인증요청부터 다시 시도하세요. 결과 단가는 과금되지 않습니다."],["보유 포인트 부족","호출 전 잔액 확인: HTTP 200 · result.error 에 사유 · api.cost=0결과를 청구하는 순간: HTTP 402 · data.error 에 사유 · api.cost=0","이 호출은 과금되지 않습니다. 결과조회도 호출할 때마다 그 상품의 결과 단가만큼 잔액을 확인합니다. 요금과 포인트를 확인한 뒤 충전하고, 결과조회는 같은 transactionId 로 다시 요청하세요."],["처리 시간 초과","HTTP 408 · data.success=3","서버가 제한 시간 안에 끝내지 못했습니다. 과금되지 않습니다. 잠시 후 같은 요청을 다시 보내세요."]]},{"title":"상태와 성공 판정","columns":["필드","의미","판단 기준"],"rows":[["HTTP 상태 코드","전송 계층의 결과","200 이 정상, 402 는 포인트 부족, 408 은 처리 시간 초과, 424 는 동일 요청 처리 중. 성공 판정에 쓰지 마세요."],["api.success","APICK 서버가 요청을 정상 처리했는지","포인트 부족(402)이나 시간 초과(408)에도 true 입니다. 업무 성공 판정에 쓰지 마세요."],["data.status","조회 진행 상태","AUTH_WAITING(승인 대기) · AUTH_COMPLETED · COLLECTING(조회 중) · SUCCESS(완료) · FAILED · AUTH_EXPIRED · AUTH_REJECTED · PARTIAL_SUCCESS. resultAvailable=true이면 결과를 사용하세요. RESULT_EXPIRED는 errorCode입니다."],["data.resultAvailable","지금 응답에 쓸 수 있는 결과가 들어 있는지","true 이면 폴링을 멈추고 result 를 사용하세요. false는 대기 또는 종료 상태일 수 있으므로 status를 함께 확인하세요."],["data.success","이 응답이 결과 제공 응답인지 (1/0)","새 유료 결과 제공에서는 1, 무료 재조회에서는 0일 수 있습니다. 결과 유무는 resultAvailable로 판단하세요. 처리 시간 초과(408)에서는 3 이 오므로 \"1 인지\"로 비교하세요."],["data.charged · api.cost","이번 호출의 과금 여부·금액","과금 회계 확인용입니다. 성공 판정에 쓰지 마세요."]]}],"x-service-errors":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}