API 명세서

기준: PRD, User-Flow, Wireframe, Glossary, ERD, Architecture, Dev-Schedule 공통 성공·오류 응답과 페이지 형식: API-Response-Convention 상태: 팀 검토용 v1 API 계약

공통 계약

항목	v1 규칙
경로·본문	기본 경로 /api, JSON UTF-8, 업로드는 multipart/form-data
응답	성공 success=true + data(객체·배열·null), 오류 { "success": false, "error": { "code": "ERROR_CODE", "message": "오류 설명" } }, 생성 201, 그 외 성공 200
인증	보호 API는 Authorization: Bearer {accessToken}, access token 15분, refresh token 30일·HttpOnly; Secure; SameSite=None 쿠키
식별자	경로 ID는 숫자, 당사자 공개 번호 P- + 대문자·숫자 8자, 지원사 공개 번호 S- + 대문자·숫자 8자, 기관 코드 AA-999
날짜·목록	시각 입력은 시간대 포함 ISO 8601, 응답은 UTC ISO 8601, 날짜는 YYYY-MM-DD, 오늘·월별 조회와 배정 기간은 Asia/Seoul 기준
페이지	page 기본 1, pageSize 기본 20·최대 100, 최신순·동률일 때 ID 역순
재시도	배정·도전행동 기록 요청 생성에 Idempotency-Key 필수, 같은 키·본문은 24시간 동안 최초 응답, 같은 키·다른 본문은 409
오류	형식 400, 인증 401, 권한 403, 리소스 404, 충돌 409, 크기 413, 파일 형식 415, 필드 검증 422, 서버 500

역할·관계

주체	열람·작성	관리·제한
주 보호자 GUARDIAN	본인 당사자의 기록·돌봄정보 열람·작성·수정·삭제	당사자 등록·프로필, 기관 연결·이전, 배정 종료, 세컨드 보호자 지정, 수정 제안 승인
세컨드 보호자	당사자별 ACTIVE 상태에서 기록·돌봄정보 열람·작성·수정·삭제	프로필·기관·배정·위임 관계 변경 불가
활동 지원사 SUPPORT_WORKER	유효 배정된 당사자 열람·기록 작성, 본인 기록 수정·삭제	타인 기록은 수정 제안만 가능
기관 INSTITUTION	연결된 당사자 열람·수정 제안·기록 요청·정보 요청 중계	소속 지원사·배정 관리, 생활기록 직접 작성 불가

• 한 보호자의 복수 당사자 등록, 당사자당 기관 한 곳, 같은 기간 복수 지원사 배정 허용
• 세컨드 보호자는 주 보호자가 ACTIVE로 전환한 동안에만 접근 가능

공통 데이터

데이터	필드·값
성별	FEMALE, MALE, NOT_SPECIFIED
장애 유형	INTELLECTUAL, AUTISM, OTHER 복수 선택, OTHER 선택 시 otherDisabilityType 필수
생활기록 분류	COMMUNICATION, LIFESTYLE, MEAL, PREFERENCE, CHALLENGING_BEHAVIOR, HEALTH, EMERGENCY, OTHER
돌봄정보 분류	COMMUNICATION, PREFERENCE, LIFESTYLE, HEALTH_MEDICATION, PRECAUTION, EMERGENCY
기록 응답	id, careRecipientId, author(id/name/role/publicCode), content, category, recordedAt, createdAt, updatedAt, pinned, media[](미디어 응답)
당사자 응답	id, careRecipientNumber, name, birthDate, gender, disabilityTypes, otherDisabilityType, disabilityGrade, latestRecordAt, createdAt
목록 응답	data.items[], data.pagination(page/pageSize/totalItems/totalPages)
필드 표기	필수는 반드시 전송, 선택은 생략 가능, 별도 표기가 없는 수정 요청은 명시한 필드 중 하나 이상 전송
입력 위치	경로 변수는 Endpoint에 표시, GET의 입력은 쿼리, Idempotency-Key는 헤더, 나머지는 JSON 본문
nullable 응답	사용자 phone/publicCode/organization, 당사자 latestRecordAt/gender/otherDisabilityType/disabilityGrade, 배정 endDate/endedAt, 정보 요청 reply, 기록 요청 completedRecordId, 돌봄정보 updatedAt은 값이 없으면 null

인증·내 정보

