> ## 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의 요청, 응답, 요금, 호출 한도를 안내합니다.

## 무엇을 조회하나요

볼타가 공공 데이터를 모아 정리한 사업자 프로필을 검색하고 조회합니다. 거래처 등록 화면에서 사업자를 검색해 고르게 하거나, 사업자등록번호만 아는 거래처의 상호, 주소, 업종을 채울 때 쓰세요.

| 경로 | 용도 |
| - | - |
| `GET /v1/businessProfiles:search` | 상호, 대표자명, 사업자등록번호로 사업자 검색 |
| `GET /v1/businessProfiles/{businessRegistrationNumber}` | 사업자등록번호 한 건의 상세 프로필 조회 |

검색으로 사업자를 고른 뒤 상세를 조회하세요. 검색 결과에는 사업자를 가려낼 값만 있고, 대표자 실명, 주소, 연락처, 업종은 상세 조회 응답에 있습니다.

## 이용 조건

발급자 등록, 공동인증서, 요청자 관리번호(`Bolta-Client-Reference-Id`)가 필요 없고 구독 플랜 제한도 없습니다. `Authorization` 헤더에 `Basic {apiKey}`만 넣으면 됩니다. 인증은 [인증 가이드](/docs/api-introduction/authentication)를 참고하세요.

## 요금

| 경로 | 요금 |
| - | - |
| 검색 | 돌려준 결과 한 건마다 9포인트 |
| 상세 조회 | 조회 성공마다 90포인트 |

* 결과가 없는 검색, 상세 조회의 `404`, 오류 응답, 테스트 키 호출은 차감하지 않습니다.
* 다음 결과를 받는 호출도 받은 건수만큼 차감합니다. 한 번에 차감하는 포인트는 최대 `limit` × 9포인트입니다.
* 같은 사업자등록번호를 다시 조회하면 다시 차감합니다.
* 잔액이 받을 결과의 요금보다 적으면 API가 결과를 일부만 돌려주지 않고 `402`나 `409`를 반환합니다. 잔액이 적으면 `limit`을 줄여 호출하세요.
* API는 조회 전에 잔액이 한 건 요금(검색 9포인트, 상세 조회 90포인트) 이상인지 확인합니다. 모자라면 결과와 관계없이 `402`나 `409`를 반환합니다.

## 검색

### 요청

```bash theme={"dark"}
curl -G https://xapi.bolta.io/v1/businessProfiles:search \
  -H "Authorization: Basic {apiKey}" \
  --data-urlencode "keyword=테스트상사" \
  -d "limit=3"
```

| 파라미터 | 필수 | 설명 |
| - | - | - |
| `keyword` | O | 검색어 |
| `limit` | X | 한 번에 받을 결과 수. 1 이상 50 이하, 기본값 20 |
| `cursor` | X | 이전 응답의 `nextCursor`. 받은 값을 그대로 보내세요 |
| `excludeStatuses` | X | 결과에서 뺄 사업자 등록 상태. `SUSPENDED`, `CLOSED`를 쉼표로 구분 |

`keyword`로 아래 값을 찾습니다.

* 상호, 이전 상호, 영문 상호
* 대표자명
* 상호 초성 3자 이상(예: `ㅌㅅㅌ`)
* 사업자등록번호 10자리. 하이픈을 넣어도 됩니다. 번호로 찾으면 그 사업자 한 건을 돌려줍니다

여러 단어를 띄어 쓰면 모든 단어가 일치하는 사업자를 찾습니다. 지역이나 업종 이름을 함께 넣어 결과를 좁히세요. 예를 들어 `다온 강남`은 강남구의 다온을 찾습니다.

검색어는 앞뒤 공백을 뺀 100자 이하, 공백과 기호를 뺀 2글자 이상으로 입력하세요. `주식회사`처럼 법인 형태만 있는 검색어는 `400 INVALID_REQUEST`를 반환합니다.

`excludeStatuses`는 휴업이나 폐업으로 확인된 사업자를 결과에서 뺍니다. 볼타가 상태를 확인하지 않은 사업자(`registration`이 `null`)와 `NOT_REGISTERED`, `UNKNOWN` 사업자는 결과에 남습니다. 거래 전에 상태를 확정하려면 [사업자등록 상태 조회](/docs/api-introduction/business-registration-status)로 확인하세요.

