데모(목업) 후보 벌크 링크 등록

크리에이터 링크를 벌크로 넣으면, 각 링크마다 데모 후보 행을 즉시 만들고 프로필·팔로워·카테고리·적합도(matchScore)·추천사(recommendReason)를 백그라운드로 자동 채웁니다. 수기 등록처럼 값을 손으로 넣지 않아도 됩니다.

개념·렌더 규칙·ID 규칙은 데모(목업) 후보 연동 가이드를 참고하세요.

지원 플랫폼

인스타그램과 틱톡을 지원합니다. 플랫폼은 요청의 platform 값으로 정하는 것을 권장하며, 생략하면 링크 모양으로 판별합니다.

권장 — `platform` 을 명시

platform 을 주면 목록 전체를 그 플랫폼으로 처리합니다. URL 이 아닌 순수 핸들(@khaby.lame)도 그 플랫폼으로 등록되므로, 어드민이 링크를 못 구한 경우에도 넣을 수 있습니다.

{
  "platform": "TIKTOK",
  "instagramLinks": ["@khaby.lame", "https://www.tiktok.com/@zachking"]
}

입력 형태는 아래를 모두 받습니다. 앞뒤 공백·대소문자·쿼리스트링·trailing slash 는 서버가 정리합니다.

플랫폼	받는 형태
인스타그램	`https://www.instagram.com/somoon_smm/` · `@somoon_smm` · `somoon_smm`
틱톡	`https://www.tiktok.com/@khaby.lame` · `m.tiktok.com` 링크 · 비디오 링크 · `@khaby.lame` · `khaby.lame`

다른 플랫폼 주소를 붙여넣으면 등록하지 않고 invalid 로 셉니다. 예를 들어 platform: "TIKTOK" 인데 인스타그램 URL 이나 유튜브 링크가 섞이면 그 줄만 건너뜁니다. 잘못 등록되면 유료 크롤이 발생하고, 같은 링크 재등록은 중복 스킵이라 삭제 후 재등록 말고는 되돌릴 방법이 없기 때문입니다.

platform 에 INSTAGRAM·TIKTOK 이 아닌 값을 주면 400 으로 거절합니다(오타를 조용히 인스타그램으로 처리하지 않습니다).

생략했을 때 (하위호환)

platform 이 없으면 링크 모양으로 건건이 판별하고, 인스타그램과 틱톡을 섞어 보낼 수 있습니다. 이때 URL 이 아닌 순수 핸들은 인스타그램으로 봅니다.

틱톡은 크롤러가 reelsAvgViews를 채우지 않고 avgViews에만 값을 넣습니다. 그래서 응답의 평균 조회수와 예상가는 avgViews 기준으로 산정됩니다. 또 틱톡 수집 경로에는 강제 재크롤이 없어 forceCrawl은 인스타그램에만 적용됩니다.

동작 방식 (중요 — 동기 응답이 아닙니다)

이 API는 두 단계로 나뉩니다.

즉시(동기): 링크마다 데모 후보 셸 행을 만들어 createdDisplayIds로 바로 돌려줍니다. 이 시점엔 accountLink·username만 채워져 있고 나머지는 null입니다.
백그라운드(비동기): 크롤 → 프로필·게시물 리드백 → 적합도(matchScore) → 추천사(recommendReason) 순서로 채워집니다. 한 건당 수십 초 걸릴 수 있습니다.

따라서 응답을 받은 뒤 진행테이블/리스트 조회를 폴링하면 값이 null에서 실제 값으로 차오르는 것을 볼 수 있습니다. matchScore와 recommendReason이 모두 채워지면 그 후보의 채움이 완료된 것입니다.

HTTP 요청

POST /ai/admin/dashboard/{campaignNo}/demo-applicants/bulk-links
Authorization: Bearer {access_token}
Content-Type: application/json

Path Parameters

파라미터	타입	필수	설명
`campaignNo`	`Long`	예	캠페인 번호

Request Body

