경비관리 솔루션에 계좌 거래내역 조회 API 연동하는 방법
경비관리 솔루션에 계좌 거래내역 조회 API를 붙이는 순서와, 요청 시점 조회와 웹훅 수신의 차이를 정리했습니다.
경비관리에 계좌 거래내역이 필요한 이유는 무엇인가요?
경비 정산에서 시간이 많이 드는 일은 은행 내역과 경비 항목을 맞춰 보는 작업입니다. 이 글의 핵심은 하나입니다. 계좌 거래내역을 API로 받아 오면 경비 입력과 대조에 드는 수작업을 줄일 수 있습니다. 경비관리 솔루션이 은행 계좌의 입금·출금 내역을 직접 가져와 경비 항목과 맞춰 볼 수 있기 때문입니다.
뱅크레일은 회원사 서버가 최종 사용자의 공동인증서를 위임받아 신한, KB국민, 우리, 하나, IBK기업, NH농협 6개 은행의 계좌 잔액과 거래내역을 API로 조회하는 B2B 서비스입니다. 오픈뱅킹이 아니라 공동인증서로 은행 인터넷뱅킹에 접속해 조회하는 방식이며, 금융기관의 공식 API를 쓰지 않습니다.
거래내역은 어떤 방식으로 받아 오나요?
경비관리 솔루션이 쓸 수 있는 방식은 크게 세 가지입니다. 화면에서 바로 확인해야 하는지, 정해진 시각에 모아서 처리하는지에 따라 고르면 됩니다.
| 방식 | 동작 | 알아둘 점 |
|---|---|---|
| 실시간 거래내역 조회 | 요청한 시점에 은행에서 직접 조회해 응답하고 저장하지 않습니다 | 은행 로그인이 일어나 수 초에서 수십 초가 걸릴 수 있고, 조회 1건으로 계산됩니다 |
| 조회 요청 후 웹훅 수신 | 요청하면 즉시 접수(202)되고 job_id를 받으며, 작업이 끝나면 웹훅으로 결과를 받습니다 | 웹훅은 조회 작업 완료 알림이며 거래 발생을 알려 주는 기능이 아닙니다 |
| 저장된 결과 조회 | 조회가 끝난 계좌와 거래내역을 API로 가져옵니다 | 거래내역은 정해진 기간만 보관하며, 그 이전 내역은 실시간 거래내역 조회로 가져옵니다 |
연동은 어떤 순서로 하나요?
조회 대상인 최종 사용자를 등록하고 공동인증서를 등록합니다. 최종 사용자당 1개를 등록하며, 다시 등록하면 교체됩니다. 콘솔에서의 등록과 교체는 PC에서만 가능합니다.
회원 콘솔에서 API 키를 발급받습니다. 모든 요청의 X-API-Key 헤더에 이 키를 담습니다.
거래내역 조회를 요청합니다. 여러 건은 일괄 요청으로 한 번에 최대 500건까지 보낼 수 있습니다.
웹훅 또는 저장된 결과 조회 API로 결과를 받습니다. 전송 실패 시 웹훅이 여러 번 다시 시도되므로 같은 작업의 알림이 중복될 수 있습니다. job_id로 구분해 한 번만 처리하세요.
받은 거래일시, 거래처, 금액, 적요를 경비관리 솔루션의 항목에 맞춰 매핑하고 분류합니다.
단계별 요청 방법은 연동 가이드에서 확인할 수 있습니다.
연동 전에 무엇을 확인해야 하나요?
위임: 서비스는 B2B 전용이며 회원사가 최종 사용자의 위임을 받아 조회하는 용도로만 쓸 수 있습니다.
조회 전용: 입금과 이체를 실행하는 기능은 없습니다. 카드 사용내역 조회도 없고 은행 계좌 잔액과 거래내역만 조회합니다.
일시 중단 가능성: 금융기관의 공식 API가 아닌 방식이므로 은행 시스템 변경 등으로 조회가 일시 중단될 수 있습니다. 조회 실패 시 재시도와 담당자 알림 흐름을 미리 준비하세요.
조회 요청과 응답은 어떤 모양인가요?
한 명의 계좌 잔액과 거래내역을 조회하는 요청 본문은 아래와 같습니다. 모든 요청의 X-API-Key 헤더에는 콘솔에서 발급한 API 키를 담습니다. 값은 모두 예시입니다.
{
"end_user_id": 1024,
"bank_code": "shinhan",
"with_transactions": true,
"webhook_url": "https://yourapp.example/webhook"
}
요청은 즉시 접수(202)되고, 작업 상태 전체가 돌아옵니다. 이때 status는 queued이고, 이후 상태 조회와 웹훅에서 job_id로 작업을 구분합니다.
{
"job_id": "3f2b8e5a-6c1d-4e7a-9b2f-8d4c1a7e5f90",
"end_user_id": 1024,
"external_ref": "client-0007",
"bank_code": "shinhan",
"channel": "corporate",
"status": "queued",
"error": null,
"requested_at": "2026-11-17T09:00:02",
"finished_at": null
}
작업이 끝났는지는 웹훅으로 받거나 job_id로 상태를 조회해 확인합니다. 상태 조회는 진행 상태만 돌려주고, 계좌와 거래내역은 웹훅 또는 저장된 결과 조회로 받습니다. 작업이 끝난 뒤의 상태 응답은 아래와 같습니다. with_transactions를 false로 보내면 거래내역 없이 계좌와 잔액만 가져옵니다.
{
"job_id": "3f2b8e5a-6c1d-4e7a-9b2f-8d4c1a7e5f90",
"end_user_id": 1024,
"external_ref": "client-0007",
"bank_code": "shinhan",
"channel": "corporate",
"status": "success",
"error": null,
"requested_at": "2026-11-17T09:00:02",
"finished_at": "2026-11-17T09:00:21"
}
경비관리 솔루션에서는 external_ref에 자사 고객 코드를 넣어 두면, 응답을 받았을 때 어느 고객의 조회인지 바로 연결할 수 있습니다.
조회가 실패하면 어떻게 처리하나요?
조회는 비동기라서 요청이 접수됐다는 것과 조회가 성공했다는 것은 다릅니다. 작업 상태(status)를 보고 다음 동작을 나누면 됩니다.
| status 값 | 의미 | 서비스에서 할 일 |
|---|---|---|
| queued, running | 접수됐거나 은행에서 조회하는 중입니다 | 웹훅을 기다리거나 job_id로 조회합니다 |
| success | 조회가 끝났습니다 | 저장된 계좌와 거래내역을 가져와 반영합니다 |
| failed | 조회가 실패했습니다. error 필드에 사유가 담깁니다 | 사유를 기록하고 같은 요청을 다시 보낼지 판단합니다 |
| blocked | 인증서가 차단된 상태입니다. 오류가 아니라 202 응답에 이 값이 옵니다 | 자동 재시도를 멈추고 최종 사용자에게 인증서 확인을 안내합니다 |
| cert_not_registered | 등록된 인증서가 없습니다 | 최종 사용자에게 인증서 등록을 요청합니다 |
웹훅으로 오는 status 값은 success, partial, failed, blocked이며, 위의 작업 상태 조회 값(queued, running 등)과는 다릅니다. 두 값을 같은 목록으로 처리하지 말고 따로 구분하세요.
요청 단계의 HTTP 응답은 작업 상태와 따로 봐야 합니다. 특히 인증서가 없을 때 요청 단계에서는 HTTP 400이 돌아오고, 작업 status의 cert_not_registered는 이미 접수된 작업에서 쓰이는 값이라 서로 다릅니다.
| HTTP 응답 | 의미 | 서비스에서 할 일 |
|---|---|---|
| 202 | 접수됐습니다. 이때 status는 queued이거나, 인증서가 차단된 경우 blocked입니다 | job_id를 저장하고 웹훅이나 상태 조회를 기다립니다 |
| 400 | end_user_id 또는 external_ref 같은 필수 값이 빠졌거나, 등록된 인증서가 없습니다 | 요청 값을 고치거나 최종 사용자에게 인증서 등록을 요청합니다 |
| 401 | 인증에 실패했습니다 | X-API-Key 헤더와 키 값을 확인합니다 |
| 402 | 무료 한도 또는 크레딧이 부족합니다 | 크레딧 상태를 확인하고 충전한 뒤 다시 요청합니다 |
| 403 | 비활성 회원입니다 | 회원 상태를 확인합니다 |
| 404 | 최종 사용자를 찾을 수 없습니다 | 등록된 사용자 ID나 external_ref를 확인합니다 |
| 422 | 요청 값 검증 오류입니다 | 필드 형식을 확인합니다 |
재시도는 failed처럼 일시적일 수 있는 경우에만 걸고, blocked나 cert_not_registered는 사람이 조치하기 전까지 다시 보내지 않는 것이 기준입니다. 같은 작업의 웹훅이 중복으로 올 수 있으므로 job_id를 키로 한 번만 처리하세요.
무료 조회는 이벤트로 제공되며 사전 안내 없이 종료될 수 있고, 종료 후에는 요금이 바뀔 수 있습니다. 요금은 메인 페이지의 요금 안내를 확인하세요. 무료 건수를 넘기면 그날은 조회가 되지 않으며, 계속 조회하려면 크레딧을 충전해야 합니다.
자주 묻는 질문
경비관리 화면에서 계좌 잔액이 바로 보이게 할 수 있나요?
실시간 거래내역 조회는 요청한 시점에 은행에서 직접 조회하므로 수 초에서 수십 초가 걸릴 수 있습니다. 화면에서 즉시 보여 줘야 한다면 로딩 상태를 함께 설계하세요. 정해진 시각에 모아서 처리해도 된다면 조회 요청과 웹훅 방식이 더 적합합니다.
웹훅으로 거래가 생길 때마다 알림을 받을 수 있나요?
아닙니다. 웹훅은 조회 작업이 끝났을 때 결과를 보내 주는 기능이며, 거래 발생이나 잔액 변동을 알려 주지 않습니다.
여러 은행 계좌를 한 번에 조회할 수 있나요?
신한, KB국민, 우리, 하나, IBK기업, NH농협 6개 은행의 개인·법인 계정을 조회할 수 있고, 일괄 요청은 한 번에 최대 500건입니다. 카카오뱅크와 토스뱅크는 공동인증서를 쓰지 않아 지원하지 않습니다.