Grind away: 매장별 엑셀을 합쳤더니 같은 거래가 두 줄: 현금영수증 일괄 연동 전 중복 제거

2026년 11월 5일 목요일

매장별 엑셀을 합쳤더니 같은 거래가 두 줄: 현금영수증 일괄 연동 전 중복 제거

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

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

반복 업무가 생기는 장면

여러 매장이 일일 수납 파일을 본사에 보내는 시나리오입니다. 수정 파일과 원본 파일이 함께 들어오면 같은 거래가 두 번 보일 수 있습니다. 행 번호가 다르다고 별도 매출은 아닙니다.

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

이번 연동에서 해결할 문제

에이픽 요청 전에 파일 수집 장부와 거래 장부를 분리합니다. 파일 이름 대신 원천 시스템의 거래 식별자를 기준으로 중복을 판단하고, 동일 식별자의 금액이 달라졌다면 덮어쓰기보다 검토 대상으로 분류합니다.

매장 식별자와 원천 거래 식별자의 조합을 내부 고유키로 정합니다. 이름·연락처·금액이 같다는 이유만으로 서로 다른 거래를 합치지 않습니다.
승인된 거래마다 안정적인 idempotency_key를 기록합니다. 파일을 다시 올렸다는 이유로 새 키를 매번 생성하지 않습니다.
이미 요청한 거래는 기존 transactionId 결과를 우선 확인합니다. 멱등키의 실제 적용 범위·유효기간은 최신 공식 정책을 확인하고, 영구 중복 방지를 APICK에만 맡기지 않습니다.

빈 회원가입 양식. 개인정보 입력이나 가입 실행 결과가 아닙니다. 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