배송/화물현황과 리스크/알림(api 활용, 공공데이터 복구시 대체될 가능성 있음)
This commit is contained in:
leeheejin
293
docs/리스크알림_API키_발급가이드.md
Normal file
293
docs/리스크알림_API키_발급가이드.md
Normal file
@@ -0,0 +1,293 @@
|
||||
# 리스크/알림 위젯 API 키 발급 가이드 🚨
|
||||
|
||||
## 📌 개요
|
||||
|
||||
리스크/알림 위젯은 **공공데이터포털 API**를 사용합니다:
|
||||
|
||||
1. ✅ **기상청 API** (날씨 특보) - **이미 설정됨!**
|
||||
2. 🔧 **국토교통부 도로교통 API** (교통사고, 도로공사) - **신규 발급 필요**
|
||||
|
||||
---
|
||||
|
||||
## 🔑 1. 기상청 특보 API (이미 설정됨 ✅)
|
||||
|
||||
현재 `.env`에 설정된 키:
|
||||
```bash
|
||||
KMA_API_KEY=ogdXr2e9T4iHV69nvV-IwA
|
||||
```
|
||||
|
||||
**사용 API:**
|
||||
- 기상특보조회서비스 (기상청)
|
||||
- URL: https://www.data.go.kr/data/15000415/openapi.do
|
||||
|
||||
**제공 정보:**
|
||||
- ☁️ 대설특보
|
||||
- 🌀 태풍특보
|
||||
- 💨 강풍특보
|
||||
- 🌊 호우특보
|
||||
|
||||
---
|
||||
|
||||
## 🚗 2. 국토교통부 도로교통 API (신규 발급)
|
||||
|
||||
### 2️⃣-1. 공공데이터포털 회원가입
|
||||
|
||||
```
|
||||
👉 https://www.data.go.kr
|
||||
```
|
||||
|
||||
1. 우측 상단 **회원가입** 클릭
|
||||
2. 이메일 입력 및 인증
|
||||
3. 약관 동의 후 가입 완료
|
||||
|
||||
---
|
||||
|
||||
### 2️⃣-2. API 활용신청
|
||||
|
||||
#### A. 실시간 교통사고 정보
|
||||
|
||||
```
|
||||
👉 https://www.data.go.kr/data/15098913/openapi.do
|
||||
```
|
||||
|
||||
**"실시간 교통사고 정보제공 서비스"** 페이지에서:
|
||||
|
||||
1. **활용신청** 버튼 클릭
|
||||
2. 활용 목적: `기타`
|
||||
3. 상세 기능 설명: `물류 대시보드 리스크 알림`
|
||||
4. 신청 완료
|
||||
|
||||
#### B. 도로공사 및 통제 정보
|
||||
|
||||
```
|
||||
👉 https://www.data.go.kr/data/15071004/openapi.do
|
||||
```
|
||||
|
||||
**"도로공사 및 통제정보 제공 서비스"** 페이지에서:
|
||||
|
||||
1. **활용신청** 버튼 클릭
|
||||
2. 활용 목적: `기타`
|
||||
3. 상세 기능 설명: `물류 대시보드 리스크 알림`
|
||||
4. 신청 완료
|
||||
|
||||
⚠️ **승인까지 약 2-3시간 소요** (즉시 승인되는 경우도 있음)
|
||||
|
||||
---
|
||||
|
||||
### 2️⃣-3. 인증키 확인
|
||||
|
||||
```
|
||||
👉 https://www.data.go.kr/mypage/myPageOpenAPI.do
|
||||
```
|
||||
|
||||
**마이페이지 > 오픈API > 인증키**에서:
|
||||
|
||||
1. **일반 인증키(Encoding)** 복사
|
||||
2. 긴 문자열 전체를 복사하세요!
|
||||
|
||||
**예시:**
|
||||
```
|
||||
aBc1234dEf5678gHi9012jKl3456mNo7890pQr1234sTu5678vWx9012yZa3456bCd7890==
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ 환경 변수 설정
|
||||
|
||||
### .env 파일 수정
|
||||
|
||||
```bash
|
||||
cd /Users/leeheejin/ERP-node/backend-node
|
||||
nano .env
|
||||
```
|
||||
|
||||
### 다음 내용 **추가**:
|
||||
|
||||
```bash
|
||||
# 기상청 API Hub 키 (기존 - 예특보 활용신청 완료 시 사용)
|
||||
KMA_API_KEY=ogdXr2e9T4iHV69nvV-IwA
|
||||
|
||||
# 국토교통부 도로교통 API 키 (활용신청 완료 시 추가)
|
||||
MOLIT_TRAFFIC_API_KEY=여기에_발급받은_교통사고_API_인증키_붙여넣기
|
||||
MOLIT_ROADWORK_API_KEY=여기에_발급받은_도로공사_API_인증키_붙여넣기
|
||||
```
|
||||
|
||||
⚠️ **주의사항:**
|
||||
- API 활용신청이 **승인되기 전**에는 더미 데이터를 사용합니다
|
||||
- **승인 후** API 키만 추가하면 **자동으로 실제 데이터로 전환**됩니다
|
||||
- 승인 여부는 각 포털의 마이페이지에서 확인 가능합니다
|
||||
|
||||
### 저장 및 종료
|
||||
- `Ctrl + O` (저장)
|
||||
- `Enter` (확인)
|
||||
- `Ctrl + X` (종료)
|
||||
|
||||
---
|
||||
|
||||
## 🔄 백엔드 재시작
|
||||
|
||||
```bash
|
||||
docker restart pms-backend-mac
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 사용 가능한 API 정보
|
||||
|
||||
### 1️⃣ 기상청 특보 (KMA_API_KEY)
|
||||
|
||||
**엔드포인트:**
|
||||
```
|
||||
GET /api/risk-alerts/weather
|
||||
```
|
||||
|
||||
**응답 예시:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"id": "weather-001",
|
||||
"type": "weather",
|
||||
"severity": "high",
|
||||
"title": "대설특보",
|
||||
"location": "강원 영동지역",
|
||||
"description": "시간당 2cm 이상 폭설 예상",
|
||||
"timestamp": "2024-10-14T10:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2️⃣ 교통사고 (MOLIT_TRAFFIC_API_KEY)
|
||||
|
||||
**엔드포인트:**
|
||||
```
|
||||
GET /api/risk-alerts/accidents
|
||||
```
|
||||
|
||||
**응답 예시:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"id": "accident-001",
|
||||
"type": "accident",
|
||||
"severity": "high",
|
||||
"title": "교통사고 발생",
|
||||
"location": "경부고속도로 서울방향 189km",
|
||||
"description": "3중 추돌사고로 2차로 통제 중",
|
||||
"timestamp": "2024-10-14T10:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3️⃣ 도로공사 (MOLIT_ROADWORK_API_KEY)
|
||||
|
||||
**엔드포인트:**
|
||||
```
|
||||
GET /api/risk-alerts/roadworks
|
||||
```
|
||||
|
||||
**응답 예시:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"id": "construction-001",
|
||||
"type": "construction",
|
||||
"severity": "medium",
|
||||
"title": "도로 공사",
|
||||
"location": "서울외곽순환 목동IC~화곡IC",
|
||||
"description": "야간 공사로 1차로 통제 (22:00~06:00)",
|
||||
"timestamp": "2024-10-14T10:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ 테스트
|
||||
|
||||
### 1. API 키 발급 확인
|
||||
```bash
|
||||
curl "https://www.data.go.kr/mypage/myPageOpenAPI.do"
|
||||
```
|
||||
|
||||
### 2. 백엔드 API 테스트
|
||||
```bash
|
||||
# 날씨 특보
|
||||
curl "http://localhost:9771/api/risk-alerts/weather" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN"
|
||||
|
||||
# 교통사고
|
||||
curl "http://localhost:9771/api/risk-alerts/accidents" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN"
|
||||
|
||||
# 도로공사
|
||||
curl "http://localhost:9771/api/risk-alerts/roadworks" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN"
|
||||
```
|
||||
|
||||
### 3. 대시보드에서 위젯 확인
|
||||
1. `http://localhost:9771/admin/dashboard` 접속
|
||||
2. 우측 사이드바 → **🚨 리스크 / 알림** 드래그
|
||||
3. 실시간 정보 확인!
|
||||
|
||||
---
|
||||
|
||||
## 🔧 트러블슈팅
|
||||
|
||||
### 1. "API 키가 유효하지 않습니다" 오류
|
||||
|
||||
**원인**: API 키가 잘못되었거나 활성화되지 않음
|
||||
|
||||
**해결방법**:
|
||||
1. 공공데이터포털에서 API 키 재확인
|
||||
2. 신청 후 **승인 대기** 상태인지 확인 (2-3시간 소요)
|
||||
3. `.env` 파일에 복사한 키가 정확한지 확인
|
||||
4. 백엔드 재시작 (`docker restart pms-backend-mac`)
|
||||
|
||||
---
|
||||
|
||||
### 2. "서비스가 허용되지 않습니다" 오류
|
||||
|
||||
**원인**: 신청한 API와 요청한 서비스가 다름
|
||||
|
||||
**해결방법**:
|
||||
1. 공공데이터포털 마이페이지에서 **신청한 서비스 목록** 확인
|
||||
2. 필요한 서비스를 **모두 신청**했는지 확인
|
||||
3. 승인 완료 상태인지 확인
|
||||
|
||||
---
|
||||
|
||||
### 3. 데이터가 표시되지 않음
|
||||
|
||||
**원인**: API 응답 형식 변경 또는 서비스 중단
|
||||
|
||||
**해결방법**:
|
||||
1. 공공데이터포털 **공지사항** 확인
|
||||
2. API 문서에서 **응답 형식** 확인
|
||||
3. 백엔드 로그 확인 (`docker logs pms-backend-mac`)
|
||||
|
||||
---
|
||||
|
||||
## 💡 참고 링크
|
||||
|
||||
- 공공데이터포털: https://www.data.go.kr
|
||||
- 기상청 Open API: https://data.kma.go.kr
|
||||
- 국토교통부 Open API: https://www.its.go.kr
|
||||
- API 활용 가이드: https://www.data.go.kr/tcs/dss/selectApiDataDetailView.do
|
||||
|
||||
---
|
||||
|
||||
**완료되면 브라우저 새로고침 (Cmd + R) 하세요!** 🚨✨
|
||||
|
||||
Reference in New Issue
Block a user