# ERP API 목록 (List vs Detail 구분)

> **작성일**: 2025-12-19
> **기준 문서**: [erp-api-development-plan.md](../plans/erp-api-development-plan.md)
> **Swagger UI**: http://sam.kr/api-docs/index.html

---

## 📊 API 유형 분류

| 유형 | 설명 | HTTP Method |
|------|------|-------------|
| **LIST** | 목록 조회 (페이지네이션) | GET |
| **DETAIL** | 단건 조회 | GET |
| **CREATE** | 생성 | POST |
| **UPDATE** | 수정 | PUT/PATCH |
| **DELETE** | 삭제 | DELETE |
| **ACTION** | 상태 변경/특수 액션 | POST/PATCH |

---

## 🗂️ Phase 1: 확장 개발 API

### 1. 휴가 관리 (Leaves) - 11개 API

| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| LIST | GET | `/v1/leaves` | 휴가 목록 조회 |
| DETAIL | GET | `/v1/leaves/{id}` | 휴가 상세 조회 |
| CREATE | POST | `/v1/leaves` | 휴가 신청 |
| UPDATE | PATCH | `/v1/leaves/{id}` | 휴가 수정 |
| DELETE | DELETE | `/v1/leaves/{id}` | 휴가 삭제 |
| ACTION | POST | `/v1/leaves/{id}/approve` | 휴가 승인 |
| ACTION | POST | `/v1/leaves/{id}/reject` | 휴가 반려 |
| ACTION | POST | `/v1/leaves/{id}/cancel` | 휴가 취소 |
| DETAIL | GET | `/v1/leaves/balance` | 내 잔여휴가 조회 |
| DETAIL | GET | `/v1/leaves/balance/{userId}` | 특정 사용자 잔여휴가 |
| UPDATE | PUT | `/v1/leaves/balance` | 잔여휴가 설정 |

---

### 2. 근무/출퇴근 설정 (Work Settings) - 10개 API

#### 2.1 근무 설정 (2개)
| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| DETAIL | GET | `/v1/settings/work` | 근무 설정 조회 |
| UPDATE | PUT | `/v1/settings/work` | 근무 설정 수정 |

#### 2.2 출퇴근 설정 (2개)
| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| DETAIL | GET | `/v1/settings/attendance` | 출퇴근 설정 조회 |
| UPDATE | PUT | `/v1/settings/attendance` | 출퇴근 설정 수정 |

#### 2.3 현장 관리 (Sites) - 6개
| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| LIST | GET | `/v1/sites` | 현장 목록 조회 |
| LIST | GET | `/v1/sites/active` | 활성 현장 목록 (셀렉트박스용) |
| DETAIL | GET | `/v1/sites/{id}` | 현장 상세 조회 |
| CREATE | POST | `/v1/sites` | 현장 등록 |
| UPDATE | PUT | `/v1/sites/{id}` | 현장 수정 |
| DELETE | DELETE | `/v1/sites/{id}` | 현장 삭제 |

---

### 3. 카드/계좌 관리 - 15개 API

#### 3.1 카드 관리 (Cards) - 7개
| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| LIST | GET | `/v1/cards` | 카드 목록 조회 |
| LIST | GET | `/v1/cards/active` | 활성 카드 목록 (셀렉트박스용) |
| DETAIL | GET | `/v1/cards/{id}` | 카드 상세 조회 |
| CREATE | POST | `/v1/cards` | 카드 등록 |
| UPDATE | PUT | `/v1/cards/{id}` | 카드 수정 |
| DELETE | DELETE | `/v1/cards/{id}` | 카드 삭제 |
| ACTION | PATCH | `/v1/cards/{id}/toggle` | 카드 사용/정지 토글 |

