거래처 등록 화면에 검색과 자동 입력 기능을 붙이려면 볼타 사업자 프로필 조회 API를 연동하면 된다. 상호나 대표자명으로 후보를 검색하는 기능과 사업자등록번호로 상세 정보를 한 번에 받아오는 기능을 따로 제공하므로, 둘을 조합해 검색창에서 선택만 하면 주소·업태·종목까지 자동으로 채워지는 화면을 만들 수 있다. 발급자 등록이나 공동인증서, 별도 구독 플랜 없이 API 키만 있으면 바로 호출할 수 있고, 검색은 건당 9원, 상세 조회는 건당 90원으로 과금된다(2026년 10월 기준). 다만 등록 상태와 과세유형은 실시간 값이 아니라 마지막으로 확인된 저장 값이므로, 거래 직전에는 별도의 등록 상태 조회 API로 다시 확인해야 한다.
거래처 등록 화면, 왜 자동화가 필요한가
거래처를 등록할 때 담당자가 상호, 대표자명, 주소, 업태, 종목을 하나씩 직접 입력하는 방식은 시간이 오래 걸리고 오탈자가 생기기 쉽다. 특히 사업자등록번호를 모르는 상태에서 거래처명만 알고 있을 때는 검색 한 번으로 후보를 찾아 선택하는 흐름이 필요하다. 반대로 사업자등록번호를 이미 알고 있다면 검색 과정 없이 바로 상세 정보를 받아 입력란을 채우는 것이 더 효율적이다.
두 상황을 하나의 화면에서 모두 처리하려면 검색 기능과 상세 조회 기능을 함께 설계해야 한다. 검색 결과에서 후보를 선택하면 그 사업자등록번호로 상세 조회를 호출해 나머지 정보를 자동 입력하는 식이다. 이렇게 연결하면 담당자는 이름 일부만 입력하고 목록에서 클릭 한 번으로 거래처 등록을 마칠 수 있다.
사업자 프로필 조회 API란
사업자 프로필 조회 API는 검색 기능과 상세 조회 기능으로 나뉜다. 검색은 상호, 이전 상호, 영문 상호, 대표자명으로 찾을 수 있고 상호 초성이나 사업자등록번호로도 찾을 수 있다. 상세 조회는 사업자등록번호를 알고 있을 때 그 사업자 하나의 프로필 전체를 받아오는 기능이다.
실제 연동 전에는 테스트 키로 먼저 시험해볼 수 있다. 테스트 키는 실제 데이터를 읽지 않고 고정된 모의 데이터를 돌려주며, '테스트상사'를 검색하면 후보 선택과 상세 조회까지 전체 흐름을 미리 확인할 수 있다. 다만 공공 데이터에 값이 없는 항목은 비어 있고, 대표자명이 원천 자료에서 가려진 형태라면 가려진 그대로 받게 되므로 입력 화면에서는 이런 빈 값을 사용자가 직접 채울 수 있도록 남겨 두어야 한다.
이름으로 검색하고 후보 선택하기
검색 기능은 사업자등록번호를 모르는 상태에서 거래처를 찾을 때 쓴다. 상호나 이전 상호, 영문 상호, 대표자명을 입력하면 조건에 맞는 후보 목록이 돌아오고, 상호의 초성이나 사업자등록번호 일부로도 검색할 수 있어 정확한 이름이 기억나지 않아도 후보를 좁힐 수 있다.
검색 결과로는 상호, 사업자등록번호, 지역, 가운데를 가린 대표자명, 저장된 등록 상태가 함께 돌아온다. 담당자는 이 정보를 보고 동명의 다른 거래처와 혼동하지 않고 올바른 후보를 선택할 수 있다. 목록에서 거래처를 선택하면 그 사업자등록번호를 다음 단계인 상세 조회에 넘기면 된다.
상세 정보로 자동 입력하기
상세 조회는 검색에서 선택한 사업자등록번호, 또는 이미 알고 있는 사업자등록번호를 넣어 그 사업자 하나의 전체 프로필을 받는 기능이다. 응답에는 상호, 대표자, 주소, 전화번호와 이메일, 업태와 종목, 개업일이 포함되어 거래처 등록 화면의 대부분의 입력란을 한 번에 채울 수 있다.
다만 모든 값이 항상 채워지는 것은 아니다. 선택한 사업자의 상세 프로필로 상호, 대표자, 주소, 업태, 종목을 채우되 공공 데이터에 없는 값은 비어 있으므로, 입력 화면은 자동 입력 후에도 사용자가 빈 칸을 직접 수정하거나 채울 수 있도록 열어 두어야 한다.
검색과 상세 조회 비교
두 기능은 쓰는 상황과 받는 정보 범위가 다르다. 화면을 설계할 때는 아래 표를 기준으로 어떤 입력값을 받을지, 어떤 결과를 돌려줄지 구분해서 적용하면 된다.
구분 | 검색 API | 상세 조회 API |
|---|---|---|
사용 시점 | 사업자등록번호를 모를 때 | 사업자등록번호를 알 때 |
입력값 | 상호, 이전 상호, 영문 상호, 대표자명, 초성, 사업자등록번호 | 사업자등록번호 1건 |
반환 정보 | 상호, 사업자등록번호, 지역, 가린 대표자명, 저장된 등록 상태 | 상호, 대표자, 주소, 전화번호와 이메일, 업태와 종목, 개업일 |
과금 기준 | 결과 1건당 9원 | 조회 성공 1건당 90원 |
두 기능이 갈리는 지점은 '사업자등록번호를 이미 알고 있는가'이다. 거래처명만 알고 있는 신규 등록 화면에서는 검색을 먼저 호출해 후보를 좁히고, 이미 사업자등록번호를 보유한 기존 거래처 정보를 갱신하는 화면이라면 검색 없이 상세 조회만 호출하는 편이 비용과 단계를 줄일 수 있다. 신규 거래처 등록 화면은 검색과 상세 조회를 순서대로 연결하고, 기존 거래처 정보 갱신 화면은 상세 조회만 단독으로 쓰는 것이 일반적인 구성이다.
과금 방식 알아보기
2026년 10월 기준, 검색 API는 돌려준 결과 1건당 9원이고 상세 조회 API는 조회에 성공한 사업자등록번호 1건당 90원이다. 검색에서 결과가 여러 건 돌아오면 건수만큼 과금되고, 상세 조회는 호출 1건이 아니라 성공적으로 조회된 사업자등록번호 기준으로 과금된다는 점을 기억해야 한다.
비용이 발생하지 않는 경우도 명확하다. 검색 결과가 없는 경우와 테스트 키로 호출하는 경우는 차감되지 않는다. 반대로 같은 사업자등록번호를 상세 조회로 다시 조회하면 매번 다시 차감되므로, 화면 안에서 같은 거래처 정보를 캐시 없이 반복 조회하도록 구현하면 불필요한 비용이 쌓일 수 있다. 이미 받아온 상세 정보는 화면 상태나 임시 저장소에 보관해 재호출을 피하는 방식으로 설계하는 것이 좋다.
등록 상태 확인이 필요하다면
검색 결과와 상세 조회 결과에 포함된 등록 상태와 과세유형은 실시간으로 조회되는 값이 아니라 마지막으로 확인되어 저장된 값이다. 거래처 등록 화면에 보여주는 용도로는 충분하지만, 세금계산서 발행이나 거래 승인처럼 현재 시점의 정확한 상태가 중요한 작업 직전에는 이 저장된 값만 보고 판단하면 안 된다.
현재 등록 상태가 폐업이나 휴업으로 바뀌었는지, 과세유형이 변경되었는지를 실제 거래 전에 확인하려면 별도의 사업자등록 상태 조회 API를 호출해야 한다. 거래처 등록 화면에서는 프로필 조회 API로 기본 정보를 채우고, 실제 거래나 세금계산서 발행 직전 단계에서는 상태 조회 API를 한 번 더 호출하는 이중 구조로 설계하는 것이 안전하다.
도입 방법과 시작하기
사업자 프로필 조회 API는 발급자 등록이나 공동인증서, 별도 구독 플랜 가입 없이 API 키만 발급받으면 바로 연동할 수 있다. 복잡한 심사나 서류 절차 없이 테스트 키로 먼저 검색과 상세 조회 흐름을 확인한 뒤, 실제 키로 전환해 서비스에 반영하는 순서로 진행하면 된다.
API 키를 발급받고 테스트 키로 '테스트상사' 검색 결과 화면을 확인한다.
검색 응답의 상호, 사업자등록번호, 지역, 가린 대표자명 항목이 거래처 목록 UI에 제대로 표시되는지 확인한다.
후보 선택 후 상세 조회를 호출해 상호, 대표자, 주소, 업태, 종목이 입력 폼에 자동으로 채워지는지 확인한다.
공공 데이터에 없는 빈 값을 사용자가 직접 수정할 수 있도록 입력 폼의 편집 가능 여부를 점검한다.
실제 키로 전환하고, 거래 직전 단계에는 등록 상태 조회 API 호출을 추가할지 결정한다.
자주 묻는 질문
검색 API만 쓰고 상세 조회는 안 써도 되나요?
가능하다. 검색 결과에도 상호, 사업자등록번호, 지역, 저장된 등록 상태가 포함되므로 간단한 확인 용도라면 검색만으로 충분할 수 있다. 다만 주소나 업태, 종목처럼 거래처 등록 화면에 필요한 세부 정보는 상세 조회를 거쳐야 채울 수 있다.
대표자명이 가려져서 나오는 이유는 무엇인가요?
검색 결과의 대표자명은 가운데를 가린 형태로 제공되며, 상세 조회에서도 원천 자료 자체가 가려진 값이면 가려진 그대로 돌아온다. 이는 공공 데이터의 원본 표기 방식을 따른 것이므로 화면에서 별도로 전체 이름을 복원할 수는 없다.
같은 거래처를 여러 번 조회하면 비용이 계속 나가나요?
그렇다. 상세 조회는 같은 사업자등록번호라도 다시 조회할 때마다 다시 차감된다. 반복 조회로 인한 비용을 줄이려면 이미 받아온 정보를 화면이나 임시 저장소에 보관해 재사용하는 방식을 권장한다.
테스트 키로 연동 전체를 검증할 수 있나요?
테스트 키는 실제 데이터 대신 고정된 모의 데이터를 돌려주므로 '테스트상사'를 검색해 후보 선택과 상세 조회까지의 전체 흐름과 화면 구성을 검증할 수 있다. 다만 실제 호출 비용이나 실 데이터의 빈 값 패턴까지 확인하려면 실제 키로도 한 번 테스트해보는 것이 좋다.
등록 상태가 저장된 값이라면 언제 다시 확인해야 하나요?
거래처 등록 단계에서는 저장된 등록 상태를 화면에 표시하는 정도로 충분하지만, 세금계산서 발행이나 실제 거래 승인처럼 현재 상태가 중요한 시점 직전에는 별도의 사업자등록 상태 조회 API로 다시 확인해야 한다.