{"swagger":"2.0","info":{"description":"## CHANGELOG\n\n### v1.1 (05.31):\n\n* 요청항목 (request body):\n * 진위확인: 선택 항목 `사업장주소(b_adr)` 추가\n * 페이지 하단의 **Model -> 사업자등록정보 진위확인 API Request** 참고\n * 상태확인: 변경사항 없음.\n* 응답항목 (response):\n * 진위확인&상태조회: `직전과세유형메세지 명칭 및 코드 (rbf_tax_type, rbf_tax_type_cd)` 추가\n * 페이지 하단의 **Model -> 사업자등록 상태조회 결과** 참고\n \n\n## 설명 \n\n* 국세청에서 제공하는 사업자등록정보 진위확인 및 사업자등록 상태조회 API 서비스입니다.\n\n* 1회 호출 시 최대 100개에 해당하는 사업자등록정보의 진위확인 또는 사업자등록 상태조회가 가능합니다.\n * 100개 초과 시에는 Too Large Request Error 가 발생합니다. (* 하단의 Too Large Request Error 부분을 참고해주세요)\n\n* 삭제된 사업자등록정보는 조회되지 않으며, 해당 정보를 요청시에는 아래와 같은 메세지가 return됩니다:\n * 진위확인: '확인할 수 없습니다'\n * 상태조회: '국세청에 등록되지 않은 사업자등록번호입니다'\n\n* Response Return Type: JSON/XML 두가지 형태로 제공되며, 아래와 같이 Request Param 형태로 호출하면\n됩니다:\n * JSON : `returnType=JSON` (Default: 넣지 않을 경우, 자동으로 JSON 으로 설정됩니다)\n * XML : `returnType=XML`\n * 예) 진위확인 서비스 response를 XML로 받을 경우: `http://api.odcloud.kr/api/nts-businessman/v1/validate?serviceKey=[서비스키]&returnType=XML`\n\n## API 호출 시의 주의사항\n\n * `GET` METHOD가 아닌 `POST` METHOD 로만 제공됩니다.\n * `serviceKey` 및 `returnType` 은 URL 에 querystring 으로 넣어주셔야 합니다.\n * 그 외 `b_no` 등의 JSON string은 반드시 `body`로 넣어 호출해주세요.\n * 호출 시도중 에러 발생 시, 에러 종류에 따라 status code가 400,411,413,500 으로 반환되며, 에러 발생시에도 response에 오류 메세지가 return됩니다. 자세한 내용은 각 API를 클릭하여 하단의 response 부분을 참고해주세요.\n \n\n* API 별 request 및 response 정보는 하단의 `API 별 request/response 샘플` 또는 페이지 최하단의\n`Models` 부분을 확인하시면 됩니다.\n\n## API 요청항목별 유의사항\n\n | API | 항목 | 내용 |\n | --- | ---- | ---- |\n |진위확인| 공통 | 요청항목이 전부 일치하는 경우, 해당 사업자에 대해 상태조회 API 호출 시의 결과가 return |\n || | 필수가 아닌 항목을 빈값으로 검색해야할 경우, 아래와 같이 empty string(\"\")으로 JSON에 포함되어야 합니다.
예) 대표자성명2(p_nm2)를 빈값으로 호출해야할 경우,
{
...,
\"p_nm2\": \"\",
...
}|\n || 사업자등록번호(필수) | 숫자로 이루어진 10자리 값만 가능 ('-' 등의 기호 반드시 제거 후 호출) |\n || 대표자성명(필수) | 외국인 사업자의 경우에는 영문명 입력 |\n || 개업일자(필수) | 1) YYYYMMDD 포맷의 날짜로 입력('-' 등의 기호 반드시 제거 후 호출)
2) 사업자등록증에 표기된 개업연월일 날짜로 입력|\n || 대표자성명2 | 외국인 사업자의 경우에만 한글명칭으로 입력(공동대표자명 입력 x)
*외국인 사업자가 아닌 경우 해당 항목 및 값을 추가하시면 진위확인이 되지 않습니다. |\n || 상호 | 1) 상호가 주식회사인 경우, 아래의 단어에 대해서는 상호의 맨 앞 또는 맨 뒤에 붙어도 동일하게 검색 가능
- (주)
- 주식회사
- （주）--> 'ㄴ' 으로 한자키 입력을 통한 특수문자 괄호
2) 앞뒤 공백(empty space) 무시하고 검색 |\n || 법인등록번호 | 숫자로 이루어진 13자리 값만 가능 ('-' 등의 기호 반드시 제거 후 호출) |\n || 주업태명 | 1) 모든 공백(앞뒤 포함)에 대해 무시하고 검색됨
예) '서 비 스' -> '서비스' 로 검색됨\" |\n || 주종목명 | 1) 모든 공백(앞뒤 포함)에 대해 무시하고 검색됨 (주업태명과 동일) |\n || 사업장주소 | 모든 공백(앞뒤 포함)에 대해 무시하고 검색됨
(예시: 서울특별시 강남구, 경기도 부천시)\n | 상태조회 | 사업자등록번호(필수) | 숫자로 이루어진 10자리 값만 가능 ('-' 등의 기호 반드시 제거 후 호출) |
\n \n## 상태조회 샘플코드 (jquery ajax method 사용)\n\n ```json\n var data = {\n \"b_no\": [\"xxxxxxx\"] // 사업자번호 \"xxxxxxx\" 로 조회 시,\n }; \n \n $.ajax({\n url: \"https://api.odcloud.kr/api/nts-businessman/v1/status?serviceKey=xxxxxx\", // serviceKey 값을 xxxxxx에 입력\n type: \"POST\",\n data: JSON.stringify(data), // json 을 string으로 변환하여 전송\n dataType: \"JSON\",\n contentType: \"application/json\",\n accept: \"application/json\",\n success: function(result) {\n console.log(result);\n },\n error: function(result) {\n console.log(result.responseText); //responseText의 에러메세지 확인\n }\n });\n ```\n","version":"1.1.0","title":"국세청_사업자등록정보 진위확인 및 상태조회 서비스"},"host":"api.odcloud.kr","basePath":"/api/nts-businessman/v1","schemes":["https","http"],"paths":{"/validate":{"post":{"description":"입력한 사업자 정보에 대한 일치여부 제공.
1회 호출 시 최대 100개 에 해당하는 사업자 상태정보 요청 가능.
일치할경우, valid: 01 및 해당하는 사업자 정보 return.
일치하지 않을 경우, valid: 02, valid_msg: 확인할 수 없습니다 return.","tags":["사업자등록정보 진위확인 API"],"operationId":"validate","consumes":["application/json"],"produces":["application/json","application/xml"],"parameters":[{"in":"body","name":"body","description":"","required":true,"schema":{"$ref":"#/definitions/ValidationApiRequest"}}],"responses":{"200":{"description":"정상 호출","schema":{"$ref":"#/definitions/ValidationApiResponse"}},"400":{"description":"JSON 포맷에 적합하지 않는 요청","schema":{"$ref":"#/definitions/BadJsonRequestApiResponse"}},"404":{"description":"Not Found Service"},"411":{"description":"필수 요청 파라미터 누락","schema":{"$ref":"#/definitions/RequestDataMarformedApiResponse"}},"413":{"description":"요청 사업자번호 또는 정보 100개 초과","schema":{"$ref":"#/definitions/TooLargeRequestApiResponse"}},"500":{"description":"Internal Server Error","schema":{"$ref":"#/definitions/InternalErrorApiResponse"}},"-5":{"description":"Http Error","schema":{"$ref":"#/definitions/HttpErrorApiResponse"}}},"security":[{"query_key":[]},{"header_key":[]}]}},"/status":{"post":{"description":"사업자 상태조회 정보 제공.
1회 호출 시 최대 100개 에 해당하는 사업자 상태정보 요청 가능.","tags":["사업자등록 상태조회 API"],"operationId":"status","consumes":["application/json"],"produces":["application/json","application/xml"],"parameters":[{"in":"body","name":"body","description":"사업자 번호 Array 입력","required":true,"schema":{"$ref":"#/definitions/StatusApiRequest"}}],"responses":{"200":{"description":"정상 호출","schema":{"$ref":"#/definitions/StatusApiResponse"}},"400":{"description":"JSON 포맷에 적합하지 않는 요청","schema":{"$ref":"#/definitions/BadJsonRequestApiResponse"}},"404":{"description":"Not Found Service"},"411":{"description":"필수 요청 파라미터 누락","schema":{"$ref":"#/definitions/RequestDataMarformedApiResponse"}},"413":{"description":"요청 사업자번호 100개 초과","schema":{"$ref":"#/definitions/TooLargeRequestApiResponse"}},"500":{"description":"Internal Server Error","schema":{"$ref":"#/definitions/InternalErrorApiResponse"}},"-5":{"description":"Http Error","schema":{"$ref":"#/definitions/HttpErrorApiResponse"}}},"security":[{"query_key":[]},{"header_key":[]}]}}},"securityDefinitions":{"query_key":{"type":"apiKey","name":"serviceKey","in":"query"},"header_key":{"type":"apiKey","name":"Authorization","in":"header"}},"definitions":{"StatusApiRequest":{"type":"object","title":"사업자등록 상태조회 API Request","required":["b_no"],"properties":{"b_no":{"type":"array","description":"사업자등록번호","items":{"type":"string","example":"0000000000"}}}},"StatusApiResponse":{"type":"object","title":"사업자등록 상태조회 API Response","properties":{"status_code":{"type":"string","description":"API 상태 코드","enum":["OK"],"xml":{"name":"StatusCode"}},"match_cnt":{"type":"integer","description":"조회 매칭 수","example":1,"xml":{"name":"MatchCnt"}},"request_cnt":{"type":"integer","description":"조회 요청 수","example":1,"xml":{"name":"RequestCnt"}},"data":{"type":"array","description":"사업자등록 상태조회 결과","items":{"$ref":"#/definitions/BusinessStatus"},"xml":{"name":"Data","wrapped":true}}},"xml":{"name":"Response"}},"ValidationApiRequest":{"type":"object","title":"사업자등록정보 진위확인 API Request","properties":{"businesses":{"type":"array","items":{"$ref":"#/definitions/BusinessDescription"}}}},"ValidationApiResponse":{"type":"object","title":"사업자등록정보 진위확인 API Response","properties":{"status_code":{"type":"string","description":"API 상태 코드","enum":["OK"],"xml":{"name":"StatusCode"}},"request_cnt":{"type":"integer","description":"조회 요청 수","example":1,"xml":{"name":"RequestCnt"}},"valid_cnt":{"type":"integer","description":"검증 Valid 수","example":1,"xml":{"name":"ValidCnt"}},"data":{"type":"array","description":"사업자등록정보 진위확인 결과","items":{"$ref":"#/definitions/BusinessValidation"},"xml":{"name":"Data","wrapped":true}}},"xml":{"name":"Response"}},"BusinessStatus":{"type":"object","title":"사업자등록 상태조회 결과","properties":{"b_no":{"type":"string","description":"사업자등록번호","example":"0000000000","xml":{"name":"BNo"}},"b_stt":{"type":"string","description":"납세자상태(명칭):
01: 계속사업자,
02: 휴업자,
03: 폐업자","example":"계속사업자","xml":{"name":"BStt"}},"b_stt_cd":{"type":"string","description":"납세자상태(코드):
01: 계속사업자,
02: 휴업자,
03: 폐업자","example":"01","xml":{"name":"BSttCd"}},"tax_type":{"type":"string","description":"과세유형메세지(명칭):
01:부가가치세 일반과세자,
02:부가가치세 간이과세자,
03:부가가치세 과세특례자,
04:부가가치세 면세사업자,
05:수익사업을 영위하지 않는 비영리법인이거나 고유번호가 부여된 단체,국가기관 등,
06:고유번호가 부여된 단체,
07:부가가치세 간이과세자(세금계산서 발급사업자),
* 등록되지 않았거나 삭제된 경우: \"국세청에 등록되지 않은 사업자등록번호입니다\"","example":"부가가치세 일반과세자","xml":{"name":"TaxType"}},"tax_type_cd":{"type":"string","description":"과세유형메세지(코드):
01:부가가치세 일반과세자,
02:부가가치세 간이과세자,
03:부가가치세 과세특례자,
04:부가가치세 면세사업자,
05:수익사업을 영위하지 않는 비영리법인이거나 고유번호가 부여된 단체,국가기관 등,
06:고유번호가 부여된 단체,
07:부가가치세 간이과세자(세금계산서 발급사업자)","example":"01","xml":{"name":"TaxTypeCd"}},"end_dt":{"type":"string","description":"폐업일 (YYYYMMDD 포맷)","example":"20000101","xml":{"name":"EndDt"}},"utcc_yn":{"type":"string","description":"단위과세전환폐업여부(Y,N)","example":"Y","xml":{"name":"UtccYn"}},"tax_type_change_dt":{"type":"string","description":"최근과세유형전환일자 (YYYYMMDD 포맷)","example":"20000101","xml":{"name":"TaxTypeChangeDt"}},"invoice_apply_dt":{"type":"string","description":"세금계산서적용일자 (YYYYMMDD 포맷)","example":"20000101","xml":{"name":"StaxInvoicePrintYnDt"}},"rbf_tax_type":{"type":"string","description":"직전과세유형메세지(명칭):
01:부가가치세 일반과세자,
02:부가가치세 간이과세자,
07:부가가치세 간이과세자(세금계산서 발급사업자),
99:해당없음","example":"부가가치세 일반과세자","xml":{"name":"RbfTaxType"}},"rbf_tax_type_cd":{"type":"string","description":"직전과세유형메세지(코드):
01:부가가치세 일반과세자,
02:부가가치세 간이과세자,
07:부가가치세 간이과세자(세금계산서 발급사업자),
99:해당없음","example":"01","xml":{"name":"RbfTaxTypeCd"}}},"xml":{"name":"Item"}},"BusinessValidation":{"type":"object","title":"사업자등록정보 진위확인 결과","properties":{"b_no":{"type":"string","description":"사업자등록번호","example":"0000000000","xml":{"name":"BNo"}},"valid":{"type":"string","description":"진위확인 결과 코드
01: Valid, 02: Invalid","enum":["01","02"],"xml":{"name":"Valid"}},"valid_msg":{"type":"string","description":"진위확인 결과 메세지:
- valid 값이 02 인 경우: 확인할 수 없습니다
- 그 외: valid_msg 프로퍼티가 return 되지 않음","example":"","xml":{"name":"ValidMsg"}},"request_param":{"$ref":"#/definitions/BusinessDescription"},"status":{"allOf":[{"$ref":"#/definitions/BusinessStatus"}],"xml":{"name":"Status"}}},"xml":{"name":"Item","wrapped":true}},"BusinessDescription":{"type":"object","title":"사업자등록정보 진위확인 Request Body","required":["b_no","start_dt","p_nm"],"properties":{"b_no":{"type":"string","description":"사업자등록번호","example":"0000000000","xml":{"name":"BNo"}},"start_dt":{"type":"string","description":"개업일자 (YYYYMMDD 포맷)","example":"20000101","xml":{"name":"StartDt"}},"p_nm":{"type":"string","description":"대표자성명1","example":"홍길동","xml":{"name":"PNm"}},"p_nm2":{"type":"string","description":"대표자성명2 - 대표자성명1 이 한글이 아닌 경우, 이에 대한 한글명","example":"홍길동","xml":{"name":"PNm2"}},"b_nm":{"type":"string","description":"상호 (Optional)","example":"(주)테스트","xml":{"name":"BNm"}},"corp_no":{"type":"string","description":"법인등록번호 (Optional)","example":"0000000000000","xml":{"name":"CorpNo"}},"b_sector":{"type":"string","description":"주업태명 (Optional)","example":"","xml":{"name":"BSector"}},"b_type":{"type":"string","description":"주종목명 (Optional)","example":"","xml":{"name":"BType"}},"b_adr":{"type":"string","description":"사업장주소 (Optional)","example":"","xml":{"name":"BAdr"}}},"xml":{"name":"Param"}},"TooLargeRequestApiResponse":{"type":"object","title":"Too Large Request Error","description":"요청하는 사업자 정보 100개 초과","properties":{"status_code":{"type":"string","enum":["TOO_LARGE_REQUEST"],"xml":{"name":"StatusCode"}}},"xml":{"name":"Response"}},"BadJsonRequestApiResponse":{"type":"object","title":"Bad Json Request Error","description":"JSON format 오류","properties":{"status_code":{"type":"string","enum":["BAD_JSON_REQUEST"],"xml":{"name":"StatusCode"}}},"xml":{"name":"Response"}},"RequestDataMarformedApiResponse":{"type":"object","title":"Request Data Malformed Error","description":"필수 항목 누락","properties":{"status_code":{"type":"string","enum":["REQUEST_DATA_MALFORMED"],"xml":{"name":"StatusCode"}}},"xml":{"name":"Response"}},"InternalErrorApiResponse":{"type":"object","title":"Internal Error","description":"내부 에러","properties":{"status_code":{"type":"string","enum":["INTERNAL_ERROR"],"xml":{"name":"StatusCode"}}},"xml":{"name":"Response"}},"HttpErrorApiResponse":{"type":"object","title":"Http Error","description":"내부 에러","properties":{"status_code":{"type":"string","enum":["HTTP_ERROR"],"xml":{"name":"StatusCode"}}},"xml":{"name":"Response"}}}}