Files
dbx-main/app/modules/performance/adapters/elevenst.py
T
king 40d94e2892 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>
2026-09-30 01:20:18 +09:00

287 lines
15 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""11번가 — 11번가 셀러 오픈API.
인증: 셀러오피스(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 "해당 건이 없습니다".
매출(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
import re
import xml.etree.ElementTree as ET
from datetime import date, timedelta
from typing import Any, Iterable
from .base import (
AdapterContext,
AdapterError,
ApiError,
AuthFailed,
CredentialField,
MarketplaceAdapter,
SaleEvent,
)
HOST = "https://api.11st.co.kr"
def _xml_text(content: bytes) -> str:
"""11번가 XML 은 euc-kr 선언이 많다 — 파이썬 XML 파서가 다바이트 인코딩 선언을 못 읽어 직접 풀고 선언을 뗀다."""
head = content[:200].decode("ascii", "ignore")
m = re.search(r"encoding=[\"']([\w-]+)", head)
enc = (m.group(1) if m else "utf-8").lower()
try:
text = content.decode("cp949" if enc in ("euc-kr", "euckr", "ks_c_5601-1987") else enc)
except (LookupError, UnicodeDecodeError):
text = content.decode("utf-8", "replace")
return re.sub(r"^\s*<\?xml[^>]*\?>", "", text)
def xml_result(content: bytes) -> tuple[str, str, int]:
"""(결과코드, 결과문구, 주문 수). 네임스페이스와 무관하게 태그 끝 이름으로 찾는다. XML 이 아니면 코드 "not-xml"."""
try:
root = ET.fromstring(_xml_text(content))
except ET.ParseError:
return "not-xml", "", 0
if root.tag.rsplit("}", 1)[-1].lower() == "html": # 오류 안내 웹페이지(IP 차단 등)
return "not-xml", "", 0
code = text = ""
orders = 0
for el in root.iter():
tag = el.tag.rsplit("}", 1)[-1].lower()
if tag in ("result_code", "resultcode") and not code:
code = (el.text or "").strip()
elif tag in ("result_text", "resulttext", "result_message", "message") and not text:
text = (el.text or "").strip()
elif tag == "order":
orders += 1
return code, text, orders
# 원본 데이터 확인용 후보 주소 — {s}/{e} = yyyyMMddHHmm, {d} = yyyyMMdd. 문서 미확인 경로가 섞여 있어
# 404 등 실패도 그대로 보여 준다(어느 주소가 살아 있는지 확인하는 것이 목적).
PROBE_PATHS: tuple[tuple[str, str, str], ...] = (
("complete", "결제완료(발주확인 전)", "/rest/ordservices/complete/{s}/{e}"),
("packaging", "발송처리 대상(발주확인 후)", "/rest/ordservices/packaging/{s}/{e}"),
("shipping", "배송중", "/rest/ordservices/shipping/{s}/{e}"),
("completed", "배송완료", "/rest/ordservices/completed/{s}/{e}"),
("cancelorders", "취소신청", "/rest/claimservice/cancelorders/{s}/{e}"),
("canceledorders", "취소완료", "/rest/claimservice/canceledorders/{s}/{e}"),
("returnorders", "반품신청", "/rest/claimservice/returnorders/{s}/{e}"),
("returnedorders", "반품완료", "/rest/claimservice/returnedorders/{s}/{e}"),
("purchaseconfirm", "구매확정(후보)", "/rest/ordservices/purchaseconfirm/{s}/{e}"),
("settlement", "정산 내역", "/rest/settlement/settlementList/{ds}/{de}"),
)
NO_DATA = re.compile(r"해당\s*건이\s*없|조회된?\s*(내역|건|데이터)이?\s*없") # 코드 -1 이어도 "0건"
PROBE_CHUNK_DAYS = 7
PROBE_MAX_DAYS = 31
# 개인정보로 보이는 항목 — 값은 보이지 않고 이름만(이름·연락처·주소·우편번호·아이디·메일·메모)
PERSONAL = re.compile(r"(nm|name|tel|tlphn|phone|hp|addr|zip|mail|id|memo|msg|pcc|clearance|birth)$|rcvr|ordnm|buyer",
re.IGNORECASE)
NUMBER = re.compile(r"^-?\d+(\.\d+)?$")
SAFE = re.compile(r"^(prd|opt|slct|dlvEtprs|dlvMthd|clm|reason|stl|sel)", re.IGNORECASE) # 상품·옵션·클레임 사유 등은 보임
def xml_records(content: bytes) -> list[dict[str, str]]:
"""응답에서 주문(또는 클레임·정산) 한 줄씩 — 자식이 모두 글자 항목인 요소를 한 줄로 본다(태그 끝 이름 → 값)."""
try:
root = ET.fromstring(_xml_text(content))
except ET.ParseError:
return []
out: list[dict[str, str]] = []
for el in root.iter():
kids = list(el)
if len(kids) >= 3 and all(len(k) == 0 for k in kids):
out.append({k.tag.rsplit("}", 1)[-1]: (k.text or "").strip() for k in kids})
return out
def field_summary(records: list[dict[str, str]]) -> list[dict[str, Any]]:
"""항목별: 채워진 줄 수, 숫자면 합계, 개인정보 아니면 예시 값 하나."""
names: dict[str, dict[str, Any]] = {}
for r in records:
for k, v in r.items():
f = names.setdefault(k, {"name": k, "filled": 0, "numeric": True, "sum": 0.0, "sample": "",
"personal": bool(PERSONAL.search(k)) and not SAFE.match(k)})
if not v:
continue
f["filled"] += 1
if NUMBER.match(v) and f["numeric"]:
f["sum"] += float(v)
else:
f["numeric"] = False
if not f["sample"] and not f["personal"]:
f["sample"] = v[:40]
for f in names.values():
f["sum"] = int(round(f["sum"])) if f["numeric"] and f["filled"] else None
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 를 넣어야 합니다.")
def credential_fields(self) -> list[CredentialField]:
return [
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
headers = {"openapikey": ctx.credentials.get("api_key").strip(), "Accept": "application/xml"}
try:
res = httpx.get(f"{HOST}{path}", headers=headers, timeout=ctx.timeout_sec)
except httpx.HTTPError as exc:
raise ApiError(f"11번가 API 연결 실패: {type(exc).__name__} — 등록한 IP 가 이 서버 IP 인지 확인하세요.") from None
code, text, _ = xml_result(res.content)
detail = text or res.text[:200].strip()
if res.status_code in (401, 403):
raise AuthFailed(f"11번가 인증 거부({res.status_code}): {detail}. 키와 등록 IP(이 서버 외부 IP)를 확인하세요.")
if res.status_code >= 400:
raise ApiError(f"11번가 API 오류({res.status_code}): {detail}")
if code == "not-xml":
raise ApiError(f"11번가가 예상하지 못한 응답을 돌려줬습니다(XML 아님): {res.text[:120].strip()}")
if code and code not in ("0", "200", "00") and not NO_DATA.search(text):
raise ApiError(f"11번가 API 오류(코드 {code}): {detail}")
return res.content
# ── 원본 데이터 확인(설정 화면 "11번가 원본 데이터 확인") ─────────
def reconcile(self, ctx: AdapterContext, day: date, to: date | None = None) -> dict[str, Any]:
"""후보 조회 주소마다 기간(day~to, 최대 31일, 7일씩 나눠)을 실제로 불러 동작 여부·줄 수·항목별 합계를 돌려준다.
셀러 API 상세 문서가 로그인 뒤에만 있어, 어느 주소·항목이 셀러오피스 화면 매출과 맞는지 실데이터로 확정하는 용도.
개인정보 항목(이름·연락처·주소·아이디 등)은 값 없이 이름만."""
self.authenticate(ctx)
to = min(max(to or day, day), day + timedelta(days=PROBE_MAX_DAYS - 1))
chunks = []
s = day
while s <= to:
e = min(to, s + timedelta(days=PROBE_CHUNK_DAYS - 1))
chunks.append((s, e))
s = e + timedelta(days=1)
out = []
for key, label, tmpl in PROBE_PATHS:
row: dict[str, Any] = {"key": key, "label": label, "path": tmpl.split("/{")[0] + "/…"}
records: list[dict[str, str]] = []
error = ""
for s, e in chunks:
ds, de = s.strftime("%Y%m%d"), e.strftime("%Y%m%d")
try:
records += xml_records(self._get(ctx, tmpl.format(s=f"{ds}0000", e=f"{de}2359", ds=ds, de=de)))
except AdapterError as exc:
error = exc.message[:200]
break
if error:
out.append({**row, "ok": False, "error": error})
else:
out.append({**row, "ok": True, "count": len(records), "fields": field_summary(records)})
return {"date": day.isoformat(), "to": to.isoformat(), "probes": out}
def test_connection(self, ctx: AdapterContext) -> str:
from app.timezone import today_kst # noqa: WPS433
self.authenticate(ctx)
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}건)."