Files
dbx-main/app/modules/performance/adapters/elevenst.py
T
king da63b93302 feat(performance): 매출 업데이트 취소 버튼
- 진행 창 [업데이트 취소](시작한 사람·관리자) → POST /api/sync/jobs/{id}/cancel
- 어댑터가 API 호출 직전마다 ctx.progress.check() — 취소면 Cancelled 로 멈추고 저장하지 않음(기존 매출 그대로),
  차례가 안 온 쇼핑몰은 취소됨으로 건너뜀, 이미 끝난 쇼핑몰 결과는 유지
- 취소 실행은 perf_sync_runs failed + 업데이트 취소, 연결 상태는 바꾸지 않음
- 테스트 1개 추가(30개 통과), performance.js/css 캐시 버전, 문서 갱신

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 15:06:25 +09:00

330 lines
18 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 실데이터·셀러오피스 "판매 상세내역"으로 확정):
- SALE = 주문 하나(`11st:{ordNo}`), 날짜 = 결제일.
- 정산된 주문: 정산 내역(/rest/settlement/settlementList/{yyyyMMdd}/{yyyyMMdd}, 정산확정일 stlDy 기준)의
판매금액합계(selPrcAmt) 합 — 판매 상세내역과 같고 배송비(도서산간 등)가 별도 줄로 들어 있다.
예: 9/10 주문 = 83,800 + 배송비 줄 3,000 = 86,800 (주문 목록의 dlvCst 는 0 이라 주문 목록만으로는 모자람).
- 정산 전 주문: 주문 상태 목록 4개(결제완료·발송대기·배송중·배송완료 — 지금 그 상태인 주문만, 배송완료에 구매확정 주문도
남음)의 ordAmt(판매금액, 11번가 부담 쿠폰 전) + 배송비(dlvCst 최댓값 한 번). 정산되면 다음 업데이트 때 정산 값으로 바뀐다.
- ordAmt − ordPayAmt = 11번가 부담 할인(= 정산 cupnAmt/tmallApplyDscAmt). 수수료는 판매금액 기준(34,900 × 13% = 4,537).
- 취소·반품된 주문은 목록에서 빠진다 → 기간을 통째로 다시 받아(replace_range) 매출에서 빠진다(취소 사건을 따로 만들지 않음).
"""
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
SETTLE_LOOKAHEAD_DAYS = 45 # 결제 → 정산확정(구매확정)까지 보통 1~3주
SETTLEMENT_PATH = "/rest/settlement/settlementList/{ds}/{de}"
EVENT_PREFIX = "11st:"
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
def _n_chunks(lo: date, hi: date) -> int:
return max(0, ((hi - lo).days + PROBE_CHUNK_DAYS) // PROBE_CHUNK_DAYS)
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 _pages(self, ctx: AdapterContext, tmpl: str, lo: date, hi: date) -> Iterable[dict[str, str]]:
"""[lo, hi] 를 7일씩 나눠 한 주소를 부른다."""
s = lo
while s <= hi:
e = min(hi, s + timedelta(days=PROBE_CHUNK_DAYS - 1))
ds, de = s.strftime("%Y%m%d"), e.strftime("%Y%m%d")
rows = xml_records(self._get(ctx, tmpl.format(s=f"{ds}0000", e=f"{de}2359", ds=ds, de=de)))
ctx.progress.step(items=len(rows))
yield from rows
s = e + timedelta(days=1)
def fetch_orders(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]:
"""결제일이 [start, end] 인 주문을 주문 단위로 합쳐 돌려준다.
1) 정산 내역 — 정산확정일 기준이라 [start, end+45일(오늘까지)] 를 불러 결제일(ordStlEndDt)로 거른다.
판매금액합계(selPrcAmt)는 셀러오피스 "판매 상세내역"과 같고 배송비 줄(도서산간 등)도 따로 들어 있다.
2) 아직 정산 전인 주문 — 주문 상태 목록 4개([start, end+30일]) 의 ordAmt + 배송비(dlvCst 최댓값 한 번).
같은 주문이 정산에 있으면 정산 값을 쓴다(정산되면 다음 업데이트 때 정산 값으로 바뀜)."""
from app.timezone import today_kst # noqa: WPS433
today = today_kst()
orders: dict[str, dict[str, Any]] = {}
def acc(oid: str, src: str, day: date) -> dict[str, Any]:
return orders.setdefault(oid, {"ordNo": oid, "_src": src, "_day": day, "amount": 0, "qty": 0,
"discount": 0, "ship": 0, "names": [], "opt": "", "raw": {}})
settle_hi = max(end, min(end + timedelta(days=SETTLE_LOOKAHEAD_DAYS), today))
hi = max(end, min(end + timedelta(days=LOOKAHEAD_DAYS), today))
# 진행 막대: 7일 구간마다 한 번 — 정산 내역 + 주문 상태 목록 4개
ctx.progress.plan(_n_chunks(start, settle_hi) + len(ORDER_PATHS) * _n_chunks(start, hi), "구간")
for r in self._pages(ctx, SETTLEMENT_PATH, start, settle_hi):
oid, day = str(r.get("ordNo") or ""), _day(r.get("ordStlEndDt"))
if not oid or day is None or not (start <= day <= end):
continue
o = acc(oid, "settlement", day)
o["amount"] += _won(r.get("selPrcAmt"))
o["qty"] += _won(r.get("ordQty"))
o["discount"] += _won(r.get("cupnAmt"))
if r.get("prdNm") and r["prdNm"] not in o["names"]:
o["names"].append(r["prdNm"])
o["opt"] = o["opt"] or str(r.get("slctPrdOptNm") or "")
for k in ("stlAmt", "selFee", "deductAmt", "bmStlDlvCst"):
o["raw"][k] = o["raw"].get(k, 0) + _won(r.get(k))
o["raw"]["stlDy"] = r.get("stlDy")
settled = set(orders)
seen: set[str] = set()
for tmpl in ORDER_PATHS:
status = ORDER_STATUS[tmpl.split("/")[3]]
for r in self._pages(ctx, tmpl, start, hi):
oid = str(r.get("ordNo") or "")
key = f"{oid}-{r.get('ordPrdSeq')}"
day = _day(r.get("ordStlEndDt") or r.get("ordDt"))
if not oid or oid in settled or key in seen or day is None or not (start <= day <= end):
continue
seen.add(key)
o = acc(oid, status, day)
o["amount"] += _won(r.get("ordAmt"))
o["ship"] = max(o["ship"], _won(r.get("dlvCst")))
o["qty"] += _won(r.get("ordQty"))
o["discount"] += max(0, _won(r.get("ordAmt")) - _won(r.get("ordPayAmt")))
if r.get("prdNm") and r["prdNm"] not in o["names"]:
o["names"].append(r["prdNm"])
o["opt"] = o["opt"] or str(r.get("slctPrdOptNm") or "")
o["raw"]["ordDt"] = r.get("ordDt")
for o in orders.values():
o["amount"] += o.pop("ship")
yield o
def normalize_order(self, o: dict[str, Any]) -> list[SaleEvent]:
"""주문 하나 → SALE(결제일). 금액 = 정산 판매금액합계(정산 전이면 ordAmt + 배송비) — 11번가 부담 쿠폰 전 금액.
수수료가 판매금액 기준이라(34,900 × 13% = 4,537, 정산 실데이터) 판매자 매출은 할인 전 금액으로 본다."""
oid, day = str(o.get("ordNo") or ""), o.get("_day")
if not oid or day is None:
return []
names = o.get("names") or []
name = names[0] + (f" 외 {len(names) - 1}건" if len(names) > 1 else "") if names else ""
return [SaleEvent(
event_type="SALE", external_event_id=f"{EVENT_PREFIX}{oid}", external_order_id=oid,
payment_date=day, event_date=day, amount=max(0, int(o.get("amount") or 0)),
product_name=name[:200], option_name=str(o.get("opt") or "")[:200], quantity=int(o.get("qty") or 0),
discount_amount=max(0, int(o.get("discount") or 0)),
order_status="정산확정" if o.get("_src") == "settlement" else str(o.get("_src") or ""),
raw={"source": o.get("_src"), **(o.get("raw") or {})},
)]
def _get(self, ctx: AdapterContext, path: str) -> bytes:
import httpx # 지연 import
ctx.progress.check() # [업데이트 취소]면 여기서 멈춤
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}건)."