feat(performance): 11번가 매출 수집 — 주문 상태 목록 기준, 결제일·판매금액+배송비

"11번가 원본 데이터 확인"(9/9~9/29) 실데이터로 확정:
- 주문 상태 목록(결제완료·발송대기·배송중·배송완료)은 지금 그 상태인 주문만 주고,
  배송완료 목록에 구매확정 주문도 남는다. 취소된 주문은 취소완료 목록으로 빠진다
- ordAmt − ordPayAmt = 11번가 부담 쿠폰(tmallApplyDscAmt 11,060), 수수료는
  판매금액 기준(34,900 × 13% = 4,537)

- fetch_orders: 목록 4개를 [기간, 기간+30일(오늘까지)] 7일씩 불러 주문일(결제일)이
  기간 안인 줄만, 주문번호+순번 중복 제거
- SALE 금액 = ordAmt + 배송비(주문번호마다 최댓값을 가장 앞 줄에 한 번),
  ordAmt − ordPayAmt 는 discount_amount 에. 구매자 정보는 raw 에 넣지 않음
- replace_range(11st: 접두어) — 다시 받으면 취소·반품된 주문이 빠진다
- "해당 건이 없습니다"(-1)는 0건. 테스트 추가, 미구현 시험은 G마켓으로

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-09-30 01:20:18 +09:00
parent 7d96f2e738
commit 40d94e2892
3 changed files with 178 additions and 10 deletions
+104 -7
View File
@@ -3,10 +3,14 @@
인증: 셀러오피스(openapi.11st.co.kr → 서비스등록·확인)에서 발급한 Open API Key 를 요청 헤더 `openapikey` 에 넣는다.
셀러 API 는 등록한 IP 에서만 호출된다("Seller API 정보 수정"에서 서버 IP 등록, 셀링툴(사방넷 등)과 함께 쓸 수 있음).
(공식 이용방법 openapi.11st.co.kr → OpenApiOperationGuide SERVICE_METHOD, 2026-09-30 확인)
응답은 XML(euc-kr). 없는 주소는 500 + resultCode -997 "등록된 API 정보가 존재하지 않습니다", 건이 없으면 -1 "해당 건이 없습니다".
연결 테스트는 결제완료(발주확인할) 주문 목록을 오늘 하루로 조회한다 — GET /rest/ordservices/complete/{시작}/{끝}
(yyyyMMddHHmm). 엔드포인트 상세 문서는 로그인 뒤에만 보여 널리 쓰이는 경로를 쓰고, 실제 호출 결과로 확인한다.
응답은 XML. 매출 수집(fetch_orders)은 맞출 셀러오피스 화면을 정한 뒤 구현한다.
매출(2026-09-30 실데이터로 확정 — 설정 화면 "11번가 원본 데이터 확인"):
- 주문 상태 목록 4개(결제완료·발송대기·배송중·배송완료)는 지금 그 상태인 주문만 준다. 배송완료 목록에 구매확정 주문도 남는다.
- SALE = 주문 한 줄, 날짜 = 결제일(ordStlEndDt, 없으면 주문일 ordDt), 금액 = ordAmt(판매금액, 11번가 부담 쿠폰 전)
+ 배송비(dlvCst, 주문번호당 한 번). ordAmt − ordPayAmt = 11번가 부담 할인(tmallApplyDscAmt). 수수료는 판매금액 기준.
- 취소·반품된 주문은 목록에서 빠진다 → 기간을 통째로 다시 받아(replace_range) 매출에서 빠진다(취소 사건을 따로 만들지 않음).
- 정산 내역(/rest/settlement/settlementList/{yyyyMMdd}/{yyyyMMdd})은 정산확정일(stlDy) 기준 — 확인 도구에서만 쓴다.
"""
from __future__ import annotations
@@ -14,9 +18,17 @@ from __future__ import annotations
import re
import xml.etree.ElementTree as ET
from datetime import date, timedelta
from typing import Any
from typing import Any, Iterable
from .base import AdapterContext, AdapterError, ApiError, AuthFailed, CredentialField, MarketplaceAdapter
from .base import (
AdapterContext,
AdapterError,
ApiError,
AuthFailed,
CredentialField,
MarketplaceAdapter,
SaleEvent,
)
HOST = "https://api.11st.co.kr"
@@ -114,10 +126,45 @@ def field_summary(records: list[dict[str, str]]) -> list[dict[str, Any]]:
return list(names.values())
# 매출 수집 — 주문 상태 목록 4개(지금 그 상태인 주문만 준다). 배송완료 목록에는 구매확정된 주문도 남는다(실데이터 확인).
# 취소·반품된 주문은 이 목록들에서 빠진다 → 기간을 통째로 다시 받아(replace_range) 매출에서 자연히 빠지게 한다.
ORDER_PATHS = ("/rest/ordservices/complete/{s}/{e}", "/rest/ordservices/packaging/{s}/{e}",
"/rest/ordservices/shipping/{s}/{e}", "/rest/ordservices/completed/{s}/{e}")
ORDER_STATUS = {"complete": "결제완료", "packaging": "발송대기", "shipping": "배송중", "completed": "배송완료"}
# 목록의 날짜 조건이 주문일인지 상태 변경일(배송완료일 등)인지 문서로 확인 못 해, 기간 뒤로 넉넉히 더 불러
# 주문일로 거른다(나중에 배송완료된 주문도 빠지지 않게).
LOOKAHEAD_DAYS = 30
EVENT_PREFIX = "11st:"
# raw 에 남길 항목 — 금액·날짜·상태·상품만(구매자 정보 제외)
RAW_KEEP = ("ordNo", "ordPrdSeq", "ordDt", "ordStlEndDt", "ordAmt", "ordPayAmt", "dlvCst", "ordQty", "prdNo",
"atmtBuyCnfrmYN", "pocnfrmDt", "selPrc", "ordPrdStat")
def _won(value: Any) -> int:
try:
return int(round(float(str(value or "0").replace(",", ""))))
except ValueError:
return 0
def _day(value: Any) -> date | None:
""""2026-09-09 15:13:16" / "2026/09/09" / "20260909" → date."""
s = re.sub(r"[^0-9]", "", str(value or ""))[:8]
if len(s) < 8:
return None
try:
return date(int(s[:4]), int(s[4:6]), int(s[6:8]))
except ValueError:
return None
class ElevenstAdapter(MarketplaceAdapter):
code = "elevenst"
name = "11번가"
auth_type = "api_key"
implemented = True
replace_range = True
event_prefix = EVENT_PREFIX
docs_url = "https://openapi.11st.co.kr/"
note = ("11번가 셀러오피스 → 오픈API 에서 발급한 키를 입력합니다. 셀러 API 는 등록한 IP 에서만 호출되므로 "
"'Seller API 정보 수정 → IP 직접 입력'에 이 서버의 외부 IP 를 넣어야 합니다.")
@@ -127,6 +174,57 @@ class ElevenstAdapter(MarketplaceAdapter):
CredentialField("api_key", "Open API Key", secret=True),
]
# ── 수집 ──────────────────────────────────────────────
def fetch_orders(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]:
"""주문 상태 목록 4개를 [start, end+30일(오늘까지)] 7일씩 불러 주문일이 [start, end] 인 줄만.
같은 줄(주문번호+순번)이 두 목록에 나오면(조회 사이 상태 변경) 한 번만.
배송비는 주문번호마다 줄들의 dlvCst 최댓값을 가장 앞 순번 줄에 한 번(_ship)."""
from app.timezone import today_kst # noqa: WPS433
hi = max(end, min(end + timedelta(days=LOOKAHEAD_DAYS), today_kst()))
seen: set[str] = set()
rows: list[dict[str, Any]] = []
for tmpl in ORDER_PATHS:
status = ORDER_STATUS[tmpl.split("/")[3]]
s = start
while s <= hi:
e = min(hi, s + timedelta(days=PROBE_CHUNK_DAYS - 1))
body = self._get(ctx, tmpl.format(s=s.strftime("%Y%m%d") + "0000", e=e.strftime("%Y%m%d") + "2359"))
for r in xml_records(body):
key = f"{r.get('ordNo')}-{r.get('ordPrdSeq')}"
day = _day(r.get("ordStlEndDt") or r.get("ordDt"))
if not r.get("ordNo") or key in seen or day is None or not (start <= day <= end):
continue
seen.add(key)
rows.append({**r, "_status": status})
s = e + timedelta(days=1)
ship: dict[str, tuple[int, int]] = {} # 주문번호 → (배송비, 가장 앞 순번)
for r in rows:
oid, seq = str(r["ordNo"]), _won(r.get("ordPrdSeq"))
cur = ship.get(oid, (0, seq))
ship[oid] = (max(cur[0], _won(r.get("dlvCst"))), min(cur[1], seq))
for r in rows:
fee, first = ship[str(r["ordNo"])]
yield {**r, "_ship": fee if _won(r.get("ordPrdSeq")) == first else 0}
def normalize_order(self, r: dict[str, Any]) -> list[SaleEvent]:
"""주문 한 줄 → SALE. 금액 = 판매금액(ordAmt, 11번가 부담 쿠폰 전) + 배송비(_ship, 주문번호당 한 줄).
수수료가 판매금액 기준이라(34,900 × 13% = 4,537, 정산 실데이터) 판매자 매출은 할인 전 금액으로 본다."""
oid, seq = str(r.get("ordNo") or ""), str(r.get("ordPrdSeq") or "")
day = _day(r.get("ordStlEndDt") or r.get("ordDt"))
if not oid or day is None:
return []
amount = _won(r.get("ordAmt")) + _won(r.get("_ship"))
opt = str(r.get("slctPrdOptNm") or "")
return [SaleEvent(
event_type="SALE", external_event_id=f"{EVENT_PREFIX}{oid}-{seq}", external_order_id=oid,
external_line_id=seq, order_date=_day(r.get("ordDt")), payment_date=day, event_date=day,
amount=max(0, amount), product_name=str(r.get("prdNm") or "")[:200], option_name=opt[:200],
quantity=int(_won(r.get("ordQty"))), discount_amount=max(0, _won(r.get("ordAmt")) - _won(r.get("ordPayAmt"))),
order_status=str(r.get("_status") or ""),
raw={k: r.get(k) for k in RAW_KEEP if r.get(k) not in (None, "")},
)]
def _get(self, ctx: AdapterContext, path: str) -> bytes:
import httpx # 지연 import
@@ -185,5 +283,4 @@ class ElevenstAdapter(MarketplaceAdapter):
d = today_kst().strftime("%Y%m%d")
body = self._get(ctx, f"/rest/ordservices/complete/{d}0000/{d}2359")
_, _, orders = xml_result(body)
return (f"11번가 연결 정상(주문 조회 권한 확인, 오늘 결제완료 {orders}건). "
"매출 수집은 다음 단계에서 구현됩니다.")
return f"11번가 연결 정상(주문 조회 권한 확인, 오늘 결제완료 {orders}건)."
@@ -383,10 +383,12 @@ def test_not_implemented_and_mock():
st = FakeStore()
creds = CredentialService(st, lambda: ring())
svc = SyncService(st, creds)
r = svc.sync_marketplace("elevenst", date(2026, 9, 29), date(2026, 9, 29))
gm = next(a for a in all_adapters() if a.code == "gmarket")
r = svc.sync_marketplace("gmarket", date(2026, 9, 29), date(2026, 9, 29))
assert r["status"] == "not_configured" # 키 미입력
creds.save(next(a for a in all_adapters() if a.code == "elevenst"), {"api_key": "k-123456"})
r = svc.sync_marketplace("elevenst", date(2026, 9, 29), date(2026, 9, 29))
secret = next(f.key for f in gm.visible_fields() if f.secret)
creds.save(gm, {f.key: ("k-123456" if f.key == secret else "v") for f in gm.visible_fields()})
r = svc.sync_marketplace("gmarket", date(2026, 9, 29), date(2026, 9, 29))
assert r["status"] == "not_implemented" and "k-123456" not in r["message"]
import httpx
orig_get, httpx.get = httpx.get, (lambda url, headers=None, timeout=None: httpx.Response(200, content=b"<orders/>"))
@@ -884,6 +886,59 @@ def test_elevenst_connection():
httpx.get = orig
def test_elevenst_collect_sales():
"""11번가 매출 = 주문 상태 목록(결제완료·발송대기·배송중·배송완료)의 줄, 결제일(없으면 주문일) 기준,
금액 = ordAmt + 배송비(주문번호마다 최댓값을 가장 앞 줄에 한 번). 같은 줄이 두 목록에 나와도 한 번, 기간 밖 주문일은 제외.
실데이터 9/9: ordAmt 34,900 / ordPayAmt 34,900, 9/10: ordAmt 83,800 / ordPayAmt 72,740(11번가 쿠폰 11,060)."""
import httpx
import app.modules.performance.sync as syncmod
import app.timezone as _tz
from app.modules.performance.adapters import elevenst as ev
def line(no, seq, day, amt, pay, ship=0, qty=1):
return (f"<ns2:order><ordNo>{no}</ordNo><ordPrdSeq>{seq}</ordPrdSeq><ordDt>{day} 15:13:16</ordDt>"
f"<ordAmt>{amt}</ordAmt><ordPayAmt>{pay}</ordPayAmt><dlvCst>{ship}</dlvCst><ordQty>{qty}</ordQty>"
f"<prdNm>밀폐용기</prdNm><rcvrNm>홍길동</rcvrNm><memNo>18550503</memNo></ns2:order>")
completed = ("<ns2:orders xmlns:ns2='x'>" + line("20260909099415322", 1, "2026-09-09", 34900, 34900) +
line("20260910099718265", 1, "2026-09-10", 83800, 72740, qty=2) +
line("20260910099718265", 2, "2026-09-10", 10000, 10000, ship=3000) +
line("20260801000000001", 1, "2026-08-01", 5000, 5000) + "</ns2:orders>").encode()
packaging = ("<ns2:orders xmlns:ns2='x'>" + line("20260909099415322", 1, "2026-09-09", 34900, 34900) +
line("20260911000000002", 1, "2026-09-11", 20000, 20000, ship=3000) + "</ns2:orders>").encode()
empty = "<ns2:orders xmlns:ns2='x'><ns2:result_code>-1</ns2:result_code><ns2:result_text>해당 건이 없습니다.</ns2:result_text></ns2:orders>".encode()
calls = []
def route(url, headers=None, timeout=None):
calls.append(url)
if "/ordservices/completed/" in url:
return httpx.Response(200, content=completed)
if "/ordservices/packaging/" in url:
return httpx.Response(200, content=packaging)
return httpx.Response(200, content=empty)
st = FakeStore()
creds = CredentialService(st, lambda: ring())
creds.save(next(a for a in all_adapters() if a.code == "elevenst"), {"api_key": "KEY-11ST"})
orig, orig_today = httpx.get, _tz.today_kst
httpx.get, _tz.today_kst = route, (lambda: date(2026, 9, 30))
try:
r = SyncService(st, creds).sync_marketplace("elevenst", date(2026, 9, 9), date(2026, 9, 11))
finally:
httpx.get, _tz.today_kst = orig, orig_today
assert r["ok"], r
ev_ = {k[2]: v for k, v in st.events.items() if k[0] == "elevenst"}
assert set(ev_) == {"11st:20260909099415322-1", "11st:20260910099718265-1", "11st:20260910099718265-2",
"11st:20260911000000002-1"} # 중복 1번, 8/1 주문 제외
assert ev_["11st:20260909099415322-1"]["amount"] == 34_900 and ev_["11st:20260909099415322-1"]["sales_date"] == date(2026, 9, 9)
assert ev_["11st:20260910099718265-1"]["amount"] == 83_800 + 3_000 # 2번 줄의 배송비를 앞 줄에 한 번
assert ev_["11st:20260910099718265-1"]["discount_amount"] == 11_060
assert ev_["11st:20260910099718265-2"]["amount"] == 10_000
assert ev_["11st:20260911000000002-1"]["amount"] == 23_000
assert "홍길동" not in repr(st.events) and "18550503" not in repr(st.events) # 구매자 정보 미저장
assert any("/20260930" in u for u in calls) and not any("/20261001" in u for u in calls) # 오늘까지만 더 불러옴
def test_registry_and_event_validation():
codes = [a.code for a in all_adapters()]
assert len(codes) == len(set(codes)) == 10