"홈택스 전자세금계산서 API 연동"으로 자동화 하는 개발 후기, 무료 개발테스트 환경 제공 방법

SOAP 기반의 "홈택스전자세금계산서API" 연동 솔루션 소개 - 바로빌

얼마 전 프로젝트로 바쁘다는 공지를 드렸던 프로젝트가 성공적으로 마무리되어 서비스를 오픈되었습니다. 이 프로젝트는 프랜차이즈 가맹점을 많이 보유한 고객사의 CTO 요구에 따라, 기존에 혼용되었던 어플리케이션, 웹, 모바일 등을 웹 기반으로 전환하는 고도화 사업이었습니다.

 

특히 ERP와 EDI를 활용한 프랜차이즈 가맹점의 홈택스전자세금계산서를 대행하기 위해 회사 전체의 전자세금계산서 연동 시스템을 웹 기반으로 전환하는 사업이고, 발급 건수는 약 1만 건 정도를 예상하고 진행되었습니다.

바로빌 홈택스세금계산서API 소개 영상

 

성공적인 구축을 위해 구글 검색과 지인 추천을 통해 여러 솔루션을 기술 상담 및 기술지원, 견적서를 참고하여 벤츠마크 테스트 한 결과, 개발팀과 고객사 모두로부터 높은 만족도를 얻은 바로빌(barobill)의 "홈택스전자세금계산서API" 솔루션을 선택했습니다. 👍

 

이번 성공적인 프로젝트 경험을 공유하여 웹 기반의 "홈택스자세금계산서API" 개발에 어려움을 겪고 있는 개발자와 CTO분들께 조금이나마 유용한 정보가 되시길 바랍니다. 

 

그럼 바로빌의 API 사용법과 주요 기능을 살펴보고, 이를 그룹웨어 및 사이트에 어떻게 적용할 수 있는지 알아보겠습니다.

 

홈택스전자세금계산서API란?

"홈택스전자세금계산서API"는 거래 발생 시 전자세금계산서를 효과적으로 발행하고 관리하는 데 필수적인 도구로, 이 API는 국세청 홈택스와 연동되어 세금 업무를 신속하고 정확하게 처리할 수 있도록 지원하며, 매번 국세청 홈택스 시스템에 접속할 필요 없이 시간과 비용을 절약할 수 있어 자동화와 효율성을 높여줍니다.

 

특히 바로빌은 국세청과 동일한 SOAP(Simple Object Access Protocol) 방식을 제공하여 전자세금계산서 연동을 다양한 백엔드 개발 언어( JAVA , .NET, PHP 등)에서 손쉽게 연동할 수 있어, 다양한 비즈니스 환경에 맞춰 활용이 가능하여 호환성과 연동 기술 지원 및 운영 유지보수를 무료로 제공한다는 점에서 매우 뛰어난 장점을 제공합니다.

개발 테스트 할 수 있는 테스트 사이트 화면

▶ API 종류와 주요 기능 및 특징 

API 기능명	기능 설명
홈택스전자(세금)계산서 매입매출 조회 API	국세청 홈택스에 API로 연동하여 전자세금계산서를 조회 및 발급할 수 있습니다. 거래명세서, 청구서 등 다양한 전자문서도 함께 발급할 수 있습니다.
홈택스 현금영수증 매입매출 조회 API	국세청 홈택스에 API로 연동하여 현금영수증을 조회 및 발급할 수 있습니다.
전자(세금)계산서 발급 API	API를 통해 표준 전자세금계산서를 발급할 수 있습니다. 거래명세서, 청구서 등 다양한 전자문서도 함께 발급할 수 있습니다.
사업자 등록 번호 조회 API	사업자 등록 번호를 기준으로 조회 및 전자문서를 함께 발급할 수 있습니다.
전자문서 발급 API	표준 전자문서를 발급할 수 있습니다.
현금영수증 발급 API	현금영수증을 발급하고 조회할 수 있어, 별도의 단말기 없이 간편하게 활용 가능합니다.
문자/카카오톡 전송 API	발급한 세금계산서나 현금영수증을 문자나 카카오톡으로 알림 전송할 수 있습니다.
팩스 전송 API	조회된 다양한 전자문서 등을 팩스로 전송할 수 있습니다.
사업자등록 상태조회 API	사업자등록 상태조회를 제공합니다.
카드사용내역 조회 API	사업자 및 사용자의 카드 사용 내역을 조회할 수 있습니다.
계좌거래내역조회 API	사업자 및 사용자의 계좌거래내역을 조회할 수 있습니다.
사업자 휴폐업 상태 조회	전자세금계산서 발급 전 거래처의 휴폐업 상태를 조회하여 불필요한 오류를 방지할 수 있습니다.

