giip

이슈 관리 API 레퍼런스

GIIP 플랫폼에서 발생하는 이슈 및 에러 로그를 프로그래밍 방식으로 조회하고 상태를 업데이트하는 API를 안내합니다.

🔌 이슈 관리 기능 페이지로 이동 →

📋 개요

이 API 모듈은 실시간 이슈 관리 솔루션인 [이슈 관리] 메뉴의 데이터를 외부 시스템과 동기화하거나, 장애 대응 파이프라인(ITSM 등)과 연동하기 위해 사용됩니다.

🔐 인증 및 헤더 (Authentication)

모든 요청은 유효한 **Secret Key (SK)**를 포함해야 합니다.

  • 전용 REST 엔드포인트: HTTP 헤더 
    x-api-key: [Your_SK]
    (권장). 
    x-giip-sk
    헤더, 
    ?token=
    쿼리도 지원.
  • giipApiSk2 래퍼: form 필드 
    token: [Your_SK]
    만 사용. SK를 
    text
    ·
    jsondata
    에 넣지 마세요.

🚀 주요 API 엔드포인트 (실제 구현 기준)

이슈 API는 두 경로 모두 정상 동작합니다. 신규 등록·코멘트 등 CRUD는 전용 REST 엔드포인트(giipv3 어드민 UI가 실제 사용하는 경로)를, SP 직접 호출은 

giipApiSk2
래퍼를 사용합니다.

1. 이슈 전용 엔드포인트 (REST API)

가장 직관적인 호출 방식이며, giipv3 어드민 UI가 실제 사용하는 경로입니다. 인증은 

x-api-key
헤더, Content-Type은 
application/json
.

  • 신규 등록: 
    POST /api/giipIssues
    — 
    isn
    을 생략(또는 0)하면 신규 이슈가 INSERT되고 새 
    isn
    을 반환합니다.
    • Body: 
      { "title":"제목(필수)", "content":"본문", "status":"PENDING", "csn":47, "target_lssn":null, "agent_workflow":null }
    • 성공: 
      { "isn":577, "message":"Issue created", "success":true }
  • 목록 조회: 
    GET /api/giipIssues?status=READY
  • 상세 조회: 
    GET /api/giipIssues?isn=7890
  • 상태 업데이트/완료: 
    PUT /api/giipIssues
    • Body: 
      { "isn":7890, "status":"DONE" }
      → 
      { "success":true }
  • 코멘트 등록: 
    POST /api/giipIssueComments
    • Body: 
      { "isn":7890, "content":"처리 완료", "author":"api-tester", "issuetype":"comment" }
      → 
      { "success":true }

2. 범용 API 래퍼 (giipApiSk2)

GIIP의 Stored Procedure를 직접 호출하는 sk 기반 방식이며, 조회(List/Get)와 에이전트 액션(Dispatch/ReadinessCheck) 에 사용합니다. 생성·상태변경·코멘트 등 쓰기(write)는 이 경로로 하지 말고 위 §1 전용 REST 엔드포인트를 사용하세요(이유는 아래 🚫 참고).

  • URL: 
    POST /api/giipApiSk2
  • Content-Type: 
    application/x-www-form-urlencoded
  • 필드: 
    • token
      : 
      [Your_SK]
      — SK는 반드시 이 필드로만 전달
    • text
      : 
      [Command] [파라미터...]
    • jsondata
      : 값 매핑용 JSON(선택). 예: 
      {}
      또는 
      {"lssn":101}

⚠️ text 작성 규칙(엄수): 

text
에는 해당 SP가 받는 정확한 파라미터만 순서대로 나열합니다. 인증(
@sk
)과 
jsondata
는 엔진(
run.ps1
)이 자동 처리하므로 절대 나열하지 마세요. 파라미터를 과다 나열하면 SP 인자 개수를 초과해 
has too many arguments specified
오류가 납니다.

명령(안전)SP 파라미터(=text에 나열)text 예시성공 응답
목록 조회
status
GiipIssueList READY
data
(이슈 배열)
상세 조회
isn
GiipIssueGet 7890
data[0]
(이슈 1건)
원격 실행
isn
GiipIssueDispatch 7890
data[0].RstVal = 200

🚫 

GiipIssuePut
을 Sk2로 상태변경에 쓰지 마세요 (데이터 파괴 위험). Sk2 
GiipIssuePut
은 내부 SP 
pApiGiipIssuePutbySK(@sk, @isn, @title, @content, @status, @csn)
에 매핑되는 전체 덮어쓰기(full overwrite) 입니다(coalesce 없음). 
GiipIssuePut 7890 DONE
로 부르면 두 번째 값 
DONE
이 @title로, 세 번째(jsondata)가 @content로 들어가 제목·본문이 파괴됩니다. 응답은 
RstVal:200
(가짜 성공)으로 나오지만 실제로는 오손된 것입니다(실측: 2026-07-09, task 20260708183049). 상태만 안전하게 바꾸려면 전용 REST 
PUT /api/giipIssues {isn, status}
를 쓰세요. 내부 
pApiGiipIssuePutbyAK
가 
ISNULL(@title, title)
로 기존 제목·본문을 보존합니다(=giipv3 프론트가 실제 쓰는 경로).

