계좌조회 API 문서

https://api.bankapi.co.kr

API Key:    {{API_KEY}}
Secret Key: {{SECRET_KEY}}

Authorization: Bearer {apiKey}:{secretKey}

Authorization: Bearer {{API_KEY}}:{{SECRET_KEY}}

curl -X POST https://api.bankapi.co.kr/v1/transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{API_KEY}}:{{SECRET_KEY}}" \
  -d '{
    "bankCode": "NH",
    "accountNumber": "{{ACCOUNT_NUMBER}}",
    "accountPassword": "1234",
    "residentNumber": "800101",
    "accountType": "personal",
    "startDate": "20260101",
    "endDate": "20260110"
  }'

// API Key 설정
const API_KEY = '{{API_KEY}}';
const SECRET_KEY = '{{SECRET_KEY}}';

const response = await fetch(
  'https://api.bankapi.co.kr/v1/transactions',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}:${SECRET_KEY}`
    },
    body: JSON.stringify({
      bankCode: 'NH',
      accountNumber: '{{ACCOUNT_NUMBER}}',
      accountPassword: '1234',
      residentNumber: '800101',
      accountType: 'personal',
      startDate: '20260101',
      endDate: '20260110'
    })
  }
);

const data = await response.json();
console.log(data);

import requests

# API Key 설정
API_KEY = '{{API_KEY}}'
SECRET_KEY = '{{SECRET_KEY}}'

response = requests.post(
    'https://api.bankapi.co.kr/v1/transactions',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {API_KEY}:{SECRET_KEY}'
    },
    json={
        'bankCode': 'NH',
        'accountNumber': '{{ACCOUNT_NUMBER}}',
        'accountPassword': '1234',
        'residentNumber': '800101',
        'accountType': 'personal',
        'startDate': '20260101',
        'endDate': '20260110'
    }
)

data = response.json()
print(data)

import java.net.http.*;
import java.net.URI;

// API Key 설정
String API_KEY = "{{API_KEY}}";
String SECRET_KEY = "{{SECRET_KEY}}";
String API_URL = "https://api.bankapi.co.kr/v1/transactions";

HttpClient client = HttpClient.newHttpClient();

String requestBody = """
    {
        "bankCode": "NH",
        "accountNumber": "{{ACCOUNT_NUMBER}}",
        "accountPassword": "1234",
        "residentNumber": "800101",
        "accountType": "personal",
        "startDate": "20260101",
        "endDate": "20260110"
    }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(API_URL))
    .header("Content-Type", "application/json")
    .header("Authorization", "Bearer " + API_KEY + ":" + SECRET_KEY)
    .POST(HttpRequest.BodyPublishers.ofString(requestBody))
    .build();

HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString()
);
System.out.println(response.body());

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

// API Key 설정
const (
    apiKey    = "{{API_KEY}}"
    secretKey = "{{SECRET_KEY}}"
    apiURL    = "https://api.bankapi.co.kr/v1/transactions"
)

func main() {
    requestBody, _ := json.Marshal(map[string]string{
        "bankCode":        "NH",
        "accountNumber":   "{{ACCOUNT_NUMBER}}",
        "accountPassword": "1234",
        "residentNumber":  "800101",
        "accountType":     "personal",
        "startDate":       "20260101",
        "endDate":         "20260110",
    })

    req, _ := http.NewRequest("POST", apiURL, bytes.NewBuffer(requestBody))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer "+apiKey+":"+secretKey)

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

{
  "success": true,
  "transactions": [
    {
      "date": "2026-01-10",
      "time": "14:30:25",
      "description": "스마트출금",
      "displayName": "스타벅스",
      "counterparty": "스타벅스코리아",
      "amount": 50000,
      "balance": 1234567,
      "type": "withdrawal",
      "branch": "강남"
    },
    {
      "date": "2026-01-09",
      "time": "09:15:00",
      "description": "FBS입금",
      "displayName": "",
      "counterparty": "홍길동",
      "amount": 3000000,
      "balance": 1284567,
      "type": "deposit",
      "branch": "국민 0068738"
    }
  ],
  "accountInfo": {
    "accountNumber": "{{ACCOUNT_NUMBER}}",
    "balance": 1284567
  }
}

{
  "success": false,
  "transactions": [],
  "error": "계좌번호 오류입니다. 계좌번호를 다시 확인해 주세요. (안내코드 01506)",
  "code": "BANK_REJECTED",
  "message": "계좌번호 오류입니다. 계좌번호를 다시 확인해 주세요. (안내코드 01506)"
}

{
  "success": false,
  "error": "INVALID_BUSINESS_NUMBER",
  "code": "INVALID_BUSINESS_NUMBER",
  "message": "사업자번호의 뒷7자리가 필요해요."
}

{
  "success": false,
  "error": "ACCOUNT_COOLDOWN",
  "code": "ACCOUNT_COOLDOWN",
  "message": "동일 계좌는 5분에 1회만 조회할 수 있습니다. 잠시 후 다시 시도해 주세요.",
  "retryAfterSec": 540
}

{
  "success": false,
  "error": "QUERY_QUOTA_EXCEEDED",
  "code": "QUERY_QUOTA_EXCEEDED",
  "message": "조회 한도(30분당 30회)를 초과했습니다.",
  "retryAfterSec": 1200
}

{
  "success": false,
  "error": "TOO_MANY_REQUESTS",
  "code": "TOO_MANY_REQUESTS",
  "message": "요청 한도(30분당 60회)를 초과했습니다.",
  "retryAfterSec": 800
}

{
  "success": false,
  "error": "Invalid API Key",
  "code": "UNAUTHORIZED",
  "message": "인증에 실패했습니다. Authorization: Bearer {apiKey}:{secretKey} 형식과 키 값을 확인해 주세요."
}

curl -X POST https://api.bankapi.co.kr/v1/transactions/login \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{API_KEY}}:{{SECRET_KEY}}" \
  -d '{
    "bankCode": "SH",
    "loginId": "{{LOGIN_ID}}",
    "loginPassword": "{{LOGIN_PASSWORD}}",
    "accounts": [
      { "accountNumber": "{{ACCOUNT_NUMBER}}", "accountPassword": "{{ACCOUNT_PASSWORD}}" }
    ],
    "startDate": "20260101",
    "endDate": "20260131",
    "sortOrder": "recent"
  }'

{
  "success": true,
  "results": [
    {
      "accountNumber": "{{ACCOUNT_NUMBER}}",
      "success": true,
      "accountInfo": {
        "accountNumber": "{{ACCOUNT_NUMBER}}",
        "accountName": "쏠편한 입출금통장(저축예금)",
        "accountHolder": "홍길동",
        "balance": 1284567
      },
      "transactions": [
        {
          "date": "2026/01/10",
          "time": "14:30:25",
          "description": "타행이체",
          "displayName": "",
          "counterparty": "홍길동",
          "amount": 50000,
          "balance": 1234567,
          "type": "withdrawal",
          "branch": "종로중"
        }
      ]
    }
  ]
}

HTTP/1.1 429 Too Many Requests
Retry-After: 540

const API_KEY = '{{API_KEY}}';
const SECRET_KEY = '{{SECRET_KEY}}';

async function getTransactions(body, maxRetries = 2) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch('https://api.bankapi.co.kr/v1/transactions', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${API_KEY}:${SECRET_KEY}`
      },
      body: JSON.stringify(body)
    });
    const data = await res.json();

    // 429(제한) 이면 retryAfterSec 만큼 대기 후 재시도
    if (res.status === 429 && attempt < maxRetries) {
      const waitSec = data.retryAfterSec || Number(res.headers.get('Retry-After')) || 60;
      console.log(`Rate limit(${data.error}) — ${waitSec}s 후 재시도`);
      await new Promise(r => setTimeout(r, waitSec * 1000));
      continue;
    }
    if (!res.ok) throw new Error(data.error || `HTTP ${res.status}`);
    return data.transactions;
  }
}

