프로젝트 및 서비스 관리 API 가이드 (v1.2)

GIIP 플랫폼 내의 조직(프로젝트)과 서비스 그룹을 관리하기 위한 API 명세입니다.

🔌 프로젝트 목록 기능 페이지로 이동 → · 👥 사용자 목록 기능 페이지로 이동 →

📋 개요

프로젝트(고객) 및 서비스 그룹 API는 GIIP 인프라를 논리적 단위로 구분하고 권한을 제어하는 핵심 기능을 제공합니다.

🔐 인증 및 보안

• Header: 공통 인증 헤더 필수
• 권한: 프로젝트 생성/삭제는 높은 등급의 관리자 권한이 요구될 수 있습니다.

📡 API 상세

1. 프로젝트 관리

프로젝트 목록 조회 (PrjList)

• 명령: text=PrjList
• 설명: 현재 사용자가 접근 가능한 모든 프로젝트(고객) 목록을 반환합니다.
• 반환예시: [{"csn":44, "cname":"Acme Corp"}, ...]

프로젝트 신규 등록 (PrjPut)

• 명령: text=PrjPut <cCode>, '<cName>'
• 파라미터:
  • cCode: 프로젝트 영문 코드 (Unique)
  • cName: 프로젝트 표시 명칭
• 예시: text=PrjPut GIIP_DEV, 'GIIP 개발팀'

프로젝트 삭제 (PrjDel)

• 명령: text=PrjDel <CSN>
• 예시: text=PrjDel 44

2. 서비스 그룹(Project Group) 관리

서비스 목록 조회 (PrjGrpList)

• 명령: text=PrjGrpList <CSN>
• 설명: 특정 프로젝트 하위의 서비스 그룹(cgCode 기반) 목록을 조회합니다.

서비스 등록/수정 (PrjGrpPut)

• 명령: text=PrjGrpPut '<CgCode>', <cSn>, '<cgName>', '<cgDesc>'
• 예시: text=PrjGrpPut 'WEB', 44, 'Web Service', 'Primary web application group'

3. 사용자 관리 (Project User Management)

프로젝트(CSN)에 속한 사용자를 조회·초대·권한변경·제거하는 API입니다. 웹 UI는 유저 목록 가이드를 참고하세요.

프로젝트 사용자 목록 조회 (UserList)

• 명령: text=UserList csn
• jsondata: {"csn": 44}
• 설명: 호출자가 속한 프로젝트(csn)의 멤버 목록을 반환합니다. 호출자가 해당 프로젝트 멤버가 아니면 오류 없이 빈 목록(0건)을 반환합니다.
• 반환 컬럼: usn, uloginid, uname, uemail, uregdt, isPay, uPerCorp(권한: 1=Member, 49=Owner)

사용자 초대/매핑 (PrjUserMap)

• 명령: text=PrjUserMap csn uloginid
• jsondata: {"csn": 44, "uloginid": "user@example.com"}
• 설명: 이미 GIIP 계정이 존재하는 사용자(uloginid=로그인ID, 보통 이메일)를 프로젝트 멤버로 매핑합니다. 신규 멤버의 권한은 항상 1(Member)로 시작합니다.
• ⚠️ 주의: uloginid에 해당하는 GIIP 계정이 아직 없으면 매핑이 실패합니다(retcode 304). userlist 페이지의 "초대" 버튼은 이 API 호출과 초대 이메일 발송을 함께 수행하되, 이 API 실패는 화면에 노출하지 않고 넘어갑니다 — 대상자가 가입 전이면 이메일만 발송되고, 실제 멤버 매핑은 대상자가 가입한 뒤 이 API를 다시 호출해야 완료됩니다.
• 반환: retcode — 200(성공), 201(미인증), 301(호출자가 해당 csn 멤버 아님), 304(대상 계정 없음), 305(이미 멤버)

사용자 권한 변경 (PrjUserPer)

