API 연동 가이드

인증부터 최종 사용자 등록, 공동인증서 등록, 조회 요청, 결과 수신까지 기본 연동 흐름을 4단계로 안내해요.

최종 업데이트

기본 주소

모든 API는 이 주소 아래로 요청해요.

https://bank.di3.kr

인증

요청마다 헤더에 내 API 키를 넣어요.

X-API-Key: YOUR_API_KEY

연동 흐름

첫 호출 해 보기

키 자리의 YOUR_API_KEY 를 내 API 키로 바꿔 주세요. 최종 사용자 등록(1단계)부터 시작해요.

curl -X POST "https://bank.di3.kr/api/end-users" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "your-internal-user-id",
    "user_type": "personal",
    "name": "홍길동"
  }'
const res = await fetch("https://bank.di3.kr/api/end-users", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "external_ref": "your-internal-user-id",
    "user_type": "personal",
    "name": "홍길동"
  }),
});
const data = await res.json();
import requests

res = requests.post(
    "https://bank.di3.kr/api/end-users",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
      "external_ref": "your-internal-user-id",
      "user_type": "personal",
      "name": "홍길동"
    },
)
print(res.json())
STEP 01POST/api/end-users

최종 사용자 등록

API를 사용할 최종 사용자를 등록해요. 응답으로 받은 id(end_user_id)를 이후 요청에 써요.

요청

curl -X POST "https://bank.di3.kr/api/end-users" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "your-internal-user-id",
    "user_type": "personal",
    "name": "홍길동"
  }'
const res = await fetch("https://bank.di3.kr/api/end-users", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "external_ref": "your-internal-user-id",
    "user_type": "personal",
    "name": "홍길동"
  }),
});
const data = await res.json();
import requests

res = requests.post(
    "https://bank.di3.kr/api/end-users",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
      "external_ref": "your-internal-user-id",
      "user_type": "personal",
      "name": "홍길동"
    },
)
print(res.json())

요청 값

이름 · 형식설명
external_ref string 선택내 시스템의 사용자 고유 ID. 이름과 둘 중 하나는 꼭 보내야 해요.
user_type string 선택personal(개인) 또는 business(사업자). 비우면 personal이에요.
name string 선택사용자 이름

응답

// 201 Created
{
  "id": 1,
  "external_ref": "your-internal-user-id",
  "user_type": "personal",
  "name": "홍길동",
  "created_at": "2026-11-16T09:00:00"
}
// 409 Conflict
{
  "detail": "이미 같은 외부 ID와 유형으로 등록된 회원이 있습니다"
}

// 422 Unprocessable Entity
{
  "detail": [{
    "type": "enum",
    "loc": ["body", "user_type"],
    "msg": "Input should be 'personal' or 'business'"
  }]
}

// 401 Unauthorized
{
  "detail": "인증 실패"
}

// 403 Forbidden
{
  "detail": "비활성 회원"
}
알아 두세요
  • 이름과 external_ref 중 하나도 없으면 422예요. 같은 external_ref와 user_type으로는 한 번만 등록할 수 있어요(409).
  • 목록 조회는 GET /api/end-users 로, 페이지를 나누어 가져와요.
  • 삭제하면 인증서와 계좌 데이터도 함께 삭제돼요.
STEP 02POST/api/certificates

공동인증서 등록

공동인증서 파일을 Base64로 보내 등록해요. SDK 팝업으로 등록하는 방법을 권장해요.

방법 A · SDK 팝업 (권장)

<script src="https://cdn.di3.kr/cert-modal.js"></script>
<script>
  DiCert.open({
    apiKey: "YOUR_API_KEY",
    endUserId: 1,
    onSuccess: (certId) => { console.log("등록 완료:", certId); }
  });
</script>

방법 B · 직접 API 호출

curl -X POST "https://bank.di3.kr/api/certificates" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "end_user_id": 1,
    "certBase64": "MIIEpAIBAAKCAQ...",
    "keyBase64": "MIIEvQIBADANBg...",
    "password": "cert_password"
  }'
const res = await fetch("https://bank.di3.kr/api/certificates", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "end_user_id": 1,
    "certBase64": "MIIEpAIBAAKCAQ...",
    "keyBase64": "MIIEvQIBADANBg...",
    "password": "cert_password"
  }),
});
const data = await res.json();
import requests

res = requests.post(
    "https://bank.di3.kr/api/certificates",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
      "end_user_id": 1,
      "certBase64": "MIIEpAIBAAKCAQ...",
      "keyBase64": "MIIEvQIBADANBg...",
      "password": "cert_password"
    },
)
print(res.json())

