물류 관리 시스템 API 통합 명세서
물류 관리 시스템의 API 명세서 인덱스입니다. 각 시스템별 상세 API 명세서는 아래 링크를 참조하시기 바랍니다.
물류 공유 플랫폼
창고 중계, 공차 중계, 배차 제어 시스템
창고 검색 및 매칭
공차 차량 중계
배차 제어 및 최적화
운송 현황 실시간 모니터링
안전 관리 시스템
무재해, 위험성 평가, 안전 교육, 예산 관리
무재해 일수 관리
위험성 평가 및 관리
안전 교육 프로그램
예산 집행 관리
물류 공유 플랫폼
| 기능 | 엔드포인트 | 설명 |
|---|---|---|
| 창고 검색 | GET /warehouses/search | 조건별 창고 검색 |
| 창고 예약 | POST /warehouses/{id}/reservation | 창고 예약 요청 |
| 공차 검색 | GET /empty-vehicles/search | 공차 차량 검색 |
| 운송 요청 | POST /transport-requests | 운송 요청 등록 |
| 매칭 | POST /matching | 차량-화물 매칭 |
| 배차 할당 | POST /dispatch/assign | 배차 할당 |
| 실시간 위치 | GET /transport/realtime | 실시간 차량 위치 |
안전 관리 시스템
| 기능 | 엔드포인트 | 설명 |
|---|---|---|
| 안전 대시보드 | GET /safety/dashboard | 종합 안전 현황 |
| 실시간 지표 | GET /safety/realtime | 실시간 안전 지표 |
| 사고 이력 | GET /safety/accidents | 사고 이력 조회 |
| 위험성 평가 | GET /risk/assessments | 위험성 평가 목록 |
| 교육 현황 | GET /education/completion | 교육 이수 현황 |
| 예산 현황 | GET /budget/safety | 안전 예산 집행 |
| 알림 스트림 | GET /alerts/stream | 실시간 알림 (SSE) |
인증 및 보안
인증 방식
http
Authorization: Bearer {jwt_token}권한 레벨
| 레벨 | 설명 | 접근 범위 |
|---|---|---|
| admin | 시스템 관리자 | 전체 시스템 관리 |
| manager | 관리자 | 데이터 조회 및 보고서 |
| operator | 운영자 | 일반 운영 기능 |
| viewer | 조회자 | 읽기 전용 |
API 응답 형식
성공 응답
json
{
"data": {
// 요청한 데이터
},
"meta": {
"timestamp": "2025-01-25T14:30:00+09:00",
"request_id": "req_123456789"
}
}에러 응답
json
{
"error": {
"code": "ERR_CODE",
"message": "에러 메시지",
"details": {
// 상세 정보
},
"timestamp": "2025-01-25T14:30:00+09:00",
"request_id": "req_123456789"
}
}페이지네이션
json
{
"data": [],
"pagination": {
"page": 1,
"per_page": 20,
"total": 100,
"total_pages": 5,
"has_next": true,
"has_prev": false
}
}Rate Limiting
| API 타입 | 제한 | 단위 |
|---|---|---|
| 일반 조회 | 100 | 분당 |
| 데이터 등록/수정 | 20 | 분당 |
| 통계/분석 | 50 | 분당 |
| 실시간 스트림 | 5 | 초당 |
| 파일 업로드 | 10 | 시간당 |
공통 WebSocket URL 패턴
text
wss://api.{system}-logistics.kr/v1/ws연결 프로토콜
- 연결 요청 with JWT 토큰
- 채널 구독
- 실시간 메시지 수신
- 하트비트 (30초마다)
날짜/시간
- ISO 8601 형식: YYYY-MM-DDTHH:mm:ss+09:00
- 타임존: KST (UTC+9)
좌표
json
{
"latitude": 36.019,
"longitude": 129.3433
}금액
- 단위: 원(KRW)
- 타입: integer
무게/용량
- 무게: kg 또는 톤
- 거리: km 또는 m
- 부피: ㎥ (입방미터)
- 면적: ㎡ (제곱미터)
| 코드 | 의미 | 설명 |
|---|---|---|
| 200 | OK | 요청 성공 |
| 201 | Created | 리소스 생성 성공 |
| 204 | No Content | 성공하였으나 응답 데이터 없음 |
| 400 | Bad Request | 잘못된 요청 |
| 401 | Unauthorized | 인증 실패 |
| 403 | Forbidden | 권한 없음 |
| 404 | Not Found | 리소스를 찾을 수 없음 |
| 409 | Conflict | 리소스 충돌 |
| 429 | Too Many Requests | 요청 한도 초과 |
| 500 | Internal Server Error | 서버 오류 |
| 502 | Bad Gateway | 게이트웨이 오류 |
| 503 | Service Unavailable | 서비스 일시 중단 |
| 코드 범위 | 카테고리 |
|---|---|
| ERR_1xxx | 인증/권한 오류 |
| ERR_2xxx | 데이터 검증 오류 |
| ERR_3xxx | 비즈니스 로직 오류 |
| ERR_4xxx | 외부 시스템 오류 |
| ERR_5xxx | 서버 내부 오류 |
| 용어 | 영문 | 설명 |
|---|---|---|
| 베이 | Bay | 창고 내 개별 저장 공간 |
| 공차 | Empty Vehicle | 화물을 싣지 않은 빈 차량 |
| 배차 | Dispatch | 차량 할당 및 운송 지시 |
| LTIFR | Lost Time Injury Frequency Rate | 휴업재해율 |
| PPE | Personal Protective Equipment | 개인보호구 |
| KPI | Key Performance Indicator | 핵심성과지표 |
| SLA | Service Level Agreement | 서비스 수준 계약 |
문서 정보
최종 수정일:2025-01-25
버전:1.1.0
다음 업데이트:2025-02-25