• 명령: text=PrjUserPer csn uloginid uper
• jsondata: {"csn": 44, "uloginid": "user@example.com", "uper": 49}
• 설명: 프로젝트 멤버의 권한을 Member(1) ↔ Owner(49)로 변경합니다. 호출자가 해당 프로젝트의 Owner(49)여야 하며, 자기 자신의 권한은 이 API로 변경할 수 없습니다.
• uper 허용값: 1(Member) 또는 49(Owner)만 허용되며, 그 외 값은 거부됩니다.
• 반환: RstVal/RstMsg — 200(성공), 401(미인증), 403(권한 부족/Owner 아님/자기 자신 대상/허용되지 않은 uper 값), 404(대상 없음 또는 비멤버)

사용자 제거 (PrjUserDel)

• 명령: text=PrjUserDel csn uloginid
• jsondata: {"csn": 44, "uloginid": "user@example.com"}
• 설명: 프로젝트 멤버십을 삭제합니다. 삭제 즉시 해당 사용자는 프로젝트의 모든 자산 접근 권한을 잃습니다.
• 반환: RstVal/RstMsg — 200(성공), 201(미인증), 301(호출자가 해당 csn 멤버 아님), 304(대상이 프로젝트 멤버 아님)

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

신규 프로젝트 등록이나 서비스 그룹 수정과 같이 인프라 전반의 구조에 영향을 주는 관리 작업 시, 작업의 정합성 확보와 상세한 감사 로그(Audit Log)를 위해 giipApiSk3 엔드포인트를 권장합니다.

• 엔드포인트: https://giipfaw.azurewebsites.net/api/giipApiSk3
• 장점: 프로젝트 생성 실패 시 호출자의 상세 환경 정보(IP, UA)와 StackTrace를 즉시 기록하여 설정 오류나 권한 이슈를 신속하게 분석할 수 있습니다.
• 활용 팁: text 명령과 jsondata의 파라미터 치환 기능을 활용하여 복잡한 서비스 그룹 설명이나 한글 명칭 등을 유실 없이 안전하게 관리하십시오.

🔧 문제 해결

증상	원인	해결
요청이 인증 오류로 거부된다	공통 인증 헤더(x-giip-ak/x-giip-sk)가 누락됨	모든 요청에 두 인증 헤더를 포함했는지 확인합니다
PrjPut 호출이 실패하거나 프로젝트가 생성되지 않는다	text 명령 시그니처(PrjPut <cCode>, '<cName>')가 맞지 않음	cCode(Unique)와 따옴표로 감싼 cName 형식을 정확히 맞춰 다시 호출합니다
PrjDel 응답의 RstVal이 0이 아니다	잘못된 CSN을 지정했거나 삭제 권한이 부족함	올바른 CSN을 확인하고, 프로젝트 삭제에 필요한 관리자 권한이 있는지 확인합니다
PrjGrpPut의 한글/특수문자 명칭이 깨진다	text 문자열에서 특수문자가 이스케이프되지 않음	giipApiSk3에서 jsondata 파라미터 치환 기능을 사용해 명칭을 유실 없이 전송합니다
PrjUserMap 호출 후에도 사용자 목록에 보이지 않는다	대상 uloginid의 GIIP 계정이 아직 없어 매핑이 실패함(초대 메일만 발송됨)	대상자가 먼저 GIIP에 가입한 뒤 다시 PrjUserMap을 호출합니다
PrjUserPer 호출이 403으로 거부된다	호출자가 해당 프로젝트 Owner(49)가 아니거나, 자기 자신을 대상으로 지정함	Owner 계정으로 호출하고, 대상은 자기 자신이 아닌 다른 멤버로 지정합니다

---

버전: 1.4 최종 업데이트: 2026-07-26 소스 파일: giipv3/public/help/api-project-user.ko.md

---

관련 문서:

• API 결과 코드 가이드 (RstVal)