기본 주소
모든 API는 이 주소 아래로 요청해요.
https://bank.di3.kr인증
요청마다 헤더에 내 API 키를 넣어요.
X-API-Key: YOUR_API_KEY연동 흐름
고객을 먼저 등록하고 받은 end_user_id를 이후에 써요.
POST /api/end-users자세히 보기 →
2공동인증서 등록SDK 팝업(권장) 또는 API로 인증서를 등록해요.
POST /api/certificates자세히 보기 →
3조회 요청비동기로 접수돼 바로 202와 job_id를 돌려줘요.
POST /api/v1/scrape자세히 보기 →
4결과 수신완료되면 웹훅으로 받거나 직접 조회해요.
Webhook / GET /api/v1/jobs/{id}자세히 보기 →
첫 호출 해 보기
키 자리의 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())
/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 로, 페이지를 나누어 가져와요.
- 삭제하면 인증서와 계좌 데이터도 함께 삭제돼요.
/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)이 지나면 인증서를 다시 등록해야 해요.
/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를 돌려줘요.
/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로 돌아와요.
/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 로, 페이지를 나누어 가져와요.
- 삭제하면 인증서와 계좌 데이터도 함께 삭제돼요.
/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": "비활성 회원"
}
/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": "비활성 회원"
}
- 삭제한 사용자의 데이터는 복구할 수 없어요.
/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)이 지나면 인증서를 다시 등록해야 해요.
/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": "비활성 회원"
}
/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를 돌려줘요.
/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로 세어져요.
- 진행 상황은 배치 결과 조회로 확인해요.
/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": "비활성 회원"
}
/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가 들어 있어요.
/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건으로 계산돼요.
- 은행의 정기점검 시간에는 호출이 실패할 수 있어요.
/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로 해당 계좌의 거래내역을 가져와요.
/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 응답에 쓰이는 상태 코드예요.