# HACS FI API 문서 — 개요

HACS(Hybrid Alternative Credit Scoring)는 금융기관(FI)이 **사용자 동의 하에** 대안신용점수를
조회할 수 있는 B2B API입니다. 모든 조회는 소프트 풀(조회해도 점수에 영향이 없는 조회)이며,
사용자가 동의하지 않으면 아무것도 제공되지 않습니다(기본 차단, 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일 |
| 속도 제한 | 60 req/min (초과 시 429 + `Retry-After`) |

## 쉬운 용어집

- **어테스테이션(attestation)** = 신용등급 증명서. 사용자가 QR로 제시하는, 발급기관이 서명한 등급 증명
- **pairwise 식별자(pairwiseSub)** = 파트너 전용 익명 ID. 기관마다 다른 값이라 기관끼리 대조 불가
- **deny-by-default** = 기본 차단. 명시 동의 시에만 데이터 제공
- **소프트 풀(soft-pull)** = 조회 기록이 점수에 영향을 주지 않는 조회
- **사유코드(reason code)** = 점수가 낮은 이유를 설명하는 코드
- **웹훅(webhook)** = 이벤트를 파트너 서버로 자동 알림
- **샌드박스(sandbox)** = 실데이터 없는 연습용 환경

## 기본 URL

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

라이브(LIVE)와 샌드박스(SANDBOX)는 같은 URL을 사용하며, 환경은 API 키에 결속됩니다.

## 응답 형식

```json
{ "success": true, "data": {}, "message": "..." }
```

실패 시 `success=false` + `errorCode`(예: `SW2300`).

## 문서

[quickstart.md](quickstart.md) · [auth.md](auth.md) · [api-reference.md](api-reference.md) ·
[sandbox.md](sandbox.md) · [errors.md](errors.md) · [webhooks.md](webhooks.md) ·
[consent-model.md](consent-model.md) · [compliance.md](compliance.md) · [recipes.md](recipes.md)