"""토스쇼핑 — 토스쇼핑 API(shopping-fep). 문서: https://shopping-docs.toss.im/dev (전체 목록 llms.txt, 각 쪽 주소 뒤에 .md 를 붙이면 원문) 인증(공식 방식): 토스쇼핑 파트너스 → 상점 이름 > 가맹점·계정 관리 > 자체 개발 → [키 발급](호출 IP 입력) → Access Key·Secret Key. OAuth2 client_credentials 로 토큰을 받는다. POST https://oauth2.cert.toss.im/token (form: grant_type=client_credentials, client_id=Access Key, client_secret=Secret Key, scope=toss-shopping-fep:write) 응답 expires_in 은 약 1년 — 매번 새로 받으면 이용이 제한될 수 있어(문서 안내) 암호화 저장해 두고 재사용, 401 이면 한 번만 새로 받는다. **키 발급 때 넣은 IP(이 서버 외부 IP)에서만 호출된다.** API 는 https://shopping-fep.toss.im, 헤더 Authorization: Bearer {token}. HTTP 200 + resultType FAIL 로 오류를 준다. 호출 제한: 셀러·API 별 읽기 초당 50회(넘으면 TOO_MANY_REQUEST). 매출 = 토스쇼핑 파트너스 "순 거래액" = 매출 − 환불(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/RETURN — 환불일에 뺀다. 주문상품 하나에 한 번(사건 ID `toss:R{orderProductId}`). `merge_refunds`: ① 클레임 목록 GET /api/v3/shopping-fep/claims(날짜 조건이 없어 전체를 넘긴다)의 환불 완료(isRefunded) CANCEL·RETURN — 날짜 = refundedDt(한국 날짜). 반품은 이것뿐(주문 내역엔 반품 완료 날짜가 없다). ② 클레임이 없는 결제취소 — 주문 내역의 canceledAt(한국 날짜). 결제완료 단계의 고객 취소는 클레임이 생기지 않는다(문서). 기간보다 CANCEL_LOOKBACK_DAYS(90)일 앞 주문까지 불러 다른 날 주문을 기간 안에 취소한 것도 잡는다. 금액 = 그 주문상품의 price(판매가 × 수량, 매출과 같은 기준), 주문 내역에 없으면(90일보다 오래된 주문) 클레임 order.price. 9/6 실데이터: 9/5 주문(276435356)을 9/6 취소 11,900 — 클레임(CANCEL/COMPLETED)·canceledAt 둘 다 9/6 = 화면 환불 11,900. 정산 건별(settlement-steps)의 REFUND 는 이 취소를 담지 않아(구매확정 전 취소는 정산에 안 올라옴) 쓰지 않는다. - 설정 화면 "쇼핑몰 원본 데이터 확인"에 날짜별 매출·환불·순 거래액과 환불 출처별(정산·취소 시각·클레임) 비교. - 구매자·수령인 이름·연락처·주소·요청사항은 저장하지 않는다. """ from __future__ import annotations import re import time from datetime import date, datetime, timedelta, timezone from typing import Any, Iterable from .base import ( credential_fingerprint, AdapterContext, AdapterError, ApiError, AuthFailed, CredentialField, MarketplaceAdapter, NotConfigured, SaleEvent, TokenExpired, ) 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 WINDOW_DAYS = 31 # 한 번에 31일까지 MAX_PAGES = 2000 # 한 구간 10만 건 — 무한 반복 방지 TOKEN_MARGIN_SEC = 3600 # 만료 1시간 전이면 새로 받는다(토큰은 약 1년) CALL_INTERVAL_SEC = 0.1 # 읽기 초당 50회 제한 — 넉넉히 RETRY_429 = 3 PROBE_MAX_DAYS = 31 KST = timezone(timedelta(hours=9)) # 결제 전 주문만 매출에서 뺀다. 결제 뒤 취소·반품은 주문일 매출에 두고 원본 확인 표에 참고로 따로 보인다. EXCLUDED_STATUS = frozenset({"BEFORE_PAYMENT"}) CLAIMED_STATUS = frozenset({"CANCELED_PAYMENT", "COMPLETED_RETURN"}) STATUS_KO = { "BEFORE_PAYMENT": "결제전", "PAID": "결제완료", "PREPARING_PRODUCT": "상품준비중", "DELIVERING": "배송중", "DELIVERED": "배송완료", "CONFIRMED_ORDER": "구매확정", "CLAIM_REQUESTED_CANCEL": "취소요청", "CANCELED_PAYMENT": "결제취소", "CLAIM_REJECTED_CANCEL": "취소거절", "REQUESTED_EXCHANGE": "교환요청", "ONGOING_EXCHANGE": "교환중", "COMPLETED_EXCHANGE": "교환완료", "CLAIM_REJECTED_EXCHANGE": "교환거절", "REQUESTED_RETURN": "반품요청", "ONGOING_RETURN": "반품중", "COMPLETED_RETURN": "반품완료", "CLAIM_REJECTED_RETURN": "반품거절", "CLAIM_COLLECTING": "수거중", "CLAIM_COLLECTED": "수거완료", "CLAIM_DELIVERING": "재배송중", } # 원본 데이터 확인에서 값을 숨기는 항목(개인정보·자유 입력) PERSONAL_KEYS = frozenset({ "ordererName", "ordererPhone", "ordererRealPhone", "receiverName", "receiverPhone", "receiverRealPhone", "address", "detailAddress", "zipCode", "shippingNote", "shippingTrackingNumber", # 클레임 목록(order.* · 수거 주소 · 요청 사유 자유 입력 · 첨부 사진) "ordererPhoneNumber", "receiverPhoneNumber", "returnAddress", "requestReason", "requestDetailReason", "requestImages[]", }) CLAIMS_PATH = "/api/v3/shopping-fep/claims" CLAIM_PAGE_SIZE = 100 CLAIM_MAX_PAGES = 100 # 클레임 목록은 날짜로 못 거른다(전체를 넘긴다) — 1만 건까지 CANCEL_LOOKBACK_DAYS = 90 # 환불 후보(주문 취소 시각): 이만큼 전 주문까지 본다 def _won(value: Any) -> int: try: return int(round(float(str(value if value is not None else 0).replace(",", "")))) except ValueError: return 0 def kst_day(value: Any) -> date | None: """주문 시각 → 한국 날짜. 시간대가 붙어 있으면(Z, +00:00 …) 한국 시간으로 바꾸고, 없으면 한국 시간으로 본다.""" s = str(value or "").strip() if not s: return None try: dt = datetime.fromisoformat(s.replace("Z", "+00:00")) except ValueError: m = re.match(r"(\d{4})-(\d{2})-(\d{2})", s) if not m: return None try: return date(int(m.group(1)), int(m.group(2)), int(m.group(3))) except ValueError: return None if dt.tzinfo is not None: dt = dt.astimezone(KST) return dt.date() def group_orders(items: Iterable[dict[str, Any]], start: date, end: date) -> dict[str, dict[str, Any]]: """주문상품 → 주문 하나로 합침(주문일이 [start, end] 이고 결제된 것 — 나중에 취소·반품된 것도 포함). 금액 = price(판매가 × 수량) 합(할인 전, 배송비 제외). 할인·배송비·취소/반품분은 참고용으로 모은다. 배송비는 묶음(deliveryFeeGroupId)마다 한 번만 센다.""" orders: dict[str, dict[str, Any]] = {} ship_groups: set[str] = set() for it in items: oid = str(it.get("orderId") or "") day = kst_day(it.get("orderedAt")) status = str(it.get("orderProductStatus") or "") if not oid or day is None or not (start <= day <= end) or status in EXCLUDED_STATUS: continue o = orders.setdefault(oid, {"orderId": oid, "_day": day, "amount": 0, "ship": 0, "claimed": 0, "qty": 0, "discount": 0, "names": [], "opt": "", "statuses": []}) price = _won(it.get("price")) o["amount"] += price if status in CLAIMED_STATUS: o["claimed"] += price group = str(it.get("deliveryFeeGroupId") or f"{oid}-{it.get('orderProductId')}") if group not in ship_groups: ship_groups.add(group) o["ship"] += _won(it.get("deliveryFee")) o["qty"] += _won(it.get("quantity")) o["discount"] += _won(it.get("totalDiscountPrice")) name = str(it.get("productName") or "") if name and name not in o["names"]: o["names"].append(name) o["opt"] = o["opt"] or str(it.get("optionName") or "") if status and status not in o["statuses"]: o["statuses"].append(status) 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 cancel_rows(items: Iterable[dict[str, Any]], start: date, end: date) -> list[dict[str, Any]]: """환불 후보 — 주문 내역의 취소 시각(canceledAt 한국 날짜)이 [start, end] 인 주문상품. 금액 = price(판매가 × 수량).""" out = [] for it in items: day = kst_day(it.get("canceledAt")) if not it.get("orderId") or day is None or not (start <= day <= end): continue status = str(it.get("orderProductStatus") or "") out.append({"orderId": str(it["orderId"]), "orderProductId": str(it.get("orderProductId") or ""), "_day": day, "amount": _won(it.get("price")), "status": status, "note": STATUS_KO.get(status, status), "order_day": kst_day(it.get("orderedAt"))}) return out def claim_rows(items: Iterable[dict[str, Any]], start: date, end: date) -> list[dict[str, Any]]: """환불 후보 — 클레임 목록의 환불 완료(isRefunded, refundedDt 한국 날짜)가 [start, end] 인 것. 금액 = order.price(문서: "상품 가격" — 수량을 곱한 값인지 실데이터로 확인), 수량은 note 에.""" out = [] for it in items: day = kst_day(it.get("refundedDt")) order = it.get("order") if isinstance(it.get("order"), dict) else {} product = it.get("product") if isinstance(it.get("product"), dict) else {} if not it.get("isRefunded") or day is None or not (start <= day <= end) or not order.get("id"): continue out.append({"orderId": str(order["id"]), "orderProductId": str(order.get("orderProductId") or ""), "_day": day, "amount": _won(order.get("price")), "note": f"{it.get('type') or '?'}/{it.get('status') or '?'} · " f"수량 {_won(product.get('quantity'))}", "order_day": kst_day(order.get("createdDt"))}) return out def merge_refunds(order_items: Iterable[dict[str, Any]], claims: Iterable[dict[str, Any]], start: date, end: date) -> list[dict[str, Any]]: """환불 규칙 — 클레임 환불 완료(CANCEL·RETURN, refundedDt) + 클레임이 없는 결제취소(canceledAt), 주문상품마다 한 번. 금액은 주문 내역의 price(판매가 × 수량)를 우선(없으면 클레임 order.price). 날짜가 [start, end] 인 것만. 클레임이 있는 주문상품은 그 클레임 날짜만 쓴다(기간 밖이어도 취소 시각으로 다시 넣지 않음 — 날짜가 바뀌지 않게).""" order_items = list(order_items) by_op = {str(it.get("orderProductId")): it for it in order_items if it.get("orderProductId")} out: dict[str, dict[str, Any]] = {} claimed_ops: set[str] = set() for c in claims: order = c.get("order") if isinstance(c.get("order"), dict) else {} product = c.get("product") if isinstance(c.get("product"), dict) else {} kind = str(c.get("type") or "") op = str(order.get("orderProductId") or "") if not c.get("isRefunded") or kind not in ("CANCEL", "RETURN") or not order.get("id") or not op: continue claimed_ops.add(op) day = kst_day(c.get("refundedDt")) if day is None or not (start <= day <= end) or op in out: continue it = by_op.get(op) or {} out[op] = {"orderId": str(order["id"]), "orderProductId": op, "_day": day, "type": kind, "amount": _won(it["price"]) if "price" in it else _won(order.get("price")), "qty": _won(it.get("quantity")) or _won(product.get("quantity")), "name": str(it.get("productName") or product.get("name") or ""), "order_day": kst_day(it.get("orderedAt") or order.get("createdDt"))} for r in cancel_rows(order_items, start, end): op = r["orderProductId"] if not op or op in claimed_ops or op in out or r["status"] != "CANCELED_PAYMENT": continue it = by_op.get(op) or {} out[op] = {"orderId": r["orderId"], "orderProductId": op, "_day": r["_day"], "type": "CANCEL", "amount": r["amount"], "qty": _won(it.get("quantity")), "name": str(it.get("productName") or ""), "order_day": kst_day(it.get("orderedAt"))} return sorted(out.values(), key=lambda x: (x["_day"], x["orderId"], x["orderProductId"])) def summary(rows: list[dict[str, Any]]) -> list[dict[str, Any]]: """원본 확인 표 — 항목별 채워진 줄·숫자 합계·예시 값(개인정보·자유 입력 항목은 값·합계 숨김).""" fields = field_summary([flatten(r) for r in rows]) for f in fields: if f["name"].rsplit(".", 1)[-1] in PERSONAL_KEYS: f["personal"], f["sample"], f["sum"] = True, "", None return fields # 토큰을 발급한 인증정보 — 이 값들이 바뀌면 저장된 토큰을 쓰지 않고 새로 받는다(credential_fingerprint) TOKEN_KEYS = ("api_key", "api_secret") class TossAdapter(MarketplaceAdapter): code = "toss" name = "토스쇼핑" auth_type = "oauth" implemented = True replace_range = True event_prefix = EVENT_PREFIX docs_url = "https://shopping-docs.toss.im/dev" note = ("토스쇼핑 파트너스 → 가맹점·계정 관리 → 자체 개발에서 발급한 Access Key·Secret Key 를 입력합니다. " "키 발급 때 이 서버의 외부 IP 를 등록해야 호출됩니다.") def __init__(self) -> None: self._last_call = 0.0 def credential_fields(self) -> list[CredentialField]: # 키 이름(api_key·api_secret)은 처음 만든 입력칸 그대로 — 이미 저장한 값이 이어진다. return [ CredentialField("api_key", "Access Key", secret=True, help="토스쇼핑 파트너스 → 가맹점·계정 관리 → 자체 개발의 Access Key"), CredentialField("api_secret", "Secret Key", secret=True, help="같은 화면의 Secret Key"), CredentialField("access_token", "Access Token", secret=True, required=False, internal=True), CredentialField("access_token_expires_at", "Access Token 만료", required=False, internal=True), # 토큰을 발급한 인증정보 지문(원문 아님) — 계정·키를 바꾸면 이전 토큰을 쓰지 않는다(2026-10-15 검토 F04) CredentialField("access_token_for", "Access Token 발급 기준", required=False, internal=True), ] # ── 인증 ────────────────────────────────────────────── def _token(self, ctx: AdapterContext, *, force: bool = False) -> str: """저장된 토큰이 1시간 넘게 남았으면 그대로, 아니면 새로 받아 암호화 저장.""" if not force: tok = ctx.credentials.get("access_token") try: exp = float(ctx.credentials.get("access_token_expires_at") or 0) except ValueError: exp = 0.0 same_account = ctx.credentials.get("access_token_for") == credential_fingerprint(ctx.credentials, TOKEN_KEYS) if tok and same_account and exp - time.time() > TOKEN_MARGIN_SEC: return tok return self._issue_token(ctx) def _issue_token(self, ctx: AdapterContext) -> str: import httpx # 지연 import access_key = ctx.credentials.get("api_key").strip() secret_key = ctx.credentials.get("api_secret").strip() if not access_key or not secret_key: raise NotConfigured("Access Key 와 Secret Key 를 입력하세요.") form = {"grant_type": "client_credentials", "client_id": access_key, "client_secret": secret_key, "scope": SCOPE} try: res = httpx.post(TOKEN_URL, data=form, timeout=ctx.timeout_sec, headers={"Accept": "application/json; charset=UTF-8"}) except httpx.HTTPError as exc: raise ApiError(f"토스 인증 서버 연결 실패: {type(exc).__name__}") from None body = self._json(res) if res.status_code >= 400 or not body.get("access_token"): msg = self._err_text(body, res) if res.status_code in (400, 401, 403): raise AuthFailed(f"토스쇼핑 토큰 발급 실패({res.status_code}): {msg}. Access Key·Secret Key 와 " "키 발급 때 등록한 IP(이 서버 외부 IP)를 확인하세요.") raise ApiError(f"토스쇼핑 토큰 발급 오류({res.status_code}): {msg}") tok = str(body["access_token"]) expires_in = _won(body.get("expires_in")) or 24 * 3600 ctx.credentials.set("access_token", tok) ctx.credentials.set("access_token_expires_at", str(int(time.time()) + expires_in)) ctx.credentials.set("access_token_for", credential_fingerprint(ctx.credentials, TOKEN_KEYS)) return tok def authenticate(self, ctx: AdapterContext) -> None: super().authenticate(ctx) self._token(ctx) def refresh_token(self, ctx: AdapterContext) -> None: self._token(ctx, force=True) # ── 호출 ────────────────────────────────────────────── @staticmethod def _json(res: Any) -> dict[str, Any]: try: body = res.json() except ValueError: return {} return body if isinstance(body, dict) else {"data": body} @staticmethod def _err_text(body: dict[str, Any], res: Any) -> str: err = body.get("error") if isinstance(err, dict): parts = [str(err.get(k)) for k in ("errorCode", "errorType", "reason", "message") if err.get(k)] else: parts = [str(body.get(k)) for k in ("error", "error_description", "code", "message") if body.get(k)] return " ".join(parts)[:300] or res.text[:200].strip() or "응답 없음" def _get(self, ctx: AdapterContext, path: str, params: dict[str, Any]) -> dict[str, Any]: """GET — 호출 간격 유지, 429·TOO_MANY_REQUEST 는 잠깐 쉬고 다시, 401 이면 토큰을 새로 받아 한 번 더. 성공이면 success 내용을 돌려준다(토스쇼핑은 HTTP 200 + resultType FAIL 로도 오류를 준다).""" import httpx # 지연 import retried_auth = False for attempt in range(RETRY_429 + 1): ctx.progress.check() # [업데이트 취소]면 여기서 멈춤 wait = CALL_INTERVAL_SEC - (time.monotonic() - self._last_call) if wait > 0: time.sleep(wait) headers = {"Authorization": f"Bearer {self._token(ctx)}", "Accept": "application/json"} try: res = httpx.get(f"{HOST}{path}", params=params, headers=headers, timeout=ctx.timeout_sec) except httpx.HTTPError as exc: raise ApiError(f"토스쇼핑 API 연결 실패: {type(exc).__name__}") from None finally: self._last_call = time.monotonic() body = self._json(res) err = body.get("error") if isinstance(body.get("error"), dict) else {} limited = res.status_code == 429 or "TOO_MANY" in str(err.get("errorCode") or err.get("errorType") or "") if limited and attempt < RETRY_429: time.sleep(1.0 * (2 ** attempt)) continue if res.status_code == 401 and not retried_auth: retried_auth = True self._token(ctx, force=True) continue if res.status_code == 401: raise TokenExpired(f"토스쇼핑 인증 만료·거부(401): {self._err_text(body, res)}") if res.status_code == 403: raise AuthFailed(f"토스쇼핑 권한 거부(403): {self._err_text(body, res)}. 키 발급 때 등록한 IP" "(이 서버 외부 IP)를 확인하세요.") if limited: raise ApiError("토스쇼핑 API 호출 제한이 계속됩니다. 잠시 뒤 다시 시도하세요.") if res.status_code >= 400: raise ApiError(f"토스쇼핑 API 오류({res.status_code}): {self._err_text(body, res)}") if body.get("resultType") == "FAIL": raise ApiError(f"토스쇼핑 API 오류: {self._err_text(body, res)}") success = body.get("success") return success if isinstance(success, dict) else {} raise ApiError("토스쇼핑 API 호출 제한이 계속됩니다. 잠시 뒤 다시 시도하세요.") def _window_items(self, ctx: AdapterContext, a: date, b: date) -> list[dict[str, Any]]: """조회 기간 [a, b](31일 이하)의 주문상품 전체 — 모든 상태, 커서로 끝까지.""" params: dict[str, Any] = {"startDate": a.isoformat(), "endDate": b.isoformat(), "limit": PAGE_SIZE} out: list[dict[str, Any]] = [] cursor = None seen: set[str] = set() for _ in range(MAX_PAGES): body = self._get(ctx, ORDERS_PATH, {**params, **({"nextCursor": cursor} if cursor else {})}) rows = [r for r in body.get("results") or [] if isinstance(r, dict)] out.extend(rows) cursor = body.get("nextCursor") if not cursor or not rows: break if str(cursor) in seen: # 커서 반복 — 끝까지 받았는지 알 수 없다(검토 F05) raise ApiError(f"토스 주문 {a.isoformat()}~{b.isoformat()} 다음 쪽 표시가 반복됩니다 — 저장하지 않았습니다.") seen.add(str(cursor)) else: raise ApiError(f"토스 주문 {a.isoformat()}~{b.isoformat()} 이 {MAX_PAGES}쪽을 넘어 끝까지 받지 못했습니다 — 저장하지 않았습니다.") return out 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 seen: set[str] = set() 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 if str(token) in seen: # 커서 반복 — 끝까지 받았는지 알 수 없다(검토 F05) raise ApiError(f"토스 정산 {a.isoformat()}~{b.isoformat()} 다음 쪽 표시가 반복됩니다 — 저장하지 않았습니다.") seen.add(str(token)) else: raise ApiError(f"토스 정산 {a.isoformat()}~{b.isoformat()} 이 {MAX_PAGES}쪽을 넘어 끝까지 받지 못했습니다 — 저장하지 않았습니다.") return out def _claims(self, ctx: AdapterContext) -> list[dict[str, Any]]: """클레임 목록 전체(유형·상태 조건 없음 = 전부 — 이 API 는 그 밖엔 날짜로 거를 수 없다), nextToken 으로 끝까지.""" out: list[dict[str, Any]] = [] token = None seen: set[str] = set() for _ in range(CLAIM_MAX_PAGES): body = self._get(ctx, CLAIMS_PATH, {"size": CLAIM_PAGE_SIZE, **({"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 or body.get("hasNext") is False: break if str(token) in seen: # 커서 반복 — 끝까지 받았는지 알 수 없다(검토 F05) raise ApiError("토스 클레임 목록의 다음 쪽 표시가 반복됩니다 — 저장하지 않았습니다.") seen.add(str(token)) else: raise ApiError(f"토스 클레임 목록이 {CLAIM_MAX_PAGES}쪽을 넘어 끝까지 받지 못했습니다 — 저장하지 않았습니다.") 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) 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 _lookback_items(self, ctx: AdapterContext, start: date) -> list[dict[str, Any]]: """기간 앞 CANCEL_LOOKBACK_DAYS 일의 주문상품 — 다른 날 주문을 기간 안에 취소한 것을 찾는 용도.""" out: list[dict[str, Any]] = [] for a, b in self._windows(start - timedelta(days=CANCEL_LOOKBACK_DAYS), start - timedelta(days=1)): rows = self._window_items(ctx, a, b) ctx.progress.step(items=len(rows)) out.extend(rows) return out def _plan(self, ctx: AdapterContext, start: date, end: date, extra: int = 0) -> None: """진행 막대: 기간 주문 구간 + 앞 90일 주문 구간 + 클레임 목록 1단계 (+ 원본 확인의 정산 구간).""" back = len(self._windows(start - timedelta(days=CANCEL_LOOKBACK_DAYS), start - timedelta(days=1))) ctx.progress.plan(len(self._windows(start, end)) + back + 1 + extra, "단계") def _claims_step(self, ctx: AdapterContext) -> list[dict[str, Any]]: claims = self._claims(ctx) ctx.progress.step(items=len(claims)) return claims # ── 수집 ────────────────────────────────────────────── def collect(self, ctx: AdapterContext, start: date, end: date) -> tuple[int, list[SaleEvent]]: """매출(주문일) + 환불(환불일, merge_refunds). 주문 내역은 환불 금액·취소 시각에도 쓰여 한 번만 부른다.""" self.authenticate(ctx) self._plan(ctx, start, end) items = list(self._items(ctx, start, end)) back = self._lookback_items(ctx, start) claims = self._claims_step(ctx) events: list[SaleEvent] = [] for o in group_orders(items, start, end).values(): events.extend(self.normalize_order(o)) for r in merge_refunds(back + items, claims, start, end): events.extend(self.normalize_refund(r)) for ev in events: ev.validate() return len(items) + len(claims), events 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 or not r.get("orderProductId"): return [] kind = "RETURN" if r.get("type") == "RETURN" else "CANCEL" return [SaleEvent( event_type=kind, external_event_id=f"{EVENT_PREFIX}R{r['orderProductId']}", external_order_id=oid, external_line_id=str(r["orderProductId"]), 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="반품 환불" if kind == "RETURN" else "취소 환불", )] 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: return [] names = o.get("names") or [] name = names[0] + (f" 외 {len(names) - 1}건" if len(names) > 1 else "") if names else "" statuses = [STATUS_KO.get(s, s) for s in o.get("statuses") or []] return [SaleEvent( event_type="SALE", external_event_id=f"{EVENT_PREFIX}{oid}", external_order_id=oid, order_date=day, payment_date=day, event_date=day, amount=max(0, int(o.get("amount") or 0)), product_name=name[:200], option_name=str(o.get("opt") or "")[:200], quantity=int(o.get("qty") or 0), discount_amount=max(0, int(o.get("discount") or 0)), order_status="/".join(statuses)[:50], )] def test_connection(self, ctx: AdapterContext) -> str: from app.timezone import today_kst # noqa: WPS433 # 입력한 새 값으로 시험할 수 있으니 저장된 토큰을 쓰지 않고 항상 새로 받는다. super().authenticate(ctx) self._token(ctx, force=True) today = today_kst() body = self._get(ctx, ORDERS_PATH, {"startDate": today.isoformat(), "endDate": today.isoformat(), "limit": 1}) n = len(body.get("results") or []) more = " 이상" if body.get("nextCursor") else "" return f"토스쇼핑 API 연결 정상(토큰 발급·주문 조회 확인, 오늘 주문상품 {n}건{more})." # ── 원본 데이터 확인(설정 화면 "쇼핑몰 원본 데이터 확인") ───────── def reconcile(self, ctx: AdapterContext, day: date, to: date | None = None) -> dict[str, Any]: """기간(최대 31일)을 실제로 불러 항목별 합계·상태별 합계와 날짜별 매출·환불·순 거래액(= 저장되는 값)을 돌려준다. 환불은 출처별(클레임 환불 완료·주문 취소 시각·정산 REFUND)로도 나란히 보여 파트너스 화면과 맞춰 볼 수 있게. 개인정보 항목은 값 없이 이름만. 저장하지 않는다.""" self.authenticate(ctx) to = min(max(to or day, day), day + timedelta(days=PROBE_MAX_DAYS - 1)) self._plan(ctx, day, to, extra=len(self._windows(day, to))) try: items = list(self._items(ctx, day, to)) back = self._lookback_items(ctx, day) except AdapterError as exc: return {"date": day.isoformat(), "to": to.isoformat(), "probes": [ {"key": "orders", "label": "주문 내역", "path": ORDERS_PATH, "ok": False, "error": exc.message[:300]}]} by_status: dict[str, list[dict[str, Any]]] = {} for it in items: by_status.setdefault(str(it.get("orderProductStatus") or "?"), []).append(it) probes = [{"key": "orders", "label": "주문 내역(전체 상태, 주문상품 단위)", "path": ORDERS_PATH, "ok": True, "count": len(items), "fields": summary(items)}] for st, rows in sorted(by_status.items()): probes.append({"key": f"status-{st}", "label": f"상태 {STATUS_KO.get(st, st)}({st})" + (" — 매출 제외(결제 전)" if st in EXCLUDED_STATUS else " — 결제 뒤 취소·반품(매출 포함)" 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]}) claims_err = "" try: claims = self._claims_step(ctx) probes.append({"key": "claims", "label": "클레임 목록(전체 — 날짜 조건 없음)", "path": CLAIMS_PATH, "ok": True, "count": len(claims), "fields": summary(claims)}) except AdapterError as exc: claims, claims_err = [], exc.message[:300] probes.append({"key": "claims", "label": "클레임 목록", "path": CLAIMS_PATH, "ok": False, "error": claims_err}) settle_err = "" try: settle = list(self._refund_items(ctx, day, to)) probes.append({"key": "settlement", "label": "정산 건별(거래일 기준, 결제·환불·배송비 줄 전체 — 참고)", "path": SETTLEMENT_PATH + " (TRANSACTION_DATE)", "ok": True, "count": len(settle), "fields": summary(settle)}) except AdapterError as exc: settle, settle_err = [], exc.message[:300] probes.append({"key": "settlement", "label": "정산 건별(참고)", "path": SETTLEMENT_PATH, "ok": False, "error": settle_err}) refunds = merge_refunds(back + items, claims, day, to) # 저장되는 환불(현재 규칙) # ── 환불 출처별 — 파트너스 화면 "환불"과 맞춰 보는 용도 ── candidates: list[dict[str, Any]] = [ {"key": "rule", "label": "적용 규칙(클레임 환불 + 클레임 없는 결제취소)", "rows": [ {**r, "note": "반품" if r["type"] == "RETURN" else "취소"} for r in refunds], "error": claims_err}, {"key": "claims", "label": "클레임 환불 완료(refundedDt, 금액 order.price)", "rows": claim_rows(claims, day, to), "error": claims_err}, {"key": "canceled", "label": f"주문 취소 시각(canceledAt, {CANCEL_LOOKBACK_DAYS}일 전 주문까지)", "rows": cancel_rows(back + items, day, to), "error": ""}, {"key": "settlement", "label": "정산 REFUND 상품 줄(거래일) — 참고", "rows": [ {**r, "note": "정산 REFUND"} for r in refund_rows(settle, day, to)], "error": settle_err}, ] for c in candidates: c["days"] = {} for r in c["rows"]: k = r["_day"].isoformat() c["days"][k] = c["days"].get(k, 0) + r["amount"] c["rows"] = [{"date": r["_day"].isoformat(), "orderDate": r["order_day"].isoformat() if r.get("order_day") else "", "orderId": r["orderId"], "orderProductId": r["orderProductId"], "amount": r["amount"], "note": r.get("note") or ""} for r in sorted(c["rows"], key=lambda x: (x["_day"], x["orderId"]))][:200] days = [] orders = group_orders(items, day, to) d = day while d <= to: day_orders = [o for o in orders.values() if o["_day"] == d] 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, "refund_candidates": candidates, "day_cols": {"amount": "매출(주문일)", "claimed": "환불(환불일)", "ship": "순 거래액(저장되는 매출)"}, "rule": "순 거래액 = 매출 − 환불. 매출 = 주문일(orderedAt) 기준 주문상품 price(판매가 × 수량) 합(할인 전, " "배송비 제외, 나중에 취소·반품된 주문 포함, 결제 전 제외). 환불 = 클레임 환불 완료(취소·반품, refundedDt) + " "클레임 없는 결제취소(canceledAt), 주문상품마다 한 번, 금액 = 그 주문상품 price. 환불일 기준"}