| 입력 | 결과 |
| - | - |
| 생략 | 상태로 거르지 않음 |
| `CLOSED` | 폐업자 제외 |
| `SUSPENDED,CLOSED` | 휴업자와 폐업자 제외 |

빈 값, 같은 값의 중복, `ACTIVE` 같은 다른 값을 넣으면 API가 `400 INVALID_REQUEST`를 반환합니다.

### 응답

```json theme={"dark"}
{
  "items": [
    {
      "businessRegistrationNumber": "1000000014",
      "organizationName": "테스트상사 주식회사",
      "representativeName": "김*타",
      "registration": { "status": "ACTIVE" },
      "region": "서울특별시 강남구"
    },
    {
      "businessRegistrationNumber": "1000000028",
      "organizationName": "테스트상사 간이점",
      "representativeName": "이*스",
      "registration": { "status": "ACTIVE" },
      "region": "서울특별시 마포구"
    },
    {
      "businessRegistrationNumber": "1000000106",
      "organizationName": "테스트상사 세금계산서점",
      "representativeName": "박*의",
      "registration": { "status": "ACTIVE" },
      "region": "부산광역시 해운대구"
    }
  ],
  "nextCursor": "djE6MDotOjM6MzFmN2UxZGI0NjJkMzVhMQ",
  "hasMore": true
}
```

| 필드 | 형식 | 설명 |
| - | - | - |
| `items` | array | 검색 결과. 관련도가 높은 순 |
| `items[].businessRegistrationNumber` | string | 하이픈 없는 10자리 사업자등록번호 |
| `items[].organizationName` | string 또는 null | 상호 |
| `items[].representativeName` | string 또는 null | 가운데를 가린 대표자명 |
| `items[].registration` | object 또는 null | 볼타가 마지막으로 확인한 사업자 등록 상태. 확인한 적이 없으면 `null` |
| `items[].registration.status` | string | 사업자 등록 상태 |
| `items[].region` | string 또는 null | 시도와 시군구 이름. 시군구를 모르면 시도만 |
| `nextCursor` | string 또는 null | 다음 결과를 받을 cursor. 마지막이면 `null` |
| `hasMore` | boolean | 다음 결과가 있으면 `true` |

모든 필드를 항상 담습니다. 값이 없으면 `null`이고, 결과가 없으면 `items`가 빈 배열입니다.

### 다음 결과 받기

`hasMore`가 `true`이면 `nextCursor`를 `cursor`에 넣어 다시 호출하세요. `keyword`와 `excludeStatuses`는 첫 요청과 같은 값을 보내고, `limit`은 바꿔도 됩니다.

```bash theme={"dark"}
curl -G https://xapi.bolta.io/v1/businessProfiles:search \
  -H "Authorization: Basic {apiKey}" \
  --data-urlencode "keyword=테스트상사" \
  -d "limit=3" \
  -d "cursor=djE6MDotOjM6MzFmN2UxZGI0NjJkMzVhMQ"
```

<Warning>
  받은 결과가 `limit`보다 적어도 `hasMore`가 `true`일 수 있습니다. `items`의 개수가 아니라 `hasMore`를 보고 이어 호출하세요.
</Warning>

* 한 검색어로 받을 수 있는 결과는 앞 1,000건까지입니다. 더 필요하면 검색어를 구체적으로 바꾸세요.
* cursor는 받을 때의 `keyword`, `excludeStatuses`, 키 모드(테스트, 라이브)에 묶입니다. 조건이 다르거나 cursor가 오래되면 API가 `400 INVALID_CURSOR`를 반환합니다. 이때는 cursor 없이 처음부터 다시 검색하세요.

## 상세 조회

### 요청

```bash theme={"dark"}
curl https://xapi.bolta.io/v1/businessProfiles/1000000014 \
  -H "Authorization: Basic {apiKey}"
```

경로에 사업자등록번호 10자리를 넣으세요. `100-00-00014`처럼 하이픈을 넣어도 됩니다. API가 형식과 체크섬을 검증합니다. 10자리가 아니면 `400 INVALID_REQUEST`, 체크섬이 맞지 않으면 `400 INVALID_BUSINESS_REGISTRATION_NUMBER`를 반환합니다.

