sam-docs/front/erp-api-list.md

ERP API 목록 (List vs Detail 구분)

작성일: 2025-12-19 기준 문서: 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 개발 계획
• ERP API 상세 스펙
• Swagger UI: http://sam.kr/api-docs/index.html