da63b93302
- 진행 창 [업데이트 취소](시작한 사람·관리자) → 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>
330 lines
18 KiB
Python
330 lines
18 KiB
Python
"""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}건)."
|