Back to Details

nts-business-registration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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

韩国国税厅营业执照信息真伪验证及状态查询

What this skill does

本Skill的功能

공공데이터포털의 국세청_사업자등록정보 진위확인 및 상태조회 서비스를 
k-skill-proxy
경유로 호출해 다음을 확인한다.
  • status
    : 사업자등록번호 기준 상태조회 (
    계속사업자
    , 
    휴업자
    , 
    폐업자
    , 과세유형 등 upstream 응답 그대로 포함)
  • validate
    : 사업자등록번호 + 개업일자 + 대표자명(및 선택 필드) 기준 진위확인
通过
k-skill-proxy
调用公共数据门户的韩国国税厅_营业执照信息真伪验证及状态查询服务，可确认以下内容：
  • status
    : 基于营业执照编号的状态查询（包含
    持续经营
    、
    停业
    、
    注销
    、征税类型等上游响应原始内容）
  • validate
    : 基于营业执照编号+开业日期+法人代表姓名（及可选字段）的真伪验证

When to use

使用场景

  • "이 사업자등록번호가 계속사업자인지 확인해줘"
  • "사업자등록번호 상태조회해줘"
  • "사업자등록번호, 개업일, 대표자명으로 진위확인해줘"
  • 거래처 등록 전 공식 NTS/공공데이터포털 기준 확인이 필요할 때
  • "帮我确认这个营业执照编号是否为持续经营状态"
  • "帮我查询营业执照编号的状态"
  • "用营业执照编号、开业日期、法人代表姓名进行真伪验证"
  • 合作方注册前，需基于官方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 접근 가능
  • 网络连接
  • python3
    环境
  • 已安装的Skill包中包含
    scripts/nts_business_registration.py
    辅助脚本
  • 可访问托管/自托管
    k-skill-proxy
    的
    /v1/nts-business/status
    、
    /v1/nts-business/validate
    路由

Credential requirements

凭证要求

  • 사용자 측 필수 시크릿 없음.
  • KSKILL_PROXY_BASE_URL
    — self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted 
    https://k-skill-proxy.nomadamas.org
    를 사용한다.
  • DATA_GO_KR_API_KEY
    는 프록시 운영 서버 환경에만 둔다. 공공데이터포털에서 
    국세청_사업자등록정보 진위확인 및 상태조회 서비스
    활용신청이 되어 있어야 한다.
  • 用户无需提供必要密钥
  • KSKILL_PROXY_BASE_URL
    — 仅在使用自托管/独立代理时设置。留空则使用默认托管地址
    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를 지정한다.
  • validate
    会将法人代表姓名(
    p_nm
    )、开业日期(
    start_dt
    )、地址·商号等可选元数据发送至托管代理及公共数据门户上游
  • 托管代理不会缓存
    validate
    的成功响应，不会附加代理
    query
    回显，即使上游返回请求值，也会从响应中移除敏感输入字段
  • 代理默认关闭Fastify请求日志。在运营者单独开启日志的自托管环境中，需自行检查请求体日志政策
  • 若对通过托管代理进行真伪验证有顾虑，可通过
    KSKILL_PROXY_BASE_URL
    指定自行运营的自托管代理

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
  • 公共数据门户文档: 
    https://www.data.go.kr/tcs/dss/selectApiDataDetailView.do?publicDataPk=15081808
  • 状态查询上游接口: 
    POST https://api.odcloud.kr/api/nts-businessman/v1/status?serviceKey=...
  • 真伪验证上游接口: 
    POST https://api.odcloud.kr/api/nts-businessman/v1/validate?serviceKey=...
  • 代理路由: 
    POST /v1/nts-business/status
    , 
    POST /v1/nts-business/validate

Inputs

输入参数

상태조회

状态查询

  • b_no
    : 사업자등록번호 10자리. 하이픈은 허용되며 helper/proxy가 숫자만 남긴다.
  • 한 요청은 최대 100개까지 보낸다.
  • b_no
    : 10位营业执照编号。允许包含连字符，辅助脚本/代理会自动仅保留数字
  • 单次请求最多可提交100个编号

