사업자 등록 검증 API 설명 - Cake-ly/cake-ly-wiki GitHub Wiki

국세청 사업자 등록 정보 진위확인 및 상태 조회

주소

사용 기술

OpenFeign API

사업자 등록 정보 진위 확인 API

  • 베이스

  • 특징

    • 1회 호출당 최대 100개 사업자 정보 처리
    • 기본 JSON

  • 메서드

    • POST

  • API

    • /validate

  • 역할

    • 입력한 사업자 정보 일치 여부 확인

  • 요청 본문

    {
  "businesses": [
    {
      "b_no": "0000000000", // 사업자등록번호 (필수, 10자리 숫자)
      "start_dt": "20000101", // 개업일자 (필수, YYYYMMDD)
      "p_nm": "홍길동", // 대표자성명 (필수)
      "p_nm2": "", // 대표자성명2 (선택, 외국인 한글명)
      "b_nm": "(주)테스트", // 상호 (선택)
      "corp_no": "0000000000000", // 법인등록번호 (선택, 13자리 숫자)
      "b_sector": "", // 주업태명 (선택)
      "b_type": "", // 주종목명 (선택)
      "b_adr": "" // 사업장주소 (선택, v1.1부터 추가)
    }
  ]
}

  • 응답

    • 일치

      {
  "status_code": "OK",
  "match_cnt": 1,
  "request_cnt": 1,
  "data": [
    {
      "b_no": "0000000000",
      "valid": "01", // 일치 시
      "rbf_tax_type": "부가가치세 일반과세자", // 직전 과세유형 (v1.1 추가)
      "rbf_tax_type_cd": "01" // 직전 과세유형 코드 (v1.1 추가)
    }
  ]
}

    • 불일치

      {
  "status_code": "OK",
  "match_cnt": 0,
  "request_cnt": 1,
  "data": [
    {
      "b_no": "0000000000",
      "valid": "02", // 불일치 시
      "valid_msg": "확인할 수 없습니다"
    }
  ]
}

사업자 등록 상태 조회

  • 베이스

    • 동일

  • API

    • /status

  • 요청

    {
  "b_no": ["0000000000"] // 사업자등록번호 배열 (필수, 10자리 숫자)
}

  • 응답

    • 등록시

      {
  "status_code": "OK",
  "match_cnt": 1,
  "request_cnt": 1,
  "data": [
    {
      "b_no": "0000000000",
      "b_stt": "계속사업자",
      "b_stt_cd": "01", // 01: 계속, 02: 휴업, 03: 폐업
      "tax_type": "부가가치세 일반과세자",
      "tax_type_cd": "01",
      "end_dt": "20000101",
      "utcc_yn": "Y",
      "tax_type_change_dt": "20000101",
      "invoice_apply_dt": "20000101",
      "rbf_tax_type": "부가가치세 일반과세자", // 직전 과세유형
      "rbf_tax_type_cd": "01" // 직전 과세유형 코드
    }
  ]
}

    • 미등록시

      등록되지 않은 경우: "tax_type": "국세청에 등록되지 않은 사업자등록번호입니다".

샘플 코드

var data = {
    "b_no": ["0000000000"]
};

$.ajax({
    url: "https://api.odcloud.kr/api/nts-businessman/v1/status?serviceKey=[서비스키]",
    type: "POST",
    data: JSON.stringify(data),
    dataType: "JSON",
    contentType: "application/json",
    accept: "application/json",
    success: function (result) {
        console.log(result);
    },
    error: function (result) {
        console.log(result.responseText);
    }
});

요청 파라미터

  • 공통:
    • serviceKey: URL 쿼리스트링으로 전달 (공공데이터포털에서 발급).
    • returnType: JSON (기본) 또는 XML.
  • 진위확인:
    • b_no: 10자리 숫자 (하이픈 제거).
    • start_dt: YYYYMMDD 형식 (하이픈 제거).
    • p_nm: 대표자 성명 (외국인: 영문명).
    • p_nm2: 외국인 한글명 (선택, 비외국인은 빈 문자열).
    • b_nm: 상호 (주식회사 관련 단어 위치 무관, 공백 무시).
    • corp_no: 13자리 숫자 (하이픈 제거).
    • b_sector, b_type, b_adr: 공백 무시.
  • 상태조회:
    • b_no: 10자리 숫자 배열 (하이픈 제거).

응답 코드

  • 200: 정상 호출.
  • 400: JSON 포맷 오류 (BAD_JSON_REQUEST).
  • 411: 필수 파라미터 누락 (REQUEST_DATA_MALFORMED).
  • 413: 100개 초과 요청 (TOO_LARGE_REQUEST).
  • 500: 서버 오류 (INTERNAL_ERROR).
  • 5: HTTP 오류 (HTTP_ERROR).