{
  "platform": "INSTAGRAM",
  "instagramLinks": [
    "https://www.instagram.com/somoon_smm/",
    "@jay.pm.ai",
    "example_handle"
  ],
  "forceCrawl": false
}

틱톡이면 platform 만 바꾸면 됩니다. 링크와 순수 핸들을 섞어도 됩니다.

{
  "platform": "TIKTOK",
  "instagramLinks": [
    "https://www.tiktok.com/@khaby.lame",
    "@zachking"
  ]
}

필드	타입	필수	설명
`instagramLinks`	`String[]`	예	크리에이터 링크 목록. URL·`@handle`·`handle` 모두 지원. 최대 30개.
`platform`	`String`	아니오	`INSTAGRAM` \| `TIKTOK`. 지정하면 목록 전체를 그 플랫폼으로 처리합니다. 생략하면 링크 모양으로 판별합니다. 다른 값이면 400.
`forceCrawl`	`Boolean`	아니오	`true`면 3일 이내 크롤 캐시가 있어도 강제 재크롤(유료). 기본 `false`.

링크는 서버가 정규화합니다. @ 제거·소문자화·쿼리스트링/슬래시 제거 후 첫 경로 세그먼트를 핸들로 뽑아 https://www.instagram.com/{handle} 형태로 저장합니다. 같은 계정을 형식만 달리해 중복 입력하면 하나로 수렴합니다.

응답

성공 응답 (200 OK)

{
  "status": 200,
  "message": "2건 생성, 채움 발사 2건",
  "data": {
    "createdDisplayIds": [100000123, 100000124],
    "invalid": 0,
    "duplicateSkipped": 1,
    "enqueued": 2
  }
}

필드	타입	설명
`createdDisplayIds`	`Long[]`	생성된 데모 후보의 응답용 ID 목록. `dummyItems[].applicationId`와 같은 값
`invalid`	`int`	링크로 인식되지 않아 건너뛴 수(인스타 예약 경로 `p/reel/stories/...`, 틱톡 프로필이 아닌 링크 포함)
`duplicateSkipped`	`int`	이미 담긴 계정이라 건너뛴 수
`enqueued`	`int`	백그라운드 채움 파이프라인에 실제로 실린 수

무엇이 채워지나

필드	소스	비고
`followerCount`·`reelsAvgViews`·`categoryTags`·최근 게시물	크롤 + 프로필/게시물 리드백
`matchScore` (적합도)	`vectorize-and-score`	데모 대시보드 점수는 이 값입니다(`fitScore` 아님)
`recommendReason` (추천사)	`influencer-evaluation`	캠페인에 상품 상세(image_analysis)가 있을 때만

추천사는 원래 "적합/부적합 스크리닝 평가"입니다. 캠페인과 결이 맞지 않는 크리에이터에는 "적합하지 않다 / 연관성이 낮다"류 문장이 나올 수 있습니다(의도된 정상 동작). 쇼케이스 품질이 중요하면 캠페인에 잘 맞는 계정을 골라 넣으세요. 추천사는 한국어로 생성됩니다.

한계·주의

한 번에 최대 30개. 링크당 유료 크롤이 유발되므로 상한을 둡니다.
게시물이 충분한 실계정을 넣어야 정상 동작합니다. 최근 게시물이 3개 미만이면 적합도(matchScore)가 산정되지 않고 null로 남습니다(정상). 비공개·삭제·존재하지 않는 계정은 채워지지 않습니다.
캠페인에 상품 상세(image_analysis)가 없으면 추천사(recommendReason)는 비어 있습니다.
채움은 값이 null인지 여부로 진행 상태를 판단합니다(별도 상태 필드 없음). 실패로 비어 있는 것과 아직 채우는 중인 것은 화면상 같게 보일 수 있습니다.
등록된 후보는 기본적으로 광고주에게 노출되지 않습니다. 채움 확인 후 노출 토글로 공개하세요.

POST /ai/admin/dashboard/{campaignNo}/demo-applicants/bulk-links