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}건)."