기본적으로 "홈택스전자세금계산서API"는 표준 전자세금계산서 연동 및 국세청 홈택스와 API 연동하여 조회, 발급, 관리 등을 모두 제공합니다.

 

개발사를 위한 개발 환경

바로빌의 "세금계산서 API"를 사용하기 위해서는 다음과 같은 개발 환경을 구축하여 테스트할 수 있습니다. 제가 프로젝트 진행했던 경험을 중심으로 설명드리고 상세한 내용은 바로빌 개발자센터에서 개발 환경 구축 및 가이드를 모두 확인할 수 있습니다. 

 

1. 백엔드 지원 개발 언어 

국세청 홈택스의 세금계산서 API를 연동하기 위해서는 SOAP 지원 언어와 패키지를 사용해야 합니다. 바로빌에서는 "세금계산서 API"를 지원하는 개발 언어와 제공 방식을 아래와 같이 안내하고 있습니다.

백엔드 개발언어	제공 방법
Java	jar 제공
.NET	Visual Studio 의 서비스 참조 추가, 웹 참조 추가 사용
Python	Zeep 패키지 사용
Node.js	soap 패키지 사용
PowerBuilder	New > Project > Web Service Proxy Wizard 사용
Delphi	File > New > Other > WebServices > WSDL Importer 사용
PHP	내장된 SOAP 모듈을 사용
ASP	SDK 클래스 모음 제공
Visual Basic 6.0	SDK 클래스 모음 제공

개발자에게 최적화된 연동 개발 환경을 마련하기 위해, 테스트 환경, 가이드 문서, 기술 지원 등 세 가지 요소를 바로빌에 문의하고 요청하는 것이 가능합니다. 구체적인 개발 환경 설정 및 절차에 대한 정보는 바로빌 세금계산서 API 개발 준비 가이드에서 확인하실 수 있습니다. 

 

2. 개발 IDE 툴

• 백엔드 개발 IDE: 자바(Java)를 사용하기 위해서는 이클립스(Eclipse)를 사용했고 .NET의 C#을 사용하기 위해서는 비주얼 스튜디오 2022(Visual Studio 2022) 그 외 인텔리제이(Intellij)도 사용했습니다.

• 프런트 엔드 개발 IDE: 비주얼스튜디오 코드(Visual Studio Code)와 인텔리제이(Intellij)를 사용했습니다. 

• 모바일(iOS 및 안드로이드) IDE: 안드로이드 스튜디오(Android Studio)의 플러터(Flutter) 기반의 웹앱을 사용했습니다. 

개발 IDE

 

3 서버 환경 

진행한 프로젝트는 웹, DB, 파일, API 서버를 리눅스(Linux) 기반으로 로드밸런싱(Load Balancing)을 적용하여 구축했고, 특정 이전 솔루션과의 호환성을 위해 윈도우 서버를 한 대 포함시켰는데, 바로빌의 "전자세금계산서 연동" 솔루션은 이 모든 환경을 완벽하게 지원하여 문제가 없었습니다. 

 

