Files
dbx-main/app/modules/performance/adapters/toss.py
T
king 931cc0d1d9 fix(performance): 토스쇼핑 환불 건별 표에 주문일을 메모가 아닌 별도 열로
- 원본 데이터 확인 → 환불 출처별 비교 건별 표: 환불일 · 주문일 · 주문번호 · 주문상품 · 금액 · 메모
  (예: 9/5 주문을 9/6 취소 → 환불일 9/6, 주문일 9/5), 메모에는 취소/반품·클레임 상태만
- 저장되는 환불 사건의 order_date(대시보드 금액 클릭 상세의 주문일 열)를 테스트로 확인
- performance.js 캐시 버전 20261001f

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 10:36:51 +09:00

605 lines
35 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""토스쇼핑 — 토스쇼핑 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 (
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
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),
]
# ── 인증 ──────────────────────────────────────────────
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
if tok 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))
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
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
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
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
def _claims(self, ctx: AdapterContext) -> list[dict[str, Any]]:
"""클레임 목록 전체(유형·상태 조건 없음 = 전부 — 이 API 는 그 밖엔 날짜로 거를 수 없다), nextToken 으로 끝까지."""
out: list[dict[str, Any]] = []
token = None
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
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. 환불일 기준"}