09 API Specification

API 카탈로그

한눈에 보기

2026-07-21 기준 FOWOCO 서버 API는 총 42개입니다.

구분	수
구현됨	1 — GET /health
계획됨	41
P0	34
P1	8

이 페이지는 누구나 범위와 담당 Issue를 찾기 위한 공개 요약입니다. 상세 요청·응답 DTO와 화면 기준은 Notion API 명세와 Figma를 확인합니다.

무엇을 최종 기준으로 보나요?

1. 기획 중인 계약과 화면 요구는 Notion·Figma를 봅니다.
2. 구현된 요청·응답 계약은 배포된 Swagger/OpenAPI를 봅니다.
3. 실제 보안·상태 규칙은 코드와 자동 테스트가 최종 기준입니다.
4. 셋이 다르면 임의로 맞추지 말고 Issue를 만들어 함께 수정합니다.

GitHub Issue의 우선순위는 여러 API를 묶은 작업의 가장 높은 우선순위입니다. API별 P0/P1 값은 Notion에서 확인합니다.

운영·인증 5개

API	사용자가 얻는 것	접근	소유 Issue	상태
GET /health	서버 최소 상태 확인	공개	#3	구현됨
POST /auth/login	Access·Refresh 세션 시작	공개	#4	계획
POST /auth/refresh	Access Token 재발급	Refresh 세션	#4	계획
POST /auth/logout	Refresh Token 폐기	로그인	#4	계획
GET /auth/me	내 사용자·사업장·역할 확인	로그인	#4	계획

근로자 4개

API	사용자가 얻는 것	접근	소유 Issue	상태
GET /workers	근로자 검색·목록	HR·ADMIN·VIEWER	#5	계획
POST /workers	근로자 등록	HR·ADMIN	#5	계획
GET /workers/{workerId}	근로자 상세	HR·ADMIN·VIEWER	#5	계획
PATCH /workers/{workerId}	근로자 정보 수정	HR·ADMIN	#5	계획

문서·파일 6개

API	사용자가 얻는 것	접근	소유 Issue	상태
POST /workers/{workerId}/documents	근로자 서류 상태 추가	HR·ADMIN	#5	계획
PATCH /workers/{workerId}/documents/{documentId}	서류 상태 수정	HR·ADMIN	#5	계획
POST /files	검증된 파일 ID 생성	HR·ADMIN	#13	계획
GET /documents	사업장 통합 문서함	로그인 역할별	#13	계획
GET /tasks/{taskId}/document-readiness	업무에 필요한 서류 준비도	로그인 역할별	#13	계획
PUT /tasks/{taskId}/document-request-draft	근로자 서류 요청 초안 저장	HR·ADMIN	#13	계획

업무카드·승인 11개

API	사용자가 얻는 것	접근	소유 Issue	상태
GET /tasks	업무카드 목록	로그인 역할별	#6	계획
POST /tasks	수동 업무카드 생성	HR·ADMIN	#6	계획
GET /tasks/{taskId}	업무 상세	로그인 역할별	#6	계획
PATCH /tasks/{taskId}	승인 전 허용 필드 수정	HR·ADMIN	#6	계획
PATCH /tasks/{taskId}/checklist-items/{itemId}	체크리스트 상태 변경	HR·ADMIN	#6	계획
POST /tasks/{taskId}/approval-requests	검토·승인 요청	HR·ADMIN	#11	계획
POST /tasks/{taskId}/approve	HR 승인 기록	HR·ADMIN	#11	계획
POST /tasks/{taskId}/reject	반려 사유 기록	HR·ADMIN	#11	계획
POST /tasks/{taskId}/evidence	완료 증빙 연결	HR·ADMIN	#11	계획
POST /tasks/{taskId}/complete	완료 조건 검사 후 완료	HR·ADMIN	#11	계획
GET /tasks/{taskId}/activities	업무 행동 이력 조회	로그인 역할별	#11	계획

AI 분석 2개

