> ## 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. # 예금주 일괄 조회 > 계좌 1~100개의 예금주명을 한 번에 조회합니다. 계좌마다 결과 하나를 요청과 같은 순서로 돌려줍니다. 찾지 못한 계좌는 `holderName`이 `null`이고 `error`에 원인이 옵니다. 한 계좌도 판정하지 못하면 이 응답 대신 `503`을 반환합니다. [예금주 조회 가이드](/docs/api-introduction/bank-account-holder) ## OpenAPI ````yaml /openapi.yaml post /v1/bankAccountHolders:bulkInquire openapi: 3.1.0 info: title: 볼타 API description: > 볼타 전자세금계산서 API입니다. [API 소개](/docs/api-introduction/overview) | [인증 가이드](/docs/api-introduction/authentication) | [사용 사례](/docs/api-introduction/usecase-b2b) version: 1.0.0 servers: - url: https://xapi.bolta.io description: 볼타 API 서버 security: - basicAuth: [] tags: - name: 세금계산서 발행 description: > 전자(세금)계산서를 정발행하거나 수정발행합니다. [발행 금액 계산](/docs/api-introduction/issuance-guide) | [수정발행 유형](/docs/api-introduction/amendment-guide) - name: 세금계산서 조회 description: 전자(세금)계산서의 발행 결과와 요청 처리 상태를 조회합니다. - name: 세금계산서 역발행 description: > 전자(세금)계산서 역발행 요청 및 관리. [이메일 승인 역발행](/docs/api-introduction/usecase-reverse-email) | [간편 승인 역발행](/docs/api-introduction/usecase-reverse-simple) - name: 현금영수증 description: > 현금영수증을 발행하거나 취소하고 처리 상태를 조회합니다. 최종 결과는 웹훅이나 상태 조회 API로 확인하세요. [현금영수증 발행 가이드](/docs/api-introduction/cash-receipt-guide) | [현금영수증 웹훅](/docs/api-introduction/webhook-cash-receipt) - name: 사업자등록 상태 조회 description: > 사업자등록번호의 등록 상태와 과세유형을 단건 또는 최대 100건 일괄로 조회합니다. 발급자 등록과 공동인증서가 필요 없습니다. [사업자등록 상태 조회 가이드](/docs/api-introduction/business-registration-status) - name: 입출금내역 조회 description: > 볼타에 연결한 내 사업자의 입출금 계좌와 입출금내역을 조회하고 동기화를 요청합니다. 스탠다드 플랜 이상을 구독해야 하며 포인트는 차감하지 않습니다. 계좌는 볼타 대시보드에서 먼저 연결하세요. [입출금내역 조회 가이드](/docs/api-introduction/bank-account-transactions) - name: 예금주 조회 description: > 은행코드와 계좌번호로 예금주명을 조회합니다. 한 계좌씩 묻는 경로와 최대 100개를 한 번에 묻는 경로가 있습니다. 예금주를 돌려준 계좌마다 50포인트를 차감합니다. [예금주 조회 가이드](/docs/api-introduction/bank-account-holder) - name: 서류 발급 description: > 홈택스 국세 증명 서류를 발급하고 원본 PDF를 내려받습니다. API 키가 속한 사업자의 서류만 발급하며, 볼타 대시보드에 공동인증서를 등록해야 합니다. 서류 한 건에 500포인트를 차감합니다. [서류 발급 가이드](/docs/api-introduction/document-issuance) - name: 발급자 description: > 세금계산서 발행 주체인 발급자를 등록하고 관리합니다. 발행 방식에 따라 공동인증서 필요 여부가 다릅니다. [용어 정리](/docs/api-introduction/glossary) | [대리 정발행](/docs/api-introduction/usecase-delegated) | [위수탁 발행](/docs/api-introduction/usecase-brokered) - name: 인증서 description: > 발급자 공동인증서 등록 및 관리. [인증서 등록](/docs/api-introduction/certificate-registration) paths: /v1/bankAccountHolders:bulkInquire: post: tags: - 예금주 조회 summary: 예금주 일괄 조회 description: > 계좌 1~100개의 예금주명을 한 번에 조회합니다. 계좌마다 결과 하나를 요청과 같은 순서로 돌려줍니다. 찾지 못한 계좌는 `holderName`이 `null`이고 `error`에 원인이 옵니다. 한 계좌도 판정하지 못하면 이 응답 대신 `503`을 반환합니다. [예금주 조회 가이드](/docs/api-introduction/bank-account-holder) requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BankAccountHolderBulkInquiryRequest' examples: 두 계좌 조회: x-parity-id: bulk summary: 일반 계좌와 금액 확인형 가상계좌 value: accounts: - bankCode: '088' accountNumber: '1000000001' - bankCode: '089' accountNumber: '1000000004' responses: '200': description: 계좌마다 결과 하나. 순서는 요청과 같습니다. content: application/json: schema: $ref: '#/components/schemas/BankAccountHolderBulkResponse' examples: 일부 실패: x-parity-id: bulk-partial summary: 한 계좌는 찾고 한 계좌는 실패 value: results: - bankCode: '088' accountNumber: '1000000001' holderName: 홍길동 error: null - bankCode: '089' accountNumber: '1000000004' holderName: null error: code: AMOUNT_REQUIRED message: 입금 금액이 정해진 가상계좌입니다. 총 지급 금액을 입력한 뒤 예금주를 다시 조회해 주세요. headers: {} '400': description: > 요청이 잘못됐습니다. 응답의 `code`는 `INVALID_REQUEST`입니다. 계좌가 없거나 100개를 넘으면, 또는 항목 하나라도 형식이 틀리면 요청 전체를 거절합니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: API 키 인증 실패. 응답 본문이 없습니다. '402': description: 포인트 잔액이 부족합니다. 응답의 `code`는 `PAYMENT_REQUIRED`입니다. 개발자센터에서 충전하세요. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: 요청한 리소스에 접근할 권한이 없습니다. 응답의 `code`는 `FORBIDDEN`입니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- 처리 중인 요청이 잡아 둔 포인트까지 합치면 잔액이 모자랍니다. 응답의 `code`는 `POINT_RESERVED_BY_IN_FLIGHT_REQUESTS`입니다. 충전하거나 처리 중인 요청이 끝난 뒤 다시 요청하세요. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: >- 하루 조회 한도에 도달했습니다. 응답의 `code`는 `RATE_LIMITED`입니다. 한도는 요청 수가 아니라 조회한 계좌 수로 셉니다. `Retry-After` 이후에 다시 시도하세요. headers: Retry-After: description: 재시도까지 남은 시간(초) schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: 서버 내부 오류. 응답의 `code`는 `INTERNAL_SERVER_ERROR`입니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: | 한 계좌도 판정하지 못했습니다. 응답의 `code`로 원인을 구분하세요. `BANK_UNAVAILABLE`: 은행 점검이나 연결 오류입니다. 잠시 후 다시 시도하세요. `LOOKUP_UNAVAILABLE`: 조회 보호 한도를 판정할 수 없습니다. `SERVICE_UNAVAILABLE`: 일시적인 내부 API 통신 오류입니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' deprecated: false components: schemas: BankAccountHolderBulkInquiryRequest: type: object description: 예금주 일괄 조회 요청 properties: accounts: type: array minItems: 1 maxItems: 100 description: 조회할 계좌. 1개 이상 100개 이하로 넣으세요. items: $ref: '#/components/schemas/BankAccountHolderInquiry' required: - accounts BankAccountHolderBulkResponse: type: object description: 예금주 일괄 조회 결과 properties: results: type: array minItems: 1 maxItems: 100 description: 요청한 계좌마다 항목 하나. 순서는 요청과 같습니다. items: $ref: '#/components/schemas/BankAccountHolderBulkItem' required: - results ErrorResponse: type: object description: API 요청 실패 시 반환되는 에러 응답 properties: code: type: string description: 에러 타입 식별자 message: type: string description: 에러 설명 traceId: type: string description: 요청 추적 식별자 required: - code - message - traceId BankAccountHolderInquiry: type: object description: 예금주를 조회할 계좌 properties: bankCode: type: string pattern: ^\d{3}$ description: >- 금융결제원 3자리 표준 은행코드. 지원하는 은행은 [예금주 조회 가이드](/docs/api-introduction/bank-account-holder)를 참고하세요. examples: - '088' accountNumber: type: string pattern: ^-*(?:\d-*){6,20}$ description: 계좌번호. 하이픈을 포함해도 됩니다. 하이픈을 뺀 숫자가 6~20자리여야 합니다. examples: - '1000000001' amount: type: integer format: int64 minimum: 1 description: 금액 확인형 가상계좌의 입금 금액(원). 일반 계좌는 비워 두세요. required: - bankCode - accountNumber BankAccountHolderBulkItem: type: object description: 계좌 한 건의 조회 결과 oneOf: - properties: holderName: type: string error: type: 'null' - properties: holderName: type: 'null' error: $ref: '#/components/schemas/BankAccountHolderInquiryError' properties: bankCode: type: string description: 요청한 은행코드 accountNumber: type: string description: 하이픈을 뗀 계좌번호 holderName: type: - string - 'null' description: 예금주명. 찾지 못했으면 `null`입니다. error: description: 예금주를 찾지 못한 원인. 찾았으면 `null`입니다. anyOf: - $ref: '#/components/schemas/BankAccountHolderInquiryError' - type: 'null' required: - bankCode - accountNumber - holderName - error BankAccountHolderInquiryError: type: object description: 일괄 조회 항목이 실패한 원인. 단건 조회가 받는 `code`와 같은 어휘입니다. properties: code: type: string enum: - ACCOUNT_NOT_VERIFIED - ACCOUNT_NOT_AVAILABLE - AMOUNT_REQUIRED - AMOUNT_MISMATCH - AMOUNT_VERIFICATION_UNAVAILABLE - UNSUPPORTED_BANK - BANK_UNAVAILABLE - LOOKUP_UNAVAILABLE - SERVICE_UNAVAILABLE - PAYMENT_REQUIRED - POINT_RESERVED_BY_IN_FLIGHT_REQUESTS - RATE_LIMITED - FORBIDDEN - INVALID_REQUEST description: 에러 타입 식별자 message: type: string description: 에러 설명. 한국어 문장입니다. required: - code - message securitySchemes: basicAuth: type: http scheme: basic description: API 키를 Base64 인코딩하여 전달합니다. Username에 API 키를 입력하고 Password는 비워두세요. ````