Admin APIMeta Marketing Insights
Meta Marketing Insights
Meta(Facebook) 광고 성과 조회 및 Collab 매핑 API
Meta Marketing Insights
Glowb 비즈니스 매니저 산하 5개 Meta 광고 계정의 캠페인 성과·트리·creative 이미지를 통합 조회하고, Collab 과 Meta 캠페인을 연결하는 API입니다.
광고 계정 (5개 멀티 적재)
매시간 :10 active batch 시작 시 /me/adaccounts 자동 sync 로 ACCOUNT row upsert. 신규 계정 연결 시 별도 시드 없이 다음 사이클에 자동 발견.
| ad_account_id | 표시명 | currency | timezone |
|---|---|---|---|
act_2916260795344961 | 글로우비 | KRW | Asia/Seoul |
act_1160065922750394 | 디웨더 | KRW | Asia/Seoul |
act_4440796359491110 | Glow.B 리빙 | KRW | Asia/Seoul |
act_1912893489351900 | Glow.B Supera | USD | Asia/Tokyo |
act_1228857182239350 | Glow.B 건식 건기식 | KRW | Asia/Seoul |
주요 기능
| 기능 | 설명 |
|---|---|
| 광고계정 목록 | GET /accounts — ADMIN 광고계정 5개 메타 |
| 인사이트 조회 | 계정 / 캠페인 / 광고세트 / 광고 단위 성과 지표 |
| 트리 구조 응답 | /campaigns 응답에 하위 객체(adsets→ads) 중첩 임베딩 |
| Collab 매핑 O/X 표시 | 캠페인 응답에 linked / linkedCollabNo 필드 + ?filter=linked|unlinked|all 쿼리 |
| 대표 이미지 | 캠페인 / 광고세트 응답에 representativeImageUrl (산하 광고 중 가장 최근 created_time 의 이미지) |
| Creative S3 백업 | 광고 이미지 / 비디오 cover(1080×1080) 자동 S3 업로드. 응답에는 광고 유형 무관 단일 imageUrl 필드로 노출 (프론트 분기 불필요) |
| Collab 매핑 CRUD (O) | Glowb Collab ↔ Meta 캠페인 수동 연결. 응답에 linked=true, linkedCollabNo=N |
| Business 직접 매핑 CRUD (X) | ADMIN 이 기업과 Meta 캠페인을 직접 연결 (Collab 없이). 응답엔 linked=false 지만 기업 화면 노출 |
| 배치 트리거 (ADMIN) | 일별 적재 즉시 실행 / 백필 / 광고계정 단일 실행 |
데이터 흐름 (배치 + DB-first)
production 환경에서 매시간 :10 active batch (최근 90일 일별 인사이트 갱신) + 매시간 :30 inactive backfill (PAUSED 캠페인 lifetime 보강) 이 5개 광고계정을 순차 처리하며 DB(TB_META_OBJECT_SNAPSHOT, TB_META_INSIGHT_DAILY) 에 적재합니다. test/staging 환경에서는 정기 스케줄 비활성 (ADMIN 트리거로만 실행).
- 적재 윈도우: 최근 90일(D-1 ~ D-90) + PAUSED 캠페인 lifetime 1회성 백필
- 사용자 응답: DB hit → 즉시 반환. 요청 기간이 DB 적재 범위 밖이면 Meta API 자동 fallback 후 DB upsert
- 멱등 보장:
(object_id, object_level, recorded_date, attribution_window)UK 기반 upsert - Creative: tree sync
/ads?fields=...,creative{id,image_hash,image_url,video_id}한 호출에 메타 + 이미지 URL 모두 포함 (추가 호출 0). 변경 감지(creative_id+image_hash+video_id) 후 변경 시만 S3 업로드. 비디오는 cover fetch 1콜 추가 - Rate limit 보호: 호출 사이 1초 throttle, 광고계정 간 5초 cooldown, 실패 시 지수 백오프(2/4/6초 × 3회). 매 응답
X-App-Usage/X-Business-Use-Case-Usage헤더 로그
권한
| 엔드포인트 | 권한 |
|---|---|
GET /accounts 광고계정 목록 | ADMIN 전용 |
GET /campaigns?accountId=...&filter=... ADMIN 광고계정/필터 파라미터 | ADMIN 전용 (기업 회원은 ADMIN 이 만든 매핑 합집합 기반, accountId 무시) |
인사이트 조회 (/insights, /{id}/insights) | ADMIN + BUSINESS (본인에게 매핑된 캠페인 한정) |
Collab 매핑 등록 / 삭제 (POST/DELETE /mapping) | ADMIN 전용 |
Business 직접 매핑 등록 / 삭제 (POST/DELETE /business-mapping) | ADMIN 전용 |
Collab 매핑 목록 (GET /mappings) | ADMIN (전체) / BUSINESS (본인 Collab만) |
Business 매핑 목록 (GET /business-mappings) | ADMIN 전용 |
| Collab 인사이트 조회 | ADMIN + BUSINESS (본인 Collab만) |
배치 트리거 (/ai/admin/meta-insight/...) | ADMIN 전용 |