🔍 응답 데이터 예시

giipApiSk2 (SP 래퍼) 응답 — 조회는 

data
배열에 레코드, SP 액션(Dispatch 등)은 성공 시 
RstVal = 200
:

{ "data": [ { "RstVal": 200, "Proc_MSG": "Dispatched", "isn": 7890 } ] }

조회 명령(

GiipIssueList
/
GiipIssueGet
)은 
data
배열에 이슈 레코드가 담깁니다.

전용 REST 엔드포인트 응답 — 성공 시 

success: true
(응답 본문에 
RstVal
없음):

{ "isn": 7890, "message": "Issue updated", "success": true }

ℹ️ 성공 판정 주의: SP 성공 코드는 

RstVal = 200
이며 
0
이 아닙니다. 실패 시 400/401/403/404를 반환합니다(K-Layer CLAIM-006). 전용 엔드포인트는 
RstVal
대신 
success
불리언을 반환합니다.

💡 활용 사례

  • 슬랙 알림 봇: API를 주기적으로 호출하여 신규 
    Critical
    이슈 발생 시 즉시 개발팀 채널에 메시지를 보냅니다.
  • 자동 복구 스크립트: 특정 유형의 이슈(예: 프로세스 다운) 탐지 시 API로 이슈를 확인하고, 원격 명령 API(
    api-system
    )를 호출하여 해당 서비스를 재시작합니다.

🛡️ Sk3(고성능 로깅) 활용

장애 대응 시스템이나 외부 티켓팅 도구와의 연동 시, 업데이트 무결성 보장과 상세한 호출 이력 추적을 위해 

giipApiSk3
엔드포인트를 권장합니다.

  • 엔드포인트: 
    https://giipfaw.azurewebsites.net/api/giipApiSk3
  • 장점: 이슈 상태 업데이트(Done 처리 등) 실패 시 호출자의 상세 환경 정보(IP, UA)와 StackTrace를 즉시 
    tErrorLogs
    에 기록하여 장애 대응 프로세스의 신뢰성을 높여줍니다.
  • 활용 팁: 
    jsondata
    치환 기능을 사용하여 이슈 내의 특정 변수값이나 긴 에러 메시지를 파라미터 유실 없이 안전하게 전송할 수 있습니다.

문제 해결

증상원인해결
인증 실패(401/권한 오류)Secret Key(SK) 누락 또는 오타
x-api-key
헤더 또는 
token
파라미터에 유효한 SK 포함
명령이 실행되지 않거나 빈 결과 반환
text
파라미터 형식 오류(명령·파라미터 구분 누락)
GiipIssueList READY
처럼 
[명령] [파라미터]
형식 준수
... has too many arguments specified
오류
text
에 SP 파라미터를 과다 나열		SP의 정확한 파라미터만 나열. 
@sk
·
jsondata
는 엔진이 자동 추가하므로 나열 금지
상태변경 했더니 제목·본문이 
DONE
/
{}
등으로 파괴됨		Sk2 
GiipIssuePut
(전체 덮어쓰기 SP)로 상태변경 시도		상태변경은 전용 REST 
PUT /api/giipIssues {isn,status}
사용(§1). Sk2 
GiipIssuePut
은 write에 쓰지 말 것
응답 
data[0].RstVal
이 200이 아님		Stored Procedure 실행 오류 또는 잘못된 
isn
Proc_MSG
확인 후 API 결과 코드 가이드 참조 (성공은 
0
이 아니라 
200
)
긴 에러 메시지·특수문자 전송 시 값 유실JSON 값 이스케이프 처리 누락
giipApiSk3
의 
jsondata
치환 기능으로 안전하게 전송

버전: 1.3 최종 업데이트: 2026-07-09 소스 파일: 

giipv3/public/help/giip-issue-api.ko.md

v1.3 변경 이력 (2026-07-09, task 20260708183049): 실제 프로덕션 API(giipv3 프론트·giipApiSk2·SP 소스)와 대조하여 정합화. ① Sk2 쓰기 경로 위험 경고 추가: Sk2 

GiipIssuePut
은 내부 
pApiGiipIssuePutbySK(@sk,@isn,@title,@content,@status,@csn)
전체 덮어쓰기 SP라 
GiipIssuePut 7890 DONE
이 제목·본문을 파괴함(응답은 가짜 
RstVal:200
). 실측 확인(577·578 오손 후 복구). 생성·상태변경·코멘트는 전용 REST 엔드포인트로, Sk2는 조회·액션 전용으로 안내. (과거 보고서의 "too many arguments 비호환" 진단은 부분적 관찰이었고, 실제로는 SP가 full-overwrite여서 위험한 것.) ② 성공 코드는 
RstVal = 200
(0 아님) — 응답 예시·문제 해결 표 정정. ③ 이슈 신규 등록 절차(
POST /api/giipIssues
, 
isn
생략 시 신규) 및 안전한 상태변경(
PUT /api/giipIssues {isn,status}
, 
ISNULL
보존) 추가.

관련 문서:

← Previous
Database Management APIs
Next →
Cost Analysis APIs