Hans API

Appearance

사업자 ​

엔드포인트 ​

국세청(hometax) 사업자등록 진위확인과 상태조회 API입니다. 사업자등록번호가 실재하는지, 계속사업자인지 폐업했는지를 확인합니다.

두 가지 조회 ​

  • 상태조회 (GET /nts/business/{bno}/status): 사업자번호만으로 납세자상태(계속/휴업/폐업)와 과세유형을 확인합니다.
  • 진위확인 (POST /nts/business/{bno}/verify): 사업자번호·개업일자·대표자성명이 국세청 등록정보와 모두 일치하는지 확인합니다. 개업일자·대표자성명은 필수이며, 개인정보가 로그에 남지 않도록 본문(body) 으로 보냅니다.

사업자번호 표기 ​

- 는 넣어도 되고 빼도 됩니다. 서버가 자동으로 제거하므로 두 표기는 같은 값입니다.

  • 사업자번호 — 645-64-01820 = 6462401820
  • 개업일자 — 2000-01-01 = 20000101

등록되지 않은 번호 ​

존재하지 않는 사업자번호도 에러가 아닙니다. registered: false 로 응답하고, taxType 에 안내 문구가 담깁니다.

json
{
  "bno": "0000000000",
  "registered": false,
  "taxType": "국세청에 등록되지 않은 사업자등록번호입니다."
}

데이터 출처 ​

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

국세청 점검 시간

국세청 시스템 점검 중에는 조회가 일시적으로 실패할 수 있습니다(503). 잠시 후 다시 시도하세요.

사업자 등록번호 상태조회​

GET
/nts/business/{bno}/status

사업자번호로 납세자상태(계속/휴업/폐업)와 과세유형을 조회한다.

등록되지 않은 번호도 에러가 아니다 — registered=false 로 응답한다.

Request

🔒 Bearer 인증 필요 · 인증 방법
GET/nts/business/{bno}/status

Path Parameters

NameTypeRequiredConstraintsDescription
bnostringrequired사업자등록번호. '-' 는 자동으로 제거된다.

Response

200

BusinessStatus

FieldTypeRequiredConstraintsDescription
bnostringrequired사업자등록번호
registeredbooleanrequired국세청에 등록된 사업자인지. false 면 나머지 상태값은 비어 있다.
statusCodestringoptional납세자상태 코드. 01:계속사업자 / 02:휴업자 / 03:폐업자
statusstringoptional납세자상태 명칭
taxTypeCodestringoptional과세유형 코드. 01:일반 / 02:간이 / 04:면세 등
taxTypestringoptional과세유형 명칭. 미등록이면 "국세청에 등록되지 않은 사업자등록번호입니다".
closedAtstringoptional폐업일 (YYYYMMDD)
{
  "bno": "6462401820",
  "registered": true,
  "statusCode": "01",
  "status": "계속사업자",
  "taxTypeCode": "01",
  "taxType": "부가가치세 일반과세자",
  "closedAt": "20200101"
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​

Powered by VitePress OpenAPI

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

POST
/nts/business/{bno}/verify

사업자번호(경로)·개업일자·대표자성명이 국세청 등록정보와 일치하는지 확인한다.
개업일자·대표자성명은 필수이고, 상호·법인번호·주소를 더 넣으면 판정이 정밀해진다.

대표자성명 등 개인정보는 URL·쿼리가 아니라 본문으로 받는다(접근 로그 노출 방지).

Request

🔒 Bearer 인증 필요 · 인증 방법
POST/nts/business/{bno}/verify

Path Parameters

NameTypeRequiredConstraintsDescription
bnostringrequired사업자등록번호. '-' 는 자동으로 제거된다.

Request Body

application/jsonrequired

BusinessVerifyRequest

FieldTypeRequiredConstraintsDescription
startDatestringrequired개업일자 (YYYYMMDD). '-' 는 자동 제거된다.
namestringrequired대표자성명
name2stringoptional대표자성명2. 대표자성명이 한글이 아닐 때의 한글명.
companyNamestringoptional상호
corpNostringoptional법인등록번호(13자리). '-' 는 자동 제거.
addressstringoptional사업장주소
{
  "startDate": "20000101",
  "name": "홍길동",
  "name2": "string",
  "companyName": "string",
  "corpNo": "string",
  "address": "string"
}

Response

200

BusinessVerification

FieldTypeRequiredConstraintsDescription
bnostringrequired사업자등록번호
validbooleanrequired진위확인 결과. 입력한 정보가 국세청 등록정보와 일치하면 true.
messagestringoptional불일치 시 안내 메시지. 일치하면 비어 있다.
statusBusinessStatusoptional함께 조회된 사업자 상태.

BusinessStatus

FieldTypeRequiredConstraintsDescription
bnostringrequired사업자등록번호
registeredbooleanrequired국세청에 등록된 사업자인지. false 면 나머지 상태값은 비어 있다.
statusCodestringoptional납세자상태 코드. 01:계속사업자 / 02:휴업자 / 03:폐업자
statusstringoptional납세자상태 명칭
taxTypeCodestringoptional과세유형 코드. 01:일반 / 02:간이 / 04:면세 등
taxTypestringoptional과세유형 명칭. 미등록이면 "국세청에 등록되지 않은 사업자등록번호입니다".
closedAtstringoptional폐업일 (YYYYMMDD)
{
  "bno": "6462401820",
  "valid": true,
  "message": "확인할 수 없습니다.",
  "status": {
    "bno": "6462401820",
    "registered": true,
    "statusCode": "01",
    "status": "계속사업자",
    "taxTypeCode": "01",
    "taxType": "부가가치세 일반과세자",
    "closedAt": "20200101"
  }
}

Playground​

Server
Authorization
Variables
Key
Value
Body

Samples​

Powered by VitePress OpenAPI