Grind away: 서버가 재시작돼도 발급 기록이 사라지지 않게: 현금영수증 작업 장부 만들기

2026년 11월 5일 목요일

서버가 재시작돼도 발급 기록이 사라지지 않게: 현금영수증 작업 장부 만들기

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

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

반복 업무가 생기는 장면

관리자가 발급을 시작한 직후 서버 배포가 진행되는 시나리오입니다. 요청을 보냈는지 기록이 없다면 담당자는 다시 발급할지 기다릴지 판단하기 어렵습니다.

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

이번 연동에서 해결할 문제

발급 작업을 메모리만으로 관리하지 않고 영속적인 작업 장부에 남깁니다. 주문이 승인된 시점, 요청 의도, 전송 상태, transactionId, 결과 확인 상태를 분리해 복구할 근거를 확보합니다.

전송 전 내부 작업과 안정적인 idempotency_key를 저장합니다. 배포 뒤 작업자가 바뀌어도 같은 거래의 식별자가 유지되어야 합니다.
응답을 받은 경우 transactionId를 저장하고 결과 조회를 이어갑니다. 요청 결과가 불확실할 때 새 키로 무조건 발급하지 않습니다.
공식 정책과 운영 기록으로 기존 처리 여부를 확인할 수 없다면 불확실 상태로 남기고 담당자가 조사합니다. timeout을 미발급의 증거로 취급하지 않습니다.

빈 회원가입 양식. 개인정보 입력이나 가입 실행 결과가 아닙니다. 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입니다. 임의의 연습 거래를 발급하지 않습니다. 개인사업자 간편인증과 법인 공동인증서 흐름을 구분하고, 법인에 이 간편인증 예시를 그대로 적용하지 않습니다. purpose는 0 소득공제·1 지출증빙, transaction_type은 01 과세·02 면세·03 간이 중 실제 거래에 맞는 값인지 확인합니다.

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

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

도입 후 확인할 변화

복구 검증은 실제 영수증을 여러 장 발급하는 테스트가 아닙니다. 개발 환경에서 전송 전·응답 저장 전·완료 갱신 전 중단을 가정하고 정적 자료로 작업 장부가 설명 가능한지 확인합니다.

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

확인한 공식 자료

현금영수증 개발가이드

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

Grind away