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

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

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

📋 개요

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

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

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

명령: 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(이미 멤버)

명령: 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(대상 없음 또는 비멤버)

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

신규 프로젝트 등록이나 서비스 그룹 수정과 같이 인프라 전반의 구조에 영향을 주는 관리 작업 시, 작업의 정합성 확보와 상세한 감사 로그(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

관련 문서: