HACS FI API 문서

HACS (Hybrid Alternative Credit Scoring) — B2B credit-score API for financial institutions.

HACS는 금융기관(FI)이 사용자 동의 하에 대안신용점수를 조회할 수 있는 B2B API입니다. 모든 조회는 소프트 풀(soft-pull, 조회해도 점수에 영향이 없는 조회)이며, 사용자가 동의하지 않으면 아무 것도 제공되지 않습니다(기본 차단, deny-by-default).

핵심 수치

항목	값	설명
점수 범위	0 ~ 850 (만점 850)	응답의 `scoreMin`=0, `scoreMax`=850
등급컷	750 / 650 / 550 / 450	EXCELLENT(750–850) · GOOD(650–749) · FAIR(550–649) · BELOW_AVERAGE(450–549) · POOR(0–449)
사유코드	총 31종, 응답당 최대 4건	점수가 낮은 이유를 설명하는 코드(사유코드). 에러·사유코드 참고
신용등급 증명서(어테스테이션) 유효기간	90일	발급 시점부터 90일. 만료 시 `verify`가 `EXPIRED` 반환
속도 제한	60 req/min	초과 시 HTTP 429 + `Retry-After` 헤더. 에러 참고

쉬운 용어집

용어	쉬운 설명
어테스테이션(attestation)	신용등급 증명서. 사용자가 QR로 제시하는, 발급기관이 서명한 등급 증명
pairwise 식별자(pairwiseSub)	파트너 전용 익명 ID. 기관마다 다른 값이라 기관끼리 사용자를 맞춰볼 수 없음
deny-by-default	기본 차단. 사용자가 명시적으로 동의한 경우에만 데이터 제공
소프트 풀(soft-pull)	조회 기록이 점수에 영향을 주지 않는 조회. 이 API의 모든 조회는 소프트 풀
사유코드(reason code)	점수가 낮은 이유를 사람이 읽을 수 있게 설명하는 코드(예: "금융 거래 이력 부족")
웹훅(webhook)	이벤트(동의 철회, 등급 변경 등)를 파트너 서버로 자동 알림하는 방식
샌드박스(sandbox)	실제 사용자 데이터 없이 개발·테스트할 수 있는 연습용 환경

문서 탐색

시작하기 (Quickstart)

등록 → 키 발급 → 샌드박스 첫 호출 → 라이브 전환. 한국어+영어 병기.

인증 (Authentication)

X-Client-Id + X-API-Key 헤더 인증과 키 관리.

API 레퍼런스

전체 엔드포인트 요청/응답 JSON 예제.

샌드박스

연습용 고정 주체(canonical subjects) 표와 결정적 응답 규칙.

에러

에러코드 표, 재시도 정책, Retry-After.

웹훅

이벤트 4종, 서명 검증 예제(Java/TypeScript), 재시도 사다리.

동의 모델

기본 차단 · 파트너 전용 익명 ID · 데이터 카테고리.

신분증 연계

국가 신분증 연계 확인 증명서(파생 VC) · 지원 원천 상태 · identityAssurance 예고.

발급기관 온보딩

기관이 신청 → 심사 → API 키 1회 수령 → 기관 명의로 증명서 발급까지.

컴플라이언스

동의·접근로그 해시체인·모델 거버넌스 등 통제 사실 기술.

레시피

등급컷 기반 여신 조건 참고표.

기본 URL

https://trendy.storydot.kr/superapp/api

모든 FI 엔드포인트는 이 기본 URL 아래 /fi/... 경로입니다. 예: POST https://trendy.storydot.kr/superapp/api/fi/score/query

라이브(LIVE)와 샌드박스(SANDBOX)는 같은 URL을 사용합니다. 환경은 API 키에 결속되어 있습니다 — 샌드박스 키로 호출하면 자동으로 합성 응답이 반환됩니다.

응답 형식

All responses use a standard envelope.

{
  "success": true,
  "data": { ... },
  "message": "Score retrieved"
}

실패 시 success=false와 errorCode(예: SW2300)가 반환됩니다.