Method	Endpoint	입력	출력 data·권한
POST	/api/auth/consent	필수 basicInfo=true, sensitiveInfo=true, caregiverShare=true, termsVersion=2026-10-09선택 marketing 기본 false	consentTicket, 30분 유효·1회 사용, 필수 동의 거부·버전 불일치 422
POST	/api/auth/register	필수 name, email, password(10~72자), role, consentTicket지원사 organizationCode 필수, 기관 organizationName 필수	201 로그인 응답이메일 중복 409
POST	/api/auth/google	필수 idToken신규 가입 시 role, consentTicket, 역할별 기관 정보 필수	기존 계정 200 로그인 응답, 신규 계정 201 로그인 응답
POST	/api/auth/login	필수 email, password	로그인 응답, 인증 실패 401
POST	/api/auth/refresh	refresh 쿠키	로그인 응답, 갱신된 refresh 쿠키
POST	/api/auth/logout	refresh 쿠키	loggedOut=true, refresh 쿠키 만료
POST	/api/auth/invitations/accept	필수 invitationToken, 로그인한 보호자 계정	careRecipientId, status=READY, 초대 이메일과 계정 이메일이 달라지면 403
GET	/api/users/me	없음	사용자 응답
PATCH	/api/users/me	name(1~50자), phone(E.164) 중 하나 이상	사용자 응답
PATCH	/api/users/me/password	필수 currentPassword, newPassword(10~72자)	changed=true, 이메일 가입 계정만
DELETE	/api/users/me	없음	deletedAt, 활성 세션 즉시 만료. 보호자가 유일 보호자인 당사자가 있으면 탈퇴 전 이관·삭제 선택 필수(409로 차단) — ADR-012 참고
GET	/api/users/me/notification-settings	없음	알림 설정 응답
PUT	/api/users/me/notification-settings	알림 설정 여섯 boolean 모두 필수, 전체 교체	알림 설정 응답

응답	data 필드
로그인 응답	accessToken, tokenType=Bearer, expiresInSeconds=900, user(id/name/email/role), refresh token은 Set-Cookie 응답 헤더
사용자 응답	id, name, email, role, phone, publicCode, organization(id/name/organizationCode 또는 null)
알림 설정 응답	recordCreated, recordUpdated, assignmentChanged, suggestionReceived, informationRequestReceived, recordRequestReceived, 기본값 모두 true

당사자·기관·돌봄 관계

Method	Endpoint	입력	출력 data·권한
GET	/api/care-recipients	선택 query(이름·공개 번호), page, pageSize	당사자 응답 목록, 접근 가능한 당사자만
POST	/api/care-recipients	필수 name(150자), birthDate(과거 날짜), disabilityTypes(13개)선택 gender, disabilityGrade(최대 20자), OTHER 선택 시 otherDisabilityType(1~50자) 필수	201 당사자 응답, 주 보호자만
GET	/api/care-recipients/{careRecipientId}	없음	당사자 응답
PATCH	/api/care-recipients/{careRecipientId}	당사자 등록 필드 중 하나 이상	당사자 응답, 주 보호자만
GET	/api/organizations/me	없음	id, name, organizationCode, 기관만
GET	/api/organizations/me/members	선택 query(이름·공개 번호), page, pageSize	회원 응답 목록, 기관만
PATCH	/api/organizations/me/members/{memberId}	필수 status=ACTIVE 또는 INACTIVE	회원 응답, 기관만, INACTIVE면 진행 중 배정 종료
POST	/api/organizations/me/recipient-links	필수 careRecipientNumber	201 기관 연결 요청 응답, status=PENDING, 기관만, 이미 연결됐으면 409
GET	/api/organizations/me/link-requests	선택 status, page, pageSize	기관 연결 요청 응답 목록, 기관만
GET	/api/care-recipients/{careRecipientId}/organization-link-requests	선택 status	기관 연결 요청 응답 배열, 주 보호자만
POST	/api/care-recipients/{careRecipientId}/organization-link-requests/{requestId}/accept	없음	기관 연결 요청 응답, status=ACCEPTED, 주 보호자만
POST	/api/care-recipients/{careRecipientId}/organization-link-requests/{requestId}/reject	없음	기관 연결 요청 응답, status=REJECTED, 주 보호자만
DELETE	/api/care-recipients/{careRecipientId}/organization-link-requests/{linkId}	없음	unlinked=true, 주 보호자만, 연결 해제 시 해당 기관 지원사 배정 전체 종료·미완료 정보 요청 CLOSED·기록 요청 CANCELLED
POST	/api/care-recipients/{careRecipientId}/institution-transfer	필수 organizationCode	careRecipientId, organization(id/name/organizationCode), 주 보호자만, 기존 배정 종료
GET	/api/care-recipients/{careRecipientId}/assignments	선택 activeOnly, page, pageSize	배정 응답 목록
POST	/api/organizations/me/assignments	필수 Idempotency-Key, careRecipientId, supportWorkerId, startDate선택 endDate, notify 기본 true	201 배정 응답, 기관만, 기간 중복 409
PATCH	/api/care-assignments/{assignmentId}	필수 endDate(날짜 또는 null)	배정 응답, 기관만
DELETE	/api/care-assignments/{assignmentId}	없음	배정 응답, 기관·주 보호자만, 중복 종료 409
GET	/api/care-recipients/{careRecipientId}/secondary-guardian	없음	세컨드 보호자 응답 또는 null, 주 보호자만
PUT	/api/care-recipients/{careRecipientId}/secondary-guardian	필수 name, email, phone	세컨드 보호자 응답, status=INVITED, 주 보호자만
PATCH	/api/care-recipients/{careRecipientId}/secondary-guardian	필수 active boolean	세컨드 보호자 응답, READY ↔ ACTIVE, 주 보호자만
DELETE	/api/care-recipients/{careRecipientId}/secondary-guardian	없음	revoked=true, 주 보호자만