요청 값

이름 · 형식설명
end_user_id integer 선택인증서를 등록할 최종 사용자 ID. end_user_id 또는 external_ref(와 user_type) 중 하나로 사용자를 지정해요.
certBase64 string 필수인증서(signCert.der)를 Base64로 인코딩한 값
keyBase64 string 필수개인키(signPri.key)를 Base64로 인코딩한 값
password string 필수인증서 비밀번호

응답

// 201 Created
{
  "id": 1,
  "end_user_id": 1,
  "cert_type": "personal",
  "channel": "personal",
  "owner_cn": "홍길동",
  "issuer_dn": null,
  "expiry": "2027-04-07",
  "fingerprint": null,
  "cert_status": "active",
  "scrape_enabled": true,
  "mismatch_reason": null,
  "created_at": "2026-11-16T09:00:00"
}
// 400 Bad Request
{
  "detail": "end_user_id 또는 external_ref 필요"
}

// 404 Not Found
{
  "detail": "사용자를 찾을 수 없습니다"
}

// 401 Unauthorized
{
  "detail": "인증 실패"
}

// 403 Forbidden
{
  "detail": "비활성 회원"
}
알아 두세요
  • 최종 사용자 한 명당 인증서는 하나예요. 다시 등록하면 기존 인증서를 바꿔 끼워요.
  • cert_status는 active · expired · mismatched · blocked 중 하나예요. scrape_enabled가 false이면 조회가 차단돼요.
  • 유효기간(expiry)이 지나면 인증서를 다시 등록해야 해요.
STEP 03POST/api/v1/scrape

조회 요청

한 명의 계좌 잔액과 거래내역 조회를 요청해요. 비동기로 처리돼서 202와 job_id를 바로 돌려주고, 끝나면 웹훅으로 알려 줘요.

요청

curl -X POST "https://bank.di3.kr/api/v1/scrape" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "end_user_id": 1,
    "bank_code": "shinhan",
    "webhook_url": "https://yourapp.com/webhook"
  }'
const res = await fetch("https://bank.di3.kr/api/v1/scrape", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "end_user_id": 1,
    "bank_code": "shinhan",
    "webhook_url": "https://yourapp.com/webhook"
  }),
});
const data = await res.json();
import requests

res = requests.post(
    "https://bank.di3.kr/api/v1/scrape",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
      "end_user_id": 1,
      "bank_code": "shinhan",
      "webhook_url": "https://yourapp.com/webhook"
    },
)
print(res.json())

요청 값

이름 · 형식설명
end_user_id integer 필수1단계에서 받은 최종 사용자 ID (숫자)
bank_code string 필수shinhan · kb · woori · hana · ibk · nh 중 하나
with_transactions boolean 선택false로 보내면 거래내역 없이 계좌와 잔액만 가져와요. 기본은 true예요.
webhook_url string 선택완료 알림을 받을 주소. 비우면 조회(폴링)로만 확인할 수 있어요.

응답

// 202 Accepted
{
  "job_id": "3f2b8e5a-6c1d-4e7a-9b2f-8d4c1a7e5f90",
  "end_user_id": 1,
  "external_ref": null,
  "bank_code": "shinhan",
  "channel": "personal",
  "status": "queued",
  "error": null,
  "requested_at": "2026-11-16T09:00:00",
  "finished_at": null
}
// 400 Bad Request
{
  "detail": "end_user_id 또는 external_ref 필요"
}

// 400 Bad Request
{
  "detail": "등록된 인증서가 없습니다"
}

// 402 Payment Required
{
  "detail": "크레딧이 부족합니다. 필요: 20원, 보유: 0원"
}

// 404 Not Found
{
  "detail": "사용자를 찾을 수 없습니다"
}

// 401 Unauthorized
{
  "detail": "인증 실패"
}

// 403 Forbidden
{
  "detail": "비활성 회원"
}
알아 두세요
  • 요청은 비동기로 처리돼요. 즉시 job_id를 받고 완료 시 웹훅으로 알려 줘요.
  • 조회 1건마다 무료 한도 또는 크레딧이 차감돼요. 부족하면 402예요.
  • 인증서가 차단된 상태이면 오류가 아니라 202에 status가 blocked로 와요.
  • end_user_id 대신 external_ref(와 user_type)로 사용자를 지정할 수도 있어요.
  • 여러 건은 일괄 요청(최대 500건)으로 한 번에 보낼 수 있어요. 이때는 batch_id를 돌려줘요.
STEP 04GET/api/v1/jobs/{job_id}

