> ## 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/businessRegistrationCertificates:extract` | 사업자등록증 한 건 인식과 진위확인 |

## 이용 조건

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

## 요금

진위확인 결과(`validation`)가 `MATCHED`나 `NOT_MATCHED`인 문서마다 100포인트를 차감합니다. `UNAVAILABLE` 결과, 오류 응답, 테스트 키 호출은 차감하지 않습니다. 같은 파일을 다시 보내면 다시 차감합니다.

## 요청

`multipart/form-data`의 `file` 파트에 파일 한 개를 넣으세요.

```bash theme={"dark"}
curl -X POST https://xapi.bolta.io/v1/businessRegistrationCertificates:extract \
  -H "Authorization: Basic {apiKey}" \
  -F "file=@certificate.pdf"
```

| 파트 | 형식 | 필수 | 설명 |
| - | - | - | - |
| `file` | 파일 | 예 | 사업자등록증 파일 한 개 |

* 형식은 PDF, JPG, PNG, WebP입니다.
* 크기는 5MB(5,242,880바이트) 이하, PDF는 5쪽 이하입니다.
* 한 요청에 문서 한 건을 보냅니다. 여러 문서는 한 건씩 차례로 보내세요.
* 사업자등록증만 받습니다. 사업자등록증명이나 등기사항증명서 같은 다른 서류와 사업자등록번호를 읽을 수 없는 파일은 `400 INVALID_FILE`을 반환합니다.

홈택스에서 내려받은 PDF를 가장 정확하게 읽습니다. 사진을 받을 때는 문서 전체가 들어오고 글자가 선명하게 찍히도록 사용자에게 안내하세요. 사업자등록번호를 읽지 못해 `400 INVALID_FILE`을 받으면 다시 찍어 달라고 안내하세요.

## 응답

API는 `200 OK`와 아래 응답을 반환합니다.

```json theme={"dark"}
{
  "certificate": {
    "businessRegistrationNumber": "1000000014",
    "organizationName": "(주)볼타테스트",
    "representativeNames": ["김볼타"],
    "openedOn": "2020-01-01",
    "address": "서울특별시 테스트구 가상로 1",
    "industries": [
      { "businessType": "정보통신업", "businessItem": "응용 소프트웨어 개발 및 공급업" }
    ],
    "corporationRegistrationNumber": "1101110000000",
    "taxRegistrationId": null
  },
  "inputQuality": "SUFFICIENT",
  "validation": "MATCHED"
}
```

| 필드 | 형식 | 설명 |
| - | - | - |
| `certificate` | object | 문서에서 읽은 값 |
| `certificate.businessRegistrationNumber` | string | 하이픈 없는 10자리 사업자등록번호 |
| `certificate.organizationName` | string 또는 null | 상호(법인명) |
| `certificate.representativeNames` | array of string | 대표자 이름. 인쇄된 순서대로 최대 10개 |
| `certificate.openedOn` | string 또는 null | 개업연월일. `YYYY-MM-DD` 형식 |
| `certificate.address` | string 또는 null | 사업장 소재지 |
| `certificate.industries` | array | 업종 행. 인쇄된 순서대로 최대 20개 |
| `certificate.industries[].businessType` | string 또는 null | 업태 |
| `certificate.industries[].businessItem` | string 또는 null | 종목 |
| `certificate.corporationRegistrationNumber` | string 또는 null | 하이픈 없는 13자리 법인등록번호. 법인 등록증에만 있음 |
| `certificate.taxRegistrationId` | string 또는 null | 종사업장번호 4자리 |
| `inputQuality` | string | 이미지 해상도 판정 |
| `validation` | string | 진위확인 결과 |

모든 필드를 항상 담습니다. 읽지 못한 값은 `null`이고, 목록은 빈 배열입니다. 사업자등록번호를 읽지 못하면 결과 대신 `400 INVALID_FILE`을 반환합니다.

`representativeNames`는 공동대표를 모두 담고 `(공동대표)` 같은 역할 표기는 뗍니다. 개인 공동사업자 등록증은 성명 칸에 인쇄된 대표 한 사람만 담습니다. 대표자를 한 명만 받는 곳에는 첫 항목을 쓰세요.

`industries`는 같은 행의 업태와 종목이 짝입니다. 대표 업종이 필요하면 첫 행을 쓰세요.

### `validation`

| 값 | 뜻 | 차감 |
| - | - | - |
| `MATCHED` | 사업자등록번호, 첫 번째 대표자명, 개업일이 국세청 등록 정보와 일치 | 100포인트 |
| `NOT_MATCHED` | 국세청 등록 정보와 일치를 확인하지 못함 | 100포인트 |
| `UNAVAILABLE` | 국세청 장애로 진위확인을 하지 못함. 읽은 값은 그대로 담음 | 없음 |

진위확인에 쓰는 값은 사업자등록번호, 첫 번째 대표자명, 개업일 세 가지입니다. 상호, 주소, 업종은 사용자가 직접 확인하게 하세요.

### `inputQuality`

| 값 | 뜻 |
| - | - |
| `SUFFICIENT` | 해상도 충분 |
| `LOW_RESOLUTION` | 해상도가 낮아 주소나 업종을 잘못 읽었을 수 있음. 더 큰 이미지나 PDF로 다시 받으세요 |