#### 3.2 계좌 관리 (Bank Accounts) - 8개
| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| LIST | GET | `/v1/bank-accounts` | 계좌 목록 조회 |
| LIST | GET | `/v1/bank-accounts/active` | 활성 계좌 목록 (셀렉트박스용) |
| DETAIL | GET | `/v1/bank-accounts/{id}` | 계좌 상세 조회 |
| CREATE | POST | `/v1/bank-accounts` | 계좌 등록 |
| UPDATE | PUT | `/v1/bank-accounts/{id}` | 계좌 수정 |
| DELETE | DELETE | `/v1/bank-accounts/{id}` | 계좌 삭제 |
| ACTION | PATCH | `/v1/bank-accounts/{id}/toggle` | 계좌 사용/정지 토글 |
| ACTION | PATCH | `/v1/bank-accounts/{id}/set-primary` | 대표계좌 설정 |

---

### 4. 입금/출금 관리 - 12개 API

#### 4.1 입금 관리 (Deposits) - 6개
| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| LIST | GET | `/v1/deposits` | 입금 목록 조회 |
| LIST | GET | `/v1/deposits/summary` | 입금 요약 (집계) |
| DETAIL | GET | `/v1/deposits/{id}` | 입금 상세 조회 |
| CREATE | POST | `/v1/deposits` | 입금 등록 |
| UPDATE | PUT | `/v1/deposits/{id}` | 입금 수정 |
| DELETE | DELETE | `/v1/deposits/{id}` | 입금 삭제 |

#### 4.2 출금 관리 (Withdrawals) - 6개
| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| LIST | GET | `/v1/withdrawals` | 출금 목록 조회 |
| LIST | GET | `/v1/withdrawals/summary` | 출금 요약 (집계) |
| DETAIL | GET | `/v1/withdrawals/{id}` | 출금 상세 조회 |
| CREATE | POST | `/v1/withdrawals` | 출금 등록 |
| UPDATE | PUT | `/v1/withdrawals/{id}` | 출금 수정 |
| DELETE | DELETE | `/v1/withdrawals/{id}` | 출금 삭제 |

---

### 5. 매출/매입 관리 - 17개 API

#### 5.1 매출 관리 (Sales) - 10개
| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| LIST | GET | `/v1/sales` | 매출 목록 조회 |
| LIST | GET | `/v1/sales/summary` | 매출 요약 (집계) |
| DETAIL | GET | `/v1/sales/{id}` | 매출 상세 조회 |
| CREATE | POST | `/v1/sales` | 매출 등록 |
| UPDATE | PUT | `/v1/sales/{id}` | 매출 수정 |
| DELETE | DELETE | `/v1/sales/{id}` | 매출 삭제 |
| ACTION | POST | `/v1/sales/{id}/confirm` | 매출 확정 |
| DETAIL | GET | `/v1/sales/{id}/statement` | 거래명세서 조회 |
| ACTION | POST | `/v1/sales/{id}/statement/issue` | 거래명세서 발행 |
| ACTION | POST | `/v1/sales/{id}/statement/send` | 거래명세서 이메일 발송 |

#### 5.2 매입 관리 (Purchases) - 7개
| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| LIST | GET | `/v1/purchases` | 매입 목록 조회 |
| LIST | GET | `/v1/purchases/summary` | 매입 요약 (집계) |
| DETAIL | GET | `/v1/purchases/{id}` | 매입 상세 조회 |
| CREATE | POST | `/v1/purchases` | 매입 등록 |
| UPDATE | PUT | `/v1/purchases/{id}` | 매입 수정 |
| DELETE | DELETE | `/v1/purchases/{id}` | 매입 삭제 |
| ACTION | POST | `/v1/purchases/{id}/confirm` | 매입 확정 |

---

### 6. 보고서 (Reports) - 4개 API

| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| DETAIL | GET | `/v1/reports/daily` | 일일 일보 조회 |
| ACTION | GET | `/v1/reports/daily/export` | 일일 일보 엑셀 다운로드 |
| DETAIL | GET | `/v1/reports/expense-estimate` | 지출 예상 내역서 조회 |
| ACTION | GET | `/v1/reports/expense-estimate/export` | 지출 예상 내역서 엑셀 다운로드 |

---

## 👤 Phase 5: 사용자/계정 관리 API

