국세청 사업자 조회 API, 30분 만에 연동하기

BTSDB 가이드 · 개발 — 상태조회·진위확인 API 실전

회원가입 때의 사업자 검증, 거래처 일괄 점검, ERP 연동은 국세청이 공공데이터포털에 개방한 「사업자등록정보 진위확인 및 상태조회 서비스」로 구현할 수 있습니다. BTSDB도 이 API를 씁니다. 신청부터 운영까지 실제로 부딪히는 지점을 정리했습니다.

POST https://api.odcloud.kr/api/nts-businessman/v1/status?serviceKey={인코딩키}
Content-Type: application/json

{"b_no": ["1208800767", "1234567890"]}

번호는 하이픈 없이 10자리 문자열로 보냅니다. 응답의 data 배열에 번호별 결과가 들어 있습니다.

등록되지 않은 번호는 오류가 아니라 정상 응답으로 옵니다. b_stt_cd가 비어 있고 tax_type에 "국세청에 등록되지 않은 사업자등록번호입니다"라는 문구가 들어 있습니다. 상태 코드가 비어 있는지로 판별하세요.

import requests

URL = "https://api.odcloud.kr/api/nts-businessman/v1/status"

def fetch_status(b_no, decoding_key):
    r = requests.post(URL, params={"serviceKey": decoding_key},
                      json={"b_no": [b_no]}, timeout=8)
    r.raise_for_status()
    items = r.json().get("data") or []
    if not items:
        return None                      # 응답 형식이 다르면 실패로 처리
    item = items[0]
    return {
        "registered": bool(item.get("b_stt_cd")),
        "status": item.get("b_stt"),
        "tax_type": item.get("tax_type"),
        "closed_on": item.get("end_dt") or None,
    }

requests가 params를 인코딩하므로 여기서는 Decoding 키를 넘깁니다.

POST https://api.odcloud.kr/api/nts-businessman/v1/validate?serviceKey={인코딩키}
Content-Type: application/json

{"businesses": [{"b_no": "1208800767", "start_dt": "20130801", "p_nm": "홍길동"}]}

응답의 valid가 01이면 일치, 02이면 불일치입니다. 개업일자와 대표자 성명은 사업자등록증에 적힌 그대로 보내야 합니다. 공동대표나 외국인 대표는 표기 방식 때문에 불일치가 나기 쉬우니 사용자에게 등록증 기준으로 입력하도록 안내하세요.

• 캐시 — 페이지를 열 때마다 호출하지 않습니다. BTSDB는 상태조회 결과를 24시간 보관합니다.
• 검증번호 먼저 — 호출 전에 10자리와 검증번호를 검사하면 잘못된 입력 대부분을 호출 없이 걸러냅니다. (검증 알고리즘과 코드)
• 미등록 결과도 저장 — 등록되지 않은 번호의 결과도 보관해 두면 같은 번호를 반복 조회하는 봇으로부터 호출 한도를 지킬 수 있습니다.
• 묶어서 호출 — 거래처 목록 점검처럼 여러 건을 볼 때는 100건씩 묶어 보냅니다.
• 시간 제한 — 응답이 늦을 때가 있으니 타임아웃을 걸고, 실패하면 사용자에게 "잠시 후 다시"를 보여줍니다.

• 인증키 오류 — Encoding 키를 라이브러리에 넘겨 이중 인코딩된 경우가 가장 많습니다.
• 활용기간 만료 — 활용신청에는 기간이 있습니다. 만료되면 갑자기 실패하므로 만료일을 달력에 적어 두고 연장 신청합니다.
• 실패를 조용히 넘김 — 응답 파싱 실패를 빈 결과로 처리하면 정상 사업자가 "미등록"으로 보입니다. 실패와 미등록을 구분하고 로그를 남깁니다.
• 키 노출 — 인증키를 소스코드에 넣지 않습니다. 저장소에 올라간 키는 재발급해야 합니다.

한두 건 확인하는 정도라면 연동 없이 상단 검색창으로 충분합니다. 국세청 상태조회에 더해 고용·산재보험, 통신판매 등록, 국민연금 자료까지 한 페이지에서 볼 수 있습니다.

국세청 사업자 조회 API는 무료인가요?

무료입니다. 공공데이터포털에서 활용신청을 하고 인증키를 발급받아 사용합니다.

한 번에 몇 건까지 조회할 수 있나요?

상태조회와 진위확인 모두 한 번의 요청에 100건까지 배열로 보낼 수 있습니다.

상호나 대표자 이름도 받아 올 수 있나요?

받을 수 없습니다. 상태조회는 상태와 과세유형만 돌려주고, 진위확인은 보낸 정보가 맞는지만 알려줍니다. 상호는 다른 공공데이터에서 가져와야 합니다.

등록되지 않은 번호는 어떻게 응답하나요?

오류가 아니라 정상 응답으로 오며, 상태 코드가 비어 있고 과세유형 문구에 등록되지 않은 번호라는 안내가 들어 있습니다.

인증키 오류가 계속 납니다.

Encoding 키와 Decoding 키를 바꿔 쓴 경우가 가장 많습니다. HTTP 라이브러리가 파라미터를 인코딩한다면 Decoding 키를 넘겨야 합니다. 활용기간이 만료되지 않았는지도 확인하세요.

• 공공데이터포털 — 국세청 사업자등록정보 진위확인 및 상태조회 서비스

API 명세는 국세청과 공공데이터포털 사정에 따라 바뀔 수 있습니다. 연동할 때는 포털의 공식 문서를 기준으로 하세요.