// local

다중 계좌 통합

분리된 여러 계좌를 한곳에 모아 봐야 할 때. 계좌마다 따로 받지 않고 한 번에 모읍니다.

// 상황

이런 상황이라면

계좌가 흩어져 있다

운영 계좌가 여러 은행에 나뉘어 있어 전체 흐름이 한눈에 안 들어옵니다.

은행마다 따로 받는다

계좌 수만큼 로그인해 내역을 받아 합칩니다.

투명성 보고가 번거롭다

비영리·임의단체는 운영 내역을 정리해 보고해야 하는데 손이 많이 갑니다.

// 흐름

어떻게 동작하나

  1. 01

    계좌별 자격증명 등록

    여러 은행 계좌의 자격증명을 등록합니다.

  2. 02

    한 번에 수집

    계좌를 돌며 같은 수집 요청을 보냅니다.

  3. 03

    통합 정리

    표준 데이터 형식으로 모인 내역을 한곳에서 정리합니다.

// schemas

사용 데이터 형식

이 시나리오에서 받는 데이터입니다. 기관이 달라도 같은 모양으로 옵니다. 필드 전체 명세는 각 데이터 형식 문서에서 확인할 수 있습니다.

// 결과물

손에 남는 것

  • 여러 은행 계좌를 한 번에
  • 전체 입출금 흐름 통합
  • 계좌별 따로 받던 수고 제거
  • 운영 현황 보고에 바로 활용

// 실행 가이드

그대로 따라 하면 됩니다

사전 점검부터 검증까지 이 페이지에서 끝납니다. 실행 방식이 여럿이면 하나만 고르면 됩니다.

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 --cert

02실행

아래 파일을 .github/workflows/ 에 저장하고 기본 브랜치에 commit. 첫 검증은 Actions 탭 → Run workflow 로 수동 트리거.

yaml
# 여러 금융기관(provider) 의 입출금내역을 병렬로 수집.
# 본 계좌 + 마이크로 그랜트·피지컬 스폰서십용 분리 계좌가 다른 은행에 있는 경우의 표준 패턴.
# provider 만 주면 각 기관에 매칭되는 credential 또는 공동인증서를 백엔드가 자동 선택.
name: 다중 기관 병렬 수집

on:
  schedule:
    - cron: '0 0 * * 1'   # 매주 월요일
  workflow_dispatch: {}

jobs:
  fetch:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    strategy:
      fail-fast: false
      matrix:
        provider:
          - CB_IBK      # 본 계좌 (기업은행)
          - CB_KB       # 마이크로 그랜트 분리 계좌
          - CB_SHINHAN  # 피지컬 스폰서십 분리 계좌
    steps:
      - uses: actions/checkout@v6

      - id: prev-week
        run: |
          echo "from=$(date -u -d '7 days ago' +%Y-%m-%d)" >> "$GITHUB_OUTPUT"
          echo "to=$(date -u -d 'yesterday' +%Y-%m-%d)" >> "$GITHUB_OUTPUT"

      - id: fetch
        uses: bolta-io/h6s-action@v0
        with:
          api-key: ${{ secrets.H6S_API_KEY }}
          schema: bank.transactions.cb.v1
          provider: ${{ matrix.provider }}
          from: ${{ steps.prev-week.outputs.from }}
          to: ${{ steps.prev-week.outputs.to }}
          output-path: ./data/bank/${{ matrix.provider }}/

      - uses: actions/upload-artifact@v4
        with:
          name: bank-${{ matrix.provider }}
          path: ${{ steps.fetch.outputs.path }}
          retention-days: 30

matrix.provider 에 대문자 코드(CB_KB·CB_SHINHAN 등)만 추가하면 기관 수만큼 병렬 확장.

03검증

  • Actions 에서 provider 수만큼 병렬 job 이 일부 실패 여부와 관계없이 완료됩니다.
  • run 페이지 Artifacts 에 bank-CB_IBK · bank-CB_KB · bank-CB_SHINHAN 이 분리 보존.
  • 한 기관 자격증명 누락 시 그 job 만 실패하고 나머지는 정상.

04흔한 에러

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 가 멈췄다.

해결 기본 브랜치에 머지하고, 가끔 수동 트리거해 활성 유지.

05변형

같은 사례에서 자주 바꾸는 옵션. 다른 사례는 아래 이전/다음에서.

기관 추가

yaml
- CB_HANA     # 하나은행 추가

Artifact 대신 PR 합본

yaml
# upload-artifact 를 빼고 weekly-multi-schema 의 collect job 패턴을 붙인다
전체 가이드 페이지로 보기

// faq

자주 묻는 질문

은행이 달라도 한 번에 되나요?

계좌별 자격증명을 등록하면 은행이 달라도 같은 흐름으로 모읍니다.

결과가 은행마다 다른 모양인가요?

아니요. 표준 데이터 형식으로 와서 한곳에서 같은 방식으로 정리됩니다.

비영리 단체도 쓸 수 있나요?

운영 계좌 내역을 모아 투명성 보고 자료로 정리하는 데 맞습니다.

// related

함께 보면 좋은 흐름

같은 데이터를 제품 연동, 내부 시스템, 자동화 작업 중 어디에 둘지에 따라 구현 방식이 달라집니다.

headless

첫 수집은 작게 시작합니다

가입하고 API 키를 만드세요. 짧은 기간의 데이터로 응답 형식을 먼저 확인할 수 있습니다.