• 윈도우 서버 프로그램은 기존 솔루션과의 호환성을 유지하기 위해 .NET C#을 사용하여 개발되었으며, 스케줄러(Scheduler)를 통해 정해진 날짜에 배치(Batch, fixedDay)로 데이터를 FTP로 전송하여 백업하는 기능을 업데이트하였습니다. 

스케줄러로 FTP로 데이터 배치 진행하는 데이터 백업

• 서버 구성도는 고객사 보안 관계로 생략하겠습니다. 

 

4. 개발 코드 샘플 테스트 

프로젝트에 사용했던 백엔드 개발 언어는 자바(Java)와 .Net기반이 C#으로 진행했고, 프런트엔드는 자바 스크립트(JavaScript)와 리엑트(Reat)로 구성하여 페이지 뷰 파싱 작업을 진행했습니다. 

 

바로빌 개발자센터의 '홈택스세금계산서 API 개발 가이드'를 참조하시고, '샘플 소스 다운로드' 메뉴에서 지원하는 다양한 개발 언어 중 사용하시는 언어의 파일을 다운로드하실 수 있습니다. 저희는 자바(Java)와 .NET 기반의 C# 샘플 소스를 설치하여 테스트를 진행했습니다.

자바(Java)와 .NET 기반의 C# 샘플 소스

 

5. 심플한 코드로 환경 테스트 진행

바로빌의 개발자 센터에서 제공하는 API를 사용하면 아래 언어별 코드로 심플하게 제공하고 있어 개발 서버에 소스를  세팅 후에 자바(Java)와 .Net기반의 C#을 테스트해서 문제없이 데이터를 SOAP 환경의 XML 기반의 메시지로 확인할 수 있었습니다. 

 

• 스프링(Spring) 프레임웍 환경의 자바 코드 예시 화면 

스프링(Spring) 프레임웍 및 자바 코드 예시 화면

• .Net C# 코드 예시 화면 

.Net C# 코드 예시 화면

이와 같이 홈택스세금계산서API 연동을 위한 개발 언어별 기본 환경을 구성할 수 있으며, 가이드 문서를 통해 SOAP 기반 연동을 처음 접하는 분들도 쉽게 진행할 수 있습니다. 필요한 도움은 고객센터를 통해 견적서와 무료로 기술 지원을 받을 수 있으니, 문제가 생겼을 때 주저하지 말고 연락해 보세요.~ 📞👍

 

저 또한 홈택스 연동을 처음 할 때 많은 기술 지원을 요청했던 경험이 있습니다. 🤣💦

 

개발 테스트 사용 방법

이제 개발 서버에서 테스트를 정식으로 진행하거나 바로빌이 제공하는 대시보드를 사용하는 방법을 살펴보겠습니다.

 

