시작하기

Quickstart — from registration to your first live call. English text follows each Korean section.

1. 파트너 등록 및 키 발급

운영팀에 파트너 등록을 요청하면 클라이언트 ID(X-Client-Id)와 API 키(X-API-Key)를 발급받습니다. 키는 발급 시 1회만 표시되며 서버에는 해시로만 저장되므로, 반드시 안전한 곳(시크릿 매니저)에 보관하세요.

키는 환경(environment)에 결속됩니다: 샌드박스 키는 항상 연습용 합성 응답을, 라이브 키는 실제 동의 기반 데이터를 반환합니다. URL은 동일합니다.

EN — Ask the operations team to register your institution as a partner. You will receive a client id (X-Client-Id) and an API key (X-API-Key). The key is shown only once at issuance and stored server-side as a hash — keep it in a secrets manager. Keys are bound to an environment: a SANDBOX key always returns synthetic responses, a LIVE key returns real consent-gated data. The base URL is the same for both.

2. 연결 확인 (whoami)

발급받은 키가 동작하는지, 어떤 환경에 결속됐는지 확인합니다.

EN — Verify your key works and see which environment it is bound to.

curl -s https://trendy.storydot.kr/superapp/api/fi/whoami \
  -H "X-Client-Id: YOUR_CLIENT_ID" \
  -H "X-API-Key: YOUR_API_KEY"
{
  "success": true,
  "data": {
    "clientId": "YOUR_CLIENT_ID",
    "name": "Example Bank",
    "environment": "SANDBOX",
    "rateLimitTier": "STANDARD",
    "status": "ACTIVE"
  },
  "message": "OK"
}

3. 샌드박스 첫 점수 조회

샌드박스에는 항상 같은 결과를 돌려주는 고정 연습 주체가 있습니다. SANDBOX-TIER-A는 항상 820점(EXCELLENT)입니다. 전체 목록은 샌드박스 페이지를 보세요.

EN — The sandbox provides canonical test subjects with deterministic results. SANDBOX-TIER-A always scores 820 (EXCELLENT). See the Sandbox page for the full table.

curl -s https://trendy.storydot.kr/superapp/api/fi/score/query \
  -H "X-Client-Id: YOUR_CLIENT_ID" \
  -H "X-API-Key: YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "pairwiseSub": "SANDBOX-TIER-A", "purpose": "UNDERWRITING" }'
{
  "success": true,
  "data": {
    "pairwiseSub": "SANDBOX-TIER-A",
    "score": 820,
    "scoreMin": 0,
    "scoreMax": 850,
    "tier": "EXCELLENT",
    "pullType": "SOFT",
    "reasonCodes": [
      {
        "code": "RC_LOW_UTILITY_PAYMENT_RELIABILITY",
        "labelEn": "Low utility bill payment reliability",
        "labelLocalized": "Low utility bill payment reliability",
        "category": "PAYMENT",
        "impactPoints": 40,
        "rank": 1
      },
      {
        "code": "RC_LOW_TELCO_PAYMENT_REGULARITY",
        "labelEn": "Irregular telecom payment history",
        "labelLocalized": "Irregular telecom payment history",
        "category": "PAYMENT",
        "impactPoints": 30,
        "rank": 2
      },
      {
        "code": "RC_CASHFLOW_INSTABILITY",
        "labelEn": "Cash-flow instability",
        "labelLocalized": "Cash-flow instability",
        "category": "FINANCIAL",
        "impactPoints": 20,
        "rank": 3
      },
      {
        "code": "RC_DID_VC_WEAK",
        "labelEn": "Limited verified digital identity",
        "labelLocalized": "Limited verified digital identity",
        "category": "IDENTITY",
        "impactPoints": 10,
        "rank": 4
      }
    ],
    "modelVersion": "sandbox-v1",
    "scoredAt": "2026-01-01 00:00:00",
    "decisionHash": "137642e7b52bcc0d414bbc194ef4626d88c9c169be4b271a11f44ec7235fc408",
    "environment": "SANDBOX",
    "confidence": "HIGH",
    "dataSufficiency": {
      "featuresObserved": 18,
      "featuresTotal": 20,
      "coveragePercent": 90.0
    }
  },
  "message": "Score retrieved"
}
거부(동의 없음) 케이스도 연습해 두세요: SANDBOX-NO-CONSENT 주체는 항상 동의 없음(DENIED)으로 응답합니다. 라이브에서 동의가 없는 사용자도 정확히 같은 형태로 거부됩니다. EN — Also rehearse the denial path: subject SANDBOX-NO-CONSENT is always denied, exactly the shape a live no-consent subject produces.

4. 라이브 전환

통합 테스트가 끝나면 운영팀에 라이브 키 발급을 요청합니다. 코드 변경은 필요 없습니다 — 헤더의 키만 라이브 키로 바꾸면 됩니다. 라이브에서는:

EN — When integration testing is done, request a LIVE key. No code changes are needed — just swap the key in your headers. In LIVE: scores are returned only when the user has consented (deny-by-default); no-consent and unknown subjects are denied with the identical label so existence cannot be inferred; every query is written to a hash-chained access log visible to the user.

5. 다음 단계