ff81d80cf9
- 9/6: 9/5 주문(276435356)을 9/6 취소 11,900 — 클레임 refundedDt·canceledAt 둘 다 일치, 정산 REFUND 에는 없음
- merge_refunds: 클레임(CANCEL·RETURN, isRefunded, refundedDt) + 클레임 없는 CANCELED_PAYMENT(canceledAt),
주문상품마다 한 번(toss:R{orderProductId}), 금액 = 주문상품 price(없으면 클레임 order.price), 교환·미환불 제외
- 수집 때 기간 앞 90일 주문도 불러 다른 날 주문의 환불을 잡는다, collect 직접 구현(정산 건별은 수집에 안 씀)
- 원본 데이터 확인: 환불 출처별 비교 첫 열 = 적용 규칙, 날짜별 표의 환불 = 저장되는 값
- performance.js 캐시 버전 20261001d, 테스트·문서 갱신
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
604 lines
35 KiB
Python
604 lines
35 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/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":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 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": f"{'반품' if r['type'] == 'RETURN' else '취소'} · 주문일 {r.get('order_day') or '?'}"}
|
||
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": f"정산 REFUND · 주문일 {r.get('order_day') or '?'}"} 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(), "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. 환불일 기준"}
|