크리에이터 마켓플레이스 탐색기·후보군 추천 두 엔드포인트 프론트 연동 가이드

연동 가이드 (프론트엔드)

크리에이터 마켓플레이스의 두 화면(A. 탐색기 / B. 후보군 추천)을 붙일 때 필요한 인증·요청·응답·페이지네이션·mock 동작을 한 곳에 모은 가이드입니다. 각 엔드포인트 상세는 탐색기·후보군 참고.

현재 백엔드는 모든 응답을 mock 으로 내려줍니다. App Review(advanced access) 승인 전까지 마켓 API 가 mock 만 주고, 후보군의 적합도·추천사는 Python 추천기를 호출하지 않습니다(가짜 URL 이라 생성 불가). 응답 mock=true 로 판별. 화면은 mock 으로 100% 구현 가능하며, 승인 후 백엔드만 실데이터로 바뀌고 응답 스키마는 동일합니다.

공통

인증: 어드민 JWT. Authorization: Bearer {admin_access_token}. 비-관리자는 403.
응답 래퍼: ApiResponse — { status, code, message, data }. 실데이터는 data 안에 있습니다.
배열 파라미터: country, interests 는 콤마 구분(country=KR,JP). 백엔드가 메타 JSON 배열로 변환.
페이지네이션: 커서 기반. 페이지당 10건 하드캡. 응답 nextCursor 를 다음 요청 cursor 로 넘기면 다음 페이지. nextCursor=null 이면 끝. → 무한 스크롤 권장(offset 페이지 없음).

A. 탐색기 — `GET .../creators`

검색·필터·열람(데모 이미지1). 카드 그리드 + 상세.

필터: country / minFollowers / maxFollowers / interests / gender / ageBucket / recommendationType / reelsInteractionRate / query
응답 data: { data: 크리에이터[], nextCursor, usagePercent, mock }
크리에이터 1명: username, biography, country, gender, isAccountVerified, ageBucket, profilePictureUrl, onboardedStatus, hasBrandPartnershipExperience, pastBrandPartnershipPartners, insights, recentMedia
카드의 기본 정보(프로필 + 인사이트 스칼라)는 목록 응답으로 바로 렌더. insights 는 메타 응답을 통째로 통과시키므로 구조 변동에 유연.
카드 클릭 상세는 GET .../creators/{id}?username=... 호출 — 리스트에 없는 오디언스 breakdown(연령/성별/지역/팔로우·미디어 유형) + 최근 미디어를 받습니다. 식별키는 IG id(불변, 리스트 응답의 id), username 은 표시용으로 함께 넘김. (리스트 row 경량 유지를 위해 무거운 데이터는 상세에서만)

B. 후보군 추천 — `GET .../candidates`

캠페인 적합도순 후보군(데모 이미지2 표). 탐색기 필터 + collabNo 추가.

응답 data: { data: 후보[], nextCursor, mock }
후보 1행(표 컬럼 매핑):

표 컬럼	응답 필드	mock 여부
순위	`rank`	파생
크리에이터	`username` / `name`, `profilePictureUrl`	실(마켓)
팔로워수	`followerCount`	실(마켓)
평균조회수	`averageViewCount`	mock
랭크	`rankScore`	mock
적합도	`fitScore` (0~100)	mock
카테고리	`categories[]`	mock
추천사	`recommendReason`	mock

정렬은 서버가 적합도순으로 내려줍니다(데모 기본). 체크박스 선택 → "캠페인 제안" 흐름은 FE 처리.

필터 enum 값

필터	형식/예시
`country`	ISO 2자리 대문자. `KR`, `JP`
`minFollowers`/`maxFollowers`	숫자. `min < max`
`interests`	UPPER_SNAKE. 예: `BEAUTY`
`gender`	대문자 enum
`ageBucket`	`18_to_24`, `25_to_34`, … 또는 `65_plus`
`recommendationType`	lower_snake. 예: `high_ad_performance`
`reelsInteractionRate`	`over_3_percent` / `over_5_percent` / `over_10_percent`

형식 위반 시 400 BAD_REQUEST(메타 silent-ignore 방지용 서버 형식 검증). 비즈니스 규칙은 강제하지 않음.

에러 처리

코드	의미	FE 처리
`400 BAD_REQUEST`	필터 형식 오류	입력값 점검 메시지
`403 FORBIDDEN`	관리자 아님	접근 차단
`502 META_UPSTREAM_ERROR`	설정 누락/토큰 만료/메타 호출 실패	재시도 또는 운영 알림

무한 스크롤 예시(개념)

1) GET .../creators?country=KR&minFollowers=10000&maxFollowers=100000
   → data.data(10건) 렌더, data.nextCursor 보관
2) 스크롤 하단 도달 → GET ...&cursor={nextCursor}
3) nextCursor === null 이면 더 호출하지 않음

후보군도 동일(.../candidates?collabNo=...&cursor=...).

기능 노출 / 심사

심사는 test 도메인 + feature flag로 진행(미완성/2번 고도화는 flag 로 가림).
A 탐색기는 마켓 API 를 실제 호출(표준 액세스라 mock 반환)해 권한 사용이 시연됨 → 심사 데모용.
B 후보군은 mock 패스스루(Python 미호출).

승인 후 변경점 (FE 영향 없음)

응답 스키마는 그대로 유지됩니다. 백엔드만:

mock 이 false 로.
후보군 fitScore/recommendReason/averageViewCount 등이 실값으로(기존 Python 추천 계약 vectorize-and-score/influencer-evaluation 연동).

즉 FE 는 지금 mock 스키마로 끝까지 구현해 두면 승인 후 추가 작업이 거의 없습니다.

연동 가이드 (FE)