볼타에 프로필이 없는 번호는 `404 NOT_FOUND`를 반환합니다.

### 응답

```json theme={"dark"}
{
  "businessRegistrationNumber": "1000000014",
  "corporateRegistrationNumber": "1101110000006",
  "businessKind": "CORPORATE",
  "commercialSalesNumber": "2021-서울강남-01234",
  "organizationName": "테스트상사 주식회사",
  "organizationNameEnglish": "Test Sangsa Co., Ltd.",
  "formerOrganizationNames": [
    { "name": "주식회사 테스트랩스", "changedOn": "2022-03-01" }
  ],
  "representativeName": "김볼타",
  "address": {
    "roadAddress": "서울특별시 강남구 가상로 1",
    "postalCode": "06236",
    "sidoCode": "11",
    "sigunguCode": "11680"
  },
  "contact": {
    "phone": "02-000-0000",
    "email": "hello@example.com",
    "websites": ["https://example.com"]
  },
  "industry": {
    "businessType": "서비스업",
    "businessItem": "응용 소프트웨어 개발",
    "standardIndustry": { "code": "58222", "name": "응용 소프트웨어 개발 및 공급업" },
    "category": { "code": "J", "name": "정보통신업" }
  },
  "openedOn": "2021-03-02",
  "businessRegisteredOn": "2021-03-02",
  "corporationEstablishedOn": "2021-02-25",
  "registration": {
    "status": "ACTIVE",
    "closedOn": null,
    "checkedAt": "2025-12-31T15:00:00Z"
  },
  "taxation": {
    "type": "GENERAL"
  }
}
```

모든 필드를 항상 담습니다. 값이 없으면 `null`이고, 목록은 빈 배열입니다.

#### 식별

| 필드 | 형식 | 설명 |
| - | - | - |
| `businessRegistrationNumber` | string | 하이픈 없는 10자리 사업자등록번호 |
| `corporateRegistrationNumber` | string 또는 null | 하이픈 없는 13자리 법인등록번호 |
| `businessKind` | string 또는 null | 사업자 구분 |
| `commercialSalesNumber` | string 또는 null | 통신판매업 신고번호 |

#### 상호와 대표자

| 필드 | 형식 | 설명 |
| - | - | - |
| `organizationName` | string 또는 null | 상호 |
| `organizationNameEnglish` | string 또는 null | 영문 상호 |
| `formerOrganizationNames` | array | 이전 상호. 최근에 바뀐 것부터 |
| `formerOrganizationNames[].name` | string | 이전 상호 |
| `formerOrganizationNames[].changedOn` | string 또는 null | 새 상호가 공시 자료에 처음 나타난 날. `YYYY-MM-DD` 형식. 변경 등기일과 다를 수 있음 |
| `representativeName` | string 또는 null | 대표자명. 원천 자료가 가려서 준 값은 가린 그대로 |

#### 주소와 연락처

| 필드 | 형식 | 설명 |
| - | - | - |
| `address` | object 또는 null | 주소. 원천 자료에 주소가 없으면 `null` |
| `address.roadAddress` | string 또는 null | 도로명주소 |
| `address.postalCode` | string 또는 null | 우편번호 5자리 |
| `address.sidoCode` | string 또는 null | 법정동 시도 코드 2자리 |
| `address.sigunguCode` | string 또는 null | 법정동 시군구 코드 5자리 |
| `contact` | object | 연락처. 항상 객체 |
| `contact.phone` | string 또는 null | 대표 전화번호. 하이픈을 넣은 형식 |
| `contact.email` | string 또는 null | 대표 이메일 |
| `contact.websites` | array of string | 홈페이지 주소 |

#### 업종

| 필드 | 형식 | 설명 |
| - | - | - |
| `industry` | object | 업종. 항상 객체 |
| `industry.businessType` | string 또는 null | 업태. 국세청 등록 기준 |
| `industry.businessItem` | string 또는 null | 종목. 국세청 등록 기준 |
| `industry.standardIndustry` | object 또는 null | 한국표준산업분류(11차) 세세분류 |
| `industry.standardIndustry.code` | string | 세세분류 코드 5자리 |
| `industry.standardIndustry.name` | string | 세세분류 이름 |
| `industry.category` | object 또는 null | 한국표준산업분류 대분류 |
| `industry.category.code` | string | 대분류 코드. `A`부터 `U`까지 |
| `industry.category.name` | string | 대분류 이름 |