### 16. 사용자 초대 (User Invitations) - 5개 API

| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| LIST | GET | `/v1/users/invitations` | 초대 목록 조회 |
| CREATE | POST | `/v1/users/invite` | 사용자 초대 발송 |
| ACTION | POST | `/v1/users/invitations/{token}/accept` | 초대 수락 |
| DELETE | DELETE | `/v1/users/invitations/{id}` | 초대 취소 |
| ACTION | POST | `/v1/users/invitations/{id}/resend` | 초대 재발송 |

---

### 17. 알림 설정 (Notification Settings) - 3개 API

| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| LIST | GET | `/v1/users/me/notification-settings` | 알림 설정 조회 |
| UPDATE | PUT | `/v1/users/me/notification-settings` | 알림 설정 수정 (단일) |
| ACTION | PUT | `/v1/users/me/notification-settings/bulk` | 알림 설정 일괄 저장 |

---

### 18. 계정 관리 (Account) - 4개 API

| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| ACTION | POST | `/v1/account/withdraw` | 회원 탈퇴 (SAM 완전 탈퇴) |
| ACTION | POST | `/v1/account/suspend` | 사용 중지 (현재 테넌트에서만 탈퇴) |
| DETAIL | GET | `/v1/account/agreements` | 약관 동의 정보 조회 |
| UPDATE | PUT | `/v1/account/agreements` | 약관 동의 정보 수정 |

---

## 🔨 Phase 2: 핵심 신규 개발 API

### 7. 전자결재 모듈 - 26개 API

#### 7.1 결재 양식 (Approval Forms) - 6개
| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| LIST | GET | `/v1/approval-forms` | 결재 양식 목록 |
| LIST | GET | `/v1/approval-forms/active` | 활성 결재 양식 (셀렉트박스용) |
| DETAIL | GET | `/v1/approval-forms/{id}` | 결재 양식 상세 |
| CREATE | POST | `/v1/approval-forms` | 결재 양식 등록 |
| UPDATE | PATCH | `/v1/approval-forms/{id}` | 결재 양식 수정 |
| DELETE | DELETE | `/v1/approval-forms/{id}` | 결재 양식 삭제 |

#### 7.2 결재선 템플릿 (Approval Lines) - 5개
| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| LIST | GET | `/v1/approval-lines` | 결재선 목록 |
| DETAIL | GET | `/v1/approval-lines/{id}` | 결재선 상세 |
| CREATE | POST | `/v1/approval-lines` | 결재선 등록 |
| UPDATE | PATCH | `/v1/approval-lines/{id}` | 결재선 수정 |
| DELETE | DELETE | `/v1/approval-lines/{id}` | 결재선 삭제 |

#### 7.3 결재 문서 (Approvals) - 15개
| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| LIST | GET | `/v1/approvals/drafts` | 기안함 (내가 작성한 문서) |
| LIST | GET | `/v1/approvals/drafts/summary` | 기안함 요약 |
| LIST | GET | `/v1/approvals/inbox` | 결재함 (결재 대기 문서) |
| LIST | GET | `/v1/approvals/inbox/summary` | 결재함 요약 |
| LIST | GET | `/v1/approvals/reference` | 참조함 (참조 문서) |
| DETAIL | GET | `/v1/approvals/{id}` | 결재 문서 상세 |
| CREATE | POST | `/v1/approvals` | 결재 문서 작성 (임시저장) |
| UPDATE | PATCH | `/v1/approvals/{id}` | 결재 문서 수정 |
| DELETE | DELETE | `/v1/approvals/{id}` | 결재 문서 삭제 |
| ACTION | POST | `/v1/approvals/{id}/submit` | 결재 상신 |
| ACTION | POST | `/v1/approvals/{id}/approve` | 결재 승인 |
| ACTION | POST | `/v1/approvals/{id}/reject` | 결재 반려 |
| ACTION | POST | `/v1/approvals/{id}/cancel` | 결재 취소/회수 |
| ACTION | POST | `/v1/approvals/{id}/read` | 참조 열람 처리 |
| ACTION | POST | `/v1/approvals/{id}/unread` | 참조 미열람 처리 |