응답	data 필드
회원 응답	id, name, publicCode, status, assignedRecipientCount
기관 연결 요청 응답	id, careRecipientId, organization(id/name/organizationCode), status
배정 응답	id, careRecipientId, supportWorker(id/name/publicCode), organization(id/name/organizationCode), startDate, endDate, endedAt
세컨드 보호자 응답	name, email, phone, status(INVITED/READY/ACTIVE), expiresAt
기관 연결 상태	PENDING, ACCEPTED, REJECTED

• 배정·기관 연결 종료 시 해당 지원사의 당사자 접근 회수
• 배정·기관 연결 종료 시 미완료 기록 요청 CANCELLED
• 기관 이전 시 미완료 정보 요청 CLOSED, 기록 요청 CANCELLED

생활기록·수정 제안

Method	Endpoint	입력	출력 data·권한
GET	/api/care-recipients/{careRecipientId}/records	선택 date 또는 year+month, page, pageSize	기록 응답 목록, 삭제 기록 제외, 날짜 필터 동시 사용 불가
GET	/api/care-recipients/{careRecipientId}/records/today	없음	오늘 기록 응답 배열
POST	/api/care-recipients/{careRecipientId}/records	필수 content(trim 후 1~500자), category, recordedAt선택 mediaIds(최대 5개), recordRequestId, pinned 기본 false	201 기록 응답, 보호자·활성 세컨드 보호자·배정 지원사만, pinned=true는 보호자·활성 세컨드 보호자만
GET	/api/care-recipients/{careRecipientId}/records/{recordId}	없음	기록 응답
PATCH	/api/care-recipients/{careRecipientId}/records/{recordId}	content, category, recordedAt, mediaIds 중 하나 이상mediaIds는 첨부 전체 교체	기록 응답, 보호자 또는 배정 중인 작성 지원사만
DELETE	/api/care-recipients/{careRecipientId}/records/{recordId}	없음	deletedAt, restoreUntil, 작성자·보호자만
POST	/api/care-recipients/{careRecipientId}/records/{recordId}/restore	없음	기록 응답, 삭제 후 30일 이내·삭제 권한자만
GET	/api/care-recipients/{careRecipientId}/records/{recordId}/revisions	선택 page, pageSize	수정 이력 응답 목록
PATCH	/api/care-recipients/{careRecipientId}/records/{recordId}/pin	필수 pinned boolean	기록 응답, 보호자·활성 세컨드 보호자만
POST	/api/care-recipients/{careRecipientId}/records/{recordId}/suggestions	필수 content, 선택 category, reason	201 수정 제안 응답, status=PENDING, 지원사·기관만
GET	/api/care-recipients/{careRecipientId}/record-suggestions	선택 status 기본 PENDING, page, pageSize	수정 제안 응답 목록, 보호자·활성 세컨드 보호자만
GET	/api/record-suggestions/mine	선택 careRecipientId, status, page, pageSize	수정 제안 응답 목록, 지원사만 (본인이 제출한 제안 이력)
POST	/api/care-recipients/{careRecipientId}/record-suggestions/{suggestionId}/decision	필수 decision=APPROVE 또는 REJECT	수정 제안 응답, status=APPROVED/REJECTED, 원본 변경 시 409
POST	/api/care-recipients/{careRecipientId}/records/{recordId}/forward-to-guardian	없음	recordId, forwardedAt, notificationId, 기관만, 도전행동 기록만, 중복 전달 409