#### 날짜

| 필드 | 형식 | 설명 |
| - | - | - |
| `openedOn` | string 또는 null | 개업일. `YYYY-MM-DD` 형식 |
| `businessRegisteredOn` | string 또는 null | 사업자등록일. `YYYY-MM-DD` 형식 |
| `corporationEstablishedOn` | string 또는 null | 법인설립일. `YYYY-MM-DD` 형식 |

세 날짜는 출처가 서로 달라 값이 다를 수 있습니다.

#### 사업자 등록 상태

| 필드 | 형식 | 설명 |
| - | - | - |
| `registration` | object 또는 null | 볼타가 마지막으로 확인한 사업자 등록 상태. 확인한 적이 없으면 `null` |
| `registration.status` | string | 사업자 등록 상태 |
| `registration.closedOn` | string 또는 null | 폐업일. `YYYY-MM-DD` 형식 |
| `registration.checkedAt` | string | 국세청에 확인한 시각. ISO 8601 UTC 형식 |
| `taxation` | object 또는 null | 마지막으로 확인한 과세 정보. 모르면 `null` |
| `taxation.type` | string | 과세유형 |

## 상태값

### 사업자 구분

| 구분(`businessKind`) | 뜻 |
| - | - |
| `INDIVIDUAL` | 개인사업자 |
| `CORPORATE` | 법인사업자 |

### 등록 상태와 과세유형

`registration.status`와 `taxation.type`의 값과 뜻은 [사업자등록 상태 조회](/docs/api-introduction/business-registration-status)의 상태값과 같습니다. 처음 보는 값은 기타로 처리하세요.

`registration`과 `taxation`은 볼타가 마지막으로 확인해 저장한 값이고, 확인한 시각은 `registration.checkedAt`에 있습니다. 호출 시점의 상태가 필요하면 [사업자등록 상태 조회](/docs/api-introduction/business-registration-status) API를 쓰세요.

## 테스트 키

테스트 키는 실제 사업자 데이터를 읽지 않고 고정된 모의 데이터를 돌려줍니다. 응답 구조는 라이브 키와 같고 포인트를 차감하지 않습니다.

### 상세 조회 테스트 번호

| 번호 | `businessKind` | `registration.status` | `taxation.type` | 비고 |
| - | - | - | - | - |
| `1000000014` | `CORPORATE` | `ACTIVE` | `GENERAL` | 모든 필드가 채워진 예시 |
| `1000000028` | `INDIVIDUAL` | `ACTIVE` | `SIMPLIFIED_RECEIPT_ISSUER` | |
| `1000000106` | `INDIVIDUAL` | `ACTIVE` | `SIMPLIFIED_TAX_INVOICE_ISSUER` | |
| `1000000033` | `INDIVIDUAL` | `ACTIVE` | `TAX_FREE` | |
| `1000000047` | `CORPORATE` | `ACTIVE` | `NONPROFIT` | |
| `1000000052` | `CORPORATE` | `ACTIVE` | `UNIQUE_NUMBER_ORGANIZATION` | |
| `1000000066` | `INDIVIDUAL` | `SUSPENDED` | `GENERAL` | |
| `1000000071` | `INDIVIDUAL` | `CLOSED` | `GENERAL` | `registration.closedOn`은 2026년 1월 1일(고정) |
| `1000000085` | `INDIVIDUAL` | `NOT_REGISTERED` | null (`taxation`이 null) | |
| `1000000090` | `INDIVIDUAL` | `UNKNOWN` | null (`taxation`이 null) | |
| `1000000111` | `INDIVIDUAL` | null (`registration`이 null) | null (`taxation`이 null) | 상태를 확인한 적 없는 예시. `address`도 `null` |
| `1000000125` | - | - | - | 프로필이 없는 번호. `404 NOT_FOUND` |

* `registration.checkedAt`은 모두 `2025-12-31T15:00:00Z`(고정)입니다.
* 법인등록번호와 법인설립일은 `businessKind`가 `CORPORATE`인 번호에만 있습니다.
* 연락처, 영문 상호, 이전 상호, 통신판매업 신고번호는 `1000000014`에만 있습니다.
* [사업자등록 상태 조회](/docs/api-introduction/business-registration-status)의 테스트 번호와 같은 번호는 두 API가 같은 등록 상태와 과세유형을 돌려줍니다.

