사업자등록 상태 조회

무엇을 조회하나요

사업자등록번호의 등록 상태와 과세유형을 돌려줍니다. 계속사업자인지, 휴업이나 폐업 상태인지, 등록되지 않은 번호인지 확인할 수 있어요.

경로	용도
`POST /v1/businessRegistrationStatuses:check`	번호 한 건 조회
`POST /v1/businessRegistrationStatuses:checkBulk`	번호 최대 100건 일괄 조회

거래처 목록처럼 여러 번호를 확인할 때는 일괄 조회를 쓰세요. 두 경로는 같은 상태값과 과세유형을 돌려줍니다.

이 API는 발급자 등록과 공동인증서 없이 API 키만으로 호출합니다. 요청자 관리번호(Bolta-Client-Reference-Id)와 멱등 키는 쓰지 않습니다.

단건 조회

요청

헤더	필수	설명
`Authorization`	O	`Basic {apiKey}` 형식으로 입력하세요. 인증 가이드를 참고하세요
`Content-Type`	O	`application/json`

curl -X POST https://xapi.bolta.io/v1/businessRegistrationStatuses:check \
  -H "Authorization: Basic {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{ "businessRegistrationNumber": "1000000014" }'

사업자등록번호는 10자리로 입력하세요. 100-00-00014처럼 하이픈을 넣어도 됩니다. API가 형식과 체크섬을 검증하고, 응답에는 하이픈을 제거한 10자리를 담습니다.

응답

{
  "businessRegistrationNumber": "1000000014",
  "registration": {
    "status": "ACTIVE",
    "closedOn": null
  },
  "taxation": {
    "type": "GENERAL",
    "changedOn": "2026-01-01"
  }
}

필드	형식	설명
`businessRegistrationNumber`	string	하이픈을 제거한 10자리
`registration.status`	string	사업자 등록 상태
`registration.closedOn`	string 또는 null	폐업일. `YYYY-MM-DD` 형식
`taxation`	object 또는 null	과세 정보
`taxation.type`	string	과세유형
`taxation.changedOn`	string 또는 null	과세유형 전환일. `YYYY-MM-DD` 형식

세 필드는 항상 응답에 담기고, 값이 없으면 null입니다.

일괄 조회

요청

헤더는 단건 조회와 같습니다.

curl -X POST https://xapi.bolta.io/v1/businessRegistrationStatuses:checkBulk \
  -H "Authorization: Basic {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{ "businessRegistrationNumbers": ["1000000014", "100-00-00028", "1000000066"] }'

businessRegistrationNumbers에 번호를 1개 이상 100개 이하로 넣으세요. 100개를 넘기면 번호를 나눠 여러 번 호출하세요.
각 번호는 단건 조회와 같은 규칙으로 검증합니다.
빈 배열, 101개 이상, 형식이 틀린 항목이 하나라도 있으면 요청 전체를 400으로 거절합니다.
같은 번호가 여러 번 들어 있으면 처음 나온 것만 남깁니다. 하이픈 표기가 달라도 같은 번호로 봅니다.

응답

{
  "results": [
    {
      "businessRegistrationNumber": "1000000014",
      "status": {
        "businessRegistrationNumber": "1000000014",
        "registration": { "status": "ACTIVE", "closedOn": null },
        "taxation": { "type": "GENERAL", "changedOn": "2026-01-01" }
      }
    },
    {
      "businessRegistrationNumber": "1000000028",
      "status": {
        "businessRegistrationNumber": "1000000028",
        "registration": { "status": "ACTIVE", "closedOn": null },
        "taxation": { "type": "SIMPLIFIED_RECEIPT_ISSUER", "changedOn": "2026-01-01" }
      }
    },
    {
      "businessRegistrationNumber": "1000000066",
      "status": {
        "businessRegistrationNumber": "1000000066",
        "registration": { "status": "SUSPENDED", "closedOn": null },
        "taxation": { "type": "GENERAL", "changedOn": "2026-01-01" }
      }
    }
  ]
}

