Files
dbx-main/app/modules/performance/adapters/toss.py
T
king 01000757f3 feat(performance): 토스쇼핑 원본 데이터 확인에 환불 후보 3가지(정산 REFUND·주문 취소 시각·클레임 환불 완료)
- 9/6 실데이터: 매출 29,600 일치, 환불 11,900 은 정산 건별 REFUND 에 없음(다른 날 주문을 9/6 에 환불)
- 후보 ① 정산 REFUND(현재 규칙) ② orders/v2 canceledAt(기간 90일 전 주문까지) ③ claims refundedDt(isRefunded)
  — 날짜별 합계를 나란히 + 건별(주문번호·금액·메모), 화면 숫자와 같은 후보로 규칙을 정한다
- 클레임 목록 개인정보(연락처·수거 주소·요청 사유·사진) 값·합계 숨김, 송장번호 합계도 숨김
- performance.js 캐시 버전 20261001c, 테스트·문서 갱신

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

547 lines
32 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 — 정산 건별 목록 GET /api/v3/shopping-fep/settlement-steps?dateCondition=TRANSACTION_DATE&fromDate=&toDate=
&size=100&nextToken= 의 stepType=REFUND 줄(상품 줄만 — 배송비 줄은 orderProductId 가 없음). 날짜 = 환불 거래 일시
(transactionTs, 한국 날짜), 금액 = −|orderProductPrice|(정산 기준 금액, 없으면 판매가 × 수량). 결제완료 단계의 고객 취소는
클레임 목록에 안 잡히고 클레임 목록은 날짜로 거를 수 없어 정산 쪽을 쓴다. 사건 ID `toss:R{orderProductId}-{거래일시}`.
- 설정 화면 "쇼핑몰 원본 데이터 확인"에 날짜별 매출·환불·순 거래액 — 파트너스 화면과 같은지 본다.
- 구매자·수령인 이름·연락처·주소·요청사항은 저장하지 않는다.
"""
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")), "note": f"{STATUS_KO.get(status, status)} · 주문일 "
f"{kst_day(it.get('orderedAt')) or '?'}"})
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'))} · 주문일 {kst_day(order.get('createdDt')) or '?'}"})
return out
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 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:
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일)의 주문상품을 실제로 불러 항목별 합계·상태별 합계·날짜별 현재 규칙 매출을 돌려준다.
토스쇼핑 파트너스 화면 매출과 어느 항목이 맞는지 실데이터로 확정하는 용도. 개인정보 항목은 값 없이 이름만."""
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)
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]})
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]})
# ── 환불 후보 세 가지 — 파트너스 화면 "환불"과 어느 쪽이 같은지 날짜별로 나란히(실데이터로 규칙 확정용) ──
candidates: list[dict[str, Any]] = [
{"key": "settlement", "label": "① 정산 REFUND 상품 줄(거래일) — 현재 규칙", "rows": refunds, "error": settle_err}]
# ② 주문 취소 시각 — 기간보다 CANCEL_LOOKBACK_DAYS 전 주문까지 본다(다른 날 주문을 이 기간에 취소한 것)
look_from = day - timedelta(days=CANCEL_LOOKBACK_DAYS)
try:
back = [r for a, b in self._windows(look_from, day - timedelta(days=1)) for r in self._window_items(ctx, a, b)]
canceled = cancel_rows(back + items, day, to)
cand_err = ""
except AdapterError as exc:
canceled, cand_err = [], exc.message[:300]
candidates.append({"key": "canceled", "label": f"② 주문 취소 시각(canceledAt, {CANCEL_LOOKBACK_DAYS}일 전 주문까지)",
"rows": canceled, "error": cand_err})
# ③ 클레임 환불 완료 시각 — 클레임 목록은 날짜로 못 거른다(전체를 받아 refundedDt 로 거름)
try:
claims = self._claims(ctx)
claimed = claim_rows(claims, day, to)
probes.append({"key": "claims", "label": "클레임 목록(전체 — 날짜 조건 없음)", "path": CLAIMS_PATH, "ok": True,
"count": len(claims), "fields": summary(claims)})
cand_err = ""
except AdapterError as exc:
claimed, cand_err = [], exc.message[:300]
probes.append({"key": "claims", "label": "클레임 목록", "path": CLAIMS_PATH, "ok": False, "error": cand_err})
candidates.append({"key": "claims", "label": "③ 클레임 환불 완료(refundedDt, 금액 order.price)",
"rows": claimed, "error": cand_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(), "orderId": r["orderId"], "orderProductId": r["orderProductId"],
"amount": r["amount"], "note": r.get("note") or f"정산 REFUND · 주문일 {r.get('order_day') 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(판매가 × 수량) 합(할인 전, "
"배송비 제외, 나중에 취소·반품된 주문 포함, 결제 전 제외). 환불 = 정산 건별 REFUND 상품 줄의 "
"orderProductPrice, 환불 거래일(transactionTs) 기준. 토스쇼핑 파트너스의 매출·환불·순 거래액과 비교"}