09 API Specification

API 카탈로그

한눈에 보기

2026-07-21 계약 기준 FOWOCO Server API는 총 46개입니다.

구분	수
구현됨	1 — GET /health
계획됨	45
M3 / P0	32
M4 / P1	14

기존 42개에서 비동기 AI Run, Worker Link 문서 제출, 전역 감사 조회를 반영해 46개가 됐습니다. Import 7개는 대표 M3 시나리오의 선행 조건이 아니므로 P1/M4로 이동했습니다.

상세 Request/Response·화면 기준은 Notion API 명세와 Figma를 봅니다. 구현된 계약의 최종 기준은 배포 Swagger/OpenAPI와 자동 test입니다.

경로 표기 규칙

• 이 표는 deployment base URL을 제외한 resource path를 기록합니다.
• gateway가 /api prefix를 사용하면 base URL에서 한 번만 붙입니다.
• /api/tasks와 /tasks를 서로 다른 API처럼 혼용하지 않습니다.
• 공개 Worker Link는 /public/worker-links/...로 명확히 구분합니다.

중복 계약을 없앤 결정

• POST /tasks/analyze와 /task-analyses/{id}/confirm은 구현하지 않습니다.
• AI 분석은 /ai-runs의 생성·조회·재시도·confirm 4개로 교체합니다.
• GET /tasks/{taskId}/activities가 화면용 timeline의 canonical API입니다. /timeline을 따로 만들지 않습니다.
• 근로자 문서는 token 전용 /public/worker-links/{token}/documents로 먼저 받고 response는 검증된 ID를 참조합니다.
• GET /audit-events는 사업장 전체 감사 검색, activities는 한 Task의 안전한 화면 이력입니다.

운영·인증 5개

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

근로자 4개

API	사용자가 얻는 것	접근	소유 Issue	상태
GET /workers	검색·filter·page 목록	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	문서 metadata 추가	HR·ADMIN	#5	계획
PATCH /workers/{workerId}/documents/{documentId}	상태·만료일 수정	HR·ADMIN	#5	계획
POST /files	검증된 file ID 생성	HR·ADMIN	#13	계획
GET /documents	사업장 통합 문서함	로그인 Role별	#13	계획
GET /tasks/{taskId}/document-readiness	Task별 준비·누락·만료 상태	로그인 Role별	#13	계획
PUT /tasks/{taskId}/document-request-draft	승인 전 요청 초안 저장	HR·ADMIN	#13	계획

Task·승인·감사 12개

API	사용자가 얻는 것	접근	소유 Issue	상태
GET /tasks	Task 목록·filter·page	로그인 Role별	#6	계획
POST /tasks	수동 Task 생성	HR·ADMIN	#6	계획
GET /tasks/{taskId}	Task 상세	로그인 Role별	#6	계획
PATCH /tasks/{taskId}	허용 field 수정·version 검사	HR·ADMIN	#6	계획
PATCH /tasks/{taskId}/checklist-items/{itemId}	checklist 변경	HR·ADMIN	#6	계획
POST /tasks/{taskId}/approval-requests	사람 검토 요청	HR·ADMIN	#11	계획
POST /tasks/{taskId}/approve	snapshot/version 승인	HR·ADMIN	#11	계획
POST /tasks/{taskId}/reject	반려 사유 기록	HR·ADMIN	#11	계획
POST /tasks/{taskId}/evidence	완료 증빙 연결	HR·ADMIN	#11	계획
POST /tasks/{taskId}/complete	guard 통과 후 완료	HR·ADMIN	#11	계획
GET /tasks/{taskId}/activities	한 Task의 timeline	로그인 Role별	#11	계획
GET /audit-events	사업장 감사 event 검색	ADMIN	#11	계획

Approval은 AI 원본, HR 수정본, changed fields, approver, 승인 시각·version·reason을 저장합니다. 날짜·금액·대상·문서·안내 내용 변경 뒤에는 재승인이 필요합니다.

비동기 AI Run 4개