응답	data 필드
수정 이력 응답	revision, changedBy(id/name/role), changedAt, content, category, recordedAt
수정 제안 응답	id, recordId, original(content/category), proposed(content/category), reason(없으면 null), suggestedBy(id/name/role), status, createdAt
수정 제안 상태	PENDING, APPROVED, REJECTED

• recordRequestId를 사용한 기록은 해당 당사자·지원사·OPEN 요청과 일치하고 category=CHALLENGING_BEHAVIOR 필수, 저장 시 요청 COMPLETED
• 수정 제안 승인 시 기록 갱신·수정 이력 추가
• 도전행동 기록은 생성 즉시 보호자에게 조회 가능, 기관의 전달 호출은 보호자에게 알림 생성

돌봄정보·미디어·AI

Method	Endpoint	입력	출력 data·권한
GET	/api/care-recipients/{careRecipientId}/care-info	없음	categories[](6개 돌봄정보 응답), pinnedRecords[](기록 응답)
GET	/api/care-recipients/{careRecipientId}/care-info/{category}	경로 category	돌봄정보 응답
PUT	/api/care-recipients/{careRecipientId}/care-info/{category}	필수 content(0~3000자, 빈 문자열로 비우기)	돌봄정보 응답, 보호자·활성 세컨드 보호자만
POST	/api/care-recipients/{careRecipientId}/media	필수 file, JPEG/PNG/WebP/MP4/MP3/M4A/WAV/WebM, 최대 50MB	201 미디어 응답, 기록 작성 권한자만
GET	/api/care-recipients/{careRecipientId}/media/{mediaId}/download-url	없음	url, expiresAt, 당사자 접근 권한 필요
DELETE	/api/care-recipients/{careRecipientId}/media/{mediaId}	없음	deleted=true, 미연결 파일은 업로더·연결 파일은 기록 수정 권한자만
POST	/api/ai/record-drafts	필수 careRecipientId, inputType=TEXT + text(1~3000자) 또는 inputType=AUDIO + mediaId(최대 10분)	transcript, content, category, 기록은 생성되지 않음

응답	data 필드
돌봄정보 응답	category, content, updatedAt, 미작성 내용은 빈 문자열
미디어 응답	mediaId, fileName, mediaType, sizeBytes

• 미디어는 같은 당사자의 기록에만 연결 가능, 기록당 최대 5개
• 다운로드 URL 유효 기간 5분

요청·알림·접근 이력

Method	Endpoint	입력	출력 data·권한
POST	/api/care-recipients/{careRecipientId}/information-requests	필수 message(1~1000자)	201 정보 요청 응답, status=SUBMITTED, 배정 지원사만
GET	/api/information-requests	선택 status, page, pageSize	정보 요청 응답 목록, 요청한 지원사만
GET	/api/organizations/me/information-requests	선택 status, page, pageSize	정보 요청 응답 목록, 기관만
POST	/api/organizations/me/information-requests/{requestId}/forward	없음	정보 요청 응답, status=FORWARDED, 기관만
GET	/api/care-recipients/{careRecipientId}/information-requests	선택 status, page, pageSize	정보 요청 응답 목록, 보호자·활성 세컨드 보호자만
POST	/api/care-recipients/{careRecipientId}/information-requests/{requestId}/reply	필수 message(1~1000자)	정보 요청 응답, status=ANSWERED, 보호자·활성 세컨드 보호자만
POST	/api/organizations/me/information-requests/{requestId}/close	없음	정보 요청 응답, status=CLOSED, 기관만
POST	/api/care-recipients/{careRecipientId}/record-requests	필수 Idempotency-Key, supportWorkerId선택 message(최대 1000자)	201 기록 요청 응답, status=OPEN, 기관만, 유효 배정이 없으면 409
GET	/api/care-recipients/{careRecipientId}/record-requests	선택 status, page, pageSize	기록 요청 응답 목록, 기관만
GET	/api/record-requests	선택 status, page, pageSize	기록 요청 응답 목록, 수신 지원사만
POST	/api/record-requests/{requestId}/cancel	없음	기록 요청 응답, status=CANCELLED, 요청 기관만·OPEN 상태만
GET	/api/notifications	선택 read, page, pageSize	알림 응답 목록, 본인만
GET	/api/notifications/unread-count	없음	count (미확인 알림 수 정수), 본인만
PATCH	/api/notifications/{notificationId}	필수 read boolean	알림 응답, 본인만
GET	/api/care-recipients/{careRecipientId}/access-logs	선택 page, pageSize	접근 이력 응답 목록, 보호자·활성 세컨드 보호자만

