[Django] 국세청 사업자등록정보 진위확인 및 상태조회 API 사용법 ( + Postman)

 

 

실제 서비스를 운영하다보면 사업자등록정보에 대한 진위여부 혹은 상태조회를 해야할 때가 있다.

이번에는 국세청에서 제공하는 사업자등록정보 진위확인 및 사업자등록 상태조회 API 서비스 사용법에 대해 알아보겠다.

 

1.  국세청 사업자등록정보 진위확인 및 상태조회 API란?

국세청 사업자등록정보 진위확인 및 상태조회 API는 한국 국세청이 제공하는 서비스로, 특정 사업자등록번호의 유효성과 상태를 확인할 수 있는 API이다. 이 API는 주로 온라인 서비스 제공자나 플랫폼 운영자가 사업자의 등록 정보를 검증하거나, 해당 사업자가 정상적으로 영업 중인지 확인하기 위해 사용된다.

 

주요 기능은 아래와 같다.

 

1) 사업자등록번호 진위확인

• 입력된 사업자등록번호가 실제로 국세청에 등록된 번호인지 확인

• 올바른 사업자등록번호 여부 반환

 

2) 사업자 상태조회

• 특정 사업자의 현재 영업 상태 확인가능 예) 정상, 폐업, 휴업 등의 상태 정보를 반환

 

해당 API를 활용하기 위해서는 공공데이터포털 사이트를 통해 service key(인증키)를 발급받은 후 자유롭게 사용할 수 있다.

---

2.  Service Key(인증키) 발급 방법

 

우선 아래 링크로 접속한다. ( 공공데이터포털 로그인 필요 회원가입 후 이용 )

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

 

 

'활용신청' 버튼 클릭 후 요구하는 정보를 입력해준다.

 

신청 후 마이페이지에 가보면 개인 API 인증키를 확인할 수 있다.

인증키 복사를 한 후 해당 인증키를 통해 API를 활용할 수 있다.

url에 param으로 사용할 경우에는 Encoding된 인증키를 복사하고, 서버 환경파일 등에 저장해둘거면 Decoding된 인증키를 복사하자

 

API 가이드라인은 위에 링크한 페이지에 가보면 Document 형식으로 잘 설명되어 있다.

(api 호출 주소, 요청시 필수 항목, 응답 항목 등...)

그렇게 때문에 바로 코드상 활용 방법으로 넘어가도록 하겠다. 

실습은 진위여부에 대한 API를 다뤄보겠다.

---

3. API 활용 - Postman, Django

우선 첫번째는 POSTMAN을 통해 호출 해볼 것이다.

우선 사업자 진위여부 호출 주소는 아래와 같으며 복사한 인증키를 serviceKey param에 넣어주면 된다.

https://api.odcloud.kr/api/nts-businessman/v1/status?serviceKey=xxxxxx

해당 예시는 API 가이드라인에 나와있는 예시이다. 잘 실행되는 것을 확인할 수 있다.

참고로 valid 값이 01 일 경우 해당 사업자가 실제로 존재(True)한다는 뜻이고,

valid 값이 02일 경우 사업자가 실제로 존재 하지않는다는(False) 뜻이다.

 

참고로 사업자등록번호, 개업일자, 대표자 성명 이렇게 세개만 필수 항목이므로,

아래와 같이 필수항목만 보내주어도 정상적으로 호출 및 응답되는 것을 확인 할 수 있다.

 

 

다음은 Django에서의 활용 방법이다.

보통 인증키 같은 경우는 .env 파일로 환경변수로써 관리하지만 해당 코드는 예시이므로 그냥 작성했다.

@api_view(['POST'])
@permission_classes([AllowAny])
def check_business_registration_api(request):
    
    """_summary_
        사업자등록 여부 진위확인 api
        - body에 담겨온 데이터를 기반으로 국세청 api를 통해 사업자 진위여부를 판별
    """
    
    business_number = request.data.get('businessNumber', '0000000000')
    start_date = request.data.get('startDate', '20000101')
    participant_name = request.data.get('participantName', 'None')
    
    service_key = "xxxxxxxxxxx"
    
    headers = {
        'accept': 'application/json',
        'Authorization': service_key,
        'Content-Type': 'application/json',
    }

    params = {
        'serviceKey': service_key,
    }
    
    json_data = {
        "businesses": [
            {
            "b_no": business_number, # 사업자등록번호
            "start_dt": start_date, # 개업년월일
            "p_nm": participant_name, # 대표자명
            }
        ]
    }

    api_response = requests.post(
        'https://api.odcloud.kr/api/nts-businessman/v1/validate', 
        headers=headers, 
        params=params, 
        json=json_data
    )

    # '01' : 유효한 사업자 / '02' : 유효하지 않은 사업자
    valid_code = api_response.json()['data'][0]['valid']
	
    is_valid = True if valid_code == '01' else False

    return Response({ 'isValid' : is_valid }, status=status.HTTP_200_OK)