API	사용자가 얻는 것	접근	소유 Issue	상태
POST /ai-runs	Run 생성, 202 + runId + statusUrl	HR·ADMIN	#24	계획
GET /ai-runs/{runId}	상태·후보·검증·version·error 조회	HR·ADMIN	#24	계획
POST /ai-runs/{runId}/retry	재시도 가능한 실패 재실행	HR·ADMIN	#24	계획
POST /ai-runs/{runId}/confirm	선택 후보만 Task로 확정	HR·ADMIN	#24	계획

상태는 QUEUED, RUNNING, VALIDATING, NEEDS_REVIEW, SUCCEEDED, RETRYING, FAILED입니다. 생성·retry·confirm에는 Idempotency-Key와 version 충돌 정책을 적용합니다.

근로자 보안 링크 4개

API	사용자가 얻는 것	접근	소유 Issue	상태
POST /tasks/{taskId}/worker-link	승인된 Task link 발급·rotation	HR·ADMIN	#7	계획
GET /public/worker-links/{token}	최소 안내·허용 행동 조회	Worker Link	#7	계획
POST /public/worker-links/{token}/documents	요청 문서 격리 제출	Worker Link	#7	계획
POST /public/worker-links/{token}/responses	확인·질문·이해 안 됨 제출	Worker Link	#7	계획

재발급은 별도 endpoint 대신 발급 요청의 rotateExisting=true를 사용하고 이전 link를 즉시 폐기합니다. Token 원문은 DB·log·metric에 남기지 않습니다.

Workflow Catalog 1개

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

Import 7개 · M4/P1

API	사용자가 얻는 것	접근	소유 Issue	상태
POST /imports	CSV/XLSX ImportJob 생성	HR·ADMIN	#14	계획
GET /imports/{importId}	진행 상태·행 오류 조회	HR·ADMIN	#14	계획
PUT /imports/{importId}/mappings	열과 system field 연결	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	계획

Dashboard·Settings 3개 · M4/P1

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

공통 응답·오류 규칙

• 공개 endpoint를 제외하면 JWT 또는 명시된 Worker Link Token이 필요합니다.
• tenant는 인증 Context에서 결정합니다.
• 400 validation, 401 인증, 403 권한, 404 resource/token 정책, 409 version/idempotency 충돌, 422 업무 규칙, 429 제한을 일관되게 사용합니다.
• 오류에는 안전한 request_id, code, 사용자용 message, 필요한 field error만 포함합니다.
• AI Provider 전문·stack trace·Secret·개인정보는 응답하지 않습니다.
• 시간은 UTC ISO-8601, page는 cursor 또는 명시된 page 규칙, enum은 Swagger에 모두 적습니다.
• 변경 command는 actor·AuditEvent를 기록하고 핵심 event는 재처리 가능하게 publication합니다.
• POST /ai-runs, retry, confirm, link rotation, response/upload, import commit은 멱등성 정책을 명시합니다.

AI Run 응답에서 확인할 field

• runId, status, validationStatus, result 또는 review reason
• agent/model/prompt/context/workflow version
• inputHash, latencyMs, retryCount, errorCode
• requestId, traceId, 생성·시작·완료 시각

민감 원문 대신 hash·reference·마스킹 요약을 사용합니다.

API 하나를 구현할 때

1. 이 표에서 소유 Issue와 선행 관계를 확인합니다.
2. Notion의 DTO·우선순위와 Figma 흐름을 확인합니다.
3. Request/Response·오류·Role·상태·멱등성 계약을 먼저 작성합니다.
4. Application/Workflow Service에 tenant·guard를 구현합니다.
5. Flyway migration과 Repository를 추가합니다.
6. 정상·validation·권한·타 사업장·중복·동시성 test를 작성합니다.
7. Swagger와 Wiki/Notion을 같은 PR/작업에서 갱신합니다.
8. PR에서 Issue를 연결하고 Project Status를 맞춥니다.

관련 링크

• MVP Epic #2
• Architecture ADR #23
• Server Roadmap
• 개발 시작 Discussion