headless

// platform

은행 데이터를 내 서비스에 임베드

사용자의 은행 입출금내역을 내 제품 안에서 보여 주고 싶을 때 씁니다. 23개 은행을 하나의 형식으로 받아 화면에 그대로 보여 줍니다.

// 상황

이런 상황이라면

기관마다 화면이 다르다

은행마다 입출금내역 화면과 다운로드 형식이 제각각이라, 내 제품에 붙이려면 기관 수만큼 파서를 만들어야 합니다.

사용자에게 또 올리라고 하기 어렵다

사용자가 은행에서 직접 엑셀을 받아 올리는 과정은 이탈을 만듭니다. 제품 안에서 바로 보여 주는 편이 낫습니다.

유지보수가 계속 쌓인다

기관이 화면을 바꿀 때마다 파서가 깨집니다. 이 일을 내부에서 직접 맡기엔 품이 많이 듭니다.

// 흐름

어떻게 동작하나

  1. 01

    자격증명 등록

    사용자의 은행 자격증명을 등록합니다. 암호화해 보관하고 수집할 때만 사용합니다.

  2. 02

    수집 요청

    계좌 목록과 입출금내역을 요청합니다. 기간이 길면 자동으로 나눠 받습니다.

  3. 03

    화면에 임베드

    표준 데이터 형식으로 온 결과를 그대로 제품 화면에 보여 줍니다. 기관 구분 없이 한 번만 매핑하면 됩니다.

// schemas

사용 데이터 형식

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

// 결과물

손에 남는 것

  • 23개 은행 입출금내역을 동일한 응답 구조로
  • 계좌 잔액과 거래 후 잔액까지 한 번에
  • 기관별 파서·유지보수에서 해방
  • 사용자가 자료를 직접 올리지 않아도 되는 흐름

// 실행 가이드

그대로 따라 하면 됩니다

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

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

02실행

실행 방식실행 방식 하나만 고르면 됩니다. 결과 형식은 같습니다.

한 줄이면 끝. 기본 출력은 터미널 표.

terminal
h6s fetch bank.transactions.cb.v1 --provider CB_KB --month 2026-04 --output markdown

이렇게 보이면 성공

✓ 132건 수신  (2026-04-01 ~ 2026-04-30)
거래일       적요              금액         잔액
2026-04-29   ㈜에이클라이언트 +1,540,000   8,420,300

provider 코드는 대문자 고정입니다. 국민은행 CB_KB · 기업은행 CB_IBK · 신한 CB_SHINHAN. 소문자로 주면 백엔드가 거부합니다.

03검증

  • 터미널에 거래일·적요·금액·잔액 4개 컬럼 표가 N건 출력된다.
  • 명령 종료 후 echo $? 가 0 (성공). 1=비즈니스 에러·3=인증 에러.
  • --save ./out/ 를 붙이면 ./out/ 아래에 자동 파일명으로 저장된다.

04흔한 에러

CREDENTIAL_INSUFFICIENT_FOR_PROVIDER

그 provider 에 매칭되는 자격증명이 워크스페이스에 없습니다.

해결 h6s credentials create --interactive --cert (공동인증서 1개로 전 기관 공용).

CERT_EXPIRED · CERT_WRONG_PASSWORD

등록된 공동인증서가 만료됐거나 비밀번호가 틀렸다.

해결 h6s credentials update 로 인증서/비밀번호 갱신 후 재실행.

DATE_RANGE_EXCEEDED

요청 기간이 그 기관이 허용하는 한 번 조회 범위를 넘었다.

해결 --month 또는 더 짧은 --from/--to 로 나눠서 호출.

NO_API_KEY

API Key 가 설정되어 있지 않습니다.

해결 h6s init 또는 export H6S_API_KEY=h6s_live_...

API_RATE_LIMITED (429)

분/시간당 호출 한도를 넘었다.

해결 잠시 후 재시도. CLI는 Retry-After 를 존중해 1회 자동 재시도합니다.

05변형

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

임의 기간 (월 단위가 아닐 때)

terminal
h6s fetch bank.transactions.cb.v1 --provider CB_KB --from 2026-04-15 --to 2026-04-22

CSV 파일로 저장

terminal
h6s fetch bank.transactions.cb.v1 --provider CB_KB --month 2026-04 --output csv --save bank-2026-04.csv

CLI 없이 raw HTTP (cURL)

terminal
curl -s https://api.h6s.ai/api/v1/data-jobs \
  -H "Authorization: Bearer $H6S_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"providerCode":"CB_KB","schema":"bank.transactions.cb.v1","params":{"month":"2026-04"}}'
# 응답의 id 로 GET /api/v1/data-jobs/{id}/results 를 완료까지 폴링
전체 가이드 페이지로 보기

// 더 보기

관련 시나리오

terminal
[2026-05-01] bank.transactions.cb.v1 124 records → admin 200[2026-05-01] hometax.tax-invoices.sales.v1 38 records → admin 200[2026-05-01] hometax.tax-invoices.purchase.v1 52 records → admin 200[2026-05-01] hometax.cash-receipts.sales.v1 17 records → admin 200 ✓ done▍

자체 정산 어드민에 매월 적재

매입·매출 세금계산서, 매출 현금영수증, 은행 입출금을 자체 어드민 백엔드로 매달 적재. 정산 매칭·중복 제거·확인은 어드민이 책임진다.

REST API·매월 1일 09:00 KST

// faq

자주 묻는 질문

어떤 은행을 지원하나요?

기업뱅킹 기준 주요 은행을 지원합니다. 전체 목록은 지원 기관 문서에서 확인할 수 있습니다.

잔액도 받을 수 있나요?

계좌 목록에서 잔액과 출금 가능액을, 입출금내역에서 거래 후 잔액을 받습니다.

입금과 출금은 어떻게 구분되나요?

금액에 부호가 붙어 옵니다. 입금은 양수, 출금은 음수입니다.

// related

함께 보면 좋은 흐름

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

headless

첫 수집은 작게 시작합니다

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

무료로 첫 수집 시작