Files
dbx-main/app/modules/performance/ad_sources/tiktok_ads.py
T
king 54e4e08802 feat(실적): 틱톡 탭과 틱톡 광고 API 연동
광고비 탭 오른쪽에 틱톡 탭 추가. 일자별 ROAS, 광고비, 매출을 광고비 탭과 같은 틀로 보여 준다.
실적 설정 광고 API 연동에 틱톡 추가(광고 계정 ID, 액세스 토큰, 선택 틱톡샵 ID).
채널 표(CHANNELS)에 넣지 않아 매출 실적·광고비 탭 합계에는 들어가지 않는다. DB 변경 없음.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 14:19:25 +09:00

203 lines
12 KiB
Python

"""틱톡 광고(TikTok API for Business v1.3) — 날짜별 광고비·매출·ROAS. 화면은 틱톡 탭(광고비 탭·매출 실적에는 안 나옴).
인증(2026-11-05): 광고 계정(advertiser) ID 하나 + 장기 액세스 토큰(머리글 Access-Token). 토큰 앱에 보고서·광고 계정 읽기 권한이 있어야 한다.
조회
GET /report/integrated/get/ — report_type=BASIC · data_level=AUCTION_ADVERTISER · 차원 advertiser_id·stat_time_day.
매출 = 웹 구매금액(total_complete_payment_rate — 이름과 달리 금액) + 틱톡샵 매출(total_onsite_shopping_value).
GET /gmv_max/report/get/ — 틱톡샵 ID 를 넣었을 때만. 비용(cost)·매출(gross_revenue)을 더한다.
- 하루 단위 조회는 기간 제한이 있어 30일씩 나눠 묻는다.
- 금액은 광고 계정 통화 → 그날 환율로 원화(fx.krw_rates, 메타와 같음).
- ROAS(%) = 매출 ÷ 광고비 × 100(합친 값으로 계산 — 틱톡의 ROAS 칸은 더할 수 없다).
공식 문서가 스크립트 화면이라 지표 이름을 이차 자료로 확인했다 — 연결 테스트가 어제 하루를 실제로 물어 지표 이름 오류까지 잡는다.
"""
from __future__ import annotations
import json
import re
from datetime import date, timedelta
from decimal import ROUND_HALF_UP, Decimal
from typing import Any
import httpx
from app.timezone import today_kst
from .. import fx
from ..adapters.base import AdapterContext, ApiError, AuthFailed, CredentialField, TokenExpired
from .base import AdDay, AdSource
from .meta_ads import _num, _won
API_BASE = "https://business-api.tiktok.com/open_api/v1.3"
MAX_DAYS = 366
SPAN_DAYS = 30
PAGE_SIZE = 100 # 계정 하나·30일 = 많아야 30줄이라 한 쪽이면 된다
RATE_LIMIT = 40100
REPORT_METRICS = ("spend", "impressions", "clicks", "complete_payment", "total_complete_payment_rate",
"onsite_shopping", "total_onsite_shopping_value")
GMV_METRICS = ("cost", "gross_revenue", "orders")
# metrics 키 — 화면 이름 그대로 저장. 틱톡 탭은 M_REVENUE 를 매출로 읽는다(ad_spend.build_tiktok_dashboard).
M_SPEND, M_REVENUE, M_ROAS = "광고비", "매출", "ROAS(%)"
M_IMPR, M_CLICKS, M_ORDERS = "노출수", "클릭수", "구매수"
M_WEB, M_SHOP, M_GMV_COST, M_GMV_REVENUE = "웹 구매금액", "틱톡샵 매출", "GMV Max 비용", "GMV Max 매출"
def _http(ctx: AdapterContext) -> httpx.Client:
"""HTTP 클라이언트 — 테스트가 바꿔 끼운다."""
return httpx.Client(timeout=ctx.timeout_sec)
def _spans(start: date, end: date) -> list[tuple[date, date]]:
"""기간을 SPAN_DAYS 일씩 나눈다."""
out = []
while start <= end:
stop = min(start + timedelta(days=SPAN_DAYS - 1), end)
out.append((start, stop))
start = stop + timedelta(days=1)
return out
class TiktokAdsSource(AdSource):
code = "tiktok"
name = "틱톡"
docs_url = "https://business-api.tiktok.com/portal/docs"
note = ("TikTok API for Business 로 날짜별 광고비·매출·ROAS 를 가져와 틱톡 탭에 보여 줍니다(매출 실적·광고비 탭 합계에는 들어가지 않음). "
"준비: 개발자 앱에서 광고 계정을 승인해 장기 액세스 토큰 발급(보고서·광고 계정 읽기 권한). 외화 계정은 그날 환율로 원화로 바꿉니다.")
def credential_fields(self) -> list[CredentialField]:
return [
CredentialField("advertiser_id", "광고 계정 ID", placeholder="7123456789012345678",
help="틱톡 광고 관리자 주소의 aadvid= 뒤 숫자."),
CredentialField("access_token", "액세스 토큰", secret=True,
help="광고 계정을 승인할 때 받은 장기 액세스 토큰. 저장 후에는 화면에 다시 보이지 않습니다."),
CredentialField("shop_id", "틱톡샵 ID", required=False, placeholder="GMV Max 캠페인을 쓸 때만",
help="GMV Max 캠페인은 일반 보고서와 따로 조회합니다 — 넣으면 그 비용·매출도 더합니다. 안 쓰면 비워 둡니다."),
]
def validate_credentials(self, values: dict[str, str]) -> list[str]:
errors = super().validate_credentials(values)
advertiser = (values.get("advertiser_id") or "").strip()
if advertiser and advertiser != "__stored__" and not re.fullmatch(r"\d{5,30}", advertiser):
errors.append("광고 계정 ID 는 숫자여야 합니다.")
shop = (values.get("shop_id") or "").strip()
if shop and shop != "__stored__" and not re.fullmatch(r"\d{5,30}", shop):
errors.append("틱톡샵 ID 는 숫자여야 합니다.")
token = (values.get("access_token") or "").strip()
if token and token != "__stored__" and (len(token) < 20 or re.search(r"\s", token)):
errors.append("액세스 토큰 형식이 아닙니다(공백 없이 통째로 붙여 넣으세요).")
return errors
def _get(self, ctx: AdapterContext, client: httpx.Client, path: str, params: dict[str, Any]) -> dict[str, Any]:
"""틱톡은 오류도 HTTP 200 + code 로 준다. 토큰은 머리글로만 보내 주소·오류 문구에 들어가지 않는다."""
ctx.progress.check()
token = (ctx.credentials.get("access_token") or "").strip()
try:
resp = client.get(API_BASE + path, params=params, headers={"Access-Token": token})
except httpx.HTTPError as exc:
raise ApiError(f"틱톡 API 에 연결하지 못했습니다({type(exc).__name__}).") from None
try:
body = resp.json()
except ValueError:
raise ApiError(f"틱톡 API 응답을 읽을 수 없습니다(HTTP {resp.status_code}).") from None
code = body.get("code") if isinstance(body, dict) else None
if resp.status_code == 200 and code == 0:
return body.get("data") or {}
text = f"틱톡 API 오류({code if code is not None else resp.status_code}): {str((body or {}).get('message') or '')[:200]}"
if code == 40102:
raise TokenExpired(text + " — 액세스 토큰을 다시 발급해 넣으세요.")
if code == RATE_LIMIT:
raise ApiError(text + " — 호출 한도에 걸렸습니다. 잠시 뒤 다시 누르세요.")
if resp.status_code in (401, 403) or (isinstance(code, int) and 40100 < code < 40200):
raise AuthFailed(text + " — 토큰과 광고 계정 ID, 앱 권한을 확인하세요.")
raise ApiError(text)
def _info(self, ctx: AdapterContext, client: httpx.Client) -> dict[str, Any]:
advertiser = (ctx.credentials.get("advertiser_id") or "").strip()
rows = self._get(ctx, client, "/advertiser/info/", {
"advertiser_ids": json.dumps([advertiser]), "fields": json.dumps(["name", "currency", "timezone"])}).get("list") or []
if not rows:
raise AuthFailed("이 토큰으로 볼 수 없는 광고 계정입니다 — 광고 계정 ID 와 승인 여부를 확인하세요.")
return rows[0]
def _rows(self, ctx: AdapterContext, client: httpx.Client, path: str, metrics: tuple[str, ...], start: date, end: date,
**extra: Any) -> list[tuple[date, dict[str, Any]]]:
"""보고서 하나를 30일씩 물어 (날짜, 지표) 목록으로."""
advertiser = (ctx.credentials.get("advertiser_id") or "").strip()
out = []
for s, e in _spans(start, end):
data = self._get(ctx, client, path, {
"advertiser_id": advertiser, "dimensions": json.dumps(["advertiser_id", "stat_time_day"]), "metrics": json.dumps(metrics),
"start_date": s.isoformat(), "end_date": e.isoformat(), "page": 1, "page_size": PAGE_SIZE, **extra})
for r in data.get("list") or []:
try:
day = date.fromisoformat(str((r.get("dimensions") or {}).get("stat_time_day"))[:10])
except ValueError:
continue
out.append((day, r.get("metrics") or {}))
return out
def _collect(self, ctx: AdapterContext, client: httpx.Client, start: date, end: date) -> dict[date, dict[str, Decimal]]:
"""날짜 → 항목 합(계정 통화)."""
sums: dict[date, dict[str, Decimal]] = {}
def day_of(d: date) -> dict[str, Decimal]:
return sums.setdefault(d, {k: Decimal(0) for k in ("spend", "impr", "clicks", "orders", "web", "shop", "gmv_cost", "gmv")})
for d, m in self._rows(ctx, client, "/report/integrated/get/", REPORT_METRICS, start, end,
report_type="BASIC", data_level="AUCTION_ADVERTISER"):
one = day_of(d)
one["spend"] += _num(m.get("spend"))
one["impr"] += _num(m.get("impressions"))
one["clicks"] += _num(m.get("clicks"))
one["orders"] += _num(m.get("complete_payment")) + _num(m.get("onsite_shopping"))
one["web"] += _num(m.get("total_complete_payment_rate"))
one["shop"] += _num(m.get("total_onsite_shopping_value"))
shop_id = (ctx.credentials.get("shop_id") or "").strip()
if shop_id:
for d, m in self._rows(ctx, client, "/gmv_max/report/get/", GMV_METRICS, start, end, store_ids=json.dumps([shop_id])):
one = day_of(d)
one["orders"] += _num(m.get("orders"))
one["gmv_cost"] += _num(m.get("cost"))
one["gmv"] += _num(m.get("gross_revenue"))
return sums
def test_connection(self, ctx: AdapterContext) -> str:
self.require_configured(ctx)
yesterday = today_kst() - timedelta(days=1)
with _http(ctx) as client:
info = self._info(ctx, client)
self._collect(ctx, client, yesterday, yesterday) # 지표 이름·GMV Max 권한까지 실제로 확인
return f"연결됨 — {info.get('name') or '광고 계정'}({info.get('currency') or '?'}·{info.get('timezone') or '?'})"
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}일까지 가져올 수 있습니다.")
self.require_configured(ctx)
with _http(ctx) as client:
currency = str(self._info(ctx, client).get("currency") or "").upper()
if not re.fullmatch(r"[A-Z]{3}", currency):
raise ApiError(f"광고 계정 통화({currency[:10] or '없음'})를 알 수 없습니다.")
sums = self._collect(ctx, client, start, end)
try:
rates = fx.krw_rates(client, currency, start, end) if sums else {}
except fx.FxError as exc:
raise ApiError(f"{currency} 광고 계정을 원화로 바꿀 환율을 가져오지 못했습니다 — {exc}") from None
return [_day(d, sums[d], rates[d]) for d in sorted(sums)]
def _day(day: date, a: dict[str, Decimal], rate: Decimal) -> AdDay:
"""합친 값(계정 통화) → 하루치(원화). ROAS 는 비율이라 반올림 전 값으로."""
spend = (a["spend"] + a["gmv_cost"]) * rate
revenue = (a["web"] + a["shop"] + a["gmv"]) * rate
roas = (revenue / spend * 100).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP) if spend > 0 else None
return AdDay(day=day, amount=_won(spend), roas=roas, metrics={
M_SPEND: _won(spend), M_REVENUE: _won(revenue), M_ROAS: float(roas) if roas is not None else None,
M_WEB: _won(a["web"] * rate), M_SHOP: _won(a["shop"] * rate), M_GMV_COST: _won(a["gmv_cost"] * rate), M_GMV_REVENUE: _won(a["gmv"] * rate),
M_IMPR: int(a["impr"]), M_CLICKS: int(a["clicks"]), M_ORDERS: int(a["orders"]),
})