결과 수신

조회 작업이 어디까지 진행됐는지 조회해요. 상태만 돌려주고, 계좌와 거래내역은 웹훅 또는 저장된 결과 조회로 받아요.

진행 상태 조회하기 (폴링)

curl -X GET "https://bank.di3.kr/api/v1/jobs/3f2b8e5a-6c1d-4e7a-9b2f-8d4c1a7e5f90" \
  -H "X-API-Key: YOUR_API_KEY"
const res = await fetch("https://bank.di3.kr/api/v1/jobs/3f2b8e5a-6c1d-4e7a-9b2f-8d4c1a7e5f90", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();
import requests

res = requests.get(
    "https://bank.di3.kr/api/v1/jobs/3f2b8e5a-6c1d-4e7a-9b2f-8d4c1a7e5f90",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json())

요청 값

이름 · 형식설명
job_id string 필수조회 요청에서 받은 job_id (주소에 넣어요)

응답

// 200 OK
{
  "job_id": "3f2b8e5a-6c1d-4e7a-9b2f-8d4c1a7e5f90",
  "end_user_id": 1,
  "external_ref": null,
  "bank_code": "shinhan",
  "channel": "personal",
  "status": "success",
  "error": null,
  "requested_at": "2026-11-16T09:00:00",
  "finished_at": "2026-11-16T09:00:12"
}
// 404 Not Found
{
  "detail": "작업을 찾을 수 없습니다"
}

// 401 Unauthorized
{
  "detail": "인증 실패"
}

// 403 Forbidden
{
  "detail": "비활성 회원"
}

웹훅으로 받기

// 작업이 끝나면 webhook_url 로 이 내용을 POST 해 드려요
{
  "job_id": "3f2b8e5a-6c1d-4e7a-9b2f-8d4c1a7e5f90",
  "batch_id": null,
  "end_user_id": 1,
  "external_ref": null,
  "bank_code": "shinhan",
  "status": "success",
  "accounts": [{
    "account_no_masked": "110-***-6789",
    "holder_name": "홍길동",
    "account_type": "입출금",
    "balance": 1234567,
    "currency": "KRW",
    "transactions": [{
      "txn_at": "2026-11-15T14:32:00",
      "amount": -50000,
      "balance_after": 1234567,
      "type": "출금",
      "memo": "스타벅스 강남점",
      "counterparty": "스타벅스"
    }]
  }],
  "error": null,
  "completed_at": "2026-11-16T09:00:12+00:00"
}
알아 두세요
  • 웹훅의 status 값: success · partial · failed · blocked
  • 웹훅 전송에 실패하면 최대 3회까지 다시 시도해요. 같은 작업의 알림이 중복으로 올 수 있으니 job_id로 구분해 주세요.
  • blocked 는 인증서가 만료됐거나 은행 보안이 강화됐을 때 나타나요.
  • 위 조회(폴링)는 진행 상태만 돌려줘요. 계좌와 거래내역은 웹훅으로 받거나 저장된 계좌 목록과 저장된 거래내역으로 가져와요.
  • 계좌번호는 가려진 상태(account_no_masked)로 오고, 일괄 요청이면 batch_id가 채워져요. 요청에 붙인 ref는 external_ref로 돌아와요.
POST/api/end-users

사용자 등록

API를 사용할 최종 사용자를 등록해요. 응답으로 받은 id(end_user_id)를 이후 요청에 써요.

요청

curl -X POST "https://bank.di3.kr/api/end-users" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "your-internal-user-id",
    "user_type": "personal",
    "name": "홍길동"
  }'
const res = await fetch("https://bank.di3.kr/api/end-users", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "external_ref": "your-internal-user-id",
    "user_type": "personal",
    "name": "홍길동"
  }),
});
const data = await res.json();
import requests

res = requests.post(
    "https://bank.di3.kr/api/end-users",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
      "external_ref": "your-internal-user-id",
      "user_type": "personal",
      "name": "홍길동"
    },
)
print(res.json())

요청 값

이름 · 형식설명
external_ref string 선택내 시스템의 사용자 고유 ID. 이름과 둘 중 하나는 꼭 보내야 해요.
user_type string 선택personal(개인) 또는 business(사업자). 비우면 personal이에요.
name string 선택사용자 이름

응답

// 201 Created
{
  "id": 1,
  "external_ref": "your-internal-user-id",
  "user_type": "personal",
  "name": "홍길동",
  "created_at": "2026-11-16T09:00:00"
}
// 409 Conflict
{
  "detail": "이미 같은 외부 ID와 유형으로 등록된 회원이 있습니다"
}