---

### 8. 급여 관리 (Payrolls) - 13개 API

| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| LIST | GET | `/v1/payrolls` | 급여 목록 조회 |
| LIST | GET | `/v1/payrolls/summary` | 급여 현황 요약 |
| DETAIL | GET | `/v1/payrolls/{id}` | 급여 상세 조회 |
| DETAIL | GET | `/v1/payrolls/{id}/payslip` | 급여명세서 조회 |
| CREATE | POST | `/v1/payrolls` | 급여 등록 |
| UPDATE | PUT | `/v1/payrolls/{id}` | 급여 수정 |
| DELETE | DELETE | `/v1/payrolls/{id}` | 급여 삭제 |
| ACTION | POST | `/v1/payrolls/calculate` | 급여 일괄 계산 |
| ACTION | POST | `/v1/payrolls/bulk-confirm` | 급여 일괄 확정 |
| ACTION | POST | `/v1/payrolls/{id}/confirm` | 급여 확정 |
| ACTION | POST | `/v1/payrolls/{id}/pay` | 급여 지급 처리 |
| DETAIL | GET | `/v1/settings/payroll` | 급여 설정 조회 |
| UPDATE | PUT | `/v1/settings/payroll` | 급여 설정 수정 |

---

### 9. 대시보드 (Dashboard) - 3개 API

| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| DETAIL | GET | `/v1/dashboard/summary` | 대시보드 요약 데이터 |
| DETAIL | GET | `/v1/dashboard/charts` | 차트 데이터 |
| DETAIL | GET | `/v1/dashboard/approvals` | 결재 현황 |

---

## 🔧 Phase 3: 추가 기능 API

### 10. AI 리포트 (AI Reports) - 4개 API

| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| LIST | GET | `/v1/reports/ai` | AI 리포트 목록 |
| DETAIL | GET | `/v1/reports/ai/{id}` | AI 리포트 상세 |
| ACTION | POST | `/v1/reports/ai/generate` | AI 리포트 생성 |
| DELETE | DELETE | `/v1/reports/ai/{id}` | AI 리포트 삭제 |

---

### 11. 가지급금 관리 (Loans) - 9개 API

| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| LIST | GET | `/v1/loans` | 가지급금 목록 조회 |
| LIST | GET | `/v1/loans/summary` | 가지급금 요약 |
| DETAIL | GET | `/v1/loans/{id}` | 가지급금 상세 조회 |
| DETAIL | GET | `/v1/loans/interest-report/{year}` | 연도별 인정이자 리포트 |
| CREATE | POST | `/v1/loans` | 가지급금 등록 |
| UPDATE | PUT | `/v1/loans/{id}` | 가지급금 수정 |
| DELETE | DELETE | `/v1/loans/{id}` | 가지급금 삭제 |
| ACTION | POST | `/v1/loans/calculate-interest` | 인정이자 계산 |
| ACTION | POST | `/v1/loans/{id}/settle` | 가지급금 정산 |

---

### 12. 바로빌 연동 (세금계산서) - 12개 API

#### 12.1 바로빌 설정 (3개)
| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| DETAIL | GET | `/v1/barobill-settings` | 바로빌 설정 조회 |
| UPDATE | PUT | `/v1/barobill-settings` | 바로빌 설정 저장 |
| ACTION | POST | `/v1/barobill-settings/test-connection` | 연동 테스트 |

#### 12.2 세금계산서 (9개)
| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| LIST | GET | `/v1/tax-invoices` | 세금계산서 목록 |
| LIST | GET | `/v1/tax-invoices/summary` | 세금계산서 요약 통계 |
| DETAIL | GET | `/v1/tax-invoices/{id}` | 세금계산서 상세 |
| DETAIL | GET | `/v1/tax-invoices/{id}/check-status` | 국세청 전송 상태 조회 |
| CREATE | POST | `/v1/tax-invoices` | 세금계산서 생성 |
| UPDATE | PUT | `/v1/tax-invoices/{id}` | 세금계산서 수정 |
| DELETE | DELETE | `/v1/tax-invoices/{id}` | 세금계산서 삭제 |
| ACTION | POST | `/v1/tax-invoices/{id}/issue` | 세금계산서 발행 |
| ACTION | POST | `/v1/tax-invoices/{id}/cancel` | 세금계산서 취소 |

