인스타그램 후보군 추천 (ADMIN)

캠페인에 적합한 마켓 크리에이터를 적합도순 후보군으로 내려줍니다(데모 "인스타그램 후보군" 표). 탐색기와 같은 필터·커서 페이지네이션을 씁니다.

1차는 mock 패스스루입니다. 마켓 API(표준 액세스)에서 받은 mock 프로필을 후보군 형태로 매핑하고, 적합도·추천사·랭크·평균조회수는 mock 값을 채웁니다. 응답 mock=true. App Review 승인 후 기존 Python 추천 계약(추천사 = /api/influence/influencer-evaluation, 적합도 = /api/vector/influencers/vectorize-and-score)으로 교체합니다. (참고: Service/kafka/PythonApiExecutor.java)

HTTP 요청

GET /ai/admin/meta-creator-marketplace/candidates
Authorization: Bearer {admin_access_token}

쿼리 파라미터

탐색기와 동일한 필터에 collabNo 가 추가됩니다. 모두 선택값.

파라미터	타입	예시	설명
`collabNo`	`Long`	`2418`	대상 캠페인. 적합도 컨텍스트(현재 mock 에선 미사용, 승인 후 스코어링에 사용)
`country`	`String`	`KR`	ISO 국가코드(콤마 다중). → `creator_countries`
`minFollowers` / `maxFollowers`	`Long`	`10000`	팔로워 범위(숫자)
`interests`	`String`	`BEAUTY`	관심사 enum(콤마 다중)
`gender` / `ageBucket`	`String`	`FEMALE` / `18_to_24`	성별 / 연령구간
`recommendationType`	`String`	`high_ad_performance`	추천유형
`reelsInteractionRate`	`String`	`over_3_percent`	릴스 응답률 구간
`query`	`String`	`makeup`	키워드
`cursor`	`String`	—	다음 페이지 커서(직전 응답 `nextCursor`)

응답

성공 응답 (200 OK) — mock

{
  "status": 200,
  "code": null,
  "message": "후보군 추천 완료",
  "data": {
    "data": [
      {
        "rank": 1,
        "username": "mocked_username_1",
        "name": "mocked_username_1",
        "profilePictureUrl": "https://...",
        "followerCount": 200000,
        "averageViewCount": 40000,
        "rankScore": 738000,
        "fitScore": 82,
        "categories": ["뷰티"],
        "recommendReason": "스킨케어 릴스의 평균 조회수가 높고, 제품 콘텐츠 성과가 우수합니다."
      }
    ],
    "nextCursor": "QVFIU...",
    "mock": true
  }
}

응답 필드

data 는 { data: 후보[], nextCursor, mock } 구조입니다.

필드	타입	설명	출처
`rank`	`int`	순위(적합도순, 1부터)	파생(정렬)
`username` / `name`	`String`	크리에이터	마켓 원본
`profilePictureUrl`	`String`	프로필 사진	마켓 원본
`followerCount`	`Long`	팔로워수	마켓 원본(total_followers)
`averageViewCount`	`Long`	평균 조회수	mock (승인 후 파생)
`rankScore`	`Long`	랭크 스코어	mock
`fitScore`	`Integer`	적합도 0~100	mock (승인 후 Python `match_score`)
`categories`	`Array`	카테고리(뷰티/일상 등)	mock (승인 후 관심사 매핑)
`recommendReason`	`String`	추천사	mock (승인 후 Python `evaluation`)
`nextCursor`	`String`	다음 페이지 커서(없으면 null)	마켓 paging
`mock`	`Boolean`	mock 여부	—

에러 응답

상태 코드	code	설명
`400`	`BAD_REQUEST`	필터 형식 위반
`403`	`FORBIDDEN`	관리자 권한 없음
`502`	`META_UPSTREAM_ERROR`	설정 누락 / 페이지토큰 추출 실패 / 메타 호출 실패

승인 후 전환 (참고)

App Review 통과 후 mock 컬럼을 실제 값으로 교체:

적합도 ← 대상 캠페인 사전 벡터화(/api/vector/campaigns/vectorize) → vectorize-and-score({account_link, collab_no}) 의 match_score
추천사 ← influencer-evaluation({creator_link, campaign_info, image_analysis}) 의 evaluation
account_link/creator_link 는 마켓 username → https://instagram.com/{username} 합성
미가입 후보는 ApplicationMatching(applicationId 1:1)에 저장 불가 → 응답 즉시 반환 또는 후보군 전용 저장 경로 사용

GET /ai/admin/meta-creator-marketplace/candidates