// 422 Unprocessable Entity
{
  "detail": [{
    "type": "enum",
    "loc": ["body", "user_type"],
    "msg": "Input should be 'personal' or 'business'"
  }]
}

// 401 Unauthorized
{
  "detail": "인증 실패"
}

// 403 Forbidden
{
  "detail": "비활성 회원"
}
알아 두세요
  • 이름과 external_ref 중 하나도 없으면 422예요. 같은 external_ref와 user_type으로는 한 번만 등록할 수 있어요(409).
  • 목록 조회는 GET /api/end-users 로, 페이지를 나누어 가져와요.
  • 삭제하면 인증서와 계좌 데이터도 함께 삭제돼요.
GET/api/end-users

사용자 목록 조회

등록된 최종 사용자를 페이지 단위로 조회해요.

요청

curl -X GET "https://bank.di3.kr/api/end-users?page=1&per_page=20&q=홍길동" \
  -H "X-API-Key: YOUR_API_KEY"
const res = await fetch("https://bank.di3.kr/api/end-users?page=1&per_page=20&q=홍길동", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();
import requests

res = requests.get(
    "https://bank.di3.kr/api/end-users",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"page": "1", "per_page": "20", "q": "홍길동"},
)
print(res.json())

요청 값

이름 · 형식설명
page integer 선택페이지 번호 (기본 1)
per_page integer 선택한 페이지에 가져올 개수 (기본 20)
q string 선택이름 또는 external_ref로 검색
user_type string 선택personal 또는 business로 거르기

응답

// 200 OK
{
  "items": [{
    "id": 1,
    "external_ref": "your-internal-user-id",
    "user_type": "personal",
    "name": "홍길동",
    "created_at": "2026-11-16T09:00:00"
  }],
  "meta": { "page": 1, "per_page": 20, "total": 42, "total_pages": 3 }
}
// 401 Unauthorized
{
  "detail": "인증 실패"
}

// 403 Forbidden
{
  "detail": "비활성 회원"
}
DEL/api/end-users/{id}

사용자 삭제

최종 사용자를 삭제해요. 인증서와 계좌 데이터도 함께 삭제돼요.

요청

curl -X DELETE "https://bank.di3.kr/api/end-users/1" \
  -H "X-API-Key: YOUR_API_KEY"
const res = await fetch("https://bank.di3.kr/api/end-users/1", {
  method: "DELETE",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
console.log(res.status);
import requests

res = requests.delete(
    "https://bank.di3.kr/api/end-users/1",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.status_code)

요청 값

이름 · 형식설명
id integer 필수삭제할 최종 사용자 ID (숫자, 주소에 넣어요)

응답

// 204 No Content
// 404 Not Found
{
  "detail": "사용자를 찾을 수 없습니다"
}

// 401 Unauthorized
{
  "detail": "인증 실패"
}

// 403 Forbidden
{
  "detail": "비활성 회원"
}
알아 두세요
  • 삭제한 사용자의 데이터는 복구할 수 없어요.
POST/api/certificates

인증서 등록

공동인증서 파일을 Base64로 보내 등록해요. SDK 팝업으로 등록하는 방법을 권장해요.

요청

curl -X POST "https://bank.di3.kr/api/certificates" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "end_user_id": 1,
    "certBase64": "MIIEpAIBAAKCAQ...",
    "keyBase64": "MIIEvQIBADANBg...",
    "password": "cert_password"
  }'
const res = await fetch("https://bank.di3.kr/api/certificates", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "end_user_id": 1,
    "certBase64": "MIIEpAIBAAKCAQ...",
    "keyBase64": "MIIEvQIBADANBg...",
    "password": "cert_password"
  }),
});
const data = await res.json();
import requests

res = requests.post(
    "https://bank.di3.kr/api/certificates",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
      "end_user_id": 1,
      "certBase64": "MIIEpAIBAAKCAQ...",
      "keyBase64": "MIIEvQIBADANBg...",
      "password": "cert_password"
    },
)
print(res.json())

요청 값

이름 · 형식설명
end_user_id integer 선택인증서를 등록할 최종 사용자 ID. end_user_id 또는 external_ref(와 user_type) 중 하나로 사용자를 지정해요.
certBase64 string 필수인증서(signCert.der)를 Base64로 인코딩한 값
keyBase64 string 필수개인키(signPri.key)를 Base64로 인코딩한 값
password string 필수인증서 비밀번호

응답

