Grind away: 예약금과 잔금을 두 번 받는 서비스: 현금영수증 발급 금액을 주문 총액과 분리하기

2026년 11월 5일 목요일

예약금과 잔금을 두 번 받는 서비스: 현금영수증 발급 금액을 주문 총액과 분리하기

에이픽 API 홍보 · 가상 업무 시나리오

실제 고객 후기나 측정한 성과가 아닙니다. 공식 문서에서 확인한 API 구조를 바탕으로 구현 방법을 설명하며, 실제 API 호출·개인정보 조회·문서 발급은 수행하지 않았습니다. 운영 화면과 장부는 자체 구현 예시입니다.

반복 업무가 생기는 장면

맞춤 제작 업체에서 예약금과 잔금을 나눠 받는 상황입니다. 주문 총액만 복사하면 아직 받지 않은 금액까지 발급 대상으로 잡을 위험이 있습니다. 담당자가 입금 내역을 한 줄씩 되짚는 이유입니다.

에이픽 공개 홈페이지. 당시 메뉴와 상품 안내를 보여주는 화면입니다. 2026-10-28 보관 화면, 공통 연결 안내용으로 재사용했습니다. 아래 발급 결과와는 별개인 공통 시작 안내입니다.

이번 연동에서 해결할 문제

입금 확인 기록을 주문과 별도 장부로 관리한 뒤, 발급 대상 금액을 담당자가 확정하는 구조를 설계합니다. 분할 수납의 세무 처리 기준은 거래 사실과 전문가 검토로 정해야 하며, 이 글이 발급 시점이나 대상 금액을 대신 결정하지 않습니다.

주문번호, 수납 식별자, 확인된 수납액, 발급 대상액을 구분합니다. 주문금액을 amount에 무조건 대입하지 않습니다.
동일 수납 건의 반복 요청에는 같은 작업 식별자를 유지합니다. 별도 거래인 예약금과 잔금에 같은 멱등키를 재사용하지 않도록 내부 규칙을 정합니다.
입금 취소·부분 환불·발급 이력 존재 여부를 발급 전 확인합니다. 애매한 건은 자동 대기열에서 제외해 담당자가 검토합니다.

빈 회원가입 양식. 개인정보 입력이나 가입 실행 결과가 아닙니다. 2026-10-28 보관 화면, 공통 연결 안내용으로 재사용했습니다. 아래 발급 결과와는 별개인 공통 시작 안내입니다.

apick.app 연결과 서버 준비

apick.app에서 해당 상품의 최신 개발가이드와 이용 조건을 확인합니다. 인증키는 서버 환경변수 APICK_API_KEY로 관리하고 프런트엔드 코드·스크린샷·공유 로그에 넣지 않습니다. 아래 변수는 실제 값이 아닌 표식입니다. 개인정보를 처리할 권한과 필요한 동의·고지를 갖춘 뒤 서버에서만 사용합니다.

공통 개발가이드의 서버 환경변수 준비 화면. 실제 인증키 값은 표시하지 않습니다. 2026-10-28 보관 화면, 공통 연결 안내용으로 재사용했습니다. 아래 발급 결과와는 별개인 공통 시작 안내입니다.

인증 요청 cURL

다음은 공식 명세 기반의 정적 요청 예시입니다. 환경변수를 준비했다고 자동 실행하지 마세요. 대상·권한·금액·인증 방식을 확인한 실제 업무에서만 호출해야 합니다.

# 공식 명세 기반 정적 예시. 실행하지 않았습니다.
curl --fail-with-body --request POST 'https://apick.app/rest/req_cash_receipt_issue' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string "name=${APICK_NAME}" \
  --form-string "birthDate=${APICK_BIRTH_DATE}" \
  --form-string "phone=${APICK_PHONE}" \
  --form-string "authProvider=${APICK_AUTH_PROVIDER}" \
  --form-string "receipt_no=${APICK_RECEIPT_NO}" \
  --form-string "amount=${APICK_AMOUNT}" \
  --form-string "idempotency_key=${APICK_IDEMPOTENCY_KEY}" \
  --form-string "purpose=${APICK_PURPOSE}" \
  --form-string "transaction_type=${APICK_TRANSACTION_TYPE}"

