Node.js 예제: 저장 내역을 빠짐없이 가져오기

2026. 11. 18. · 82bank

82bank 에는 내역을 가져오는 길이 두 가지 있습니다. 은행에 바로 가서 받아 오는 실시간 조회(POST /v1/transactions)와, 82bank 가 정해진 주기로 모아 둔 것을 가져가는 저장 내역 조회(GET /v1/accounts/{id}/transactions)입니다. 실시간 조회는 같은 계좌 5분에 한 번으로 제한되고 시간이 걸립니다. 자기 서버의 데이터베이스에 거래를 옮겨 두려는 경우에는 저장 내역 조회가 맞습니다. 이 글은 그 코드를 Node.js 로 짭니다.

준비

Node.js 18 이상이면 fetch 가 들어 있어 따로 설치할 것이 없습니다. 관리 화면 [API 키]에서 키를 만들어 환경변수 BANK82_KEY, BANK82_SECRET 에 넣고, 가져올 계좌의 id 는 GET /v1/accounts 로 확인합니다.

호출 함수: 한도에 걸리면 기다렸다 다시

const BASE = "https://82bank.app/v1";
const AUTH = "Bearer " + process.env.BANK82_KEY + ":" + process.env.BANK82_SECRET;
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function call(path) {
  for (let i = 0; i < 3; i++) {
    const res = await fetch(BASE + path, { headers: { Authorization: AUTH } });
    const data = await res.json();
    if (res.status === 429) {
      // 키당 30분 60회를 넘으면 retryAfterSec 초 뒤에 다시
      await sleep((data.retryAfterSec || 60) * 1000);
      continue;
    }
    if (!res.ok) throw new Error(data.code + ": " + data.message);
    return data;
  }
  throw new Error("호출 한도에 계속 걸립니다");
}

오류 응답에는 항상 code 가 있습니다. UNAUTHORIZED 면 키나 시크릿이 틀렸거나 폐기된 것이고, NOT_FOUND 면 계좌 id 가 틀렸거나 다른 가입 단위의 계좌입니다. 429 는 기다리면 풀리므로 다시 부르고, 나머지는 사람이 봐야 하므로 던집니다.

cursor 로 끝까지 넘기기

async function fetchAll(accountId, from, to) {
  const out = [];
  let cursor = "";
  do {
    const q = new URLSearchParams({ from, to, limit: "500" });
    if (cursor) q.set("cursor", cursor);
    const page = await call("/accounts/" + accountId + "/transactions?" + q);
    out.push(...page.items);
    cursor = page.nextCursor;
  } while (cursor);
  return out;
}

저장 내역은 최신순으로 오고, 한 번에 최대 500건입니다. 응답의 nextCursor 를 다음 요청의 cursor 로 넘기면 앞 쪽에서 받은 것 다음부터 이어서 옵니다. nextCursor 가 비어 있으면 끝입니다. 쪽 번호(offset) 방식과 달리, 넘기는 사이에 새 거래가 저장되어도 같은 거래를 두 번 받거나 건너뛰지 않습니다.

id 로 중복 막기

// 예: better-sqlite3 로 자기 DB 에 쌓기
import Database from "better-sqlite3";
const db = new Database("bank.db");
db.exec("CREATE TABLE IF NOT EXISTS tx (id TEXT PRIMARY KEY, date TEXT, time TEXT, type TEXT, amount INTEGER, balance INTEGER, counterparty TEXT, description TEXT)");
const ins = db.prepare("INSERT INTO tx VALUES (@id, @date, @time, @type, @amount, @balance, @counterparty, @description) ON CONFLICT(id) DO NOTHING");

const today = new Date(Date.now() + 9 * 3600e3).toISOString().slice(0, 10); // 한국 날짜
const yesterday = new Date(Date.now() + 9 * 3600e3 - 86400e3).toISOString().slice(0, 10);
const rows = await fetchAll(process.env.ACCOUNT_ID, yesterday, today);
let added = 0;
for (const t of rows) added += ins.run(t).changes;
console.log("받은 거래", rows.length, "새로 넣은 거래", added);

거래마다 82bank 가 정한 id 가 있습니다. 같은 거래는 몇 번을 받아도 id 가 같으므로, 자기 DB 에서 id 를 기본키로 두고 이미 있으면 넘어가면 됩니다. 그래서 조회 기간을 넉넉하게 어제부터 오늘까지로 잡아 겹치게 받아도 안전합니다. 은행 거래에는 같은 시각, 같은 금액, 같은 적요인 거래가 진짜로 두 건 있을 수 있는데, 82bank 는 저장할 때 이것을 두 건으로 구분해 각자 다른 id 를 줍니다.

언제 돌릴까

계좌 수집 주기가 10분이면 이 코드를 10분마다 돌려도 충분합니다. 키 하나로 30분에 60번까지 부를 수 있으니, 계좌가 여러 개면 한 번 돌 때 부르는 횟수를 세어 보세요. 새 거래를 바로 알아야 한다면 이 코드는 하루 한 번 빠진 것을 채우는 용도로 두고, 평소에는 웹훅으로 받는 조합이 좋습니다. 저장 내역만 보면 82bank 가 다음 주기까지 기다리니, 급할 때는 POST /v1/accounts/{id}/refresh 로 바로 수집을 요청할 수 있습니다(같은 계좌 5분에 한 번).

실시간 조회 예제

요청할 때 은행에 바로 가서 받아 오고 싶다면 실시간 조회를 씁니다. 결과는 82bank 에 저장되지 않습니다. 실제 은행은 남의 계좌번호로 틀린 비밀번호를 넣어 계좌를 잠그지 못하도록 관리 화면에서 먼저 등록한 계좌만 조회할 수 있습니다(아니면 ACCOUNT_NOT_REGISTERED). 아래는 계좌번호 방식 은행(/v1/transactions) 예이고, 신한은행은 이용자 ID 로 로그인하는 /v1/transactions/login 을 씁니다(API 문서).

// Node.js 18 이상 (fetch 내장)
const KEY = process.env.BANK82_KEY;       // bk_…
const SECRET = process.env.BANK82_SECRET; // sk_…

const res = await fetch("https://82bank.app/v1/transactions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + KEY + ":" + SECRET,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    bankCode: "KB",
    accountType: "personal",
    accountNumber: "123456789012",
    accountPassword: "1234",
    residentNumber: "900101",
    startDate: "20261111",
    endDate: "20261118",
  }),
});
const data = await res.json();
if (res.status === 429) {
  console.log("잠시 뒤 다시:", data.retryAfterSec, "초");
} else if (!data.success) {
  console.log("실패:", res.status, data.code, data.message);
} else {
  for (const t of data.transactions) {
    console.log(t.date, t.time, t.type, t.amount, t.counterparty);
  }
}

다른 글