// 201 Created
{
  "id": 1,
  "end_user_id": 1,
  "cert_type": "personal",
  "channel": "personal",
  "owner_cn": "홍길동",
  "issuer_dn": null,
  "expiry": "2027-04-07",
  "fingerprint": null,
  "cert_status": "active",
  "scrape_enabled": true,
  "mismatch_reason": null,
  "created_at": "2026-11-16T09:00:00"
}
// 400 Bad Request
{
  "detail": "end_user_id 또는 external_ref 필요"
}

// 404 Not Found
{
  "detail": "사용자를 찾을 수 없습니다"
}

// 401 Unauthorized
{
  "detail": "인증 실패"
}

// 403 Forbidden
{
  "detail": "비활성 회원"
}
알아 두세요
  • 최종 사용자 한 명당 인증서는 하나예요. 다시 등록하면 기존 인증서를 바꿔 끼워요.
  • cert_status는 active · expired · mismatched · blocked 중 하나예요. scrape_enabled가 false이면 조회가 차단돼요.
  • 유효기간(expiry)이 지나면 인증서를 다시 등록해야 해요.
GET/api/certificates

인증서 목록 조회

등록된 인증서 목록을 조회해요. 응답은 목록(배열) 그대로예요.

요청

curl -X GET "https://bank.di3.kr/api/certificates?end_user_id=1" \
  -H "X-API-Key: YOUR_API_KEY"
const res = await fetch("https://bank.di3.kr/api/certificates?end_user_id=1", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();
import requests

res = requests.get(
    "https://bank.di3.kr/api/certificates",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"end_user_id": "1"},
)
print(res.json())

요청 값

이름 · 형식설명
end_user_id integer 선택이 최종 사용자의 인증서만 볼 때 넣어요

응답

// 200 OK
[
  {
    "id": 1,
    "end_user_id": 1,
    "cert_type": "personal",
    "channel": "personal",
    "owner_cn": "홍길동",
    "issuer_dn": null,
    "expiry": "2027-04-07",
    "fingerprint": null,
    "cert_status": "active",
    "scrape_enabled": true,
    "mismatch_reason": null,
    "created_at": "2026-11-16T09:00:00"
  }
]
// 401 Unauthorized
{
  "detail": "인증 실패"
}

// 403 Forbidden
{
  "detail": "비활성 회원"
}
POST/api/v1/scrape

단건 조회 요청

한 명의 계좌 잔액과 거래내역 조회를 요청해요. 비동기로 처리돼서 202와 job_id를 바로 돌려주고, 끝나면 웹훅으로 알려 줘요.

요청

curl -X POST "https://bank.di3.kr/api/v1/scrape" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "end_user_id": 1,
    "bank_code": "shinhan",
    "webhook_url": "https://yourapp.com/webhook"
  }'
const res = await fetch("https://bank.di3.kr/api/v1/scrape", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "end_user_id": 1,
    "bank_code": "shinhan",
    "webhook_url": "https://yourapp.com/webhook"
  }),
});
const data = await res.json();
import requests

res = requests.post(
    "https://bank.di3.kr/api/v1/scrape",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
      "end_user_id": 1,
      "bank_code": "shinhan",
      "webhook_url": "https://yourapp.com/webhook"
    },
)
print(res.json())

요청 값

이름 · 형식설명
end_user_id integer 필수1단계에서 받은 최종 사용자 ID (숫자)
bank_code string 필수shinhan · kb · woori · hana · ibk · nh 중 하나
with_transactions boolean 선택false로 보내면 거래내역 없이 계좌와 잔액만 가져와요. 기본은 true예요.
webhook_url string 선택완료 알림을 받을 주소. 비우면 조회(폴링)로만 확인할 수 있어요.

응답

// 202 Accepted
{
  "job_id": "3f2b8e5a-6c1d-4e7a-9b2f-8d4c1a7e5f90",
  "end_user_id": 1,
  "external_ref": null,
  "bank_code": "shinhan",
  "channel": "personal",
  "status": "queued",
  "error": null,
  "requested_at": "2026-11-16T09:00:00",
  "finished_at": null
}
// 400 Bad Request
{
  "detail": "end_user_id 또는 external_ref 필요"
}

// 400 Bad Request
{
  "detail": "등록된 인증서가 없습니다"
}

// 402 Payment Required
{
  "detail": "크레딧이 부족합니다. 필요: 20원, 보유: 0원"
}

// 404 Not Found
{
  "detail": "사용자를 찾을 수 없습니다"
}

// 401 Unauthorized
{
  "detail": "인증 실패"
}

