| name | nts-business-registration |
| description | 국세청 사업자등록정보 진위확인 및 사업자등록 상태조회를 공공데이터포털 API(k-skill-proxy 경유)로 수행한다. |
| license | MIT |
| metadata | {"category":"business","locale":"ko-KR","phase":"v1"} |
국세청 사업자등록정보 진위확인 및 상태조회
What this skill does
공공데이터포털의 국세청_사업자등록정보 진위확인 및 상태조회 서비스를 k-skill-proxy 경유로 호출해 다음을 확인한다.
status: 사업자등록번호 기준 상태조회 (계속사업자, 휴업자, 폐업자, 과세유형 등 upstream 응답 그대로 포함)validate: 사업자등록번호 + 개업일자 + 대표자명(및 선택 필드) 기준 진위확인
When to use
- "이 사업자등록번호가 계속사업자인지 확인해줘"
- "사업자등록번호 상태조회해줘"
- "사업자등록번호, 개업일, 대표자명으로 진위확인해줘"
- 거래처 등록 전 공식 NTS/공공데이터포털 기준 확인이 필요할 때
Prerequisites
- 인터넷 연결
python3- 설치된 skill payload 안에
scripts/nts_business_registration.py helper 포함
- hosted/self-host
k-skill-proxy의 /v1/nts-business/status, /v1/nts-business/validate route 접근 가능
Credential requirements
- 사용자 측 필수 시크릿 없음.
KSKILL_PROXY_BASE_URL — self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted https://k-skill-proxy.nomadamas.org 를 사용한다.DATA_GO_KR_API_KEY 는 프록시 운영 서버 환경에만 둔다. 공공데이터포털에서 국세청_사업자등록정보 진위확인 및 상태조회 서비스 활용신청이 되어 있어야 한다.
Validate privacy boundary
validate는 대표자명(p_nm), 개업일자(start_dt), 주소·상호 같은 선택 메타데이터를 hosted proxy와 공공데이터포털 upstream으로 전송한다.- hosted proxy는
validate 성공 응답을 캐시하지 않고, 프록시 query echo를 붙이지 않으며, upstream이 요청값을 되돌려도 민감 입력 필드를 응답에서 제거한다.
- 프록시의 기본 Fastify request logging은 꺼져 있다. 운영자가 별도 로그를 켠 self-host 환경에서는 요청 본문 로깅 정책을 직접 점검해야 한다.
- hosted proxy 경유가 부담스러운 진위확인 업무는
KSKILL_PROXY_BASE_URL로 직접 운영하는 self-host proxy를 지정한다.
Official surfaces
- 공공데이터포털 문서:
https://www.data.go.kr/tcs/dss/selectApiDataDetailView.do?publicDataPk=15081808
- 상태조회 upstream:
POST https://api.odcloud.kr/api/nts-businessman/v1/status?serviceKey=...
- 진위확인 upstream:
POST https://api.odcloud.kr/api/nts-businessman/v1/validate?serviceKey=...
- 프록시 route:
POST /v1/nts-business/status, POST /v1/nts-business/validate
Inputs
상태조회
b_no: 사업자등록번호 10자리. 하이픈은 허용되며 helper/proxy가 숫자만 남긴다.- 한 요청은 최대 100개까지 보낸다.
진위확인
필수:
b_no: 사업자등록번호 10자리start_dt: 개업일자 YYYYMMDD (하이픈/점 허용)p_nm: 대표자 성명
선택:
p_nm2: 대표자 성명2b_nm: 상호corp_no: 법인등록번호b_sector: 주업태명b_type: 주종목명b_adr: 사업장주소
텍스트 필드는 NTS 입력 규격에 맞춰 보수적으로 길이를 제한한다(p_nm/p_nm2 30자, b_nm 200자, b_sector/b_type 100자, b_adr 500자). corp_no는 제공할 경우 숫자 13자리여야 한다.
Workflow
- 사용자 입력에서 사업자등록번호는 숫자 10자리인지 확인한다.
- 상태조회만 필요하면
status를 호출한다.
- 진위확인은 최소
b_no, start_dt, p_nm이 있을 때만 호출한다.
- 개인정보/거래처 정보는 필요한 필드만 보내고, 프록시 응답을 그대로 보존하되 핵심 상태/진위 결과를 짧게 요약한다.
- upstream이
upstream_not_configured, 활용신청 미승인, 인증키 오류 등을 반환하면 설정/승인 문제로 안내한다.
CLI examples
python3 scripts/nts_business_registration.py status \
--b-no 123-45-67890
python3 scripts/nts_business_registration.py validate \
--business-json '{"b_no":"123-45-67890","start_dt":"2020-01-31","p_nm":"홍길동","b_nm":"테스트상사"}'
Direct proxy examples
curl -fsS -X POST "$KSKILL_PROXY_BASE_URL/v1/nts-business/status" \
-H 'content-type: application/json' \
-d '{"b_no":["123-45-67890"]}'
curl -fsS -X POST "$KSKILL_PROXY_BASE_URL/v1/nts-business/validate" \
-H 'content-type: application/json' \
-d '{"businesses":[{"b_no":"123-45-67890","start_dt":"20200131","p_nm":"홍길동"}]}'
Failure modes
400 bad_request: 사업자등록번호가 10자리가 아니거나 진위확인 필수 필드가 빠짐.503 upstream_not_configured: 프록시 서버에 DATA_GO_KR_API_KEY가 없음.- upstream 인증/활용신청 오류: API 키가 해당 서비스에 승인되지 않았거나 만료/오류 상태.
- 빈 결과 또는 진위불일치: 공식 응답의
valid, valid_msg, b_stt 값을 그대로 근거로 설명한다.
Done when
- 상태조회는 공식 응답의
b_stt, b_stt_cd, tax_type 등 핵심 필드를 확인했다.
- 진위확인은
valid, valid_msg 결과를 확인했다.
- API 키는 사용자에게 요구하지 않고 프록시 서버에만 둔다는 점을 지켰다.
