무료 시작

API 키 헤더

X-API-Key:
YOUR_API_KEY

API 레퍼런스

최종 사용자

공동인증서

스크래핑

실시간 거래내역

참조

STEP 01 POST /api/end-users

최종 사용자 등록

API를 사용할 최종 사용자를 등록합니다. 등록 후 반환되는 end_user_id를 이후 요청에 활용합니다.

Request

json
{
  "external_ref": "your-internal-user-id",
  "user_type": "individual",
  "name": "홍길동"
}

Response

json
// 201 Created
{
  "id": "usr_abc123",
  "external_ref": "your-internal-user-id",
  "user_type": "individual",
  "name": "홍길동",
  "created_at": "2025-01-01T00:00:00Z"
}

참고사항

  • external_ref: 내부 시스템의 사용자 고유 ID
  • user_type: 'individual'(개인) 또는 'business'(법인)
  • name은 선택 항목
  • 목록 조회: GET /api/end-users (페이지네이션 지원)
  • 삭제(DELETE) 시 인증서·계좌 데이터가 cascade 삭제됩니다
STEP 02 POST /api/certificates

공동인증서 등록

최종 사용자의 공동인증서를 등록합니다. 두 가지 방법을 지원합니다.

방법 A (권장) — DiCert SDK 팝업

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

방법 B — 직접 API 호출

json
POST /api/certificates
{
  "end_user_id": "usr_abc123",
  "certBase64": "MIIEpAIBAAKCAQ...",
  "keyBase64": "MIIEvQIBADANBg...",
  "password": "cert_password"
}
STEP 03 POST /api/v1/scrape

스크래핑 요청

계좌 잔액 및 거래내역 조회를 요청합니다. 비동기로 처리되며 202를 즉시 반환합니다.

Request

json
// 단건 요청
POST /api/v1/scrape
{
  "end_user_id": "usr_abc123",
  "bank_code": "shinhan",
  "webhook_url": "https://yourapp.com/webhook"
}

// 일괄 요청 (최대 500건)
POST /api/v1/scrape/bulk
{
  "requests": [
    { "end_user_id": "usr_001", "bank_code": "shinhan" },
    { "end_user_id": "usr_002", "bank_code": "hana" }
  ],
  "webhook_url": "https://yourapp.com/webhook"
}

Response

json
// 202 Accepted
{
  "job_id": "job_xyz789",
  "status": "queued",
  "estimated_seconds": 10
}

참고사항

  • 비동기 처리: 즉시 job_id 반환, 완료 시 Webhook 알림
  • 지원 bank_code: shinhan, kb, woori, hana, ibk, nh
  • 일괄 요청은 batch_id 반환
STEP 04 Webhook / Polling

결과 수신

스크래핑 완료 시 결과를 Webhook 또는 폴링으로 수신합니다.

Request (폴링)

http
GET /api/v1/jobs/{job_id}
GET /api/v1/batches/{batch_id}

Response (Webhook)

json
{
  "job_id": "job_xyz789",
  "status": "success",
  "end_user_id": "usr_abc123",
  "bank_code": "shinhan",
  "accounts": [{
    "account_no": "110-123-456789",
    "balance": 1234567,
    "transactions": [{
      "date": "2025-01-15",
      "amount": -50000,
      "type": "출금",
      "description": "스타벅스 강남점",
      "balance_after": 1234567
    }]
  }]
}

참고사항

  • status 값: 'success' | 'partial' | 'failed' | 'blocked'
  • Webhook 실패 시 30초, 60초 간격으로 최대 3회 재시도
  • blocked: 인증서 만료 또는 은행 보안 강화 시 발생