01000757f3
- 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>
547 lines
32 KiB
Python
547 lines
32 KiB
Python
"""토스쇼핑 — 토스쇼핑 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) 기준. 토스쇼핑 파트너스의 매출·환불·순 거래액과 비교"}
|