같은 요청의 결과 확인

인증 요청 응답에서 받은 transactionId를 해당 업무에 연결합니다. 본인 승인이 필요한 단계는 사용자가 직접 처리하며, 결과 준비 상태를 확인하기 전에 완료로 표시하지 않습니다.

# 승인 뒤, 요청 응답의 transactionId로 결과를 확인하는 구조입니다.
curl --fail-with-body --request POST 'https://apick.app/rest/get_cash_receipt_issue' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string "transactionId=${APICK_TRANSACTION_ID}"

공통 연결 확인용 /rest/info 정적 cURL 예시. 이 글의 발급 API를 실행한 화면이 아닙니다. 2026-10-28 보관 화면, 공통 연결 안내용으로 재사용했습니다. 아래 발급 결과와는 별개인 공통 시작 안내입니다.

정적 응답 일부와 업무 처리

아래는 공식 문서의 가상 정적 응답 예시에서 일부 필드를 발췌한 JSON입니다. 금액 1,000·910·90은 공식 예시의 값이며 식별값은 비공개 표식으로 바꿨습니다. 실제 거래 결과가 아니며, 전체 응답이나 모든 상태를 나타내지 않습니다.

{
  "data": {
    "result": {
      "cashReceiptIssue": {
        "승인번호": "[비공개]",
        "거래일시": "[비공개]",
        "합계금액": 1000,
        "공급가액": 910,
        "부가세": 90,
        "용도구분": "소득공제"
      }
    }
  }
}

결과의 합계금액을 발급 대상으로 승인한 수납 건과 대조합니다. 주문 전체 잔액과 API 포인트 비용을 합계금액에 더하지 않습니다. 승인번호의 존재만으로 주문 전체가 결제 완료됐다고 바꾸지 마세요.

인증·비용과 발급 전 확인

현금영수증은 실제 거래 증빙을 발행하는 API입니다. 임의의 연습 거래를 발급하지 않습니다. 개인사업자 간편인증과 법인 공동인증서 흐름을 구분하고, 법인에 이 간편인증 예시를 그대로 적용하지 않습니다. purpose는 0 소득공제·1 지출증빙, transaction_type은 01 과세·02 면세·03 간이 중 실제 거래에 맞는 값인지 확인합니다.

공식 문서상 인증 요청 20P, 첫 결과 제공 100P이며, 무료 포인트 사용 불가·최소 1회 결제 조건이 있습니다. 포인트는 영수증 거래 금액이나 현금 매출과 다른 단위입니다. 사용 가능한 포인트 재원·결제 이력 조건·실제 과금 정책은 운영 직전에 확인하세요. 오류나 거절이 발생했다고 모든 단계의 비용이 0이라고 가정하지 않습니다.

HTTP 상태와 업무 상태를 구분하고 승인 대기·준비 중·실패를 따로 표시합니다. 결과를 기다리는 동안 새 인증 요청을 반복하지 않습니다. 거절·만료와 불확실한 결과는 검토 대상으로 남기고, 최신 조회 간격 및 동시처리 제한을 따릅니다.

도입 후 확인할 변화

운영 지표는 주문 총액과 수납액을 혼동해 보류된 건수, 중복 요청 차단 건수입니다. 입금과 발급 연결이 명확해지면 담당자가 엑셀을 다시 맞추는 시간을 측정할 수 있습니다.

에이픽 API로 반복 입력을 연결하되, 사람이 결정해야 하는 승인과 예외는 명확히 남겨 보세요.

확인한 공식 자료

현금영수증 개발가이드

명세 확인 기준: 2026-11-05. 이미지 4장은 APICK 공개 화면의 2026-10-28 보관본이며 공통 연결 설명용입니다. 해당 문서의 실발급 화면이나 현재 운영 성과 증거가 아닙니다.

Grind away