### 검색 테스트 데이터

모의 사업자 25곳이 있고 상호는 모두 `테스트상사`로 시작합니다. 위 표에서 프로필이 있는 11곳과 `테스트상사 01호점`부터 `테스트상사 14호점`까지 14곳입니다. 14곳은 개인 계속사업자이고 `taxation.type`은 `GENERAL`입니다.

테스트 키 검색은 상호에 검색어가 들어 있는 사업자와 사업자등록번호가 같은 사업자를 찾습니다. 대표자명, 초성, 지역 이름 검색은 라이브 키로 확인하세요.

* `keyword=테스트상사`는 25곳을 모두 돌려줍니다.
* `limit=10`으로 호출하면 `nextCursor`로 세 번에 나눠 받는 흐름을 시험할 수 있습니다.
* `excludeStatuses=SUSPENDED,CLOSED`를 넣으면 `1000000066`과 `1000000071`이 빠집니다.
* 맞는 사업자가 없는 검색어는 빈 `items`를 돌려줍니다.

25곳 모두 상세 조회가 되고, 같은 번호의 검색 결과와 상세 응답은 값이 같습니다. 그 밖의 번호를 테스트 키로 상세 조회하면 API가 `400`과 `INVALID_REQUEST`를 반환합니다.

## 호출 한도

| 경로 | 한도 |
| - | - |
| 검색 | 1분에 120회 |
| 상세 조회 | 1분에 300회 |

한도는 결과 건수가 아니라 호출 횟수로 셉니다. 같은 파트너의 같은 모드 키는 한도를 함께 쓰고, 테스트 키와 라이브 키는 따로 셉니다.

한도를 넘으면 API가 `429`와 `RATE_LIMITED`를 반환하고 `Retry-After` 헤더에 재시도까지 남은 초를 담습니다. 그 시간만큼 기다린 뒤 다시 호출하세요.

## 오류

| 상태 코드 | 에러 코드 | 발생 조건 |
| - | - | - |
| `400` | `INVALID_REQUEST` | `keyword` 누락이나 검색어 규칙 위반, 범위를 벗어난 `limit`, `excludeStatuses`의 빈 값, 중복, 받지 않는 값, 10자리가 아닌 사업자등록번호, 테스트 키의 목록 밖 번호 조회 |
| `400` | `INVALID_BUSINESS_REGISTRATION_NUMBER` | 상세 조회에서 체크섬이 맞지 않는 번호 |
| `400` | `INVALID_CURSOR` | 형식이 틀린 cursor, 받을 때와 검색 조건이나 키 모드가 다른 cursor, 오래된 cursor |
| `401` | - | API 키 인증 실패. 응답 본문 없음 |
| `402` | `PAYMENT_REQUIRED` | 포인트 잔액 부족. 개발자센터에서 충전하세요 |
| `404` | `NOT_FOUND` | 상세 조회에서 프로필이 없는 번호 |
| `409` | `AVAILABLE_POINTS_INSUFFICIENT` | 진행 중인 다른 요청 때문에 지금 쓸 수 있는 포인트 부족. 충전하거나 그 요청이 끝난 뒤 다시 요청하세요 |
| `429` | `RATE_LIMITED` | 호출 한도 초과. `Retry-After` 헤더 동반 |
| `500` | `INTERNAL_SERVER_ERROR` | 서버 내부 오류 |
| `503` | `LOOKUP_UNAVAILABLE` | 지금은 검색이나 조회를 할 수 없음. 잠시 후 다시 시도하세요 |
| `503` | `SERVICE_UNAVAILABLE` | 일시적인 내부 API 통신 오류 |

전체 에러 코드는 [에러 코드](/docs/api-introduction/error-codes)를 참고하세요.

## 관련 문서

* [사업자 프로필 검색 API](/api-reference/business-profile/search-business-profiles)
* [사업자 프로필 상세 조회 API](/api-reference/business-profile/retrieve-business-profile)
* [요금 안내](/docs/api-introduction/pricing)
* [사업자등록 상태 조회](/docs/api-introduction/business-registration-status)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.