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:
@@ -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
|
||||
|
||||
@@ -83,6 +83,22 @@
|
||||
그 주문의 마지막 클레임 품목에 한 번 더한다. 톡체크아웃·자체몰의 환불 기록 없는 취소는 카페24 환불합계에 없음
|
||||
(9/4: 98,700 + 네이버페이 19,900 + 배송비 3,500 = 122,100 / 9/16: 톡체크아웃 취소 9,900 제외 → 201,100).
|
||||
|
||||
### 11번가 (`adapters/elevenst.py`, 구현됨)
|
||||
|
||||
- 인증: 셀러오피스 Open API Key → 헤더 `openapikey`. **셀러 API 는 등록 IP 에서만** 호출된다(Seller API 정보 수정 →
|
||||
IP 직접 입력에 운영 서버 외부 IP, 셀링툴 사방넷과 함께 사용 가능). 응답은 XML(euc-kr 선언 → 직접 디코딩).
|
||||
- 없는 주소 = 500 + `-997 등록된 API 정보가 존재하지 않습니다`, 건 없음 = `-1 해당 건이 없습니다`(0건으로 처리).
|
||||
- 상세 문서가 로그인 뒤에만 있어 설정 화면 **"11번가 원본 데이터 확인"**(`reconcile(day, to)`, 후보 주소별 동작·항목 합계,
|
||||
개인정보 값 숨김)으로 실데이터를 보고 확정했다(2026-09-30).
|
||||
- 주문 상태 목록 4개(`/rest/ordservices/complete|packaging|shipping|completed/{yyyyMMddHHmm}/{…}`)는 **지금 그 상태인 주문만**
|
||||
준다. 배송완료 목록에 구매확정 주문도 남는다. 취소·반품된 주문은 목록에서 빠지고 `/rest/claimservice/canceledorders|…` 에 있다.
|
||||
- SALE = 주문 한 줄(`11st:{ordNo}-{ordPrdSeq}`), 날짜 = 결제일(`ordStlEndDt`, 없으면 주문일 `ordDt`), 금액 = `ordAmt`
|
||||
(판매금액, 11번가 부담 쿠폰 전) + 배송비(`dlvCst`, 주문번호마다 최댓값을 가장 앞 줄에 한 번). `ordAmt − ordPayAmt` = 11번가
|
||||
부담 할인(`discount_amount` 에 기록). 수수료는 판매금액 기준(정산 `selFee` = 34,900 × 13%).
|
||||
- `replace_range` — 기간을 통째로 다시 받아 취소·반품된 주문이 매출에서 빠진다(취소 사건을 따로 만들지 않음 → 지난 날짜
|
||||
금액이 나중에 줄 수 있음). 목록의 날짜 조건이 주문일인지 상태 변경일인지 몰라 **기간 뒤 30일(오늘까지)을 더 불러 주문일로 거른다.**
|
||||
- 정산 내역 `/rest/settlement/settlementList/{yyyyMMdd}/{yyyyMMdd}` 은 정산확정일(`stlDy`) 기준 — 확인 도구에서만 쓴다.
|
||||
|
||||
### 연동 단계 체크리스트(쇼핑몰마다)
|
||||
|
||||
- 공식 문서로 인증 방식·호출 제한·페이지네이션·주문 상태 코드·취소/반품 API·날짜 필드 확인
|
||||
|
||||
Reference in New Issue
Block a user