API	사용자가 얻는 것	접근	소유 Issue	상태
POST /tasks/analyze	자연어에서 검토할 후보 생성	HR·ADMIN	#8	계획
POST /task-analyses/{analysisId}/confirm	선택 후보만 실제 Task로 확정	HR·ADMIN	#8	계획

AI 분석 후보는 실제 업무가 아닙니다. confirm 뒤에도 Task는 승인 전 상태이며 자동 발송되지 않습니다.

근로자 보안 링크 3개

API	사용자가 얻는 것	접근	소유 Issue	상태
POST /tasks/{taskId}/worker-link	승인된 업무 링크 발급·회전	HR·ADMIN	#7	계획
GET /public/worker-links/{token}	최소 안내 확인	유효한 링크	#7	계획
POST /public/worker-links/{token}/responses	확인·질문·이해 안 됨·파일 제출	유효한 링크	#7	계획

재발급은 별도 endpoint가 아니라 발급 요청의 rotateExisting 정책으로 처리하고 이전 링크를 즉시 폐기합니다.

Workflow Catalog 1개

API	사용자가 얻는 것	접근	소유 Issue	상태
GET /workflow-catalogs	업무 유형별 필수정보·체크리스트·완료 조건	로그인	#6	계획

파일 가져오기 7개

API	사용자가 얻는 것	접근	소유 Issue	상태
POST /imports	CSV/XLSX 가져오기 작업 생성	HR·ADMIN	#14	계획
GET /imports/{importId}	진행 상태·행 오류 조회	HR·ADMIN	#14	계획
PUT /imports/{importId}/mappings	업로드 열과 시스템 필드 연결	HR·ADMIN	#14	계획
POST /imports/{importId}/validate	행별 형식·필수값·중복 검증	HR·ADMIN	#14	계획
PATCH /imports/{importId}/rows	오류 행 수정·제외 선택	HR·ADMIN	#14	계획
POST /imports/{importId}/commit	선택한 정상 행만 등록	HR·ADMIN	#14	계획
POST /imports/{importId}/retry	실패 행 재검증·재처리	HR·ADMIN	#14	계획

대시보드·설정 3개

API	사용자가 얻는 것	접근	소유 Issue	상태
GET /dashboard/today	오늘 할 일·만료 임박·대기 요약	로그인 역할별	#15	계획
GET /settings	사업장 운영 설정 확인	로그인 역할별	#16	계획
PATCH /settings	허용된 사업장 설정 수정	ADMIN·일부 HR	#16	계획

모든 API의 공통 규칙

• 인증 API와 공개 링크를 제외하면 JWT 인증이 필요합니다.
• 클라이언트가 보낸 company_id가 아니라 인증 Context의 사업장으로 범위를 제한합니다.
• 권한 부족은 403, 인증 실패는 401로 일관되게 처리합니다.
• 오류 응답에 request_id, 오류 코드, 사용자용 설명을 포함합니다.
• 날짜·시간대, 페이지네이션, Enum, Idempotency 규칙을 Swagger에 적습니다.
• 실제 개인정보, 토큰, Secret, 전체 외부 LLM 응답은 로그에 남기지 않습니다.
• 변경 API는 actor와 AuditLog를 기록합니다.
• AI 결과와 요청 초안은 HR 승인 전에 외부 발송할 수 없습니다.

API 하나를 구현할 때

1. 표에서 소유 Issue를 엽니다.
2. Notion에서 요청·응답·우선순위·Figma 화면을 확인합니다.
3. Request/Response DTO와 오류 케이스를 먼저 적습니다.
4. Service에서 권한·사업장·상태 규칙을 구현합니다.
5. Repository·migration을 추가합니다.
6. 정상·검증 실패·권한 부족·타 사업장 테스트를 작성합니다.
7. Swagger 예시와 Wiki를 갱신합니다.
8. PR에서 소유 Issue를 닫고 Project 상태를 맞춥니다.

관련 링크

• MVP Epic #2
• M3 Milestone
• M4 Milestone
• Server Roadmap · 팀원 전용
• 개발 시작 안내 Discussion
• M3 범위 Discussion