// 403 Forbidden
{
  "detail": "비활성 회원"
}
알아 두세요
  • 요청은 비동기로 처리돼요. 즉시 job_id를 받고 완료 시 웹훅으로 알려 줘요.
  • 조회 1건마다 무료 한도 또는 크레딧이 차감돼요. 부족하면 402예요.
  • 인증서가 차단된 상태이면 오류가 아니라 202에 status가 blocked로 와요.
  • end_user_id 대신 external_ref(와 user_type)로 사용자를 지정할 수도 있어요.
  • 여러 건은 일괄 요청(최대 500건)으로 한 번에 보낼 수 있어요. 이때는 batch_id를 돌려줘요.
POST/api/v1/scrape/bulk

일괄 조회 요청

최대 500건의 조회를 한 번에 요청해요.

요청

curl -X POST "https://bank.di3.kr/api/v1/scrape/bulk" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobs": [
      {
        "end_user_id": 1,
        "bank_code": "shinhan",
        "ref": "order-1001"
      },
      {
        "end_user_id": 2,
        "bank_code": "hana",
        "ref": "order-1002"
      }
    ],
    "webhook_url": "https://yourapp.com/webhook"
  }'
const res = await fetch("https://bank.di3.kr/api/v1/scrape/bulk", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "jobs": [
      {
        "end_user_id": 1,
        "bank_code": "shinhan",
        "ref": "order-1001"
      },
      {
        "end_user_id": 2,
        "bank_code": "hana",
        "ref": "order-1002"
      }
    ],
    "webhook_url": "https://yourapp.com/webhook"
  }),
});
const data = await res.json();
import requests

res = requests.post(
    "https://bank.di3.kr/api/v1/scrape/bulk",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
      "jobs": [
        {
          "end_user_id": 1,
          "bank_code": "shinhan",
          "ref": "order-1001"
        },
        {
          "end_user_id": 2,
          "bank_code": "hana",
          "ref": "order-1002"
        }
      ],
      "webhook_url": "https://yourapp.com/webhook"
    },
)
print(res.json())

요청 값

이름 · 형식설명
jobs array 필수조회할 건 목록 (1~500건). 각 건은 end_user_id와 bank_code가 필요하고, with_transactions · ref · webhook_url은 선택이에요.
webhook_url string 선택완료 알림을 받을 주소. 비우면 조회(폴링)로만 확인할 수 있어요.

응답

// 202 Accepted
{
  "batch_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "webhook_url": "https://yourapp.com/webhook",
  "total": 2,
  "queued": 2,
  "processing": 0,
  "success": 0,
  "failed": 0,
  "created_at": "2026-11-16T09:00:00"
}
// 402 Payment Required
{
  "detail": "크레딧이 부족합니다. 필요: 20원, 보유: 0원"
}

// 422 Unprocessable Entity
{
  "detail": [{
    "type": "missing",
    "loc": ["body", "jobs"],
    "msg": "Field required"
  }]
}

// 401 Unauthorized
{
  "detail": "인증 실패"
}

// 403 Forbidden
{
  "detail": "비활성 회원"
}
알아 두세요
  • 건마다 보낸 ref는 웹훅의 external_ref로 그대로 돌아와요. 내 쪽 식별자를 붙여 두면 결과를 맞춰 보기 쉬워요.
  • 사용자나 인증서가 없거나 차단된 건은 요청 전체가 실패하지 않고 그 건만 failed로 세어져요.
  • 진행 상황은 배치 결과 조회로 확인해요.
GET/api/v1/jobs/{job_id}

작업 상태 조회

조회 작업이 어디까지 진행됐는지 조회해요. 상태만 돌려주고, 계좌와 거래내역은 웹훅 또는 저장된 결과 조회로 받아요.

요청

curl -X GET "https://bank.di3.kr/api/v1/jobs/3f2b8e5a-6c1d-4e7a-9b2f-8d4c1a7e5f90" \
  -H "X-API-Key: YOUR_API_KEY"
