APICK 전자세금계산서 API로 주문 승인부터 발급번호 저장까지 설계하기

10월 28, 2026

이 글은 2026년 10월 28일 확인한 APICK 공개 화면과 공식 개발가이드를 바탕으로 한 실무 설계 예시입니다. 실제 회원가입 제출, API 키 발급, 인증서 등록, 유료 API 호출은 수행하지 않았으며, 예시를 실제 연동 성공 사례로 제시하지 않습니다.

B2B 주문이 승인될 때마다 담당자가 거래처와 품목을 다시 입력한다면, 자동화할 첫 지점은 발급 버튼보다 앞에 있습니다. 주문 데이터가 확정됐는지 확인하고, 발급 요청과 발급 완료를 나누어 관리하는 것입니다. APICK의 신규 전자세금계산서 API를 이용해 이 흐름을 어떻게 설계할지 살펴봅니다.

전자세금계산서 정발급 공식 명세 — APICK 공식 공개 화면(2026-10-28), 실제 API 호출 결과가 아닙니다.

사례는 월말에 몰리는 B2B 주문 발급

가상의 도매 플랫폼을 생각해 보겠습니다. 영업 담당자는 주문을 확정하고, 회계 담당자는 공급받는 사업자와 금액을 검토합니다. 이때 내부 상태를 검토 중 → 승인 완료 → 발급 접수 → 결과 확인으로 나눕니다. 이 상태 이름은 구현을 위한 제안이며 APICK의 응답 필드가 아닙니다.

좋은 시작점은 승인 완료 주문 한 건입니다. 모든 주문을 한꺼번에 자동 발급하기보다, 거래처 정보 수정·품목 추가·담당자 승인 취소가 생겼을 때 어느 단계에서 멈출지 먼저 정하세요.

가입에서 서버 연동까지 준비하기

APICK의 공개 가입 화면은 Google 계정으로 시작하거나 다른 이메일로 가입하는 경로를 제공합니다. 서비스 담당자가 약관과 필요한 정보를 확인한 뒤 직접 가입하고, 개발가이드의 내 인증키 확인하기 링크로 이동하는 순서입니다. 해당 링크는 /my_page?tab=api_info로 연결되며 로그인 전에는 로그인 화면이 표시됩니다. 이 글에서는 공개 화면까지만 확인했습니다.

APICK 회원가입 빈 양식. 입력·제출·가입은 진행하지 않음 — APICK 공식 공개 화면(2026-10-28), 실제 API 호출 결과가 아닙니다.

키를 준비했다면 서버의 APICK_API_KEY 환경변수에 보관하세요. 고객 브라우저, 모바일 앱 소스, 블로그 본문에는 넣지 않습니다. 계정 확인용 첫 요청과 상품별 호출을 구분하고, 실제 실행 전에는 이용 조건·포인트·필수 입력을 다시 확인합니다. 무료 가입과 무료 호출은 다릅니다. 공식 문서의 최초 결제 필요 목록 등 상품별 이용 조건도 확인하세요.

법인이라면 인증서 준비가 먼저입니다

공식 발급 문서는 법인에 공동인증서 인증을 요구합니다. 계정 담당자가 인증서 관리 화면에서 등록하고 로그인 확인을 마친 뒤, 같은 계정의 API 키와 certificate_id를 사용하는 구조입니다. 개인사업자와 법인의 인증 흐름을 한 화면으로 뭉뚱그리지 않는 것이 좋습니다.

인증서 파일, 개인키 파일, 비밀번호는 블로그 촬영 대상에서 제외합니다. 등록 화면을 보여줄 때도 파일 경로·인증서 식별값·사업자 정보까지 가려야 합니다. 이 원고를 위한 인증서 업로드나 비밀번호 입력은 하지 않았습니다. 인증 방식과 준비 조건은 공식 전자세금계산서 발급 가이드에서 확인할 수 있습니다.

접수와 완료를 나누어 연결합니다

공식 흐름은 POST /rest/req_etax_issue로 접수하고, 받은 transactionId로 POST /rest/get_etax_issue 결과를 확인하는 방식입니다. 내부 주문번호와 transactionId를 함께 관리하면 운영자가 어떤 주문의 요청인지 추적하기 쉬워집니다.

