사업자등록 상태 조회

무엇을 조회하나요

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

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

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

이 API는 발급자 등록과 공동인증서가 필요 없습니다. 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자리를 담습니다. 테스트 키와 라이브 키 중 무엇으로 조회할지는 API 키가 결정합니다. 요청 본문이나 헤더로 모드를 지정하지 않습니다.

응답

{
  "businessRegistrationNumber": "1000000014",
  "registration": {
    "status": "ACTIVE",
    "closedOn": null
  },
  "taxType": "GENERAL"
}

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

세 필드는 항상 응답에 담기고, 값이 없으면 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 },
        "taxType": "GENERAL"
      }
    },
    {
      "businessRegistrationNumber": "1000000028",
      "status": {
        "businessRegistrationNumber": "1000000028",
        "registration": { "status": "ACTIVE", "closedOn": null },
        "taxType": "SIMPLIFIED"
      }
    },
    {
      "businessRegistrationNumber": "1000000066",
      "status": {
        "businessRegistrationNumber": "1000000066",
        "registration": { "status": "SUSPENDED", "closedOn": null },
        "taxType": null
      }
    }
  ]
}

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

라이브 키로 조회할 때 일부 번호의 사업자등록 상태를 이번 요청에서 확인하지 못하면, 그 번호의 항목은 status가 null로 옵니다. 아래 번호는 형식을 보여 주는 예시입니다.

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

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

상태값

등록 상태

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

통신 실패를 UNKNOWN으로 돌려주지 않습니다. 사업자등록 상태를 확인할 수 없으면 503과 LOOKUP_UNAVAILABLE을 반환합니다. 두 경우를 구분해서 처리하세요.

과세유형

과세유형(`taxType`)	뜻
`GENERAL`	일반과세자
`SIMPLIFIED`	간이과세자
`TAX_FREE`	면세사업자
`NONPROFIT`	비영리
`OTHER_CORPORATION`	기타 법인

과세유형은 계속사업자 결과에서만 값이 있습니다. 나머지 상태에서는 null입니다. closedOn은 폐업자일 때만 날짜를 담습니다. 나머지 상태에서는 null입니다.

테스트 키로 조회하기

테스트 키는 실제 조회를 하지 않고 아래 고정 번호만 모의 응답으로 돌려줍니다. 결과는 고정값이라 실제 사업자등록 상태와 무관합니다.

번호	`registration.status`	`taxType`	`registration.closedOn`
`1000000014`	`ACTIVE`	`GENERAL`	null
`1000000028`	`ACTIVE`	`SIMPLIFIED`	null
`1000000033`	`ACTIVE`	`TAX_FREE`	null
`1000000047`	`ACTIVE`	`NONPROFIT`	null
`1000000052`	`ACTIVE`	`OTHER_CORPORATION`	null
`1000000066`	`SUSPENDED`	null	null
`1000000071`	`CLOSED`	null	2026년 1월 1일 (고정)
`1000000085`	`NOT_REGISTERED`	null	null
`1000000090`	`UNKNOWN`	null	null

하이픈을 넣을 때는 100-00-00014처럼 입력하세요. 목록에 없는 번호를 테스트 키로 조회하면 400과 INVALID_REQUEST를 반환합니다. 형식이나 체크섬이 잘못된 번호는 입력 오류로 거절합니다. 일괄 조회도 규칙이 같습니다. 목록에 없는 번호가 하나라도 섞이면 요청 전체를 400으로 거절하고, 그 번호를 status: null 항목으로 돌려주지 않습니다.

402, 429, 503을 강제로 재현하는 테스트 시나리오는 제공하지 않습니다. 실제 인증 실패와 호출 한도 초과, 서비스 장애는 아래 오류 처리대로 응답합니다.

라이브 키로 위 번호를 보내면 모의 응답 없이 실제 조회를 수행합니다.

요금

사업자등록 상태 조회 API의 요금은 별도 협의로 정합니다. 도입을 검토 중이라면 볼타 담당자에게 문의하세요.

호출 한도

API 키의 모드별로 24시간에 사업자등록번호 10,000건까지 조회할 수 있습니다. 한도는 요청 수가 아니라 조회한 번호 수로 셉니다. 중복을 줄인 뒤 번호 100건을 담은 일괄 조회라면 한 번에 한도를 100건 씁니다. 24시간은 첫 호출 시점부터 계산합니다.

같은 파트너의 같은 모드 키는 한도를 함께 씁니다.
테스트 키와 라이브 키는 한도를 공유하지 않습니다.

볼타 서비스 전체의 일일 조회 한도에 도달해도 429를 반환합니다. 한도를 모두 쓰면 429와 RATE_LIMITED를 반환하고 Retry-After 헤더에 재시도까지 남은 초를 담습니다. 이 값을 읽어 재시도 시점을 잡으세요.

볼타는 이 API에 자동 재시도를 두지 않습니다. 429나 503을 받았을 때 곧바로 다시 호출하면 한도만 더 빨리 소진합니다.

오류

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

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

API 소개

API 가이드

사용 사례

SDK/노코드 연동

무엇을 조회하나요

단건 조회

요청

응답

일괄 조회

요청

응답

상태값

등록 상태

과세유형

테스트 키로 조회하기

요금

호출 한도

오류

관련 문서

​무엇을 조회하나요

​단건 조회

​요청

​응답

​일괄 조회

​요청

​응답

​상태값

​등록 상태

​과세유형

​테스트 키로 조회하기

​요금

​호출 한도

​오류

​관련 문서

무엇을 조회하나요

단건 조회

요청

응답

일괄 조회

요청

응답

상태값

등록 상태

과세유형

테스트 키로 조회하기

요금

호출 한도

오류

관련 문서