// industry
이커머스 셀러
스마트스토어 · 자사몰 · 쿠팡. PG ↔ 은행 정산 차이를 월말 PR 로.
// schemas
사용 스키마
bank.transactions.cb.v1hometax.tax-invoices.sales.v1
// scenario
이커머스 셀러 — PG ↔ 은행 정산 대사
네이버페이·카카오페이·토스·스마트스토어 정산서와 은행 실입금을 일자별로 매칭. 차이만 CSV 로 추려 회계담당에게.
- 주기
- 매주 월요일
- 대상
- 스마트스토어·자사몰·쿠팡 등 PG 정산이 일상인 이커머스 셀러.
- 채널
- CLI · Claude Code
01사전 점검
아래 명령을 그대로 붙여넣어 지금 내 환경이 준비됐는지 확인한다.
CLI 가 설치돼 있다
h6s --version버전 문자열이 출력된다
아니면 —
npm i -g @h6s-ai/cli로그인(또는 API Key)이 돼 있다
h6s whoami워크스페이스와 사용량이 출력된다
아니면 —
h6s init # 또는 export H6S_API_KEY=h6s_live_...워크스페이스에 대상 자격증명이 있다
h6s credentials list공동인증서 또는 대상 기관 자격증명이 1건 이상 보인다
아니면 —
h6s credentials create --interactive --certPG 정산서 CSV 가 준비돼 있다
ls ./pg-settlement/네이버페이·카카오페이·토스 등 정산서 CSV 가 보인다
아니면 —
각 PG 관리자에서 주간 정산서를 내려받아 한 폴더에 둔다(은행 측은 자동 수집).
02실행
이 한 줄로 끝. 수집 → 룰북·대사 → 외부 전송까지 internal-finance skill 이 오케스트레이션한다.
지난 주 PG 정산서랑 은행 입금 일자별로 매칭하고 차이만 pg-bank-gap-<주차>.csv 로 정리해줘.
내부적으로 도는 수집 명령: h6s fetch bank.transactions.cb.v1 --provider CB_KB --from 2026-04-27 --to 2026-05-03 --output csv
03검증
- PG 정산액 vs 은행 실입금이 일자별로 매칭된다.
- 차이 있는 행만 pg-bank-gap-<주차>.csv 로 추려진다(다음 영업일 입금 등 사유 표기).
04흔한 에러
CREDENTIAL_INSUFFICIENT_FOR_PROVIDER그 provider 에 매칭되는 자격증명이 워크스페이스에 없다.
해결 h6s credentials create --interactive --cert (공동인증서 1개로 전 기관 공용).
CERT_EXPIRED · CERT_WRONG_PASSWORD등록된 공동인증서가 만료됐거나 비밀번호가 틀렸다.
해결 h6s credentials update 로 갱신 후 재실행.
NO_API_KEYAPI Key 가 설정돼 있지 않다.
해결 h6s init 또는 export H6S_API_KEY=h6s_live_...
05변형
같은 사례에서 자주 바꾸는 옵션. 다른 사례는 아래 이전/다음에서.
기간 바꾸기
이번 달 전체 PG-은행 정산 대사 해줘// scenario
이커머스 셀러 — 월말 정산 차이 PR
매월 1일 전월 PG 정산 합계 ↔ 은행 입금 합계 차이만 추린 PR. 차이가 0 이면 PR 미생성.
- 주기
- 매월 1일 09:00 KST
- 대상
- 월 정산을 PR review 로 처리하고 싶은 셀러·셀러 회계 담당.
- 채널
- GitHub Actions
01사전 점검
아래 명령을 그대로 붙여넣어 지금 내 환경이 준비됐는지 확인한다.
repo secret H6S_API_KEY 가 등록돼 있다
gh secret list목록에 H6S_API_KEY 가 보인다
아니면 —
gh secret set H6S_API_KEY # 또는 repo Settings → Secrets워크스페이스에 대상 자격증명이 있다
h6s credentials list그 기관에 매칭되는 자격증명이 1건 이상 보인다
아니면 —
h6s credentials create --interactive --certActions 가 PR 을 만들 수 있다
repo Settings → Actions → General → Workflow permissions"Read and write" + "Allow GitHub Actions to create pull requests" 체크
아니면 —
두 옵션을 켠다 (yml 의 permissions 블록만으로도 동작하지만 repo 설정이 우선).PG 정산서를 둘 폴더 규칙이 정해져 있다
ls ./incoming/pg-settlement/월별 폴더(<YYYY-MM>)에 PG 정산 CSV 를 둘 자리가 있다
아니면 —
incoming/pg-settlement/<월>/ 에 정산서를 채우는 운영 절차를 만든다.
02실행
아래 파일을 .github/workflows/ 에 저장하고 기본 브랜치에 commit. 첫 검증은 Actions 탭 → Run workflow 로 수동 트리거.
# 매월 1일 (한국시간 09:00) 전월 PG 정산 합계 ↔ 은행 입금 합계 차이만 추려 PR 로 올린다.
# PG 정산서는 운영자가 별도 폴더(`./incoming/pg-settlement/<YYYY-MM>/*.csv`)에 두고,
# h6s-action 이 은행 입금만 받아 한 step 에서 비교.
# 차이가 0이면 PR 자체가 생성되지 않는다 (변경 없음 → create-pull-request skip).
name: 이커머스 PG-은행 월말 정산 차이 PR
on:
schedule:
- cron: '0 0 1 * *' # 매월 1일 00:00 UTC (KST 09:00)
workflow_dispatch: {}
jobs:
reconcile:
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
steps:
- uses: actions/checkout@v6
- id: prev-month
run: |
MONTH=$(date -u -d '1 month ago' +%Y-%m)
START=$(date -u -d "${MONTH}-01" +%Y-%m-%d)
END=$(date -u -d "${MONTH}-01 +1 month -1 day" +%Y-%m-%d)
echo "month=${MONTH}" >> "$GITHUB_OUTPUT"
echo "start=${START}" >> "$GITHUB_OUTPUT"
echo "end=${END}" >> "$GITHUB_OUTPUT"
- id: fetch
uses: bolta-io/h6s-action@v0
with:
api-key: ${{ secrets.H6S_API_KEY }}
schema: bank.transactions.cb.v1
provider: CB_KB
from: ${{ steps.prev-month.outputs.start }}
to: ${{ steps.prev-month.outputs.end }}
output-path: ./settlement/${{ steps.prev-month.outputs.month }}/_bank/
- name: PG ↔ 은행 차이 추출
id: diff
run: |
# 운영자가 incoming/pg-settlement/<month>/ 에 PG 정산 CSV 들을 채워둔다.
# 비교 스크립트는 호출자 repo 의 scripts/pg-bank-diff.mjs 로 위임 (sample).
mkdir -p ./settlement/${{ steps.prev-month.outputs.month }}
node scripts/pg-bank-diff.mjs \
--pg ./incoming/pg-settlement/${{ steps.prev-month.outputs.month }}/ \
--bank ${{ steps.fetch.outputs.path }} \
--out ./settlement/${{ steps.prev-month.outputs.month }}/
- uses: peter-evans/create-pull-request@v6
with:
title: 'settlement: ${{ steps.prev-month.outputs.month }} PG-은행 차이'
body: |
자동 생성. PG 정산서와 은행 입금의 차이를 일자별로 정리.
- 기간: ${{ steps.prev-month.outputs.start }} ~ ${{ steps.prev-month.outputs.end }}
- 은행 fetch 요약: ${{ steps.fetch.outputs.summary }}
- Job ID: `${{ steps.fetch.outputs.job-id }}`
> 차이 0 이면 이 PR 은 생성되지 않는다.
branch: settlement/${{ steps.prev-month.outputs.month }}
commit-message: 'chore(settlement): ${{ steps.prev-month.outputs.month }} 차이 추출'
add-paths: settlement/은행 측만 자동 수집. PG 정산서는 운영자가 incoming/pg-settlement/<월>/ 에 채워둔다. 비교 스크립트(pg-bank-diff.mjs)는 호출자 repo 가 제공.
03검증
- Actions 초록 + 차이가 있으면 settlement/<월> 브랜치 PR 생성.
- 차이가 0 이면 PR 이 생성되지 않는다(정상 — 변경 없음).
- PR 에 일자별 차이 CSV + 요약이 들어간다.
04흔한 에러
워크플로우는 초록인데 PR 이 안 생긴다Actions 의 PR 생성 권한이 막혀 있거나 변경 파일이 없다(중복 실행).
해결 repo Settings → Actions 에서 PR 생성 허용. 같은 기간 재실행이면 정상.
fetch step 에서 NO_API_KEY 로 실패secret 이름이 yml 의 secrets.H6S_API_KEY 와 다르다.
해결 secret 을 정확히 H6S_API_KEY 로 등록.
CREDENTIAL_INSUFFICIENT_FOR_PROVIDER그 provider 에 매칭되는 자격증명이 워크스페이스에 없다.
해결 h6s credentials create --interactive --cert (공동인증서 1개로 전 기관 공용).
cron 시간이 지나도 안 돈다yml 이 기본 브랜치에 없거나, repo 가 60일 비활성이라 scheduled workflow 가 멈췄다.
해결 기본 브랜치에 머지하고, 가끔 수동 트리거해 활성 유지.
diff step 에서 scripts/pg-bank-diff.mjs not found호출자 repo 에 비교 스크립트가 없다(샘플 위임).
해결 repo 에 scripts/pg-bank-diff.mjs 추가(정산액·실입금 일자 매칭 로직).
05변형
같은 사례에서 자주 바꾸는 옵션. 다른 사례는 아래 이전/다음에서.
주간으로 전환
- cron: '0 0 * * 1' # 매주 월요일// related