const res = await fetch("https://bank.di3.kr/api/v1/jobs/3f2b8e5a-6c1d-4e7a-9b2f-8d4c1a7e5f90", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();
import requests

res = requests.get(
    "https://bank.di3.kr/api/v1/jobs/3f2b8e5a-6c1d-4e7a-9b2f-8d4c1a7e5f90",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json())

요청 값

이름 · 형식설명
job_id string 필수조회 요청에서 받은 job_id (주소에 넣어요)

응답

// 200 OK
{
  "job_id": "3f2b8e5a-6c1d-4e7a-9b2f-8d4c1a7e5f90",
  "end_user_id": 1,
  "external_ref": null,
  "bank_code": "shinhan",
  "channel": "personal",
  "status": "success",
  "error": null,
  "requested_at": "2026-11-16T09:00:00",
  "finished_at": "2026-11-16T09:00:12"
}
// 404 Not Found
{
  "detail": "작업을 찾을 수 없습니다"
}

// 401 Unauthorized
{
  "detail": "인증 실패"
}

// 403 Forbidden
{
  "detail": "비활성 회원"
}
알아 두세요
  • status: queued · running · success · failed · blocked · cert_not_registered
  • 작업이 success가 된 뒤에는 계좌 목록과 거래내역으로 저장된 결과를 가져올 수 있어요.
GET/api/v1/batches/{batch_id}

배치 상태 조회

일괄 조회의 진행 건수를 조회해요.

요청

curl -X GET "https://bank.di3.kr/api/v1/batches/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" \
  -H "X-API-Key: YOUR_API_KEY"
const res = await fetch("https://bank.di3.kr/api/v1/batches/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();
import requests

res = requests.get(
    "https://bank.di3.kr/api/v1/batches/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json())

요청 값

이름 · 형식설명
batch_id string 필수일괄 요청에서 받은 batch_id (주소에 넣어요)

응답

// 200 OK
{
  "batch_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "webhook_url": "https://yourapp.com/webhook",
  "total": 2,
  "queued": 0,
  "processing": 1,
  "success": 1,
  "failed": 0,
  "created_at": "2026-11-16T09:00:00"
}
// 404 Not Found
{
  "detail": "배치를 찾을 수 없습니다"
}

// 401 Unauthorized
{
  "detail": "인증 실패"
}

// 403 Forbidden
{
  "detail": "비활성 회원"
}
알아 두세요
  • 건수(queued · processing · success · failed)만 돌려줘요. 건별 결과는 웹훅으로 오고, 웹훅에 batch_id가 들어 있어요.
GET/api/end-users/{id}/banks/{bank_code}/transactions

실시간 거래내역 조회

저장하지 않고 은행에서 직접 조회해요. 전체 내역이 한 번에 돌아와요.

요청

curl -X GET "https://bank.di3.kr/api/end-users/1/banks/shinhan/transactions?account_no=110-123-456789&from_date=2026-11-01&to_date=2026-11-15" \
  -H "X-API-Key: YOUR_API_KEY"
const res = await fetch("https://bank.di3.kr/api/end-users/1/banks/shinhan/transactions?account_no=110-123-456789&from_date=2026-11-01&to_date=2026-11-15", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();
import requests

res = requests.get(
    "https://bank.di3.kr/api/end-users/1/banks/shinhan/transactions",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"account_no": "110-123-456789", "from_date": "2026-11-01", "to_date": "2026-11-15"},
)
print(res.json())

요청 값

이름 · 형식설명
id integer 필수최종 사용자 ID (숫자, 주소에 넣어요)
bank_code string 필수은행 코드 (주소에 넣어요)
account_no string 필수조회할 계좌번호 (하이픈 있어도 없어도 돼요)
from_date date 필수조회 시작일 (YYYY-MM-DD)
to_date date 필수조회 종료일 (YYYY-MM-DD)

응답

// 200 OK
{
  "transactions": [{
    "txn_at": "2026-11-15T14:32:00",
    "type": "출금",
    "amount": -50000,
    "balance_after": 1234567,
    "memo": "스타벅스 강남점",
    "counterparty": "스타벅스",
    "counterparty_name": "스타벅스",
    "counterparty_account": null
  }],
  "summary": {
    "total_in": 3000000,
    "total_out": 1765433,
    "count": 1,
    "by_counterparty": [
      { "name": "스타벅스", "account_no": "", "in_amount": 0, "out_amount": 50000, "count": 1 }
    ]
  }
}
// 400 Bad Request
{
  "detail": "날짜 형식 오류 (YYYY-MM-DD)"
}

// 400 Bad Request
{
  "detail": "등록된 인증서가 없습니다"
}

// 402 Payment Required
{
  "detail": "크레딧이 부족합니다. 필요: 20원, 보유: 0원"
}

// 404 Not Found
{
  "detail": "사용자를 찾을 수 없습니다"
}

// 500 Internal Server Error
{
  "detail": "은행 조회 중 발생한 오류 내용"
}

// 401 Unauthorized
{
  "detail": "인증 실패"
}

// 403 Forbidden
{
  "detail": "비활성 회원"
}
알아 두세요
  • 입금은 amount가 양수, 출금은 음수예요. type에는 입금 · 출금이 들어와요.
  • 은행에 로그인해서 바로 가져오기 때문에 몇 초에서 수십 초까지 걸릴 수 있어요. 조회 1건으로 계산돼요.
  • 은행의 정기점검 시간에는 호출이 실패할 수 있어요.
GET/api/end-users/{id}/accounts

저장된 계좌 목록

조회가 끝난 뒤 저장된 최종 사용자의 계좌를 가져와요.

요청

curl -X GET "https://bank.di3.kr/api/end-users/1/accounts" \
  -H "X-API-Key: YOUR_API_KEY"
const res = await fetch("https://bank.di3.kr/api/end-users/1/accounts", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();
import requests

res = requests.get(
    "https://bank.di3.kr/api/end-users/1/accounts",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json())

요청 값

이름 · 형식설명
id integer 필수최종 사용자 ID (숫자, 주소에 넣어요)

응답

// 200 OK
[
  {
    "id": 5,
    "bank_code": "shinhan",
    "channel": "personal",
    "account_no_masked": "110-***-6789",
    "holder_name": "홍길동",
    "account_type": "입출금",
    "balance": 1234567,
    "currency": "KRW",
    "updated_at": "2026-11-16T09:00:12"
  }
]
// 404 Not Found
{
  "detail": "사용자를 찾을 수 없습니다"
}

// 401 Unauthorized
{
  "detail": "인증 실패"
}

// 403 Forbidden
{
  "detail": "비활성 회원"
}
알아 두세요
  • 계좌번호는 가려진 상태(account_no_masked)로 돌아와요.
  • 응답의 id로 해당 계좌의 거래내역을 가져와요.
GET/api/accounts/{account_id}/transactions

저장된 거래내역

저장된 계좌의 거래내역을 최신순으로 가져와요.

요청

curl -X GET "https://bank.di3.kr/api/accounts/5/transactions?from_date=2026-11-15" \
  -H "X-API-Key: YOUR_API_KEY"
const res = await fetch("https://bank.di3.kr/api/accounts/5/transactions?from_date=2026-11-15", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();
import requests

res = requests.get(
    "https://bank.di3.kr/api/accounts/5/transactions",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from_date": "2026-11-15"},
)
print(res.json())

요청 값

이름 · 형식설명
account_id integer 필수저장된 계좌 목록 응답의 id (주소에 넣어요)
from_date date 선택이 날짜부터의 거래만 가져와요 (YYYY-MM-DD)

응답

// 200 OK
[
  {
    "id": 101,
    "txn_at": "2026-11-15T14:32:00",
    "amount": -50000,
    "balance_after": 1234567,
    "type": "출금",
    "memo": "스타벅스 강남점",
    "counterparty": "스타벅스",
    "counterparty_name": "스타벅스",
    "counterparty_account": null
  }
]
// 400 Bad Request
{
  "detail": "거래내역은 최근 N일치만 보관됩니다. 조회 가능한 최초 날짜는 YYYY-MM-DD입니다."
}

// 404 Not Found
{
  "detail": "계좌를 찾을 수 없습니다"
}

// 401 Unauthorized
{
  "detail": "인증 실패"
}

// 403 Forbidden
{
  "detail": "비활성 회원"
}
알아 두세요
  • 저장된 거래내역은 정해진 기간(최근 며칠)만 보관해요. 그 이전 날짜를 from_date로 보내면 400이에요.
  • 더 오래된 내역이나 최신 내역이 필요하면 실시간 거래내역 조회를 써요.

지원 은행

뱅크레일에서 조회할 수 있는 은행이에요. bank_code로 요청해요.

은행개인 계좌법인 계좌실시간 거래내역
신한은행 shinhan 지원지원지원
국민은행 kb 지원지원지원
우리은행 woori 지원지원지원
하나은행 hana 지원지원지원
기업은행 ibk 지원지원지원
농협은행 nh 지원지원지원

HTTP 상태 코드

API 응답에 쓰이는 상태 코드예요.

201Created리소스 생성 성공
202Accepted비동기 요청 접수
204No Content삭제 성공
400Bad Request요청에 필요한 값이 빠졌거나 선행 조건이 없음 (사용자 지정 누락, 인증서 없음 등)
401UnauthorizedAPI 키 인증 실패
402Payment Required크레딧 부족 또는 무료 한도 초과
403Forbidden정지된 회원 또는 서비스 기간 만료
404Not Found리소스 없음
409Conflict중복 리소스
422Unprocessable값 형식 오류 (허용되지 않는 값, 숫자 자리에 문자 등)
500Server Error서버 오류 · 은행 조회 실패 시에도 나올 수 있어요