"""카페24 — 공통 연동 계층(app/integrations/cafe24) 재사용. 카페24는 이미 OAuth 로 연결해 쓰고 있다(상품관리). 실적 설정에서 인증정보를 따로 받지 않고, 같은 토큰 저장소(cafe24_db)와 클라이언트(재시도·429·토큰 자동 갱신)를 쓴다. 주문 읽기 권한(mall.read_order)이 필요하다 — config.DEFAULT_SCOPES 에 포함, 권한 추가 후 카페24 상품관리 → 시스템에서 한 번 다시 연결해야 한다. 카페24 관리자 "일별 매출내역"과 같은 기준으로 센다(Admin API 문서 2026-09-01 확인). - 결제합계(SALE, +): GET /admin/orders date_type=pay_date(결제일), 결제된(paid=T) 주문마다 상품구매금액 + 배송비 − 할인 − 쿠폰 (주문의 initial_order_amount — 결제 당시 금액) 환불은 따로 빼므로 취소 후 금액(actual_order_amount)이 아니라 결제 당시 금액을 쓴다. - 환불합계(CANCEL/RETURN, −): GET /admin/refunds date_type=refund_date(환불완료일), 실제 환불액(actual_refund_amount). 환불코드가 R 로 시작하면 반품, 그 밖은 취소. - 수집 기간을 통째로 다시 받는다(replace_range) — 결제·환불 모두 기간 안 날짜로 조회되므로 그 기간의 카페24 실데이터를 지우고 새로 넣는다. 규칙이 바뀌거나 주문이 사라져도 이중 집계 없음. - 자체몰 주문(market_id 가 self/빈값)은 카페24 열. 카페24 마켓 통합관리로 들어온 다른 마켓 주문 (스마트스토어·쿠팡 등)은 MARKET_MAP 으로 해당 쇼핑몰 열에 넣는다(환불도 원 주문으로 판단). MARKET_MAP 에 없는 마켓은 카페24 열 — 전체 합계는 항상 카페24 일별 매출내역과 같다. 네이버페이 결제(order_place_id=NCHECKOUT)는 자체몰 주문이라 카페24 열. 카페24 가 만든 사건은 모두 외부 사건 ID 앞에 "c24:" — 다시 받을 때 이것만 골라 교체하므로 해당 쇼핑몰을 나중에 직접 연동해도 그 데이터는 건드리지 않는다(단, 같은 주문을 양쪽에서 받지 않게 직접 연동을 켜는 쇼핑몰은 MARKET_MAP 에서 빼야 한다). - 한 호출 검색기간 3개월 미만 → 60일씩 나눠 요청. orders limit ≤ 1000, refunds limit ≤ 500, offset ≤ 15000. - 개인정보(구매자 이름·주소·연락처·계좌)는 저장하지 않는다 — raw 에는 금액·상태 필드만. - 할인 항목 구성·마켓 주문 포함 여부는 `reconcile()`(설정 화면 "카페24 매출 대조")로 카페24 화면과 대조해 확정한다. """ from __future__ import annotations from datetime import date, timedelta from decimal import ROUND_HALF_UP, Decimal, InvalidOperation from typing import Any, Iterable from .base import ( AdapterContext, ApiError, AuthFailed, MarketplaceAdapter, NotConfigured, SaleEvent, TokenExpired, ) ORDER_SCOPE = "mall.read_order" ORDER_LIMIT = 1000 REFUND_LIMIT = 500 LOOKUP_BATCH = 100 MAX_OFFSET = 15000 CHUNK_DAYS = 60 EVENT_PREFIX = "c24:" # 카페24 자체몰 주문 채널 — market_id 는 외부 마켓만이 아니라 주문 채널·간편결제도 담는다 # (실데이터 확인 2026-09-30: mobile=모바일웹, NCHECKOUT=네이버페이, KAKAOPAY=톡체크아웃). # 이 주문들은 카페24 자체몰 매출이다. 비교는 소문자로. SELF_CHANNELS: dict[str, str] = { # self 는 PC 전용이 아니다 — 주문경로(order_place_name)가 "PC쇼핑몰"·"모바일웹"으로 나뉘어 섞여 있다(실데이터 확인). "": "자체몰", "self": "자체몰", "cafe24": "자체몰", "mobile": "모바일웹", "mobile_d": "모바일앱", "ncheckout": "네이버페이", "kakaopay": "톡체크아웃", } # 카페24 마켓 통합관리가 가져온 외부 마켓 주문의 market_id(또는 order_place_id) → 우리 쇼핑몰 열. # 여기에도 SELF_CHANNELS 에도 없는 채널은 "알 수 없는 채널"로 카페24 열에 남긴다 — 전체 합계는 항상 # 카페24 화면과 같다. 결제수단(네이버페이·카카오페이)과 헷갈릴 수 있는 일반 이름(naver, kakao)은 넣지 않는다. # 실제 값은 설정 → "카페24 매출 대조"의 주문 채널별 표로 확인해 보탠다. MARKET_MAP: dict[str, str] = { "shopn": "naver", "smartstore": "naver", "storefarm": "naver", "coupang": "coupang", "sk11st": "elevenst", "11st": "elevenst", "elevenst": "elevenst", "gmarket": "gmarket", "lotteon": "lotteon", "gsshop": "gsshop", "kakaotalkstore": "kakao", "talkstore": "kakao", "kakaostyle": "kakao", "ohouse": "ohouse", "todayhouse": "ohouse", "bucketplace": "ohouse", "tossshopping": "toss", } def _key(value: Any) -> str: return str(value or "").strip().lower() def channel_kind(market_id: Any, order_place_id: Any = None) -> str: """self(자체몰 채널) / market(외부 마켓, 해당 쇼핑몰 열) / unknown(모르는 채널 → 카페24 열).""" if market_id is None or _key(market_id) in SELF_CHANNELS: return "self" if _key(market_id) in MARKET_MAP or _key(order_place_id) in MARKET_MAP: return "market" return "unknown" def target_code(market_id: Any, order_place_id: Any = None) -> str: """이 주문을 집계할 쇼핑몰 열. 자체몰 채널·모르는 채널은 카페24.""" if channel_kind(market_id, order_place_id) != "market": return "cafe24" return MARKET_MAP.get(_key(market_id)) or MARKET_MAP[_key(order_place_id)] # 결제합계 = 상품구매금액 + 배송비 − 할인 − 쿠폰 (initial_order_amount 의 필드) DISCOUNT_FIELDS = ("membership_discount_amount", "set_product_discount_amount", "app_discount_amount", "market_other_discount_amount", "shipping_fee_discount_amount") COUPON_FIELDS = ("coupon_discount_price", "coupon_shipping_fee_amount") AMOUNT_FIELDS = ("order_price_amount", "shipping_fee", *DISCOUNT_FIELDS, *COUPON_FIELDS, "points_spent_amount", "credits_spent_amount", "payment_amount") def _won(value: Any) -> int: """카페24 금액 문자열("29000.00") → 원 단위 정수.""" try: return int(Decimal(str(value or "0")).quantize(Decimal(1), rounding=ROUND_HALF_UP)) except (InvalidOperation, ValueError): return 0 def _day(value: Any) -> date | None: """"2018-07-04T11:21:35+09:00" / "2017-07-10 15:55:51" → date (카페24 는 KST 로 준다).""" s = str(value or "").strip() if len(s) < 10: return None try: return date.fromisoformat(s[:10]) except ValueError: return None def order_amounts(order: dict[str, Any]) -> dict[str, int]: """결제 당시 금액(initial_order_amount, 없으면 actual_order_amount) 항목별 원 단위.""" a = order.get("initial_order_amount") or order.get("actual_order_amount") or {} return {k: _won(a.get(k)) for k in AMOUNT_FIELDS} def order_total(order: dict[str, Any]) -> int: """결제합계 = 상품구매금액 + 배송비 − 할인 − 쿠폰.""" a = order_amounts(order) return (a["order_price_amount"] + a["shipping_fee"] - sum(a[k] for k in DISCOUNT_FIELDS) - sum(a[k] for k in COUPON_FIELDS)) def is_self_market(market_id: Any) -> bool: """카페24 자체몰 채널(PC·모바일·네이버페이·톡체크아웃 등)인가.""" return channel_kind(market_id) == "self" def _chunks(start: date, end: date) -> Iterable[tuple[date, date]]: s = start while s <= end: e = min(end, s + timedelta(days=CHUNK_DAYS - 1)) yield s, e s = e + timedelta(days=1) class Cafe24Adapter(MarketplaceAdapter): code = "cafe24" name = "카페24" auth_type = "shared" implemented = True replace_range = True event_prefix = EVENT_PREFIX docs_url = "https://apidocs.cafe24.com/docs/admin/get-orders" note = ("카페24 상품관리에서 연결한 OAuth 토큰을 함께 씁니다(여기서 따로 입력하지 않음). " "주문 읽기 권한이 필요해 권한 추가 후 한 번 다시 연결해야 합니다.") # ── 연결 ────────────────────────────────────────────── def is_configured(self, ctx: AdapterContext) -> bool: return True def _repo(self, ctx: AdapterContext): return getattr(ctx.app_state, "cafe24_store", None) if ctx.app_state is not None else None def shared_status(self, ctx: AdapterContext) -> dict: from app.integrations.cafe24.config import load_config # 지연 import from app.integrations.cafe24.tokens import TokenService # 지연 import repo = self._repo(ctx) config = load_config() if repo is None: return {"connected": False, "missing": config.missing or ["CAFE24_DB_URL"], "needs_reauth": False} return TokenService(repo, config).status() def authenticate(self, ctx: AdapterContext) -> None: st = self.shared_status(ctx) if not st.get("connected"): if st.get("missing"): raise NotConfigured("카페24 연동 환경변수가 설정되지 않았습니다.") if st.get("needs_reauth") and str(st.get("reason", "")).startswith("refresh"): raise TokenExpired("카페24 연결이 만료되었습니다. 카페24 상품관리 → 시스템에서 재연결하세요.") raise AuthFailed("카페24에 연결되어 있지 않습니다. 카페24 상품관리 → 시스템에서 연결하세요.") if ORDER_SCOPE not in str(st.get("scopes") or ""): raise AuthFailed("카페24 토큰에 주문 읽기 권한(mall.read_order)이 없습니다. " "카페24 상품관리 → 시스템에서 다시 연결하세요.") def _client(self, ctx: AdapterContext): from app.integrations.cafe24 import build_cafe24_api # 지연 import return build_cafe24_api(self._repo(ctx)).client def _get(self, ctx: AdapterContext, path: str, params: dict[str, Any]) -> dict[str, Any]: from app.integrations.cafe24.errors import ( # 지연 import Cafe24ApiError, Cafe24AuthError, Cafe24ConfigError, Cafe24RateLimitError, ) try: return self._client(ctx).get(path, params=params) except Cafe24ConfigError as exc: raise NotConfigured(str(exc)) from None except Cafe24AuthError as exc: raise AuthFailed(str(exc)) from None except Cafe24RateLimitError as exc: raise ApiError(f"카페24 호출 제한(429): {exc}") from None except Cafe24ApiError as exc: status = getattr(exc, "status", None) if status == 403: raise AuthFailed(f"카페24 권한 오류(403): {exc}. 주문 권한 추가 후 재연결하세요.") from None raise ApiError(f"카페24 API 오류({status}): {exc}") from None def test_connection(self, ctx: AdapterContext) -> str: from app.timezone import today_kst # noqa: WPS433 self.authenticate(ctx) today = today_kst().isoformat() self._get(ctx, "/admin/orders", {"start_date": today, "end_date": today, "date_type": "pay_date", "limit": 1}) return "카페24 연결 정상(주문 조회 권한 확인)." # ── 조회 ────────────────────────────────────────────── def _paged(self, ctx: AdapterContext, path: str, key: str, params: dict[str, Any], limit: int) -> Iterable[dict[str, Any]]: offset = 0 while True: if offset > MAX_OFFSET: raise ApiError(f"카페24 조회 건수가 너무 많습니다({params.get('start_date')}~{params.get('end_date')}). " "기간을 줄여 다시 시도하세요.") rows = self._get(ctx, path, {**params, "limit": limit, "offset": offset}).get(key) or [] yield from rows if len(rows) < limit: return offset += limit def paid_orders(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]: for s, e in _chunks(start, end): yield from self._paged(ctx, "/admin/orders", "orders", {"start_date": s.isoformat(), "end_date": e.isoformat(), "date_type": "pay_date", "embed": "items"}, ORDER_LIMIT) def refunds(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]: for s, e in _chunks(start, end): yield from self._paged(ctx, "/admin/refunds", "refunds", {"start_date": s.isoformat(), "end_date": e.isoformat(), "date_type": "refund_date"}, REFUND_LIMIT) def market_ids(self, ctx: AdapterContext, refunds: list[dict[str, Any]]) -> dict[str, tuple[Any, Any, Any]]: """환불의 원 주문 (market_id, order_place_id, order_place_name) — 주문일 60일 구간·100건씩 묶어 조회. 못 찾으면 자체몰.""" pairs = sorted({(_day(r.get("order_date")) or date.min, str(r.get("order_id") or "")) for r in refunds if r.get("order_id")}) out: dict[str, Any] = {} i = 0 while i < len(pairs): first = pairs[i][0] group = [p for p in pairs[i:i + LOOKUP_BATCH] if (p[0] - first).days < CHUNK_DAYS] ids = [oid for _, oid in group] if first != date.min: params = {"order_id": ",".join(ids), "start_date": first.isoformat(), "end_date": group[-1][0].isoformat(), "date_type": "order_date", "limit": LOOKUP_BATCH} for o in self._get(ctx, "/admin/orders", params).get("orders") or []: out[str(o.get("order_id"))] = (o.get("market_id"), o.get("order_place_id"), o.get("order_place_name")) i += len(group) return out # ── 수집(어댑터 공통 흐름) ────────────────────────────── def fetch_orders(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]: yield from self.paid_orders(ctx, start, end) def fetch_refunds(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]: rows = [r for r in self.refunds(ctx, start, end) if str(r.get("status") or "T") == "T"] markets = self.market_ids(ctx, rows) for r in rows: mid, place, _name = markets.get(str(r.get("order_id")), ("self", None, None)) yield {**r, "_market_id": mid, "_order_place_id": place} def normalize_order(self, order: dict[str, Any]) -> list[SaleEvent]: """결제 주문 → SALE. 자체몰은 카페24 열, 마켓 연동 주문은 해당 쇼핑몰 열(MARKET_MAP).""" if order.get("paid") != "T": return [] pay_day = _day(order.get("payment_date")) if pay_day is None: return [] items = order.get("items") or [] names = [str(i.get("product_name") or "") for i in items if i.get("product_name")] name = names[0] + (f" 외 {len(names) - 1}건" if len(names) > 1 else "") if names else "" oid = str(order.get("order_id") or "") target = target_code(order.get("market_id"), order.get("order_place_id")) return [SaleEvent( marketplace_code=target, event_type="SALE", external_event_id=f"{EVENT_PREFIX}{oid}-PAY", external_order_id=oid, order_date=_day(order.get("order_date")), payment_date=pay_day, event_date=pay_day, amount=max(0, order_total(order)), product_name=name, quantity=sum(int(i.get("quantity") or 0) for i in items), order_status="결제완료", discount_amount=sum(order_amounts(order)[k] for k in DISCOUNT_FIELDS + COUPON_FIELDS), raw={"order_id": oid, "market_id": order.get("market_id"), "order_place_id": order.get("order_place_id"), "items": len(items), **{f"initial_{k}": v for k, v in order_amounts(order).items()}}, )] def normalize_refund(self, refund: dict[str, Any]) -> list[SaleEvent]: """환불 → CANCEL/RETURN(−). 원 주문의 market_id 로 결제와 같은 쇼핑몰 열에 넣는다.""" day = _day(refund.get("refund_date")) code = str(refund.get("refund_code") or "") if day is None or not code: return [] amount = _won(refund.get("actual_refund_amount")) return [SaleEvent( marketplace_code=target_code(refund.get("_market_id"), refund.get("_order_place_id")), event_type="RETURN" if code.upper().startswith("R") else "CANCEL", external_event_id=f"{EVENT_PREFIX}{code}", external_order_id=str(refund.get("order_id") or ""), external_line_id=",".join(refund.get("order_item_code") or []), order_date=_day(refund.get("order_date")), event_date=day, amount=-amount, quantity=-int(refund.get("quantity") or 0), order_status="환불완료", raw={"refund_code": code, "order_id": refund.get("order_id"), "status": refund.get("status"), "actual_refund_amount": refund.get("actual_refund_amount"), "used_points": refund.get("used_points"), "used_credits": refund.get("used_credits"), "quantity": refund.get("quantity"), "order_item_code": refund.get("order_item_code")}, )] # ── 대조(설정 화면 "카페24 매출 대조") ───────────────── def reconcile(self, ctx: AdapterContext, day: date) -> dict[str, Any]: """그날 결제 주문·환불을 항목별로 합산 — 카페24 일별 매출내역과 비교해 규칙을 확정하는 용도. groups["self"] = 카페24 열(자체몰 채널 + 알 수 없는 채널), groups["market"] = 다른 쇼핑몰 열로 가는 외부 마켓 주문. by_channel = 주문 채널(market_id)별 내역. 개인정보는 담지 않는다. """ self.authenticate(ctx) def empty() -> dict[str, int]: return {"orders": 0, "items": 0, "lines": 0, **{k: 0 for k in AMOUNT_FIELDS}, "total": 0} def channel(mid: Any, place: Any, place_name: Any = None) -> dict[str, Any]: """(market_id, 주문경로) 한 쌍 = 한 줄. self 안에도 PC쇼핑몰·모바일웹 경로가 섞여 있어 나눠 본다.""" mkey = "" if mid is None else str(mid) pname = str(place_name or place or "") kind = channel_kind(mid, place) return by_channel.setdefault((mkey, pname), { "market_id": mkey or "(없음)", "place": pname, "place_id": str(place or ""), "label": SELF_CHANNELS.get(_key(mid), ""), "names": set(), "kind": kind, "target": target_code(mid, place), "orders": 0, "total": 0, "refund_count": 0, "refund_amount": 0, # 기기 — 주문의 order_from_mobile(T=모바일에서 주문). PC 채널(self)에도 모바일 주문이 섞여 있다. "pc_orders": 0, "pc_total": 0, "mobile_orders": 0, "mobile_total": 0, }) groups = {"self": empty(), "market": empty()} by_channel: dict[str, dict[str, Any]] = {} by_payment: dict[str, dict[str, Any]] = {} # 결제수단 조합별(카페24 열 주문만) unpaid = 0 for o in self.paid_orders(ctx, day, day): if o.get("paid") != "T": unpaid += 1 continue ch = channel(o.get("market_id"), o.get("order_place_id"), o.get("order_place_name")) total = order_total(o) ch["orders"] += 1 ch["total"] += total dev = "mobile" if str(o.get("order_from_mobile") or "").upper() == "T" else "pc" ch[f"{dev}_orders"] += 1 ch[f"{dev}_total"] += total if ch["target"] == "cafe24": names = [str(n) for n in (o.get("payment_method_name") or o.get("payment_method") or []) if n] pkey = " + ".join(names) or "(없음)" pm = by_payment.setdefault(pkey, {"method": pkey, "orders": 0, "total": 0}) pm["orders"] += 1 pm["total"] += total for n in (o.get("order_place_name"), o.get("order_place_id")): if n: ch["names"].add(str(n)) g = groups["self" if ch["target"] == "cafe24" else "market"] g["orders"] += 1 g["items"] += sum(int(i.get("quantity") or 0) for i in o.get("items") or []) g["lines"] += len(o.get("items") or []) for k, v in order_amounts(o).items(): g[k] += v g["total"] += order_total(o) rows = [r for r in self.refunds(ctx, day, day) if str(r.get("status") or "T") == "T"] markets = self.market_ids(ctx, rows) refunds = {"self": {"count": 0, "actual_refund_amount": 0, "used_points": 0, "used_credits": 0}, "market": {"count": 0, "actual_refund_amount": 0, "used_points": 0, "used_credits": 0}} for r in rows: mid, place, place_name = markets.get(str(r.get("order_id")), ("self", None, None)) ch = channel(mid, place, place_name) g = refunds["self" if ch["target"] == "cafe24" else "market"] g["count"] += 1 for k in ("actual_refund_amount", "used_points", "used_credits"): g[k] += _won(r.get(k)) ch["refund_count"] += 1 ch["refund_amount"] += _won(r.get("actual_refund_amount")) channels_out = sorted(({**v, "names": sorted(v["names"])} for v in by_channel.values()), key=lambda v: v["total"], reverse=True) return {"date": day.isoformat(), "orders": groups, "refunds": refunds, "unpaid_orders": unpaid, "by_channel": channels_out, "by_payment": sorted(by_payment.values(), key=lambda v: v["total"], reverse=True), "formula": "결제합계 = 상품구매금액 + 배송비 − 할인(" + ", ".join(DISCOUNT_FIELDS) + ") − 쿠폰(" + ", ".join(COUPON_FIELDS) + ")"}