진위확인

真伪验证

필수:
  • b_no
    : 사업자등록번호 10자리
  • start_dt
    : 개업일자 
    YYYYMMDD
    (하이픈/점 허용)
  • p_nm
    : 대표자 성명
선택:
  • p_nm2
    : 대표자 성명2
  • b_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자리여야 한다.
必填项:
  • b_no
    : 10位营业执照编号
  • start_dt
    : 开业日期，格式为
    YYYYMMDD
    （允许包含连字符/点）
  • p_nm
    : 法人代表姓名
可选项:
  • p_nm2
    : 法人代表姓名2
  • b_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

工作流程

  1. 사용자 입력에서 사업자등록번호는 숫자 10자리인지 확인한다.
  2. 상태조회만 필요하면 
    status
    를 호출한다.
  3. 진위확인은 최소 
    b_no
    , 
    start_dt
    , 
    p_nm
    이 있을 때만 호출한다.
  4. 개인정보/거래처 정보는 필요한 필드만 보내고, 프록시 응답을 그대로 보존하되 핵심 상태/진위 결과를 짧게 요약한다.
  5. upstream이 
    upstream_not_configured
    , 활용신청 미승인, 인증키 오류 등을 반환하면 설정/승인 문제로 안내한다.
  1. 验证用户输入的营业执照编号是否为10位数字
  2. 若仅需状态查询，则调用
    status
    接口
  3. 真伪验证仅在至少提供
    b_no
    、
    start_dt
    、
    p_nm
    时才会调用
  4. 仅发送必要的个人信息/合作方信息字段，保留代理响应原始内容，但简要总结核心状态/真伪结果
  5. 若上游返回
    upstream_not_configured
    、使用申请未通过、认证密钥错误等信息，将提示用户检查配置/申请状态

CLI examples

CLI示例

bash
python3 scripts/nts_business_registration.py status \
  --b-no 123-45-67890
bash
python3 scripts/nts_business_registration.py validate \
  --business-json '{"b_no":"123-45-67890","start_dt":"2020-01-31","p_nm":"홍길동","b_nm":"테스트상사"}'
bash
python3 scripts/nts_business_registration.py status \
  --b-no 123-45-67890
bash
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

直接调用代理示例

bash
curl -fsS -X POST "$KSKILL_PROXY_BASE_URL/v1/nts-business/status" \
  -H 'content-type: application/json' \
  -d '{"b_no":["123-45-67890"]}'
bash
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":"홍길동"}]}'
bash
curl -fsS -X POST "$KSKILL_PROXY_BASE_URL/v1/nts-business/status" \
  -H 'content-type: application/json' \
  -d '{"b_no":["123-45-67890"]}'
bash
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
    값을 그대로 근거로 설명한다.
  • 400 bad_request
    : 营业执照编号非10位，或真伪验证必填字段缺失
  • 503 upstream_not_configured
    : 代理服务器未配置
    DATA_GO_KR_API_KEY
  • 上游认证/使用申请错误: API密钥未通过对应服务的审核，或已过期/存在错误
  • 空结果或真伪不一致: 直接依据官方响应的
    valid
    、
    valid_msg
    、
    b_stt
    值进行说明

Done when

完成标准

  • 상태조회는 공식 응답의 
    b_stt
    , 
    b_stt_cd
    , 
    tax_type
    등 핵심 필드를 확인했다.
  • 진위확인은 
    valid
    , 
    valid_msg
    결과를 확인했다.
  • API 키는 사용자에게 요구하지 않고 프록시 서버에만 둔다는 점을 지켰다.
  • 状态查询已确认官方响应的
    b_stt
    、
    b_stt_cd
    、
    tax_type
    等核心字段
  • 真伪验证已确认
    valid
    、
    valid_msg
    结果
  • 严格遵循不向用户索要API密钥，仅在代理服务器配置密钥的规则