개발할 때는 다음 순서로 업무 규칙을 연결하세요.

회계 담당자가 거래처·작성일·품목·공급가액·세액을 검토합니다.
확정 주문 한 건에 대응하는 idempotency_key를 정해 저장합니다.
서버에서 필수 입력을 구성하고 발급 접수를 보냅니다.
접수 응답만으로 고객에게 발급 완료를 알리지 않습니다.
결과의 승인번호와 전송상태를 확인한 뒤 주문 기록에 연결합니다.

공식 문서는 같은 멱등 키로 다시 요청해도 중복 발급되지 않는다고 안내합니다. 네트워크 오류 때문에 다시 보낼 때 새 키를 발급하는 로직은 넣지 마세요. 응답이 불확실한 경우에는 재발급보다 기존 처리 결과 확인이 먼저입니다.

코드에 넣을 값부터 검토하는 예시

아래는 미실행·네트워크 요청 없는 서버용 입력 구성 예시입니다. 실제 사업자번호·인증서 ID·키가 없으며 발급 API를 호출하지 않습니다. 품목 및 세금 처리는 담당자의 검토가 끝난 값을 사용해야 합니다.

// 구조 설명용. fetch 호출 없음. 실제 발급을 수행하지 않습니다.
function prepareIssueFields(approvedOrder, certificateId) {
  return {
    business_type: "corporate",
    certificate_id: certificateId,
    businessNo: approvedOrder.sellerBusinessNo,
    idempotency_key: approvedOrder.issueRequestKey,
    buyerNo: approvedOrder.buyerBusinessNo,
    buyerName: approvedOrder.buyerName,
    items: JSON.stringify(approvedOrder.approvedItems)
  };
}
// approvedOrder는 우리 서비스의 내부 데이터 모델입니다.
// APICK 필수·선택 필드 전체는 실행 시점의 공식 명세로 검증하세요.

공식 정적 cURL 요청 예시. 실제 키·API 호출·성공 결과가 아님 — APICK 공식 공개 화면(2026-10-28), 실제 API 호출 결과가 아닙니다.

APICK은 별도로 /rest/req_etax_issue_preview 초안 검증 경로를 안내합니다. 실제 발급 없이 입력과 합계를 확인하는 용도이며, 이 글에서는 그 경로도 호출하지 않았습니다. 미리보기 검증이 끝나더라도 회계적 판단과 발급 승인이 자동으로 충족되는 것은 아닙니다.

오류가 발생했을 때 회계팀이 알아야 할 정보

합계 불일치, 인증서 확인 실패, 처리 결과 불확실을 같은 “발급 실패”로 표시하면 재작업이 늘어납니다. 입력 수정이 필요한 요청과 확인을 기다려야 하는 요청을 분리하세요. 특히 공식 문서의 ETAX_ISSUE_UNKNOWN_PENDING 상황에서는 새 키로 발급하지 말고 기존 발급 여부를 확인해야 합니다.

로그에는 내부 작업번호, 오류 분류, 재확인 필요 여부를 남기고 원문 인증정보나 세금계산서 전체 내용을 무분별하게 기록하지 않습니다. 운영 화면에서는 발급권한과 조회권한도 구분해 두는 편이 안전합니다.

도입 전에 확인할 비용과 범위

인증·결과 제공의 과금 조건, 결제·이용 조건, 결과 재조회 기간은 최신 상품 문서에서 확인하세요. “요청 실패”와 “이미 처리됐는데 클라이언트가 응답을 못 받은 경우”는 다를 수 있습니다. 이 글은 세법상 발급 의무나 발급시기 판단을 대신하지 않습니다.

다음 단계: APICK 발급 가이드를 열고, 현재 주문관리 화면에서 발급 승인을 내리는 위치와 승인번호를 보관할 위치를 먼저 정해 보세요. 주문 한 건을 끝까지 추적할 수 있으면 이후 자동화 범위를 넓히기 쉬워집니다.

공식 화면과 개발가이드

APICK 가입 화면

APICK 시작 가이드

전자세금계산서 발급 가이드

#APICK #에이픽 #전자세금계산서API #B2B자동화 #세금계산서연동

이 블로그 검색

apick