// 사용 예
const txs = await getTransactions({
  bankCode: 'NH', accountNumber: '{{ACCOUNT_NUMBER}}', accountPassword: '1234',
  residentNumber: '800101', startDate: '20260101', endDate: '20260110'
});
txs.forEach(t => console.log(`${t.date} ${t.type} ${t.amount}원 (잔액 ${t.balance})`));

import requests, time

API_KEY = '{{API_KEY}}'
SECRET_KEY = '{{SECRET_KEY}}'

def get_transactions(body, max_retries=2):
    for attempt in range(max_retries + 1):
        res = requests.post(
            'https://api.bankapi.co.kr/v1/transactions',
            headers={
                'Content-Type': 'application/json',
                'Authorization': f'Bearer {API_KEY}:{SECRET_KEY}'
            },
            json=body
        )
        data = res.json()

        # 429(제한) 이면 retryAfterSec 만큼 대기 후 재시도
        if res.status_code == 429 and attempt < max_retries:
            wait = data.get('retryAfterSec') or int(res.headers.get('Retry-After', 60))
            print(f"Rate limit({data['error']}) — {wait}s 후 재시도")
            time.sleep(wait)
            continue
        res.raise_for_status()
        return data['transactions']

# 사용 예
txs = get_transactions({
    'bankCode': 'NH', 'accountNumber': '{{ACCOUNT_NUMBER}}', 'accountPassword': '1234',
    'residentNumber': '800101', 'startDate': '20260101', 'endDate': '20260110'
})
for t in txs:
    print(f"{t['date']} {t['type']} {t['amount']}원 (잔액 {t['balance']})")

{
  "success": false,
  "error": "ACCOUNT_COOLDOWN",
  "code": "ACCOUNT_COOLDOWN",
  "message": "동일 계좌는 5분에 1회만 조회할 수 있습니다. 잠시 후 다시 시도해 주세요.",
  "retryAfterSec": 540
}