1. 바로빌 개발자 센터 웹사이트(https://dev.barobill.co.kr)에 접속하여 무료로 회원가입하고 로그인합니다. 

2. '내 파트너 목록 보기' 메뉴에서 연동할 사이트의 등록을 위해 해당 사이트로 이동합니다. 

3. 테스트할 사이트를 등록하기 위해 "새 파트너 등록하기"와 "기존 파트너 등록하기" 중에서 "새 파트너 등록하기"를 선택합니다.

내 파트너 목록 보기 > 파트너 목록 화면

4. 새 파트너 등록 안내에 따라 모든 절차를 진행하여 등록을 완료합니다.

새 파트너 등록 과정

• 개발 서버에 테스트했을 때 대시 보드를 별도로 만들어서 API를 각 메뉴 및 항목에 넣어 데이터 값이 나오도록 구성하여 UI 화면을 고객사의 요구사항에 맞추어 테스트 검증을 진행했던 화면입니다. 

테스트 서버에서 별도로 제작한 대시 보드에서 API로 연동한 데이터 값을 조회 및 관리하는 화면

5. 새 파트너가 등록되면, 테스트용과 운영용 연동 인증키가 자동으로 발급됩니다. 

1. 연동인증키는, B5B015A0-XXXX-XXXX-XXXX-0242AC130003 와 같은 36자리의 UUID 형식으로 되어 있습니다.
2. React, Angular, Vue와 같은 front-end 기반 기술을 사용하시는 경우, 브라우저에서 연동인증키에 접근할 수 없도록 설정해야 합니다.

6. 등록된 파트너 목록에서 확인하고자 하는 파트너를 선택하세요.

테스트 할 등록된 파트너 사이트

7. 왼쪽 콘솔 메뉴에서 '인증키 및 제휴 정보'를 선택하여 확인하실 수 있습니다.

인증키 정보

8. 콘솔에서 모든 API는 파트너와 회원사를 식별하기 위해 첫 번째 파라미터에는 파트너의 연동 인증키를, 두 번째 파라미터에는 회원사의 사업자 번호를 입력하여 확인합니다.

인증키 식별 확인

• 파트너와 회원사가 연결되지 않은 경우에는 API 호출에 실패하게 됩니다.
• 파트너, 회원사의 연결에 대한 자세한 내용은 바로빌 API 기본구조 가이드 - 회원구조를 참고해 주세요.

 

기본 개발 환경을 이렇게 설정하고 검증할 수 있습니다. 

 

테스트 사이트, FTP, 방화벽, API URL 제공

바로빌 테스트 사이트는 개발자들이 바로빌 API를 이용하여 생성된 자료를 확인하고 기능을 테스트할 수 있는 공간을 제공합니다. 또한, 이 사이트를 통해 원하는 화면 구성에 대한 아이디어를 얻을 수 있습니다. 

 

1. 테스트용 바로빌 사이트: 바로빌 테스트 사이트 (https://test.barobill.co.kr)
2. 테스트용 바로빌 FTP: 바로빌 테스트 FTP

3. 방화벽: Outbound 방화벽 설정된 환경에서 연동하는 경우, 바로빌 API 서버에 대해 Outbound 방화벽 허용 설정이 필요합니다. 관련 내용은 방화벽 설정에서 확인할 수 있습니다.

4. 바로빌 API는 각 테스트 및 운영 환경 서비스별로 별도의 URL을 제공합니다.

• 테스트 개발 환경의 서비스 기능별 API 주소 

테스트 서버 API 주소

• 운영 환경의 서비스 기능별 API 주소 

운영 서버 API 주소

5. 개발 언어 환경에 맞는 샘플소스를 다운로드하고, 연동방법을 "샘플 다운로드" 메뉴에서 확인하세요.

바로빌에서 지원하는 개발 언어

 

개발 언어 설정

개발자는 이제 백엔드 개발 언어에 대한 IDE 도구를 설정하고 호출 테스트를 진행할 수 있습니다. 이번에는 가장 널리 사용되는 스프링 부트(Spring Boot) 프레임웍의 자바(Java) 설정 방법을 살펴보겠습니다. 

 

1. 바로빌 API를 사용하려면, 지원되는 버전의 jar 파일을 다운로드하여 설정해야 합니다. 바로빌 개발자센터에서 제공하는 가이드를 참고하여 적절한 파일을 선택하고, 필요한 설정을 진행하세요.

자바(Java) 버전

2. Dependency 추가, IDE(이클립스, Intellij 등)에서 jar 파일을 프로젝트에 직접 추가하거나, 빌드툴(Maven, Gradle 등)을 이용하여 프로젝트에 jar 파일을 추가할 수 있습니다.

Dependency 및 프레임웍 설정

3. Spring Boot 3.x 를 사용하는 경, Spring Boot 3.x 를 사용하는 경우 아래 의존성을 추가해야 합니다.

Spring Boot 3.x 버전인 경우 의존성 추가 설정

4. API 호출 방법은 다음과 습니다. 

샘플 테스트 소스를 사용하여 세금계산서 등의 호출 확인

 

이와 같이 자바(Java) 세팅을 할 수 있으며, 위 내용과 코드 이미지는 예시이며, 상세한 개발 언어별 개발환경 구축 방법은 "바로빌 개발자 API 개발 준비"에서 확인할 수 있고, 실제 샘플 코드는 "샘플 다운로드"에서 확인할 수 있습니다. 다른 지원 언어도 제공하고 있으니 개발사 환경에 맞추어 세팅하면 됩니다. 

 

홈택스전자세금계산서API 사용 시 주의 사항

바로빌 API 사용 시에는 다음과 같은 점을 고려하여 안전하고 효율적인 연동을 보장할 수 있습니다.

1. API 호출 한도: 일일 및 월간 호출 한도에 따라 종량 요금제 등의 다양한 요금제가 있으니 개발사에 맞는 요금제를 확인하고, 트래픽 관리 방안을 마련해야 하며, 사전 고객센터로 상담하여 확인하는 것을 추천드립니다. 
2. 보안 관리: 인증서 및 바로빌 API 인증키 관리에 주의하여 외부 접근을 차단해야 합니다.
3. 버전 업데이트: 국세청 홈택스 정책 변화에 따른 API 업데이트가 주기적으로 이루어지므로, 바로빌의 공지 사항을 주의 깊게 살펴야 합니다.

 

자주 묻는 질문(FAQ)

질문 1: 홈택스전자세금계산서API는 누가 사용할 수 있나요?

답변: 주로 전자세금계산서를 발급해야 하는 기업이나 쇼핑몰, ERP 등의 시스템에 연동을 사용하는 사업자에게 적합합니다.

질문 2: 사업자 등록 번호 조회 API 및 상태 조회 기능은 어떻게 이용할 수 있나요?

답변: 사업자 등록 번호 조회 API를 통해 거래처의 휴폐업 상태를 사전에 확인함으로써 잘못된 세금계산서 발행을 방지할 수 있습니다.

질문 3:사용 요금은 어떻게 책정되나요?

답변: 바로빌 API 서비스는 사용한 만큼 지불하는 종량제 방식이며, 사이트 유형에 따라 구축형도 가능하며, 일부 서비스는 무료로 제공됩니다.

질문 4: 연동에 필요한 시간이 얼마나 걸리나요?

답변: API 연동은 1~2일 이내에 완료할 수 있습니다. 필요한 경우, 테스트 환경에서 사전 점검을 통해 빠르게 진행할 수 있습니다. 

질문 5: 바로빌을 통해 API를 연동할 때 추가 비용이 발생하나요?
답변: 바로빌 API 서비스는 연동 및 유지비용은 무료입니다. 

질문 6: 인증키는 어디서 발급받나요?
답변: 인증키는 바로빌 개발자 센터에서 회원가입 후 발급받을 수 있습니다.

 

질문 7: 바로빌의 API는 국세청에서 요구하는 표준 인증을 받은 기업인가요?
답변: 바로빌 API 서비스는 100여 가지 항목의 테스트를 성공적으로 통과하고 국세청의 표준인증(표준전자세금계산서 v3.0)을 획득한 인증된 전자세금계산서 ASP 사업자입니다. 

 

마치며

SOAP 기반의 바로빌 홈택스전자세금계산서API는 국세청 홈택스에 직접 접속하지 않고도 세금계산서의 조회, 발급, 내역 관리 등을 자동화할 수 있는 솔루션으로, 다양한 개발 언어를 지원하며, 기업들이 필요로 하는 부분만을 선택하여 사용할 수 있는 맞춤형 API 서비스를 제공합니다.

 

홈택스전자세금계산서API 연동을 고려하고 있다면, 개발자 센터에서 제공하는 샘플 소스와 API 매뉴얼을 참고하여 더욱 효과적인 연동을 시도해 보세요. 아래 버튼을 클릭하면 세금계산서 API 상세 내용을 확인할 수 있습니다. 

 

해당 게시물은 업체로부터 소정의 대가를 받아 작성된 글입니다.