응답	data 필드
정보 요청 응답	id, careRecipientId, requestedBy(id/name/role), message, status, reply, createdAt, updatedAt
기록 요청 응답	id, careRecipientId, supportWorker(id/name/publicCode), requestedBy(id/name/role), message, status, completedRecordId, createdAt
알림 응답	id, type, message, read, createdAt
접근 이력 응답	actor(id/name/role), action, resourceType, resourceId, occurredAt
정보 요청 상태	SUBMITTED, FORWARDED, ANSWERED, CLOSED
기록 요청 상태	OPEN, COMPLETED, CANCELLED
알림 유형	RECORD_CREATED, RECORD_UPDATED, ASSIGNMENT_CHANGED, SUGGESTION_RECEIVED, SUGGESTION_DECIDED, INFORMATION_REQUEST_RECEIVED, INFORMATION_REQUEST_REPLIED, RECORD_REQUEST_RECEIVED, RECORD_REQUEST_COMPLETED, RECORD_FORWARDED, ORGANIZATION_LINK_REQUESTED, ORGANIZATION_LINK_ACCEPTED, ORGANIZATION_LINK_REJECTED
접근 동작	READ, CREATE, UPDATE, DELETE

• 정보 요청 상태 SUBMITTED → FORWARDED → ANSWERED → CLOSED
• 응답 기록 저장 시 해당 기록 요청 COMPLETED

어드민

모든 엔드포인트는 ADMIN 역할 전용. 일반 사용자 접근 시 403.

Method	Endpoint	입력	출력 data
GET	/api/admin/stats	없음	totalUsers, guardians, supportWorkers, institutions, totalOrganizations, totalCareRecipients, totalRecords
GET	/api/admin/users	선택 role, organizationId, page, size	사용자 요약 응답 목록
POST	/api/admin/users	필수 name, email, password(6자 이상), role선택 phone, organizationId	201 사용자 요약 응답
PATCH	/api/admin/users/{id}	필수 name, email, role선택 phone, organizationId	사용자 요약 응답
DELETE	/api/admin/users/{id}	없음	null (204), 본인 계정 삭제 불가
GET	/api/admin/users/{id}/records	없음	기록 요약 응답 목록
GET	/api/admin/organizations	없음	기관 어드민 응답 목록
POST	/api/admin/organizations	필수 name선택 ownerId	201 기관 어드민 응답, 6자리 organizationCode 자동 발급
PATCH	/api/admin/organizations/{id}	필수 name	기관 어드민 응답
DELETE	/api/admin/organizations/{id}	없음	null (204)
GET	/api/admin/organizations/{id}/records	없음	기록 요약 응답 목록
GET	/api/admin/care-recipients	선택 search(이름·공개 번호)	당사자 어드민 응답 목록
POST	/api/admin/care-recipients	필수 name(150자), birthDate, disabilityTypes(13개)선택 gender, disabilityGrade, otherDisabilityType, guardianId	201 당사자 어드민 응답, careRecipientNumber 자동 발급

응답	data 필드
사용자 요약 응답	id, name, email, role, phone, publicCode, organizationId
기관 어드민 응답	id, name, organizationCode, ownerId, ownerName, createdAt
당사자 어드민 응답	id, careRecipientNumber, name, birthDate, gender, disabilityTypes, disabilityGrade, otherDisabilityType, guardianName, guardianEmail, organizationName, createdAt
기록 요약 응답	(AdminRecordSummaryResponse — 상세 필드는 Swagger 참고)

• careRecipientNumber(P-XXXXXXXX)는 어드민 또는 보호자 직접 등록 시 자동 발급. 기관이 연결 요청(POST /api/organizations/me/recipient-links) 시 이 번호를 보호자로부터 전달받아 입력함.

---

변경 이력

날짜	내용	작성자
2026-10-08	최초 API 경로·응답 초안
2026-10-09	PRD·User-Flow·Wireframe 기준 API v1 입력·출력 계약 정리	Codex
2026-10-22	누락 엔드포인트 5개 추가, 어드민 섹션 추가, 알림 타입 3개 추가(INFORMATION_REQUEST_REPLIED, RECORD_REQUEST_COMPLETED, ORGANIZATION_LINK_ACCEPTED/REJECTED), DELETE .../organization-link-requests/{linkId} 사이드이펙트 보완, GET /api/record-suggestions/mine careRecipientId 필터 추가	Claude Code