세무·회계 사무소를 위한 여러 고객사 계좌 조회 방식

세무·회계 사무소가 여러 고객사의 계좌 거래내역을 조회할 때 쓰는 인증서 위임, 일괄 요청, 웹훅 처리 순서를 정리했습니다.

여러 고객사 계좌를 한 번에 어떻게 조회하나요?

고객사가 여럿이면 계좌 조회를 한 곳씩 돌리기 어렵습니다. 핵심만 말하면, 고객사별 공동인증서를 위임받아 등록하고 일괄 요청으로 조회한 뒤 웹훅으로 완료를 받는 흐름입니다. 사무소 서버가 회원사 역할을 하고, 고객사는 조회 대상인 최종 사용자가 됩니다.

지원 은행은 신한, KB국민, 우리, 하나, IBK기업, NH농협 6개이며 각 은행의 개인·법인 계정을 모두 조회할 수 있습니다. 카카오뱅크와 토스뱅크는 공동인증서를 쓰지 않아 지원하지 않습니다.

어떤 순서로 진행하나요?

  1. 고객사로부터 조회에 대한 위임을 받습니다. 서비스는 B2B 전용이며 회원사가 최종 사용자의 위임을 받아 조회하는 용도로만 쓸 수 있습니다.

  2. 고객사별 공동인증서를 등록합니다. 최종 사용자(고객사)당 1개를 등록하며 다시 등록하면 교체됩니다. 회원 콘솔에서의 등록과 교체는 PC에서만 가능합니다.

  3. 조회를 일괄 요청합니다. 한 번에 최대 500건까지 보낼 수 있고, 요청은 즉시 접수(202)되어 job_id를 받습니다.

  4. 작업이 끝나면 웹훅으로 결과를 받거나 저장된 계좌와 거래내역을 API로 가져옵니다.

  5. 받은 내역을 사무소의 장부 시스템에 고객사별로 나누어 반영합니다.

일괄 요청 방법은 일괄 조회 요청 안내에서 확인할 수 있습니다.

사무소가 운영할 때 신경 쓸 점은 무엇인가요?

상황알아둘 점
웹훅이 두 번 온다전송 실패 시 여러 번 다시 시도하므로 같은 작업의 알림이 중복될 수 있습니다. job_id로 구분해 한 번만 처리하세요
거래가 생기면 바로 알고 싶다웹훅은 조회 작업 완료 알림이며 거래 발생을 알려 주지 않습니다. 필요한 주기로 조회를 요청해야 합니다
오래된 거래내역이 필요하다저장된 거래내역은 정해진 기간만 보관합니다. 그 이전 내역은 실시간 거래내역 조회로 가져옵니다
고객사 인증서를 바꿨다다시 등록하면 교체됩니다
조회가 일시적으로 안 된다금융기관의 공식 API가 아닌 방식이라 은행 시스템 변경 등으로 조회가 일시 중단될 수 있습니다

일괄 요청은 어떤 모양인가요?

일괄 요청은 jobs 배열에 조회 건을 담고, 건마다 ref를 붙여 응답과 연결합니다. 사용자는 end_user_id 대신 external_ref로 지정할 수도 있고, 법인 고객은 user_type을 business로 보냅니다. 한 번에 최대 500건이며 값은 모두 예시입니다.

{
  "jobs": [
    {
      "external_ref": "client-0001",
      "user_type": "business",
      "bank_code": "kb",
      "ref": "2026-11-A-001"
    },
    {
      "external_ref": "client-0002",
      "user_type": "business",
      "bank_code": "woori",
      "ref": "2026-11-A-002"
    }
  ],
  "webhook_url": "https://yourapp.example/webhook"
}

일괄 요청은 batch_id를 돌려주며, 배치 상태 조회에서 진행 현황을 확인할 수 있습니다. 응답에는 total, queued, processing, success, failed 건수가 담깁니다.

{
  "batch_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "webhook_url": "https://yourapp.example/webhook",
  "total": 2,
  "queued": 0,
  "processing": 1,
  "success": 1,
  "failed": 0,
  "created_at": "2026-11-17T09:00:02"
}

webhook_url은 요청에 넣지 않았다면 null일 수 있습니다. 배치 상태 조회는 건수만 돌려주고, 건별 결과는 웹훅으로 오며 웹훅에 batch_id가 들어 있습니다.

일부 건이 실패하면 어떻게 하나요?

일괄 요청에서는 건마다 결과가 다릅니다. 배치 상태의 failed 건수가 0이 아니면 웹훅으로 받은 건별 결과에서 실패한 건의 status와 error를 확인하고, 일시적인 실패로 보이는 건만 다시 요청하세요. 작업 상태가 blocked(인증서 차단)이거나 cert_not_registered(인증서 미등록)인 고객사는 자동으로 다시 보내지 말고 고객사에 인증서 확인을 안내하는 것이 기준입니다. 무료 한도나 크레딧이 부족하면 요청이 402로 거절되므로, 일괄 요청 전에 충전 상태를 확인해 두세요.

자주 묻는 질문

고객사의 계정 종류는 어떻게 구분하나요?

신한, KB국민, 우리, 하나, IBK기업, NH농협 6개 은행의 개인·법인 계정을 조회할 수 있습니다. 개인사업자가 어느 계정 종류에 해당하는지는 문의하기로 확인하세요.

조회 결과에 계좌번호가 그대로 나오나요?

저장된 결과 조회에서는 계좌번호가 가려진 상태로 제공됩니다.

목록으로