feat(performance): 토스쇼핑 매출 = 순 거래액(매출 − 환불) — 정산 건별 REFUND 를 환불일에 차감

- 사용자 지정: 토스쇼핑 파트너스 "순 거래액" 기준(9/6 화면 매출 29,600 − 환불 11,900 = 17,700)
- 환불: GET /settlement-steps dateCondition=TRANSACTION_DATE 의 stepType=REFUND 상품 줄 → CANCEL 사건,
  날짜 = transactionTs 한국 날짜, 금액 = -|orderProductPrice|, 배송비 줄 제외, 31일 구간 + nextToken
  (클레임 목록은 날짜로 거를 수 없고 결제완료 단계 고객 취소가 안 잡혀 정산 쪽을 사용)
- 원본 데이터 확인: 날짜별 매출(주문일)·환불(환불일)·순 거래액 + 정산 stepType 별 항목 합계
- 원본 확인 표의 매출 열 이름도 day_cols 로 바꿀 수 있게(performance.js), 캐시 버전 20261001b
- 테스트·문서 갱신

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-01 10:12:07 +09:00
parent a45f78217c
commit d75dec2a50
6 changed files with 176 additions and 38 deletions
+106 -15
View File
@@ -11,14 +11,17 @@
API 는 https://shopping-fep.toss.im, 헤더 Authorization: Bearer {token}. HTTP 200 + resultType FAIL 로 오류를 준다.
호출 제한: 셀러·API 별 읽기 초당 50회(넘으면 TOO_MANY_REQUEST).
매출 수집 — 주문 내역 조회 GET /api/v3/shopping-fep/orders/v2?startDate=&endDate=&limit=50&nextCursor=
(한 번에 31일까지, 상태 생략 = 전체 상태, 커서 페이지). 줄 = 주문상품(orderProductId), 묶음 = 주문(orderId).
**잠정 규칙(토스쇼핑 파트너스 화면과 대조 전)**:
- SALE = 주문 하나(`toss:{orderId}`), 날짜 = 주문 시각(orderedAt, 한국 날짜 — 토스쇼핑은 주문 = 결제).
- 금액 = 주문상품 price(판매가 × 수량) 합 — 할인 전, 배송비 제외. 할인(totalDiscountPrice = 토스쇼핑 할인 +
토스페이 할인)은 discount_amount 로만 보관. 결제 전(BEFORE_PAYMENT)만 빼고, 결제 뒤 취소·반품도 주문일 매출에 둔다
(원본 데이터 확인 표에 참고 열로 따로) → 지난 날짜 매출이 나중에 줄지 않는다(네이버와 같은 방식).
- 실데이터로 파트너스 화면 매출과 맞춰 본 뒤 규칙을 확정한다(설정 화면 "쇼핑몰 원본 데이터 확인").
매출 = 토스쇼핑 파트너스 "순 거래액" = 매출 − 환불(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}-{거래일시}`.
- 설정 화면 "쇼핑몰 원본 데이터 확인"에 날짜별 매출·환불·순 거래액 — 파트너스 화면과 같은지 본다.
- 구매자·수령인 이름·연락처·주소·요청사항은 저장하지 않는다.
"""
@@ -45,6 +48,8 @@ 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
@@ -135,6 +140,24 @@ def group_orders(items: Iterable[dict[str, Any]], start: date, end: date) -> dic
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 summary(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
"""원본 확인 표 — 항목별 채워진 줄·숫자 합계·예시 값(개인정보·자유 입력 항목은 값 숨김)."""
fields = field_summary([flatten(r) for r in rows])
@@ -293,23 +316,64 @@ class TossAdapter(MarketplaceAdapter):
break
return out
def _items(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]:
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
@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)
ctx.progress.plan(len(windows), "31일 구간")
for a, b in windows:
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:
@@ -342,11 +406,18 @@ class TossAdapter(MarketplaceAdapter):
토스쇼핑 파트너스 화면 매출과 어느 항목이 맞는지 실데이터로 확정하는 용도. 개인정보 항목은 값 없이 이름만."""
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)
@@ -358,14 +429,34 @@ class TossAdapter(MarketplaceAdapter):
" — 결제 뒤 취소·반품(매출 포함)" 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]})
days = []
orders = group_orders(items, day, to)
d = day
while d <= to:
day_orders = [o for o in orders.values() if o["_day"] == d]
days.append({"date": d.isoformat(), "orders": len(day_orders), "amount": sum(o["amount"] for o in day_orders),
"claimed": sum(o["claimed"] for o in day_orders), "ship": sum(o["ship"] for o in day_orders)})
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,
"rule": "주문일(orderedAt, 한국 날짜) 기준 주문상품 price(판매가 × 수량) 합 — 할인 전, 배송비 제외, "
"결제 뒤 취소·반품분 포함, 결제 전 제외. 잠정 규칙 — 토스쇼핑 파트너스 매출과 비교해 확정"}
"day_cols": {"amount": "매출(주문일)", "claimed": "환불(환불일)", "ship": "순 거래액(저장되는 매출)"},
"rule": "순 거래액 = 매출 − 환불. 매출 = 주문일(orderedAt) 기준 주문상품 price(판매가 × 수량) 합(할인 전, "
"배송비 제외, 나중에 취소·반품된 주문 포함, 결제 전 제외). 환불 = 정산 건별 REFUND 상품 줄의 "
"orderProductPrice, 환불 거래일(transactionTs) 기준. 토스쇼핑 파트너스의 매출·환불·순 거래액과 비교"}
@@ -239,4 +239,4 @@
} | tojson }}</script>
{% endblock %}
{% block scripts %}<script src="/static/performance.js?v=20261001a" defer></script>{% endblock %}
{% block scripts %}<script src="/static/performance.js?v=20261001b" defer></script>{% endblock %}
@@ -124,7 +124,7 @@
· <b>네이버</b>: 결제일 기준 상품주문 전체(상태별 합계 포함)와 날짜별 "현재 규칙 매출" — 스마트스토어센터 매출과 비교해 주세요.<br>
· <b>11번가</b>: 주문·클레임·정산 조회 주소별 동작 여부. 정산은 정산일 기준일 수 있어 매출이 있던 날부터 넉넉히(예: 3주).<br>
· <b>GS샵</b>: 매출 내역·배송비 내역(매출인식일 기준)의 항목별 합계 — 협력사 포털 매출 화면의 같은 기간 숫자와 비교해 주세요.<br>
· <b>토스쇼핑</b>: 주문 내역(주문일 기준, 상태별 합계 포함)과 날짜별 "현재 규칙 매출" — 토스쇼핑 파트너스 매출과 비교해 주세요.</p>
· <b>토스쇼핑</b>: 날짜별 매출·환불·순 거래액(= 저장되는 매출)과 주문 상태별·정산 항목 합계 — 토스쇼핑 파트너스의 같은 날 숫자와 비교해 주세요.</p>
<div class="perf-sample-form">
<select class="erp-input" id="perf-probe-code" aria-label="쇼핑몰">
<option value="naver">네이버 스마트스토어</option>
@@ -179,4 +179,4 @@
</section>
{% endblock %}
{% block scripts %}<script src="/static/performance.js?v=20261001a" defer></script>{% endblock %}
{% block scripts %}<script src="/static/performance.js?v=20261001b" defer></script>{% endblock %}
@@ -476,9 +476,17 @@ def test_toss_token_and_connection():
httpx.post, httpx.get, ts.CALL_INTERVAL_SEC = orig
def _toss_step(step, order_id, op_id, ts, price, *, qty=1):
"""정산 건별 목록 items[] 한 줄 — op_id None = 배송비 줄."""
return {"orderId": order_id, "orderProductId": op_id, "transactionTs": ts, "originTransactionTs": "2026-08-31T16:00:00Z",
"stepType": step, "orderProductPrice": price, "stockPrice": price // max(1, qty), "quantity": qty,
"displayProductName": "밀폐용기", "orderProductStatus": "CANCELED_PAYMENT" if step == "REFUND" else "CONFIRMED_ORDER"}
def test_toss_collect_sales():
"""토스쇼핑 매출(잠정) = 주문 단위, 주문일(한국 날짜) 기준, 주문상품 price(판매가 × 수량) 합 — 할인 전, 배송비 제외.
결제 뒤 취소·반품도 포함, 결제 전만 뺀다. 31일 구간으로 나눠 부르고 커서로 끝까지 받는다. 구매자 정보는 저장 안 함."""
"""토스쇼핑 매출 = 파트너스 "순 거래액" = 매출 − 환불(9/6 화면: 29,600 − 11,900 = 17,700).
매출 = 주문 단위, 주문일(한국 날짜), 주문상품 price 합(할인 전·배송비 제외, 나중에 취소·반품된 주문 포함, 결제 전 제외).
환불 = 정산 건별(거래일 기준) REFUND 상품 줄, 환불일. 31일 구간 + 커서. 구매자 정보는 저장 안 함."""
import httpx
from app.modules.performance.adapters import toss as ts
@@ -490,9 +498,21 @@ def test_toss_collect_sales():
_toss_item(3, 31, "2026-08-31T09:00:00", 4000, status="BEFORE_PAYMENT")], None),
("2026-09-01", None): ([_toss_item(4, 41, "2026-09-01T10:00:00", 15000, status="COMPLETED_RETURN")], None),
}
calls = []
settle = {
("2026-08-01", None): ([_toss_step("PAY", 2, 21, "2026-08-31T16:00:00Z", 9900),
_toss_step("REFUND", 2, 21, "2026-08-31T17:30:00Z", -9900)], "s2"), # 9/1 02:30 KST
("2026-08-01", "s2"): ([_toss_step("REFUND", 2, None, "2026-08-31T17:30:00Z", -3000), # 배송비 줄 → 제외
_toss_step("REFUND", 9, 91, "2026-07-31T10:00:00", -5000)], None), # 기간 밖
("2026-09-01", None): ([_toss_step("REFUND", 4, 41, "2026-09-02T09:00:00+09:00", 15000)], None),
}
calls, scalls = [], []
def get(url, params=None, headers=None, timeout=None):
if url.endswith("/settlement-steps"):
assert params["dateCondition"] == "TRANSACTION_DATE" and params["size"] == 100
scalls.append((params["fromDate"], params["toDate"], params.get("nextToken")))
rows, tok = settle.get((params["fromDate"], params.get("nextToken")), ([], None))
return httpx.Response(200, json={"resultType": "SUCCESS", "success": {"items": rows, "nextToken": tok}})
key = (params["startDate"], params.get("nextCursor"))
calls.append((params["startDate"], params["endDate"], params.get("nextCursor")))
rows, cur = pages.get(key, ([], None))
@@ -513,8 +533,19 @@ def test_toss_collect_sales():
assert r["ok"], r
assert calls == [("2026-08-01", "2026-08-31", None), ("2026-08-01", "2026-08-31", "p2"),
("2026-09-01", "2026-09-02", None)] # 31일 구간 + 커서
assert scalls == [("2026-08-01", "2026-08-31", None), ("2026-08-01", "2026-08-31", "s2"),
("2026-09-01", "2026-09-02", None)]
ev_ = {k[2]: v for k, v in st.events.items() if k[0] == "toss"}
assert set(ev_) == {"toss:1", "toss:2", "toss:4"} # 결제 전(3)만 제외
refunds = {k: v for k, v in ev_.items() if k.startswith("toss:R")}
assert set(ev_) - set(refunds) == {"toss:1", "toss:2", "toss:4"} # 결제 전(3)만 제외
assert sorted((v["amount"], v["sales_date"]) for v in refunds.values()) == [
(-15000, date(2026, 9, 2)), (-9900, date(2026, 9, 1))] # 환불일 기준, 배송비 줄·기간 밖 제외
assert all(v["event_type"] == "CANCEL" for v in refunds.values())
# 순 거래액: 9/1 = 매출 9,900(주문 2) − 환불 9,900 = 0, 9/2 = 0 − 15,000
net = {}
for v in ev_.values():
net[v["sales_date"]] = net.get(v["sales_date"], 0) + v["amount"]
assert net == {date(2026, 8, 31): 25000, date(2026, 9, 1): 15000 + 9900 - 9900, date(2026, 9, 2): -15000}
assert ev_["toss:1"]["amount"] == 25000 and ev_["toss:1"]["discount_amount"] == 1000 # 할인 전·배송비 제외
assert ev_["toss:1"]["quantity"] == 3 and ev_["toss:1"]["product_name"] == "밀폐용기 외 1건"
assert ev_["toss:1"]["sales_date"] == date(2026, 8, 31)
@@ -535,10 +566,15 @@ def test_toss_reconcile_hides_personal():
access_token_expires_at=str(int(_t.time()) + 99999)))
rows = [_toss_item(1, 11, "2026-09-09T10:00:00", 20000, ship=3000, group=1),
_toss_item(2, 21, "2026-09-09T11:00:00", 9900, status="CANCELED_PAYMENT", ship=3000, group=2)]
steps = [_toss_step("REFUND", 2, 21, "2026-09-10T11:00:00", -9900), _toss_step("REFUND", 2, None, "2026-09-10T11:00:00", -3000)]
def get(url, params=None, headers=None, timeout=None):
if url.endswith("/settlement-steps"):
return httpx.Response(200, json={"resultType": "SUCCESS", "success": {"items": steps, "nextToken": None}})
return httpx.Response(200, json={"resultType": "SUCCESS", "success": {"results": rows, "nextCursor": None}})
orig = (httpx.get, ts.CALL_INTERVAL_SEC)
httpx.get = lambda url, params=None, headers=None, timeout=None: httpx.Response(
200, json={"resultType": "SUCCESS", "success": {"results": rows, "nextCursor": None}})
ts.CALL_INTERVAL_SEC = 0
httpx.get, ts.CALL_INTERVAL_SEC = get, 0
try:
rec = ts.TossAdapter().reconcile(ctx, date(2026, 9, 9), to=date(2026, 9, 10))
finally:
@@ -551,9 +587,13 @@ def test_toss_reconcile_hides_personal():
assert f[k]["personal"] and f[k]["sample"] == "", k
assert not f["productName"]["personal"] and f["productName"]["sample"] == "밀폐용기"
assert "홍길동" not in repr(rec) and "010-1234-5678" not in repr(rec) and "010-9999-8888" not in repr(rec)
assert rec["days"] == [{"date": "2026-09-09", "orders": 2, "amount": 29900, "claimed": 9900, "ship": 6000},
{"date": "2026-09-10", "orders": 0, "amount": 0, "claimed": 0, "ship": 0}]
assert any("결제 뒤 취소·반품(매출 포함)" in p["label"] for p in rec["probes"])
# 날짜별: 매출(주문일) · 환불(환불일, 배송비 줄 제외) · 순 거래액
assert rec["days"] == [{"date": "2026-09-09", "orders": 2, "amount": 29900, "claimed": 0, "ship": 29900},
{"date": "2026-09-10", "orders": 0, "amount": 0, "claimed": 9900, "ship": -9900}]
assert rec["day_cols"]["ship"].startswith("순 거래액")
labels = [p["label"] for p in rec["probes"]]
assert any("결제 뒤 취소·반품(매출 포함)" in x for x in labels)
assert any(x.startswith("정산 REFUND — 환불") for x in labels) and any("배송비 줄" in x for x in labels)
def test_not_implemented_and_mock():
+2 -1
View File
@@ -996,7 +996,8 @@
// 날짜별 현재 규칙 매출(네이버·토스쇼핑) — 쇼핑몰 관리자 화면 매출과 나란히 비교
const days = (r.days || []).length ? '<h4 class="perf-h" style="margin:14px 0 6px">날짜별 현재 규칙 매출</h4>' +
(r.rule ? '<p class="perf-muted">규칙: ' + esc(r.rule) + "</p>" : "") +
'<table class="perf-table"><thead><tr><th class="perf-th-label">날짜</th><th>주문 수</th><th>매출</th>' +
'<table class="perf-table"><thead><tr><th class="perf-th-label">날짜</th><th>주문 수</th><th>' +
esc((r.day_cols || {}).amount || "매출") + "</th>" +
"<th>" + esc((r.day_cols || {}).claimed || "그중 결제 뒤 취소·반품(참고)") + "</th><th>" +
esc((r.day_cols || {}).ship || "배송비(참고, 매출 제외)") + "</th></tr></thead><tbody>" +
r.days.map(function (d) {
+15 -9
View File
@@ -29,7 +29,7 @@
오류 클래스 = 연결 상태: `NotConfigured`(인증정보 미설정) · `AuthFailed`(인증 실패) · `TokenExpired` · `ApiError` · `NotImplementedYet`(연동 준비 중).
**연동 현황**: 카페24·11번가·네이버 스마트스토어·GS샵·토스쇼핑 = **구현됨**(토스쇼핑은 매출 규칙 잠정), 나머지 5개는 입력칸만 정의(수집은 `NotImplementedYet`). 쇼핑몰별 입력칸은
**연동 현황**: 카페24·11번가·네이버 스마트스토어·GS샵·토스쇼핑 = **구현됨**, 나머지 5개는 입력칸만 정의(수집은 `NotImplementedYet`). 쇼핑몰별 입력칸은
**연동 단계에서 공식 API 문서로 확정**한다.
### 카페24 (`adapters/cafe24.py`, 구현됨)
@@ -147,7 +147,7 @@
**GS샵 수수료율은 0%**. 배송비 제외, `ordType` 이 SALE 이 아니면 RETURN 음수. `replace_range`.
원본 데이터 확인에 날짜별 현재 규칙 매출·취소/반품·배송비(참고).
### 토스쇼핑 (`adapters/toss.py`, 구현됨 — 매출 규칙 잠정)
### 토스쇼핑 (`adapters/toss.py`, 구현됨)
- 문서: `https://shopping-docs.toss.im/dev` (공개, 전체 목록 `llms.txt`, 쪽 주소 뒤 `.md` = 원문). 문의는 문서의 디스코드.
- 인증: 토스쇼핑 파트너스 → 상점 이름 > 가맹점·계정 관리 > **자체 개발** → [키 발급](**호출 IP 입력 — 운영 서버 외부 IP**, 등록된
@@ -162,13 +162,19 @@
전체, 커서(`nextCursor` null = 끝). 줄 = 주문상품(`orderProductId`), 주문 = `orderId`. 금액 항목: `price`(판매가 × 수량)·
`originPrice`(정상가 × 수량)·`totalDiscountPrice`(= `tossShoppingDiscount` + `tossPayDiscount`)·`tossPayPoint`·`deliveryFee`
(묶음 `deliveryFeeGroupId` 마다). 결제일 필드는 따로 없고 `orderedAt`(주문 = 결제) · `canceledAt` · `confirmedAt`.
- **매출 규칙(잠정, 파트너스 화면과 대조 전)**: SALE = 주문 하나(`toss:{orderId}`), 날짜 = `orderedAt` 의 한국 날짜, 금액 =
`price` 합(할인 전, 배송비 제외), 할인은 `discount_amount` 로만. 결제 전(`BEFORE_PAYMENT`)만 빼고 결제 뒤 취소·반품도 주문일 매출에
둔다(네이버와 같은 방식 → 지난 날짜 매출이 나중에 줄지 않음). `replace_range`. 개인정보(주문자·수령인·주소·요청사항·송장)는 저장 안 함.
- 정산 API `GET /settlement-steps`(`dateCondition` PAYOUT_DATE·PAYOUT_BASE_DATE·TRANSACTION_DATE…, 31일, `stepType` PAY|REFUND,
셀러 부담 쿠폰 `shoppingDiscountMerchant`, 정산 지급액 `settlementAmount`)은 구매확정·취소된 건만 나온다 — 규칙 확정 때 필요하면 쓴다.
- 확정 방법: 설정 화면 "쇼핑몰 원본 데이터 확인" → 토스쇼핑, 매출이 있던 기간 → 날짜별 현재 규칙 매출·상태별 항목 합계를 토스쇼핑
파트너스 매출 화면과 비교해 맞는 항목(`price` / `price − totalDiscountPrice` / 취소 제외 여부)으로 규칙을 고친다.
- **매출 규칙 = 파트너스 "순 거래액" = 매출 − 환불**(2026-10-01 사용자 지정, 9/6 화면: 매출 29,600 − 환불 11,900 = 순 거래액 17,700).
- 매출 SALE = 주문 하나(`toss:{orderId}`), 날짜 = `orderedAt` 의 한국 날짜, 금액 = `price` 합(할인 전, 배송비 제외), 할인은
`discount_amount` 로만. 결제 전(`BEFORE_PAYMENT`)만 빼고 나중에 취소·반품된 주문도 주문일 매출에 둔다(화면 "매출"도 환불 전).
- 환불 CANCEL = 정산 건별 `GET /api/v3/shopping-fep/settlement-steps?dateCondition=TRANSACTION_DATE&fromDate&toDate&size=100&nextToken`
(31일, 결제·환불·배송비 줄)의 **`stepType=REFUND` 상품 줄**(배송비 줄 = `orderProductId` 없음 → 제외), 날짜 = 환불 거래 일시
`transactionTs` 의 한국 날짜, 금액 = −|`orderProductPrice`|(없으면 판매가 × 수량). 사건 ID `toss:R{orderProductId}-{거래일시}`.
클레임 목록 API 는 날짜로 거를 수 없고(REQUESTED·REVOKED 만 7일 조회) 결제완료 단계의 고객 취소는 클레임으로 안 잡혀서 쓰지 않는다.
- `replace_range`(접두어 `toss:` — 매출·환불 함께 교체). 진행 막대 = 주문 + 정산 31일 구간 수. 개인정보(주문자·수령인·주소·요청사항·
송장)는 저장 안 함.
- 정산 줄의 다른 항목: 셀러 부담 쿠폰 `shoppingDiscountMerchant`, 정산 지급액 `settlementAmount`, 수수료 `payFee`·`productFee`.
- 대조: 설정 화면 "쇼핑몰 원본 데이터 확인" → 토스쇼핑 — 날짜별 **매출(주문일)·환불(환불일)·순 거래액**(`day_cols`)과 주문 상태별·
정산 stepType 별 항목 합계. 파트너스 화면 숫자와 다르면 금액 항목(`price` / `price − totalDiscountPrice`, 환불 `orderProductPrice` /
`orderProductPaidAmount`)이나 날짜 기준을 여기서 보고 고친다(실데이터 대조는 아직 — 운영 서버 IP 에서만 호출됨).
### 연동 단계 체크리스트(쇼핑몰마다)