전자세금계산서 발급 API, 주문 데이터에서 요청 필드를 만드는 순서
전자세금계산서 발급 API, 주문 데이터에서 요청 필드를 만드는 순서
주문 관리 화면에 전자세금계산서 발급 기능을 붙일 때는 버튼보다 데이터 연결부터 정리하는 편이 좋습니다. 주문의 결제자, 증빙을 받을 사업자, 발행 사업자가 서로 다를 수 있기 때문입니다. 에이픽에 추가된 전자세금계산서 발급 API를 기준으로 어떤 값을 어디에서 가져올지 살펴봅니다.
1. 발행자와 공급받는자를 다른 객체로 관리하기
공식 가이드에는 발행자 사업자등록번호인 businessNo, 공급받는자 사업자등록번호인 buyerNo, 공급받는자 상호인 buyerName이 구분되어 있습니다. 주문 테이블의 회사명 하나를 양쪽에 복사하는 방식은 피하세요. 발행 사업자 설정과 구매자 증빙 신청 정보를 나눈 뒤 각각의 출처를 요청 미리보기에 표시하는 구성을 권합니다.
여러 사업장을 운영하는 서비스라면 로그인한 직원의 소속만으로 발행자를 정하지 않는 편이 좋습니다. 예를 들어 A사업장의 주문을 B사업장 관리자가 처리하더라도 발행 사업자는 해당 거래 기준으로 선택해야 합니다. 번호는 숫자 계산값이 아닌 10자리 문자열로 다루고, 상호를 바꿨을 때 번호도 함께 확인하도록 화면을 구성합니다.
2. 작성일자와 품목은 요청 시점에 확정하기
writtenDate는 작성일자를 나타내는 YYYYMMDD 형식의 필드입니다. 가이드는 생략 시 오늘을 기본값으로 안내합니다. 주문 생성일, 입금 확인일, 작성일자는 서로 다른 값일 수 있으므로 하나의 날짜로 합치지 마세요. 어떤 날짜가 적절한지는 업무 담당자가 확인하고, 프로그램은 선택된 날짜를 빠짐없이 전달하도록 역할을 나눕니다.
items에는 itemName, quantity, unitPrice, supplyAmount, taxAmount가 포함됩니다. 상품 목록을 그대로 보내기보다 실제 발급에 사용할 품목 목록을 별도로 확정하는 설계가 유용합니다. 예를 들어 주문에는 배송 안내용 항목이 있어도 증빙 품목에 넣을지는 별도 판단이 필요합니다. 요청 직전 확정본을 남겨야 이후 주문 편집과 발급 기록을 구별할 수 있습니다.
3. 인증 정보와 거래 정보의 입력 경계를 정하기
발급 요청은 POST /rest/req_etax_issue로 접수하고, 받은 transactionId로 /rest/get_etax_issue에서 결과를 확인하는 구조입니다. 법인은 공동인증서가 필수이며 개인사업자는 간편인증 또는 공동인증서를 준비합니다. API 키는 발행 사업자 인증을 대체하지 않습니다. 거래정보와 인증 준비 상태를 화면에서 따로 보여주세요.
가이드에는 business_no와 businessNo가 함께 등장하며, 각각 사업자 확인과 발행자 정보 설명에 쓰입니다. 내부 변수 이름을 비슷하게 만들기보다 대표자 확인용 정보와 발행자 정보를 명시적으로 매핑하는 편이 안전합니다. 인증 방식별 조건과 문서의 필드 표가 다르게 읽히는 부분은 운영 호출 전에 공식 예제와 지원 창구로 확인하세요.
4. 발급 요청 한 건을 독립된 기록으로 남기기
주문번호만 저장하면 같은 주문에서 어떤 입력으로 발급을 요청했는지 설명하기 어렵습니다. 내부 발급 요청 번호, 주문번호, 발행 사업자, 공급받는자, 확정 품목, 작성일자를 한 묶음으로 남기는 방식을 권합니다. idempotency_key는 공식 필수값이며, 결과가 불명확한 건에 새 키를 붙여 다시 발급하는 동작은 별도로 막아야 합니다.
검토할 사례는 공급받는자 정보가 주문 후 변경된 경우, 작성일자를 비워 둔 경우, 다른 사업장을 선택한 경우, 품목이 없는 경우입니다. 각 사례에서 잘못된 값이 어디서 차단되는지 문서로 남겨보세요. 발급 결과가 도착하면 승인번호를 해당 요청 기록에 연결합니다. 이 구조가 있어야 수정발급을 추가할 때도 원본을 정확히 찾을 수 있습니다.
공식 발급 가이드를 열고 현재 주문 데이터와 필드별 대응표를 먼저 만들어 보세요. 연결되지 않는 값이 첫 개발 범위입니다. 이 글은 에이픽 자사 서비스 소개 콘텐츠입니다. 공식 개발가이드를 바탕으로 AI를 활용해 작성했으며, 이미지는 AI 생성 개념 이미지와 설명용 도표이며 실제 서비스 화면이 아닙니다. 예시는 구현 검토용이며 실제 발급 실행 결과가 아닙니다.
공식 근거
기능 근거: 2026년 11월 3일 확인한 공식 공개 가이드. 최신 입력 조건과 이용 범위는 링크에서 다시 확인해 주세요.
댓글
댓글 쓰기