### 입력 화면에 미리 채우기

`validation`이 `MATCHED`이고 `inputQuality`가 `SUFFICIENT`면 입력 화면에 값을 미리 채워도 됩니다. 저장하거나 세금계산서를 발행하기 전에는 사용자가 값을 확인하고 고칠 수 있게 하세요.

## 처리 시간

API는 요청 하나를 최대 약 45초 안에 끝냅니다. 클라이언트 읽기 타임아웃은 60초 이상으로 잡으세요. 그 안에 인식하지 못하면 API가 `503 EXTRACTION_UNAVAILABLE`을 반환합니다.

## 데이터 보관

볼타는 올린 파일과 읽은 값을 저장하지 않습니다. 응답에는 주민등록번호 같은 개인식별번호를 담지 않습니다.

## 테스트 키

테스트 키로 보내면 올린 파일과 관계없이 위 응답 예시와 같은 고정 결과를 돌려주고 포인트를 차감하지 않습니다. 빈 파일, 5MB 초과, 지원하지 않는 형식은 라이브 키와 같은 오류를 반환합니다.

고정 결과의 `1000000014`는 [사업자등록 상태 조회](/docs/api-introduction/business-registration-status) 테스트 키의 계속사업자 번호와 같습니다. 인식 결과를 상태 조회 테스트 호출에 그대로 이어 볼 수 있습니다.

## 호출 한도

| 한도 | 값 | 넘으면 |
| - | - | - |
| 동시 요청 | 파트너당 1건. 라이브 키만 해당 | `429 TOO_MANY_IN_FLIGHT` |
| 하루 처리량 | 24시간에 1,000건. 테스트 키와 라이브 키는 따로 셈 | `429 RATE_LIMITED` |
| 볼타 인식 처리량 | 볼타 전체 공유 | `429 RATE_LIMITED` |

라이브 키는 앞 요청의 응답을 받은 뒤 다음 파일을 보내세요. 같은 파트너의 라이브 키가 여러 개여도 동시 요청을 함께 셉니다.

`429`를 받으면 `Retry-After` 헤더의 초만큼 기다린 뒤 같은 파일로 다시 보내세요.

## 오류

| 상태 코드 | 에러 코드 | 발생 조건 |
| - | - | - |
| `400` | `INVALID_REQUEST` | `file` 파트 누락, 빈 파일, 5MB 초과 |
| `400` | `INVALID_FILE` | 지원하지 않는 형식, 읽을 수 없는 파일, 5쪽 초과 PDF, 사업자등록증이 아니거나 사업자등록번호를 읽을 수 없는 파일 |
| `401` | - | API 키 인증 실패. 응답 본문 없음 |
| `402` | `PAYMENT_REQUIRED` | 포인트 잔액 부족. 개발자센터에서 충전하세요 |
| `409` | `POINT_RESERVED_BY_IN_FLIGHT_REQUESTS` | 처리 중인 요청까지 합치면 잔액 부족. 충전하거나 끝난 뒤 다시 요청하세요 |
| `415` | `UNSUPPORTED_MEDIA_TYPE` | `Content-Type`이 `multipart/form-data`가 아님 |
| `429` | `TOO_MANY_IN_FLIGHT` | 같은 파트너의 처리 중인 요청이 있음. `Retry-After` 뒤에 다시 시도하세요 |
| `429` | `RATE_LIMITED` | 하루 처리 한도 초과 또는 볼타 인식 처리량 포화. `Retry-After` 뒤에 다시 시도하세요 |
| `500` | `INTERNAL_SERVER_ERROR` | 서버 내부 오류 |
| `503` | `EXTRACTION_UNAVAILABLE` | 인식 실패 또는 처리 시간 초과. 잠시 후 다시 시도하세요 |
| `503` | `LOOKUP_UNAVAILABLE` | 호출 한도를 판정할 수 없음 |
| `503` | `SERVICE_UNAVAILABLE` | 일시적인 내부 API 통신 오류 |

`INVALID_FILE`의 `message`는 원인마다 다르고, 사용자에게 그대로 보여 줘도 됩니다.

| 원인 | `message` |
| - | - |
| 형식 | jpg, png, webp, pdf 형식만 업로드할 수 있습니다. |
| 읽을 수 없는 파일 | 파일을 읽을 수 없습니다. 사업자등록증 파일을 확인해 주세요. |
| 쪽수 | 5쪽 이하의 PDF만 업로드할 수 있습니다. |
| 사업자등록증이 아니거나 사업자등록번호를 읽을 수 없음 | 사업자등록증을 찾지 못했습니다. 사업자등록증명이나 등기사항증명서 같은 다른 서류는 받지 않습니다. 사업자등록증 파일을 확인해 주세요. |

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

## 관련 문서

* [사업자등록증 인식과 진위확인 API](/api-reference/business-registration-certificate-extraction-and-verification/extract-and-verify-business-registration-certificate)
* [요금 안내](/docs/api-introduction/pricing)
* [사업자등록 상태 조회](/docs/api-introduction/business-registration-status)