필드	형식	설명
`results`	array	요청한 번호마다 항목 하나. 중복을 줄인 뒤 요청 순서를 따름
`results[].businessRegistrationNumber`	string	하이픈을 제거한 10자리
`results[].status`	object 또는 null	단건 조회 응답과 같은 구조. 이번 요청에서 확인하지 못했으면 `null`

라이브 키로 조회할 때 일부 번호의 사업자등록 상태를 이번 요청에서 확인하지 못하면, 그 번호의 항목은 status가 null로 옵니다.

{ "businessRegistrationNumber": "1000000028", "status": null }

null은 미등록(NOT_REGISTERED)과 다릅니다. 나머지 항목은 그대로 유효하니 잠시 후 null인 번호만 다시 조회하세요. 테스트 키 응답에는 null 항목이 나오지 않습니다. 한 건도 확인하지 못하면 200 대신 503과 LOOKUP_UNAVAILABLE을 반환합니다. 파트너 호출 한도가 부족하거나, 한 건도 확인하지 못한 채 볼타 서비스 전체의 일일 조회 한도에 도달하면 429와 RATE_LIMITED를 반환합니다. 조회 도중 전체 한도에 도달하면 이미 확인한 번호는 200으로 돌려주고 나머지는 status: null로 둡니다.

상태값

등록 상태

상태(`status`)	뜻
`ACTIVE`	계속사업자
`SUSPENDED`	휴업자
`CLOSED`	폐업자
`NOT_REGISTERED`	미등록 번호
`UNKNOWN`	위 네 가지에 속하지 않는 기타 등록 상태

UNKNOWN은 조회 실패를 뜻하지 않습니다. 사업자등록 상태를 확인할 수 없으면 API가 503과 LOOKUP_UNAVAILABLE을 반환합니다.

과세유형

API는 국세청 과세유형을 그대로 돌려줍니다.

과세유형(`taxation.type`)	뜻
`GENERAL`	일반과세자
`SIMPLIFIED_RECEIPT_ISSUER`	간이과세자. 세금계산서 발행 불가
`SIMPLIFIED_TAX_INVOICE_ISSUER`	간이과세자. 세금계산서 발행 가능
`SPECIAL_TAXPAYER`	과세특례자
`TAX_FREE`	면세사업자
`NONPROFIT`	수익사업을 영위하지 않는 비영리법인이거나 고유번호가 부여된 단체
`UNIQUE_NUMBER_ORGANIZATION`	고유번호가 부여된 단체

간이과세자의 세금계산서 발행 가능 여부는 SIMPLIFIED_RECEIPT_ISSUER와 SIMPLIFIED_TAX_INVOICE_ISSUER로 구분하세요. 처음 보는 값은 기타로 처리하세요. taxation은 국세청이 과세유형을 주지 않으면 null입니다. 계속사업자는 항상 값이 있고, 미등록과 기타 상태는 항상 null입니다. 휴업자와 폐업자는 국세청이 마지막 과세유형을 주면 값이 있고, 주지 않으면 null입니다. closedOn은 폐업자일 때만 값이 있습니다.

테스트 키로 조회하기

테스트 키는 실제 조회를 하지 않고 아래 고정 번호만 모의 응답으로 돌려줍니다.

번호	`registration.status`	`taxation.type`	`registration.closedOn`
`1000000014`	`ACTIVE`	`GENERAL`	null
`1000000028`	`ACTIVE`	`SIMPLIFIED_RECEIPT_ISSUER`	null
`1000000106`	`ACTIVE`	`SIMPLIFIED_TAX_INVOICE_ISSUER`	null
`1000000033`	`ACTIVE`	`TAX_FREE`	null
`1000000047`	`ACTIVE`	`NONPROFIT`	null
`1000000052`	`ACTIVE`	`UNIQUE_NUMBER_ORGANIZATION`	null
`1000000066`	`SUSPENDED`	`GENERAL`	null
`1000000071`	`CLOSED`	`GENERAL`	2026년 1월 1일 (고정)
`1000000085`	`NOT_REGISTERED`	null (`taxation`이 null)	null
`1000000090`	`UNKNOWN`	null (`taxation`이 null)	null

