> ## Documentation Index > Fetch the complete documentation index at: https://docs.bolta.io/llms.txt > Use this file to discover all available pages before exploring further. # 사업자등록 상태 조회 > 사업자등록번호의 등록 상태와 과세유형을 단건 또는 일괄로 조회하는 API의 입력 규칙과 응답을 안내합니다. ## 무엇을 조회하나요 사업자등록번호의 등록 상태와 과세유형을 돌려줍니다. 계속사업자인지, 휴업이나 폐업 상태인지, 아예 등록되지 않은 번호인지 확인할 수 있어요. | 경로 | 용도 | | ------------------------------------------------- | ---------------- | | `POST /v1/businessRegistrationStatuses:check` | 번호 한 건 조회 | | `POST /v1/businessRegistrationStatuses:checkBulk` | 번호 최대 100건 일괄 조회 | 거래처 목록처럼 여러 번호를 확인할 때는 일괄 조회를 쓰세요. 두 경로는 같은 상태값과 과세유형을 돌려줍니다. 이 API는 발급자 등록과 공동인증서가 필요 없습니다. API 키만 있으면 바로 호출할 수 있습니다. 세금계산서 발행 API와 달리 요청자 관리번호(`Bolta-Client-Reference-Id`)를 쓰지 않고, 멱등 키도 제공하지 않습니다. ## 단건 조회 ### 요청 | 헤더 | 필수 | 설명 | | --------------- | -- | ------------------------------------------------------------------------------------------- | | `Authorization` | O | `Basic {apiKey}` 형식으로 입력하세요. 자세한 내용은 [인증 가이드](/docs/api-introduction/authentication)를 참고하세요 | | `Content-Type` | O | `application/json` | ```bash theme={"dark"} 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 키가 결정합니다. 요청 본문이나 헤더로 모드를 지정하지 않습니다. ### 응답 ```json theme={"dark"} { "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`입니다. ## 일괄 조회 ### 요청 헤더는 단건 조회와 같습니다. ```bash theme={"dark"} 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`으로 거절합니다. * 같은 번호가 여러 번 들어 있으면 처음 나온 것만 남깁니다. 하이픈 표기가 달라도 같은 번호로 봅니다. ### 응답 ```json theme={"dark"} { "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`로 옵니다. 아래 번호는 형식을 보여 주는 예시입니다. ```json theme={"dark"} { "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 통신 오류 | 전체 에러 코드는 [에러 코드](/docs/api-introduction/error-codes)에서 확인하세요. ## 관련 문서 * [사업자등록 상태 단건 조회 API](/api-reference/사업자등록-상태-조회/사업자등록-상태-단건-조회) * [사업자등록 상태 일괄 조회 API](/api-reference/사업자등록-상태-조회/사업자등록-상태-일괄-조회) * [인증 가이드](/docs/api-introduction/authentication) * [용어 정리](/docs/api-introduction/glossary)