CatQuest 데이터 API 레퍼런스

🐾 CatQuest 페이지로 이동 →

CatQuest 화면은 **giip 이슈 목록 API(giipIssues)**를 읽어 각 이슈를 고양이 카드로 그립니다. 이 문서는 그 데이터 원천을 API로 직접 조회하는 방법과, 화면의 상태→고양이 매핑을 설명합니다.

• 호스트: https://giipfaw.azurewebsites.net
• 인증: x-api-key 헤더(또는 Authorization: Bearer <key>)에 로그인 사용자의 AK, 프로젝트 SK, 또는 사용자 고정 키 중 하나를 전달합니다. 세 종류의 상세 정의·발급처·권한 범위는 이슈·태스크 API → 인증 (이 API와 동일한 giipIssues 엔드포인트를 사용하므로 인증 사양도 공통)을 참조하세요. 조회 범위는 키의 csn(프로젝트) 로 제한됩니다. JSON 바디나 쿼리 문자열로 키를 전달하는 방식은 지원되지 않습니다(실측 확인, 2026-08-20) — 반드시 헤더로 전달하세요.
• 응답 코드(RstVal) 규약은 API 결과 코드 를 참조하세요.

---

이슈 목록 조회 — giipIssues GET

CatQuest가 페이지 로드 시 호출하는 읽기 API입니다.

curl "https://giipfaw.azurewebsites.net/api/giipIssues?csn=47" \
  -H "x-api-key: ${GIIP_API_KEY}"

요청 파라미터

이름	위치	필수	설명
csn	query	✅	조회할 프로젝트 번호. CatQuest는 현재 선택된 프로젝트의 csn을 자동으로 넣습니다.

응답 예시

{
  "issues": [
    {
      "isn": 735,
      "title": "admin/catquest 유저 가이드 생성",
      "status": "READY",
      "regdate": "2026-07-24T08:54:00Z",
      "summary": "가이드 버튼 활성화",
      "last_comment_date": "2026-07-24T09:00:00Z",
      "blocked_by_isn": null,
      "blocked_by_title": null
    }
  ]
}

응답 필드 (CatQuest가 사용하는 것)

필드	타입	화면에서의 쓰임
isn	number	이슈 번호(#isn 배지). 어떤 고양이를 배정할지도 isn으로 결정됩니다.
title	string	카드 상단 말풍선 제목
status	string	고양이 행동(애니메이션)을 결정 — 아래 매핑표 참조
regdate	string	등록 일시(🐣)
summary	string	카드 하단 요약(있을 때만)
last_comment_date	string | null	최종 코멘트 일시(💬), 없으면 "코멘트 없음"
blocked_by_isn	number | null	대기(blocked-by) 배지 — 이 이슈를 막고 있는 점유 이슈 번호
blocked_by_title	string | null	대기 배지의 툴팁(점유 이슈 제목)

상태 → 고양이 행동 매핑

CatQuest 프론트가 status 값을 다음 규칙으로 애니메이션에 매핑합니다(서버 값이 아니라 화면 표현 규칙).

status	고양이 상태	이미지 파일 패턴
PENDING	playing	/images/catquest/<cat>_playing.png
READY	ready	/images/catquest/<cat>_ready.png
IN_PROGRESS	hunting	/images/catquest/<cat>_hunting.png
REVIEW	delivering	/images/catquest/<cat>_delivering.png
DONE	playing	/images/catquest/<cat>_playing.png

• <cat> 은 isn % 8 로 8종(mochi·sherlock·nimbus·pixel·cocoa·midnight·luna·leo) 중 하나가 고정 배정됩니다.

관련 API

• 이슈 등록·수정·상태변경: 프로그램으로 이슈를 생성/전이하려면 이슈 및 태스크 API 를 참조하세요.
• 코멘트 조회/추가: 이슈 상세 화면은 giipIssueComments API를 사용합니다.

문제 해결

증상	원인	해결
401 {"error":"Auth required"}	x-api-key 헤더 자체가 없거나, JSON 바디/쿼리 문자열 등 미지원 방식으로 키를 전달함	x-api-key: <key> 헤더(또는 Authorization: Bearer <key>)로 전달. 실측 확인: 바디 token·쿼리 ?token=은 읽히지 않습니다
401 {"error":"Invalid session"}	키 오타·만료·비활성화(SK 재발급/회전, AK 세션 만료 등)	유효한 키로 재시도하거나 재로그인합니다. 키 조건 상세는 이슈·태스크 API 참조
빈 issues: [](해당 csn에 이슈가 없는 경우)	해당 csn에 이슈가 없음	csn 값을 확인하거나 이슈를 등록합니다
빈 issues: [](키에 권한이 없는 경우)	키가 그 csn에 접근 권한이 없음(401이 아니라 빈 배열이 됨 — 실측 확인, 2026-08-20)	해당 csn용 키를 사용하거나 관리자에게 권한 부여를 요청합니다
csn 없이 호출	필수 파라미터 누락	?csn=<번호> 를 반드시 포함합니다

---

버전: 1.1 최종 업데이트: 2026-08-20(테스트 대상 API: giipfaw 프로덕션) 소스 파일: giipv3/public/help/api-catquest.ko.md

v1.1 변경 이력 (2026-08-20, giip #1280): 인증 섹션을 이슈·태스크 API의 확장된 인증 정의로 링크하여 중복을 제거. curl 예제를 환경변수화. 401의 원인(키 미도달/키 무효)과 csn 권한 불일치 시 동작(401이 아니라 빈 배열)을 문제 해결 표에 추가(giip-issue-api의 실측 결과 반영).