"""메타 광고(Meta Marketing API — Insights) — 날짜별 광고비·ROAS·보고서 항목. 인증(2026-10-16 사용자: 토큰·광고 계정 ID 준비 완료) - 액세스 토큰 하나(시스템 사용자 토큰 권장 — 만료 없음. 사용자 토큰은 약 60일 뒤 만료) + 광고 계정 ID 여러 개. 토큰에 ads_read 권한이 있어야 하고, 토큰 주인(시스템 사용자 등)이 각 광고 계정에 배정돼 있어야 한다. - 메타 문서대로 토큰은 access_token 매개변수로 보낸다. 앱 설정에서 "앱 시크릿 필요"를 켰다면 앱 시크릿을 넣어 appsecret_proof(HMAC-SHA256)를 같이 보낸다. 토큰은 오류 문구에 넣지 않고(주소도 넣지 않음), ad_sync 가 저장된 비밀값을 다시 한 번 가린다. httpx 요청 로그(INFO)는 주소에 토큰이 들어가므로 켜지 않는다. 조회(GET /{버전}/act_{계정}/insights) level=account · time_increment=1(하루씩) · time_range={since, until} · fields=spend·노출·클릭·구매 전환 등. - 날짜는 광고 계정 시간대 기준. 광고가 없던 날은 행이 없다. 여러 계정은 날짜별로 더한다. - 원화가 아닌 계정(USD 등, 2026-10-16)은 지출 금액·구매 전환값을 그날 환율로 원화 환산(fx.krw_rates — Frankfurter 중앙은행 고시 환율 종합, 그날 값이 없으면 앞 가장 가까운 날). 계정 탭에 원래 통화 지출·적용 환율. ROAS 는 비율이라 환율과 무관. - 기여(어트리뷰션)는 메타가 광고 관리자 설정을 그대로 따른다(2025-06 부터 API 의 기여 매개변수는 무시됨) — 화면 값과 같다. - 구매 전환값·구매수 = action_values·actions 의 구매 항목 하나(omni_purchase → purchase → 픽셀 구매 순서로 처음 있는 것). 메타는 같은 구매를 여러 action_type 에 같은 값으로 겹쳐 주므로 더하지 않는다. - 금액(광고비) = 지출 금액 그대로(원 반올림) — **메타 지출 금액은 이미 부가세 포함**(2026-10-16 사용자 확인). 부가세를 더하는(× 1.1) 것은 비용이 부가세 별도인 구글만이다. - ROAS(%) = 구매 전환값 ÷ 지출 금액 × 100 — 광고 관리자 "구매 ROAS" 와 같은 값, 지출 0 이면 없음. - 나머지 항목(노출수·클릭수·클릭률·링크 클릭·구매수·구매 전환값)은 광고비 탭 메타 머리글 → 일자별 표. - **기간으로 물으면 지출·노출·클릭이 0 으로 오는 메타 응답(2026-10-21 운영 확인, v26.0)** — 10/01~10/21 을 한 번에 물으면 날마다 spend='0'·impressions='0'·clicks='0' 인데 링크 클릭·구매는 들어오고, 같은 날을 하루만 물으면 정상(10/20 지출 817,212원). 그래서 기간 응답에서 "지출·노출 0 인데 링크 클릭·구매가 있는" 날(실제로는 있을 수 없는 조합)은 그날 하루만 다시 물어 그 값으로 바꾼다(_refetch_suspect_days). 집행이 없는 계정·날은 행이 없거나 다 0 이라 다시 묻지 않는다. 진단: scripts/meta_insights_raw.py. API 버전은 설정 칸(기본 DEFAULT_VERSION) — 메타는 버전을 약 2년 뒤 종료하므로 종료 안내가 오면 설정에서 올린다. """ from __future__ import annotations import hashlib import hmac import json import re from datetime import date from decimal import ROUND_HALF_UP, Decimal from typing import Any import httpx from ..adapters.base import AdapterContext, AdapterError, ApiError, AuthFailed, CredentialField, NotConfigured, TokenExpired from .. import fx from .base import ACCOUNTS_KEY, AdDay, AdSource API_BASE = "https://graph.facebook.com" DEFAULT_VERSION = "v26.0" # 2026-07-29 출시(2026-10 기준 최신) MAX_DAYS = 366 MAX_ACCOUNTS = 30 MAX_PAGES = 50 # 계정 하나 페이지 상한(하루 한 줄이라 366일도 몇 쪽) PURCHASE_TYPES = ("omni_purchase", "purchase", "offsite_conversion.fb_pixel_purchase") INSIGHT_FIELDS = "date_start,account_id,account_name,account_currency,spend,impressions,clicks,inline_link_clicks,actions,action_values" # 일자별 표(광고비 탭 메타 머리글) 항목 — 순서 = 열 순서. 클릭률·ROAS 합계는 ad_spend.detail_table 이 이름으로 다시 계산. M_SPEND = "지출 금액(부가세 포함)" # = 광고비(메타 지출 금액은 부가세 포함 — 구글처럼 따로 더하지 않음) M_IMPR, M_CLICKS, M_CTR, M_LINK = "노출수", "클릭수", "클릭률(%)", "링크 클릭" M_PURCHASES, M_VALUE, M_ROAS = "구매수", "구매 전환값", "ROAS(%)" M_FX = "적용 환율(원)" # 외화 계정 탭에만 — 그날 1 계정 통화 = ? 원(fx.krw_rates) # 메타 오류 코드 → 고칠 곳 안내(오류 문구 뒤에 붙임). 권한 오류는 연결 테스트가 원인을 진단한다(_diagnose) — # 불러오기에서 난 오류엔 그 안내를 붙이고, 연결 테스트 자체에서는 진단 결과로 바꿔 쓴다. _DIAG_HINT = "(실적 설정 → 광고 API 연동 → 메타 [연결 테스트]가 원인을 진단합니다)" _HINTS = { 190: "토큰이 만료됐거나 무효입니다. 비즈니스 설정 → 시스템 사용자에서 토큰을 다시 만들어 [액세스 토큰]에 넣으세요(시스템 사용자 토큰은 만료 없음).", 102: "토큰을 읽을 수 없습니다. 토큰을 다시 복사해 넣으세요.", 200: "토큰에 권한이 없습니다. 토큰을 만들 때 ads_read 권한을 고르고, 토큰 주인(시스템 사용자)을 이 광고 계정에 배정했는지 확인하세요" + _DIAG_HINT + ".", 10: "토큰에 권한이 없습니다(ads_read). 앱·토큰 권한을 확인하세요.", 100: "요청 값이 올바르지 않습니다 — 광고 계정 ID 가 맞는지, 토큰 주인이 그 계정을 볼 수 있는지 확인하세요.", 803: "광고 계정 ID 를 찾을 수 없습니다(숫자만, act_ 는 있어도 됨).", 4: "메타 API 호출 한도에 걸렸습니다. 잠시 뒤 다시 누르세요.", 17: "메타 API 호출 한도에 걸렸습니다. 잠시 뒤 다시 누르세요.", 613: "메타 API 호출 한도에 걸렸습니다. 잠시 뒤 다시 누르세요.", 80000: "광고 계정 호출 한도에 걸렸습니다. 잠시 뒤 다시 누르세요.", 80004: "광고 계정 호출 한도에 걸렸습니다. 잠시 뒤 다시 누르세요.", 2635: "API 버전이 종료됐습니다 — 실적 설정에서 API 버전을 최신으로 바꾸세요.", } _RATE_LIMIT = {4, 17, 613, 80000, 80004} _AUTH = {10, 102, 200} _ACCOUNT_STATUS = {1: "운영 중", 2: "사용 중지", 3: "미결제", 7: "검토 대기", 8: "결제 대기", 9: "유예 기간", 100: "종료 대기", 101: "종료"} def _http(ctx: AdapterContext) -> httpx.Client: """HTTP 클라이언트 — 테스트가 바꿔 끼운다.""" return httpx.Client(timeout=ctx.timeout_sec) def parse_account_ids(raw: str) -> list[str]: """'act_123, 456\\n789' → ['123', '456', '789'](순서 유지·중복 제거). 형식이 틀리면 ValueError.""" out: list[str] = [] for part in re.split(r"[\s,;]+", raw or ""): if not part: continue v = part[4:] if part.lower().startswith("act_") else part if not re.fullmatch(r"\d{5,20}", v): raise ValueError("광고 계정 ID 는 숫자여야 합니다(act_ 는 있어도 됨, 여러 개는 쉼표나 줄바꿈으로 구분).") if v not in out: out.append(v) if len(out) > MAX_ACCOUNTS: raise ValueError(f"광고 계정은 {MAX_ACCOUNTS}개까지 넣을 수 있습니다.") return out def _num(v: Any) -> Decimal: """메타 응답 숫자(문자열로 옴, 0 이면 빠지기도 함) → Decimal.""" if v is None or v == "": return Decimal(0) try: return Decimal(str(v)) except ArithmeticError: return Decimal(0) def _won(v: Decimal) -> int: return int(v.quantize(Decimal(1), rounding=ROUND_HALF_UP)) def _purchase(items: Any) -> Decimal: """actions / action_values 목록에서 구매 값 하나(PURCHASE_TYPES 순서로 처음 있는 것 — 겹친 값을 더하지 않는다).""" by_type = {str((i or {}).get("action_type")): (i or {}).get("value") for i in (items or []) if isinstance(i, dict)} for t in PURCHASE_TYPES: if t in by_type: return _num(by_type[t]) return Decimal(0) def _meta_error(resp: httpx.Response) -> tuple[int, str]: """메타 오류 응답 {"error": {"message", "code", "error_subcode", ...}} → (코드, 문구).""" try: err = (resp.json() or {}).get("error") or {} except ValueError: return 0, f"HTTP {resp.status_code}" if not isinstance(err, dict): return 0, f"HTTP {resp.status_code}" msg = str(err.get("error_user_msg") or err.get("message") or f"HTTP {resp.status_code}") try: code = int(err.get("code") or 0) except (TypeError, ValueError): code = 0 return code, msg class MetaAdsSource(AdSource): code = "meta" name = "메타 광고" docs_url = "https://developers.facebook.com/docs/marketing-api/insights" note = ("메타 마케팅 API(Insights)로 광고 계정별 날짜별 지출 금액·구매 ROAS·노출수·클릭수·구매를 가져와 계정을 합칩니다. " "준비: ① ads_read 권한이 있는 액세스 토큰(비즈니스 설정 → 시스템 사용자 토큰 권장 — 만료 없음) " "② 토큰 주인을 각 광고 계정에 배정. 광고비 = 메타 지출 금액 그대로(이미 부가세 포함)입니다.") def credential_fields(self) -> list[CredentialField]: return [ CredentialField("account_ids", "광고 계정 ID", multiline=True, placeholder="act_1234567890\nact_9876543210", help="광고비를 가져올 광고 계정 번호(광고 관리자 주소의 act= 뒤 숫자). 여러 개면 줄바꿈이나 쉼표로 — " "날짜별로 합쳐서 메타 한 칸에 들어갑니다."), CredentialField("access_token", "액세스 토큰", secret=True, help="ads_read 권한이 있는 토큰. 저장 후에는 화면에 다시 보이지 않습니다."), CredentialField("app_secret", "앱 시크릿", secret=True, required=False, placeholder="앱에서 '앱 시크릿 필요'를 켰을 때만", help="메타 앱 설정 → 고급에서 'API 호출에 앱 시크릿 필요'를 켰다면 넣습니다(appsecret_proof). 아니면 비워 둡니다."), CredentialField("api_version", "API 버전", required=False, placeholder=DEFAULT_VERSION, help=f"비워 두면 {DEFAULT_VERSION}. 메타가 버전 종료를 알리면 새 버전(예: v27.0)으로 바꿉니다."), ] def validate_credentials(self, values: dict[str, str]) -> list[str]: errors = super().validate_credentials(values) ids = (values.get("account_ids") or "").strip() if ids and ids != "__stored__": try: parse_account_ids(ids) except ValueError as exc: errors.append(str(exc)) token = (values.get("access_token") or "").strip() if token and token != "__stored__" and (len(token) < 20 or re.search(r"\s", token)): errors.append("액세스 토큰 형식이 아닙니다(공백 없이 통째로 붙여 넣으세요).") ver = (values.get("api_version") or "").strip() if ver and ver != "__stored__" and not re.fullmatch(r"v\d{2,3}\.0", ver): errors.append("API 버전은 v26.0 처럼 입력하세요.") return errors # ── 요청 ────────────────────────────────────────────── def _setup(self, ctx: AdapterContext) -> tuple[list[str], str, dict[str, str]]: self.require_configured(ctx) try: accounts = parse_account_ids(ctx.credentials.get("account_ids")) except ValueError as exc: raise NotConfigured(str(exc)) from None if not accounts: raise NotConfigured("광고 계정 ID 를 입력하세요.") token = (ctx.credentials.get("access_token") or "").strip() auth = {"access_token": token} secret = (ctx.credentials.get("app_secret") or "").strip() if secret: auth["appsecret_proof"] = hmac.new(secret.encode(), token.encode(), hashlib.sha256).hexdigest() version = (ctx.credentials.get("api_version") or "").strip() or DEFAULT_VERSION return accounts, version, auth def _get(self, ctx: AdapterContext, client: httpx.Client, url: str, params: dict[str, Any] | None) -> dict[str, Any]: ctx.progress.check() try: resp = client.get(url, params=params) except httpx.HTTPError as exc: raise ApiError(f"메타 API 에 연결하지 못했습니다({type(exc).__name__}).") from None # 주소(토큰 포함)는 넣지 않는다 if resp.status_code != 200: code, msg = _meta_error(resp) hint = _HINTS.get(code, "") text = f"메타 API 오류({code or resp.status_code}): {msg[:200]}" + (f" — {hint}" if hint else "") if code == 190: raise TokenExpired(text) auth_problem = code in _AUTH or (resp.status_code in (401, 403) and code not in _RATE_LIMIT) raise (AuthFailed if auth_problem else ApiError)(text) try: body = resp.json() except ValueError: raise ApiError("메타 API 응답을 읽을 수 없습니다.") from None return body if isinstance(body, dict) else {} # ── 권한 진단(연결 테스트가 권한 오류를 받았을 때) ───────── def _diagnose(self, ctx: AdapterContext, client: httpx.Client, version: str, auth: dict[str, str], accounts: list[str]) -> str: """토큰이 받은 권한·권한 대상 계정·볼 수 있는 광고 계정을 메타에 물어 원인을 짚는다(2026-10-16 #200 오류). 조회가 실패해도 예외를 내지 않는다(진단은 덧붙이는 정보). 토큰 값은 문구에 넣지 않는다.""" lines: list[str] = [] scopes: set[str] | None = None ads_targets: set[str] | None = None # ads_read/ads_management 가 특정 계정에만 걸려 있으면 그 계정들 try: # ① 토큰 점검 — 앱 개발자 토큰·시스템 사용자 토큰이면 같은 토큰으로 된다 d = (self._get(ctx, client, f"{API_BASE}/{version}/debug_token", {**auth, "input_token": auth["access_token"]}).get("data") or {}) scopes = {str(s) for s in d.get("scopes") or []} for g in d.get("granular_scopes") or []: if str((g or {}).get("scope")) in ("ads_read", "ads_management") and (g or {}).get("target_ids"): ads_targets = (ads_targets or set()) | {str(t) for t in g["target_ids"]} exp = int(d.get("expires_at") or 0) expires = "만료 없음" if exp == 0 else date.fromtimestamp(exp).isoformat() + " 만료" lines.append(f"토큰: 앱 {d.get('application') or d.get('app_id') or '?'}({d.get('app_id') or '?'}) · {expires}" + ("" if d.get("is_valid", True) else " · 무효")) except AdapterError: try: # ② 토큰 점검을 못 하면 받은 권한 목록만 rows = self._get(ctx, client, f"{API_BASE}/{version}/me/permissions", dict(auth)).get("data") or [] scopes = {str(r.get("permission")) for r in rows if r.get("status") == "granted"} except AdapterError: pass if scopes is not None: has = sorted(scopes & {"ads_read", "ads_management"}) lines.append("광고 권한: " + (", ".join(has) if has else "없음(ads_read·ads_management 둘 다 없음)")) visible: set[str] | None = None try: # ③ 이 토큰으로 볼 수 있는 광고 계정 rows = self._get(ctx, client, f"{API_BASE}/{version}/me/adaccounts", {**auth, "fields": "account_id,name", "limit": 200}).get("data") or [] visible = {str(r.get("account_id") or "") for r in rows} lines.append(f"이 토큰으로 보이는 광고 계정 {len(visible)}개") except AdapterError: pass missing = [a for a in accounts if visible is not None and a not in visible] not_target = [a for a in accounts if ads_targets is not None and a not in ads_targets] # 결론 — 가장 앞선 원인 하나 if scopes is not None and not scopes & {"ads_read", "ads_management"}: todo = ("토큰에 ads_read 권한이 없습니다 → 토큰을 새로 만들면서 ads_read 를 체크하세요" "(비즈니스 설정 → 사용자 → 시스템 사용자 → 새 토큰 생성 → 권한에서 ads_read).") elif missing: todo = ("입력한 계정 중 이 토큰 주인에게 배정되지 않은 계정: " + ", ".join("act_" + a for a in missing) + " → 비즈니스 설정 → 사용자 → 시스템 사용자(토큰 주인) → [자산 할당] → 광고 계정에서 그 계정을 고르고 " "'성과 보기'(또는 전체 권한)를 켠 뒤, 토큰을 새로 만들어 넣으세요(배정 전에 만든 토큰은 권한이 안 바뀔 수 있음).") elif not_target: todo = ("토큰의 ads_read 권한이 다른 계정에만 걸려 있습니다(대상 아님: " + ", ".join("act_" + a for a in not_target) + ") → 토큰을 새로 만들 때 이 광고 계정도 대상에 포함하세요.") elif visible is not None: todo = ("토큰 권한·계정 배정은 맞습니다 → 앱 쪽 문제일 가능성이 큽니다: 앱이 이 광고 계정을 가진 비즈니스에 연결돼 있는지" "(비즈니스 설정 → 계정 → 앱), 앱 대시보드에 Marketing API 제품이 추가돼 있는지, 앱이 '제한 액세스'라면 토큰 주인이 앱의 " "관리자·개발자 역할인지 확인하세요.") else: todo = "토큰 정보를 메타에서 읽지 못해 원인을 좁히지 못했습니다 — 토큰 권한(ads_read)과 광고 계정 배정을 확인하세요." return "[진단] " + " · ".join(lines + [todo]) # ── 연결 테스트 · 가져오기 ───────────────────────────── def test_connection(self, ctx: AdapterContext) -> str: accounts, version, auth = self._setup(ctx) parts: list[str] = [] not_krw = False with _http(ctx) as client: for acc in accounts: try: info = self._get(ctx, client, f"{API_BASE}/{version}/act_{acc}", {**auth, "fields": "name,currency,timezone_name,account_status"}) except AuthFailed as exc: # 권한 오류(#200 등) — 메타에 토큰 정보를 물어 원인을 덧붙인다 # 진단(고칠 곳)을 맨 앞에, 메타 원문은 짧게 뒤에 — 길면 화면·기록에서 뒤가 잘리므로(2026-10-16 "[진…" 잘림) original = str(exc).split(" — ")[0] original = re.sub(r",?\s*refer to https?://\S+(?: for details)?", "", original) raise AuthFailed(self._diagnose(ctx, client, version, auth, accounts) + f" (메타 원문: {original})") from None cur = str(info.get("currency") or "?") not_krw = not_krw or cur != "KRW" status = _ACCOUNT_STATUS.get(info.get("account_status"), "") parts.append(f"{info.get('name') or acc}({cur}·{info.get('timezone_name') or '?'}{'·' + status if status else ''})") msg = f"연결됨 — 광고 계정 {len(accounts)}개: " + ", ".join(parts) if not_krw: msg += f" (원화가 아닌 계정은 날마다 그날 환율로 원화로 바꿔 넣습니다 — {fx.SOURCE_LABEL})" return msg def _refetch_suspect_days(self, ctx: AdapterContext, client: httpx.Client, version: str, params: dict[str, Any], raw: list[tuple[str, date, str, dict[str, Any]]]) -> list[tuple[str, date, str, dict[str, Any]]]: """_suspect 줄은 그 계정·그날 하루만 다시 물어 바꾼다(하루 조회는 지출·노출·클릭이 정상). 하루 조회도 같으면 그대로 둔다.""" out = [] for acc, day, cur, r in raw: if _suspect(r): one = {**params, "time_range": json.dumps({"since": day.isoformat(), "until": day.isoformat()})} rows = self._get(ctx, client, f"{API_BASE}/{version}/act_{acc}/insights", one).get("data") or [] fresh = next((x for x in rows if str(x.get("date_start")) == day.isoformat()), None) if fresh is not None: r, cur = fresh, str(fresh.get("account_currency") or cur).upper() out.append((acc, day, cur, r)) return out def fetch_days(self, ctx: AdapterContext, start: date, end: date) -> list[AdDay]: if end < start: start, end = end, start if (end - start).days + 1 > MAX_DAYS: raise ApiError(f"한 번에 {MAX_DAYS}일까지 가져올 수 있습니다.") accounts, version, auth = self._setup(ctx) params = {**auth, "level": "account", "time_increment": 1, "limit": 100, "fields": INSIGHT_FIELDS, "time_range": json.dumps({"since": start.isoformat(), "until": end.isoformat()})} raw: list[tuple[str, date, str, dict[str, Any]]] = [] # (계정, 날짜, 통화, insights 한 줄) names: dict[str, str] = {} with _http(ctx) as client: for acc in accounts: url: str | None = f"{API_BASE}/{version}/act_{acc}/insights" page_params: dict[str, Any] | None = params for _ in range(MAX_PAGES): body = self._get(ctx, client, url, page_params) for r in body.get("data") or []: try: day = date.fromisoformat(str(r.get("date_start"))) except ValueError: continue if r.get("account_name"): names[acc] = str(r["account_name"])[:100] raw.append((acc, day, str(r.get("account_currency") or "KRW").upper(), r)) nxt = ((body.get("paging") or {}).get("next") or "").strip() if not nxt: break if not nxt.startswith(API_BASE + "/"): raise ApiError("메타 API 다음 쪽 주소가 올바르지 않습니다.") url, page_params = nxt, None # next 주소에 매개변수(토큰 포함)가 다 들어 있다 else: raise ApiError("메타 API 응답 쪽수가 너무 많습니다. 기간을 줄여 다시 시도하세요.") raw = self._refetch_suspect_days(ctx, client, version, params, raw) # 원화가 아닌 계정(USD 등) — 그날 환율로 원화 환산(2026-10-16). 통화마다 기간 환율을 한 번에. rates: dict[str, dict[date, Decimal]] = {} for cur in sorted({c for _a, _d, c, _r in raw if c != "KRW"}): if not re.fullmatch(r"[A-Z]{3}", cur): raise ApiError(f"광고 계정 통화({cur[:10]})를 알 수 없습니다.") try: rates[cur] = fx.krw_rates(client, cur, start, end) except fx.FxError as exc: raise ApiError(f"{cur} 광고 계정을 원화로 바꿀 환율을 가져오지 못했습니다 — {exc}") from None sums: dict[date, dict[str, Decimal]] = {} # 날짜 → 모든 계정 합(원화) per_acc: dict[date, dict[str, dict[str, Any]]] = {} # 날짜 → 계정 → 그 계정 값(상세보기 계정별 탭) for acc, day, cur, r in raw: rate = Decimal(1) if cur == "KRW" else rates[cur][day] one = per_acc.setdefault(day, {}).setdefault(acc, {**_zero(), "cur": cur, "rate": rate, "orig": Decimal(0)}) _add(one, r, rate) one["orig"] += _num(r.get("spend")) # 그 계정 통화 그대로의 지출 금액 _add(sums.setdefault(day, _zero()), r, rate) out: list[AdDay] = [] for day in sorted(sums): amount, roas, metrics = _convert(sums[day]) # 계정별 값 — 화면 표 열이 아니라 상세보기 계정별 탭용(ad_spend.detail_tabs, "_" 로 시작하는 키는 표 열에서 빠짐). # 계정마다 따로 반올림하므로 계정 광고비 합이 합계와 1원 다를 수 있다. accounts_out: dict[str, Any] = {} for acc, a in per_acc.get(day, {}).items(): a_amount, a_roas, a_metrics = _convert(a) if a["cur"] != "KRW": # 외화 계정 — 원래 통화 지출과 적용 환율도 보여 준다(계정 탭) a_metrics[f"지출 금액({a['cur']})"] = float(a["orig"].quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)) a_metrics[M_FX] = float(a["rate"]) accounts_out[acc] = {"name": names.get(acc) or f"act_{acc}", "amount": a_amount, "roas": float(a_roas) if a_roas is not None else None, "metrics": a_metrics} metrics[ACCOUNTS_KEY] = accounts_out out.append(AdDay(day=day, amount=amount, roas=roas, metrics=metrics)) return out def _suspect(r: dict[str, Any]) -> bool: """기간 응답에서 지출·노출이 0 인데 링크 클릭·구매가 있는 줄 — 메타 기간 조회가 핵심 칸을 0 으로 준 경우(2026-10-21).""" return (_num(r.get("spend")) == 0 and _num(r.get("impressions")) == 0 and (_num(r.get("inline_link_clicks")) > 0 or _purchase(r.get("actions")) > 0)) def _zero() -> dict[str, Decimal]: return {k: Decimal(0) for k in ("spend", "impr", "clicks", "link", "purchases", "value")} def _add(acc: dict[str, Any], r: dict[str, Any], rate: Decimal = Decimal(1)) -> None: """insights 한 줄(계정 하나·하루)을 더한다 — 금액(지출·구매 전환값)은 × rate(그날 1 계정 통화 = ? 원)로 원화.""" acc["spend"] += _num(r.get("spend")) * rate acc["impr"] += _num(r.get("impressions")) acc["clicks"] += _num(r.get("clicks")) acc["link"] += _num(r.get("inline_link_clicks")) acc["purchases"] += _purchase(r.get("actions")) acc["value"] += _purchase(r.get("action_values")) * rate def _convert(a: dict[str, Decimal]) -> tuple[int, Decimal | None, dict[str, Any]]: """더한 값 → (광고비 원, ROAS %, 일자별 표 항목). 광고비 = 지출 금액 그대로(메타 지출은 부가세 포함, 2026-10-16).""" amount = _won(a["spend"]) roas = (a["value"] / a["spend"] * 100).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP) if a["spend"] > 0 else None ctr = (a["clicks"] / a["impr"] * 100).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP) if a["impr"] > 0 else None return amount, roas, { M_SPEND: amount, M_IMPR: int(a["impr"]), M_CLICKS: int(a["clicks"]), M_CTR: float(ctr) if ctr is not None else None, M_LINK: int(a["link"]), M_PURCHASES: int(a["purchases"]), M_VALUE: _won(a["value"]), M_ROAS: float(roas) if roas is not None else None, }