diff --git a/app/modules/performance/adapters/toss.py b/app/modules/performance/adapters/toss.py index 49d8e24..f58ca87 100644 --- a/app/modules/performance/adapters/toss.py +++ b/app/modules/performance/adapters/toss.py @@ -11,14 +11,17 @@ API 는 https://shopping-fep.toss.im, 헤더 Authorization: Bearer {token}. HTTP 200 + resultType FAIL 로 오류를 준다. 호출 제한: 셀러·API 별 읽기 초당 50회(넘으면 TOO_MANY_REQUEST). -매출 수집 — 주문 내역 조회 GET /api/v3/shopping-fep/orders/v2?startDate=&endDate=&limit=50&nextCursor= - (한 번에 31일까지, 상태 생략 = 전체 상태, 커서 페이지). 줄 = 주문상품(orderProductId), 묶음 = 주문(orderId). - **잠정 규칙(토스쇼핑 파트너스 화면과 대조 전)**: - - SALE = 주문 하나(`toss:{orderId}`), 날짜 = 주문 시각(orderedAt, 한국 날짜 — 토스쇼핑은 주문 = 결제). - - 금액 = 주문상품 price(판매가 × 수량) 합 — 할인 전, 배송비 제외. 할인(totalDiscountPrice = 토스쇼핑 할인 + - 토스페이 할인)은 discount_amount 로만 보관. 결제 전(BEFORE_PAYMENT)만 빼고, 결제 뒤 취소·반품도 주문일 매출에 둔다 - (원본 데이터 확인 표에 참고 열로 따로) → 지난 날짜 매출이 나중에 줄지 않는다(네이버와 같은 방식). - - 실데이터로 파트너스 화면 매출과 맞춰 본 뒤 규칙을 확정한다(설정 화면 "쇼핑몰 원본 데이터 확인"). +매출 = 토스쇼핑 파트너스 "순 거래액" = 매출 − 환불(2026-10-01 사용자 지정, 9/6 화면: 매출 29,600 − 환불 11,900 = 17,700). + - 매출 SALE — 주문 내역 조회 GET /api/v3/shopping-fep/orders/v2?startDate=&endDate=&limit=50&nextCursor= + (한 번에 31일까지, 상태 생략 = 전체 상태, 커서 페이지). 줄 = 주문상품(orderProductId), 묶음 = 주문(orderId). + 주문 하나 = 사건 하나(`toss:{orderId}`), 날짜 = 주문 시각(orderedAt, 한국 날짜 — 토스쇼핑은 주문 = 결제), + 금액 = 주문상품 price(판매가 × 수량) 합 — 할인 전, 배송비 제외. 할인(totalDiscountPrice = 토스쇼핑 할인 + 토스페이 할인)은 + discount_amount 로만 보관. 결제 전(BEFORE_PAYMENT)만 빼고 결제 뒤 취소·반품도 주문일 매출에 둔다(화면 "매출"도 환불 전 금액). + - 환불 CANCEL — 정산 건별 목록 GET /api/v3/shopping-fep/settlement-steps?dateCondition=TRANSACTION_DATE&fromDate=&toDate= + &size=100&nextToken= 의 stepType=REFUND 줄(상품 줄만 — 배송비 줄은 orderProductId 가 없음). 날짜 = 환불 거래 일시 + (transactionTs, 한국 날짜), 금액 = −|orderProductPrice|(정산 기준 금액, 없으면 판매가 × 수량). 결제완료 단계의 고객 취소는 + 클레임 목록에 안 잡히고 클레임 목록은 날짜로 거를 수 없어 정산 쪽을 쓴다. 사건 ID `toss:R{orderProductId}-{거래일시}`. + - 설정 화면 "쇼핑몰 원본 데이터 확인"에 날짜별 매출·환불·순 거래액 — 파트너스 화면과 같은지 본다. - 구매자·수령인 이름·연락처·주소·요청사항은 저장하지 않는다. """ @@ -45,6 +48,8 @@ from .naver import field_summary, flatten TOKEN_URL = "https://oauth2.cert.toss.im/token" HOST = "https://shopping-fep.toss.im" ORDERS_PATH = "/api/v3/shopping-fep/orders/v2" +SETTLEMENT_PATH = "/api/v3/shopping-fep/settlement-steps" +SETTLEMENT_SIZE = 100 # 문서 1~100 SCOPE = "toss-shopping-fep:write" EVENT_PREFIX = "toss:" PAGE_SIZE = 50 # 문서 최대 50 @@ -135,6 +140,24 @@ def group_orders(items: Iterable[dict[str, Any]], start: date, end: date) -> dic return orders +def refund_rows(items: Iterable[dict[str, Any]], start: date, end: date) -> list[dict[str, Any]]: + """정산 건별 목록 → 환불(stepType REFUND) 상품 줄만, 환불일(transactionTs 한국 날짜)이 [start, end] 인 것. + 금액은 양수로(사건에서 − 를 붙인다). 배송비 줄(orderProductId 없음)은 매출에 배송비를 넣지 않으므로 뺀다.""" + out = [] + for it in items: + if str(it.get("stepType") or "") != "REFUND" or not it.get("orderProductId") or not it.get("orderId"): + continue + day = kst_day(it.get("transactionTs")) + if day is None or not (start <= day <= end): + continue + amount = abs(_won(it.get("orderProductPrice"))) or abs(_won(it.get("stockPrice"))) * max(1, _won(it.get("quantity"))) + out.append({"orderId": str(it["orderId"]), "orderProductId": str(it["orderProductId"]), + "_day": day, "_ts": str(it.get("transactionTs") or ""), "amount": amount, + "qty": _won(it.get("quantity")), "name": str(it.get("displayProductName") or ""), + "order_day": kst_day(it.get("originTransactionTs"))}) + return out + + def summary(rows: list[dict[str, Any]]) -> list[dict[str, Any]]: """원본 확인 표 — 항목별 채워진 줄·숫자 합계·예시 값(개인정보·자유 입력 항목은 값 숨김).""" fields = field_summary([flatten(r) for r in rows]) @@ -293,23 +316,64 @@ class TossAdapter(MarketplaceAdapter): break return out - def _items(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]: + def _settlement_items(self, ctx: AdapterContext, a: date, b: date) -> list[dict[str, Any]]: + """거래일 기준 [a, b](31일 이하)의 정산 건별 줄 전체(결제·환불·배송비), nextToken 으로 끝까지.""" + params: dict[str, Any] = {"dateCondition": "TRANSACTION_DATE", "fromDate": a.isoformat(), + "toDate": b.isoformat(), "size": SETTLEMENT_SIZE} + out: list[dict[str, Any]] = [] + token = None + for _ in range(MAX_PAGES): + body = self._get(ctx, SETTLEMENT_PATH, {**params, **({"nextToken": token} if token else {})}) + rows = [r for r in body.get("items") or [] if isinstance(r, dict)] + out.extend(rows) + token = body.get("nextToken") + if not token or not rows: + break + return out + + @staticmethod + def _windows(start: date, end: date) -> list[tuple[date, date]]: windows = [] a = start while a <= end: b = min(end, a + timedelta(days=WINDOW_DAYS - 1)) windows.append((a, b)) a = b + timedelta(days=1) - ctx.progress.plan(len(windows), "31일 구간") - for a, b in windows: + return windows + + def _items(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]: + """주문 내역(매출) — 31일 구간마다 진행 막대 한 칸(plan 은 부르는 쪽이 주문 + 정산 구간 수로 정한다).""" + for a, b in self._windows(start, end): rows = self._window_items(ctx, a, b) ctx.progress.step(items=len(rows)) yield from rows + def _refund_items(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]: + """정산 건별(환불이 들어 있음) — 31일 구간마다 진행 막대 한 칸.""" + for a, b in self._windows(start, end): + rows = self._settlement_items(ctx, a, b) + ctx.progress.step(items=len(rows)) + yield from rows + # ── 수집 ────────────────────────────────────────────── def fetch_orders(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]: + ctx.progress.plan(2 * len(self._windows(start, end)), "31일 구간") # 주문 내역 + 정산(환불) yield from group_orders(self._items(ctx, start, end), start, end).values() + def fetch_refunds(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]: + yield from refund_rows(self._refund_items(ctx, start, end), start, end) + + def normalize_refund(self, r: dict[str, Any]) -> list[SaleEvent]: + oid, day = str(r.get("orderId") or ""), r.get("_day") + if not oid or day is None: + return [] + return [SaleEvent( + event_type="CANCEL", external_event_id=f"{EVENT_PREFIX}R{r['orderProductId']}-{r.get('_ts') or day}"[:200], + external_order_id=oid, external_line_id=str(r.get("orderProductId") or ""), event_date=day, + order_date=r.get("order_day"), amount=-abs(int(r.get("amount") or 0)), + product_name=str(r.get("name") or "")[:200], quantity=int(r.get("qty") or 0), order_status="환불", + )] + def normalize_order(self, o: dict[str, Any]) -> list[SaleEvent]: oid, day = str(o.get("orderId") or ""), o.get("_day") if not oid or day is None: @@ -342,11 +406,18 @@ class TossAdapter(MarketplaceAdapter): 토스쇼핑 파트너스 화면 매출과 어느 항목이 맞는지 실데이터로 확정하는 용도. 개인정보 항목은 값 없이 이름만.""" self.authenticate(ctx) to = min(max(to or day, day), day + timedelta(days=PROBE_MAX_DAYS - 1)) + ctx.progress.plan(2 * len(self._windows(day, to)), "31일 구간") try: items = list(self._items(ctx, day, to)) except AdapterError as exc: return {"date": day.isoformat(), "to": to.isoformat(), "probes": [ {"key": "orders", "label": "주문 내역", "path": ORDERS_PATH, "ok": False, "error": exc.message[:300]}]} + settle_err = "" + try: + settle = list(self._refund_items(ctx, day, to)) + except AdapterError as exc: + settle, settle_err = [], exc.message[:300] + refunds = refund_rows(settle, day, to) by_status: dict[str, list[dict[str, Any]]] = {} for it in items: by_status.setdefault(str(it.get("orderProductStatus") or "?"), []).append(it) @@ -358,14 +429,34 @@ class TossAdapter(MarketplaceAdapter): " — 결제 뒤 취소·반품(매출 포함)" if st in CLAIMED_STATUS else ""), "path": "orderProductStatus", "ok": True, "count": len(rows), "fields": [f for f in summary(rows) if f["sum"] is not None]}) + if settle_err: + probes.append({"key": "settlement", "label": "정산 건별(거래일 기준 — 환불)", "path": SETTLEMENT_PATH, + "ok": False, "error": settle_err}) + else: + probes.append({"key": "settlement", "label": "정산 건별(거래일 기준, 결제·환불·배송비 줄 전체)", + "path": SETTLEMENT_PATH + " (TRANSACTION_DATE)", "ok": True, "count": len(settle), + "fields": summary(settle)}) + steps: dict[str, list[dict[str, Any]]] = {} + for it in settle: + kind = str(it.get("stepType") or "?") + ("" if it.get("orderProductId") else " · 배송비 줄") + steps.setdefault(kind, []).append(it) + for kind, rows in sorted(steps.items()): + probes.append({"key": f"step-{kind}", "label": f"정산 {kind}" + + (" — 환불(순 거래액에서 뺌)" if kind == "REFUND" else ""), + "path": "stepType", "ok": True, "count": len(rows), + "fields": [f for f in summary(rows) if f["sum"] is not None]}) days = [] orders = group_orders(items, day, to) d = day while d <= to: day_orders = [o for o in orders.values() if o["_day"] == d] - days.append({"date": d.isoformat(), "orders": len(day_orders), "amount": sum(o["amount"] for o in day_orders), - "claimed": sum(o["claimed"] for o in day_orders), "ship": sum(o["ship"] for o in day_orders)}) + sales = sum(o["amount"] for o in day_orders) + refund = sum(r["amount"] for r in refunds if r["_day"] == d) + days.append({"date": d.isoformat(), "orders": len(day_orders), "amount": sales, "claimed": refund, + "ship": sales - refund}) d += timedelta(days=1) return {"date": day.isoformat(), "to": to.isoformat(), "probes": probes, "days": days, - "rule": "주문일(orderedAt, 한국 날짜) 기준 주문상품 price(판매가 × 수량) 합 — 할인 전, 배송비 제외, " - "결제 뒤 취소·반품분 포함, 결제 전 제외. 잠정 규칙 — 토스쇼핑 파트너스 매출과 비교해 확정"} + "day_cols": {"amount": "매출(주문일)", "claimed": "환불(환불일)", "ship": "순 거래액(저장되는 매출)"}, + "rule": "순 거래액 = 매출 − 환불. 매출 = 주문일(orderedAt) 기준 주문상품 price(판매가 × 수량) 합(할인 전, " + "배송비 제외, 나중에 취소·반품된 주문 포함, 결제 전 제외). 환불 = 정산 건별 REFUND 상품 줄의 " + "orderProductPrice, 환불 거래일(transactionTs) 기준. 토스쇼핑 파트너스의 매출·환불·순 거래액과 비교"} diff --git a/app/modules/performance/templates/performance/index.html b/app/modules/performance/templates/performance/index.html index 71102cf..49aa57c 100644 --- a/app/modules/performance/templates/performance/index.html +++ b/app/modules/performance/templates/performance/index.html @@ -239,4 +239,4 @@ } | tojson }} {% endblock %} -{% block scripts %}{% endblock %} +{% block scripts %}{% endblock %} diff --git a/app/modules/performance/templates/performance/settings.html b/app/modules/performance/templates/performance/settings.html index f380e4f..9450650 100644 --- a/app/modules/performance/templates/performance/settings.html +++ b/app/modules/performance/templates/performance/settings.html @@ -124,7 +124,7 @@ · 네이버: 결제일 기준 상품주문 전체(상태별 합계 포함)와 날짜별 "현재 규칙 매출" — 스마트스토어센터 매출과 비교해 주세요.
· 11번가: 주문·클레임·정산 조회 주소별 동작 여부. 정산은 정산일 기준일 수 있어 매출이 있던 날부터 넉넉히(예: 3주).
· GS샵: 매출 내역·배송비 내역(매출인식일 기준)의 항목별 합계 — 협력사 포털 매출 화면의 같은 기간 숫자와 비교해 주세요.
- · 토스쇼핑: 주문 내역(주문일 기준, 상태별 합계 포함)과 날짜별 "현재 규칙 매출" — 토스쇼핑 파트너스 매출과 비교해 주세요.

+ · 토스쇼핑: 날짜별 매출·환불·순 거래액(= 저장되는 매출)과 주문 상태별·정산 항목 합계 — 토스쇼핑 파트너스의 같은 날 숫자와 비교해 주세요.