taxation이 있는 번호의 taxation.changedOn은 모두 2026년 1월 1일(고정)입니다. 목록에 없는 번호를 테스트 키로 조회하면 API가 400과 INVALID_REQUEST를 반환합니다. 일괄 조회는 목록에 없는 번호가 하나라도 섞이면 요청 전체를 거절합니다.

요금

상태를 확인한 사업자등록번호마다 10포인트를 차감합니다. 일괄 조회에서 확인하지 못한 번호(status가 null), 오류 응답, 테스트 키 호출은 차감하지 않습니다. 한 요청에 같은 번호를 여러 번 넣어도 한 번만 차감합니다. 요청을 다시 보내면 다시 차감합니다.

호출 한도

API 키의 모드별로 24시간에 사업자등록번호 10,000건까지 조회할 수 있습니다. 한도는 요청 수가 아니라 중복을 뺀 번호 수로 셉니다. 24시간은 첫 호출 시점부터 계산합니다. 같은 파트너의 같은 모드 키는 한도를 함께 씁니다. 한도를 모두 쓰거나 볼타 서비스 전체의 일일 조회 한도에 도달하면 API가 429와 RATE_LIMITED를 반환하고 Retry-After 헤더에 재시도까지 남은 초를 담습니다. 이 값을 읽어 재시도 시점을 잡으세요. 503을 받으면 곧바로 다시 호출하지 말고 잠시 후 다시 조회하세요.

오류

상태 코드	에러 코드	발생 조건
`400`	`INVALID_REQUEST`	번호 누락, 10자리가 아닌 입력, 테스트 키의 목록 밖 번호 조회. 일괄 조회의 빈 배열, 100개 초과
`400`	`INVALID_BUSINESS_REGISTRATION_NUMBER`	체크섬이 맞지 않는 번호
`401`	-	API 키 인증 실패. 응답 본문 없음
`402`	`PAYMENT_REQUIRED`	포인트 잔액 부족. 개발자센터에서 충전하세요
`403`	`FORBIDDEN`	리소스 접근 권한 없음
`409`	`AVAILABLE_POINTS_INSUFFICIENT`	진행 중인 다른 요청 때문에 지금 쓸 수 있는 포인트 부족. 충전하거나 그 요청이 끝난 뒤 다시 요청하세요
`429`	`RATE_LIMITED`	파트너 호출 한도 또는 볼타 서비스 전체 조회 한도 초과. `Retry-After` 헤더 동반
`500`	`INTERNAL_SERVER_ERROR`	서버 내부 오류
`503`	`LOOKUP_UNAVAILABLE`	사업자등록 상태를 확인할 수 없음. 일괄 조회는 한 건도 확인하지 못한 경우
`503`	`SERVICE_UNAVAILABLE`	일시적인 내부 API 통신 오류

전체 에러 코드는 에러 코드에서 확인하세요.

API 소개

API 가이드

사용 사례

SDK/노코드 연동

무엇을 조회하나요

단건 조회

요청

응답

일괄 조회

요청

응답

상태값

등록 상태

과세유형

테스트 키로 조회하기

요금

호출 한도

오류

관련 문서

​무엇을 조회하나요

​단건 조회

​요청

​응답

​일괄 조회

​요청

​응답

​상태값

​등록 상태

​과세유형

​테스트 키로 조회하기

​요금

​호출 한도

​오류

​관련 문서

무엇을 조회하나요

단건 조회

요청

응답

일괄 조회

요청

응답

상태값

등록 상태

과세유형

테스트 키로 조회하기

요금

호출 한도

오류

관련 문서