Collab 기반 Meta 인사이트 조회

Collab에 매핑된 Meta 캠페인의 성과 지표를 조회합니다. 기업 회원은 본인 Collab만 조회할 수 있습니다.

매핑이 먼저 등록되어 있어야 합니다. production 환경에서 매시간 두 번 (:10 active batch — 최근 90일 일별 인사이트 갱신, :30 inactive backfill — PAUSED 캠페인 lifetime 보강) 이 5개 광고계정(글로우비/디웨더/리빙/Supera/건식건기식) 의 트리·일별 인사이트를 TB_META_OBJECT_SNAPSHOT / TB_META_INSIGHT_DAILY 에 적재하며 광고 cover 이미지도 함께 S3 백업합니다. 응답은 DB-first. 요청 기간이 적재 범위(최근 90일)를 벗어나면 Meta API 로 자동 fallback 후 DB upsert.

권한

사용자	동작
ADMIN	모든 Collab 의 매핑 인사이트 조회 가능
기업 회원	본인 Collab 만 조회 가능 (다른 기업의 Collab 조회 시 `403`)

내부적으로 collabNo → TB_COLLAB_META_CAMPAIGN 매핑 lookup → 매핑된 meta_campaign_id 의 인사이트를 조회합니다. 매핑이 없으면 404.

HTTP 요청

GET /ai/business/meta/collab/{collabNo}/insights
Authorization: Bearer {access_token}

Path Parameters

파라미터	타입	필수	설명
`collabNo`	`Integer`	예	Glowb Collab 번호

Query Parameters

파라미터	기본값	설명
`level`	`campaign`	집계 단위: `campaign` \| `adset` \| `ad`
`datePreset`	`lifetime`	기간 프리셋. 허용: `today`, `yesterday`, `last_7d`, `last_14d`, `last_30d`, `last_90d`, `this_month`, `last_month`, `lifetime` (적재된 전체 기간 — `since`/`until` 무관, 일자 제한 없음)
`since`	-	시작일 `YYYY-MM-DD`. 지정 시 `datePreset` 무시
`until`	-	종료일 `YYYY-MM-DD`
`timeIncrement`	-	`1`(일별) \| `7`(주별) \| `monthly`
`attributionWindows`	`7d_click`	기여 기간: `1d_click` \| `7d_click` \| `28d_click` \| `1d_view` \| `7d_view`

응답

성공 응답 (200 OK)

{
  "status": 200,
  "code": null,
  "message": "Collab 인사이트 조회 완료",
  "data": [
    {
      "campaignId": "120243507818540347",
      "campaignName": "봄 시즌 프로모션",
      "impressions": "44024",
      "reach": "25111",
      "clicks": "2882",
      "spend": "184585",
      "ctr": "6.546429",
      "cpc": "64.047536",
      "cpm": "4192.82664",
      "frequency": "1.753176",
      "actions": [
        { "actionType": "purchase", "value": "2", "value1dClick": null, "value7dClick": "2", "value28dClick": null, "value1dView": null, "value7dView": null },
        { "actionType": "link_click", "value": "821", "value1dClick": null, "value7dClick": null, "value28dClick": null, "value1dView": null, "value7dView": null }
      ],
      "costPerActionType": [
        { "actionType": "purchase", "value": "92292.5", "value1dClick": null, "value7dClick": "92292.5", "value28dClick": null, "value1dView": null, "value7dView": null }
      ],
      "actionValues": [
        { "actionType": "purchase", "value": "561600", "value1dClick": null, "value7dClick": "561600", "value28dClick": null, "value1dView": null, "value7dView": null }
      ],
      "revenue": 561600.0,
      "roas": 3.04,
      "dateStart": "2026-03-30",
      "dateStop": "2026-04-05"
    }
  ]
}

응답 필드 설명

필드	설명
`impressions`	노출수
`reach`	도달 사용자 수 (중복 제거)
`clicks`	클릭수
`spend`	지출 금액
`ctr`	클릭률 (clicks / impressions × 100)
`cpc`	클릭당 비용. clicks=0 이면 `null`
`cpm`	1,000 노출당 비용
`frequency`	1인당 평균 노출 횟수
`actions`	전환/행동 배열 (`actionType` + `value` + attribution 윈도우별 분해)
`costPerActionType`	행동당 비용 배열
`actionValues`	전환 금액 배열. `purchase` = 구매 전환 금액(매출 원천). `revenue` 계산의 기반
`revenue`	매출 = `actionValues` 의 `purchase` 금액 EQUALS 합산 (광고계정 통화 기준). 구매 추적 시작(2025-11-27) 이전 일자 행은 `null`
`roas`	광고 대비 매출 = `revenue / spend`. 지출 0 또는 매출 추적 이전이면 `null`
`dateStart` / `dateStop`	결과 기간

revenue/roas 는 서버 계산 필드입니다. revenue 는 action_values 의 purchase 금액만 EQUALS 매칭으로 합산합니다 — Meta 는 같은 구매 1건을 omni_purchase 등 여러 action_type 으로 펼쳐 적재하므로 부분일치로 더하면 매출이 몇 배로 부풀 수 있습니다. 캠페인 목록(/campaigns)의 결과값과 동일 기준이라 일별 매출 합 = 캠페인 결과 매출. 구매 전환 금액은 2025-11-27 부터 적재되어 그 이전 일자 행은 revenue/roas 가 null 입니다.

actions 주요 actionType

actionType	설명
`purchase`	구매
`link_click`	링크 클릭
`landing_page_view`	랜딩페이지 조회
`add_to_cart`	장바구니 추가
`initiate_checkout`	체크아웃 시작
`lead`	리드 수집
`video_view`	영상 조회
`page_engagement`	페이지 참여
`post_engagement`	게시물 참여

에러 응답

상태 코드	설명
`401`	인증 실패
`403`	본인 Collab 이 아닌 경우 (다른 기업 Collab 조회 시도)
`404`	`collabNo` 에 매핑된 Meta 캠페인이 존재하지 않음 (`TB_COLLAB_META_CAMPAIGN` row 없음)
`500`	DB miss → on-demand Meta API fallback 중 실패. 다른 `datePreset` 으로 재시도하거나 `lifetime` / `since` + `until` 사용 권장

GET /ai/business/meta/collab/{collabNo}/insights