---

## 💼 Phase 4: SaaS 기능 API

### 13. 요금제 관리 (Plans) - 7개 API

| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| LIST | GET | `/v1/plans` | 요금제 목록 |
| LIST | GET | `/v1/plans/active` | 활성 요금제 목록 |
| DETAIL | GET | `/v1/plans/{id}` | 요금제 상세 |
| CREATE | POST | `/v1/plans` | 요금제 등록 |
| UPDATE | PUT | `/v1/plans/{id}` | 요금제 수정 |
| DELETE | DELETE | `/v1/plans/{id}` | 요금제 삭제 |
| ACTION | PATCH | `/v1/plans/{id}/toggle` | 요금제 활성/비활성 |

---

### 14. 구독 관리 (Subscriptions) - 8개 API

| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| LIST | GET | `/v1/subscriptions` | 구독 목록 |
| DETAIL | GET | `/v1/subscriptions/current` | 현재 구독 조회 |
| DETAIL | GET | `/v1/subscriptions/{id}` | 구독 상세 |
| CREATE | POST | `/v1/subscriptions` | 구독 신청 |
| ACTION | POST | `/v1/subscriptions/{id}/cancel` | 구독 해지 |
| ACTION | POST | `/v1/subscriptions/{id}/renew` | 구독 갱신 |
| ACTION | POST | `/v1/subscriptions/{id}/suspend` | 구독 일시정지 |
| ACTION | POST | `/v1/subscriptions/{id}/resume` | 구독 재개 |

---

### 15. 결제 관리 (Payments) - 7개 API

| 유형 | Method | Endpoint | 설명 |
|------|--------|----------|------|
| LIST | GET | `/v1/payments` | 결제 내역 목록 |
| LIST | GET | `/v1/payments/summary` | 결제 요약 |
| DETAIL | GET | `/v1/payments/{id}` | 결제 상세 |
| CREATE | POST | `/v1/payments` | 결제 처리 |
| ACTION | POST | `/v1/payments/{id}/complete` | 결제 완료 처리 |
| ACTION | POST | `/v1/payments/{id}/cancel` | 결제 취소 |
| ACTION | POST | `/v1/payments/{id}/refund` | 결제 환불 |

---

## 📊 API 통계 요약

| Phase | 카테고리 | API 개수 |
|-------|----------|----------|
| Phase 1 | 휴가 관리 | 11 |
| Phase 1 | 근무/출퇴근 설정 | 10 |
| Phase 1 | 카드/계좌 관리 | 15 |
| Phase 1 | 입금/출금 관리 | 12 |
| Phase 1 | 매출/매입 관리 | 17 |
| Phase 1 | 보고서 | 4 |
| Phase 2 | 전자결재 | 26 |
| Phase 2 | 급여 관리 | 13 |
| Phase 2 | 대시보드 | 3 |
| Phase 3 | AI 리포트 | 4 |
| Phase 3 | 가지급금 | 9 |
| Phase 3 | 바로빌 연동 | 12 |
| Phase 4 | 요금제 관리 | 7 |
| Phase 4 | 구독 관리 | 8 |
| Phase 4 | 결제 관리 | 7 |
| Phase 5 | 사용자 초대 | 5 |
| Phase 5 | 알림 설정 | 3 |
| Phase 5 | 계정 관리 | 4 |
| **Total** | - | **170개** |

---

## 🔗 관련 문서

- [ERP API 개발 계획](../plans/erp-api-development-plan.md)
- [ERP API 상세 스펙](./erp-api-detail.md)
- Swagger UI: http://sam.kr/api-docs/index.html
