개념

Open API v2의 도메인 어휘입니다. 모두 Kolleges 도메인 표준 용어입니다.

핵심 리소스

용어	의미
club	클래스를 운영하고 자격증명을 발급하는 주체. clubDomain으로 식별(경로).
apiClient	대시보드에서 발급하는 크리덴셜 단위. 클럽 1개에 묶이며 최소권한 scope를 가집니다.
achievement	재사용 가능한 발급 템플릿/양식(예: “2026 수료증”).
design	achievement에 연결된 인증서·배지의 시각 디자인.
issuance	한 번 발급된 자격증명(= 한 명에게 발급된 인증서/배지).
holder	자격증명의 수령 주체. PII-free 앵커(did:key)로, 수령자 개인정보와 분리됩니다.
credential (VC)	발급된 issuance의 영구 검증 가능 형태 — Open Badges 3.0 / W3C VC, did:key·VC-JWT.

영구성 불변식

발급된 VC는 그 사용자·클럽·issuance 레코드가 삭제돼도 검증 가능하게 살아남습니다. 자격증명은 개인정보를 담지 않는 holder(did:key)에 앵커되고, 수령자 개인정보는 별도로 소거 가능합니다.

응답 envelope

모든 성공 응답은 세 형태 중 하나입니다.

// 단건
{ "data": { /* 리소스 */ } }

// 커서 페이지네이션 목록
{ "data": [ /* … */ ], "meta": { "nextCursor": "…" | null } }

// 발급 배치 (BatchResultDto) — 항상 HTTP 200
{
  "results": [
    { "ref": "u-42", "status": "issued", "resourceId": 456 },
    { "ref": "u-43", "status": "skipped", "error": null },
    { "ref": "u-44", "status": "failed", "error": { "code": "…", "detail": "…" } }
  ],
  "summary": { "total": 3, "ok": 1, "skipped": 1, "failed": 1 }
}

단건도 배열 하나

발급 엔드포인트는 단건이든 배치든 동일합니다 — recipients 배열에 1개를 넣으면 됩니다. 응답은 항상 BatchResultDto(per-recipient ref 키)로, 부분 실패를 명확히 구분합니다.

멱등성

발급 등 쓰기 요청은 Idempotency-Key 헤더가 필수입니다. 같은 키로 재시도하면 새로 발급하지 않고 최초 결과를 그대로 반환합니다 — 네트워크 실패 시 안전하게 재시도할 수 있습니다. 키는 논리적 작업 단위(예: 주문 번호)로 잡으세요.

취소 = 무효화

issuance 취소는 무효화(revocation)입니다. 발급된 VC 자체는 영구 보존되지만, 상태가 revoked로 바뀌어 검증 시 무효로 표시됩니다. 하드 삭제가 아니라 상태 전이입니다.

진화 정책

응답의 enum은 additive하게 진화할 수 있습니다 — 미지의 enum 값을 만나면 관용적으로 처리하세요(알 수 없는 값에 대해 실패하지 말 것). 새 필드가 추가돼도 기존 필드는 유지됩니다.