Vercel 관리 API 가이드 (v1.2)

GIIP 플랫폼은 Vercel 프로젝트의 설정을 관리하고 배포 이력을 조회하기 위한 API를 제공합니다. 이 API는 기본적으로 Sk3(JSON 데이터 기반) 인터페이스를 사용하여 요청을 처리합니다.

🔌 Vercel 상태 페이지로 이동 →

📋 개요

Vercel 관리 API는 GIIP에 등록된 Vercel 프로젝트 설정을 조회하거나, 최신 배포 이력을 모니터링하는 데 사용됩니다.

🔐 인증 및 보안

모든 요청은 GIIP 공통 인증 헤더를 포함해야 합니다.

• Header: x-giip-ak, x-giip-sk
• Body Context: Sk3 인터페이스 (jsondata 필드 사용)

📡 API 상세 (Sk3)

1. Vercel 설정 목록 조회 (VercelConfigsList)

• 명령: text=VercelConfigsList
• jsondata: {"csn": 123} (선택 사항: 프로젝트 식별자)
• 설명: 현재 등록된 모든 Vercel 설정 정보와 연동된 Vercel 프로젝트명을 반환합니다.

2. Vercel 설정 생성 (VercelConfigCreate)

• 명령: text=VercelConfigCreate
• jsondata:

{
  "csn": 123,
  "configName": "Production_Main",
  "vercelProjectName": "giip-next-app",
  "vercelToken": "vcl_token_...",
  "vercelTeamId": "team_xxx",
  "vercelProjectId": "prj_xxx"
}

3. Vercel 설정 수정/삭제 (VercelConfigUpdate / VercelConfigDelete)

• 수정: text=VercelConfigUpdate + {"vcId": 123, ...}
• 삭제: text=VercelConfigDelete + {"vcSn": 123} (또는 vcId)

4. 배포 이력 조회 (VercelDeploymentsList)

• 명령: text=VercelDeploymentsList
• jsondata: {"vcId": 123, "limit": 20}
• 설명: 특정 설정(vcId)에 해당하는 Vercel 배포 목록을 최신순으로 조회합니다.

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

Vercel 관리 API는 설계 단계부터 giipApiSk3 인터페이스를 표준으로 채택하고 있습니다. 모든 설정 관리 및 조회 요청에 대해 상세한 실행 컨텍스트와 에러 트레이싱을 제공합니다.

• 엔드포인트: https://giipfaw.azurewebsites.net/api/giipApiSk3
• 장점: Vercel 토큰 오류나 배포 상태 동기화 실패 시, 호출자의 IP, User-Agent 및 상세한 서버 측 StackTrace를 자동으로 기록하여 연동 문제를 신속하게 진단할 수 있도록 도와줍니다.
• 활용 팁: VercelConfigCreate와 같이 파라미터가 많은 요청을 보낼 때, jsondata 객체 구조를 활용하면 복잡한 토큰 값들을 유실 없이 안전하게 전송하고 로그를 남길 수 있습니다.

🔧 문제 해결

증상	원인	해결
요청이 인증 오류로 거부됨	x-giip-ak / x-giip-sk 헤더 누락 또는 잘못된 키	유효한 인증 헤더를 포함하여 재요청
text 명령이 인식되지 않거나 빈 응답	text 값 오타(예: VercelConfigList ↔ VercelConfigsList)	정확한 명령명을 확인하여 text 파라미터에 지정
배포 목록이 비어 있거나 동기화 실패	vercelToken이 만료되었거나 잘못됨	VercelConfigUpdate로 유효한 토큰을 갱신한 뒤 재조회
VercelDeploymentsList가 결과를 반환하지 않음	vcId가 잘못되었거나 해당 설정에 배포 이력 없음	VercelConfigsList로 올바른 vcId를 확인한 후 재요청

---

버전: 1.3 최종 업데이트: 2026-04-10 소스 파일: giipv3/public/help/api-vercel.ko.md

---

관련 문서:

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