wz-opensdk 0.1.0__py3-none-any.whl

wz_opensdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: wz-opensdk
+Version: 0.1.0
+Summary: 万桩开放平台 Python OpenSDK
+License: MIT
+Project-URL: Homepage, https://gitee.com/wz-open-platform/wz-opensdk-python
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# wz-opensdk
+
+万桩开放平台 Python SDK。覆盖 Apifox 项目 `wz-open` 中文目录下的公开 API（设备、充电、续费、开票、回调日志）。`inner/*` 内部接口不在本 SDK 中。SDK 只做 client，不解析平台推送到合作方的入站回调。
+
+发行名：`wz-opensdk`。导入名：`wzopensdk`。Python **3.9+**。
+
+## 安装
+
+```bash
+pip install wz-opensdk
+```
+
+尚未发布到 PyPI 时，可从 Gitee 安装：
+
+```bash
+pip install git+https://gitee.com/wz-open-platform/wz-opensdk-python.git@v0.1.0
+```
+
+本地开发：
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## 快速开始
+
+```python
+import os
+from wzopensdk import WzOpenClient, Endpoints
+from wzopensdk.device import DeviceNumRequest
+
+client = WzOpenClient(
+    endpoint=Endpoints.PROD,  # 测试环境用 Endpoints.TEST
+    app_id=os.environ["WZ_OPEN_APP_ID"],
+    app_secret=os.environ["WZ_OPEN_APP_SECRET"],
+)
+
+device = client.device.find_one(DeviceNumRequest("18000001"))
+```
+
+也可 `WzOpenClient.from_env()`（读 `WZ_OPEN_APP_ID` / `WZ_OPEN_APP_SECRET`，可选 `WZ_OPEN_ENDPOINT`，缺省测试环境）。
+
+按域调用，方法不堆在 `WzOpenClient` 上：
+
+- `client.device` 设备绑定、计费模式、状态、在线日志
+- `client.charge.start` / `stop`
+- `client.renew`
+- `client.invoice`
+- `client.callback.log` / `retry_finish_order`
+
+默认请求超时 10s。
+
+## 签名
+
+SDK 按接入指引自动加 `app_id`、`timestamp`、`sign`（HMAC-SHA256 大写 hex）。调用方不要自己拼签，也不要传 `company_id`。金额单位为分。
+
+契约快照：[../api/openapi.json](../api/openapi.json)（汽车桩 `saveMode`/`getMode` 在 SDK 中拆成独立方法；`/open/device/setting/sync` 属于 inner，本 SDK 不实现）。公开能力合计 40 条出站 API。
+
+## 日志
+
+使用标准库 `logging`，logger 名 `wzopensdk`。可传入自定义 logger。
+
+成功请求的 info 日志会带 `method`、`path`；响应头有 `X-B3-TraceId` 时再带 `traceId`。失败时同一字段出现在 error 日志里，并可从 `WzOpenAPIError.trace_id` 读取。
+
+## HTTP
+
+可配 timeout（默认 10s）、retry_count（失败重试且每次重签）、retry_wait、user_agent、proxy_url，或直接传入 `httpx.Client`。
+
+## 环境
+
+| 环境 | Base URL |
+| --- | --- |
+| 测试 | `https://dev-api-open.wanzhuangkj.com` |
+| 正式 | `https://api-open.wanzhuangkj.com` |
+
+## 开发
+
+```bash
+pip install -e ".[dev]"
+python3 -m pytest -q
+# 或 make test
+```
+
+现网验证（需要凭证）：
+
+```bash
+export WZ_OPEN_APP_ID=...
+export WZ_OPEN_APP_SECRET=...
+make verify
+```

wz_opensdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+wzopensdk/__init__.py,sha256=113LusWCYLL8ynMfXnlgmM7ps3hfxCQGtqtRzqCwQ_Q,322
+wzopensdk/callback.py,sha256=mhnNxkaiXMGYm8tSq2KwdKz22VvLMiBlhR8N6zBTLuc,2012
+wzopensdk/charge.py,sha256=uAVjuD8tYktCX5YzLvL_39YTtsZzTZ-Z4-fSg5dOIWg,880
+wzopensdk/client.py,sha256=Ipr1rBmHkwijvvVRLXqxgupwm_k5LZP5Y66MytbvStg,2342
+wzopensdk/device.py,sha256=dCC2zKiAWe82Q1pPNLANvIeN6-U_hJSzeup7En230mY,11254
+wzopensdk/endpoints.py,sha256=JrReG5nVhJ8-_vAUWUPXW0VNqrKIU_4fieHvS1xtCKU,146
+wzopensdk/errors.py,sha256=prEXr0FNn7WLGB-W4mYXHRNXEq6jGbQkcYVp1_-GLBY,1504
+wzopensdk/invoice.py,sha256=nck0pgW09zxmZkjd3Qxi6RcuhdyCWDJ5ge7Zfj4Ic1c,2540
+wzopensdk/renew.py,sha256=j9d2iCwwNsOJv-I0rA4k5Vb7Sh4wnA7a0i7DzOWl3Bo,1790
+wzopensdk/_internal/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+wzopensdk/_internal/http.py,sha256=9M7CLYbovHuNroFXYZt7h5ici3m1ySCOSC8UzfHmAGE,6841
+wzopensdk/_internal/params.py,sha256=6Tdckct8TyM_WodDYQEHsn0pq9SjFhzwkQH499faLf0,1593
+wzopensdk/_internal/signer.py,sha256=k49hcX7tSbprnHslO2JLZZM1ue9xhciQPO35yLyWb9E,2464
+wz_opensdk-0.1.0.dist-info/METADATA,sha256=hshmA9321JDveL-lW0xyHggrG-C0Lm5SRNr3Zb066F4,2978
+wz_opensdk-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+wz_opensdk-0.1.0.dist-info/top_level.txt,sha256=4--5oBhCOH3qUaCMca1XDJ8s7g9MqV7qM1tgYVx8JfI,10
+wz_opensdk-0.1.0.dist-info/RECORD,,

wz_opensdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

wz_opensdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+wzopensdk

wzopensdk/__init__.py

@@ -0,0 +1,13 @@
+"""万桩开放平台 Python OpenSDK。"""
+
+from wzopensdk.client import WzOpenClient
+from wzopensdk.endpoints import Endpoints
+from wzopensdk.errors import WzOpenAPIError, WzOpenConfigError, WzOpenError
+
+__all__ = [
+    "Endpoints",
+    "WzOpenAPIError",
+    "WzOpenClient",
+    "WzOpenConfigError",
+    "WzOpenError",
+]

wzopensdk/_internal/__init__.py

@@ -0,0 +1 @@
+

wzopensdk/_internal/http.py

@@ -0,0 +1,207 @@
+"""Sign, send, retry, and decode open-platform envelopes."""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from typing import Any, Callable, TypeVar
+
+import httpx
+
+from wzopensdk._internal import params as paramx
+from wzopensdk._internal import signer
+from wzopensdk.errors import WzOpenAPIError, WzOpenError
+
+CODE_SUCCESS = 1
+HEADER_B3_TRACE_ID = "X-B3-TraceId"
+T = TypeVar("T")
+
+
+class HttpInvoker:
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        app_id: str,
+        app_secret: str,
+        timeout: float = 10.0,
+        retry_count: int = 0,
+        retry_wait: float = 0.2,
+        user_agent: str = "wz-opensdk/python",
+        proxy_url: str | None = None,
+        insecure_skip_verify: bool = False,
+        logger: logging.Logger | None = None,
+        http_client: httpx.Client | None = None,
+        clock: Callable[[], int] | None = None,
+    ) -> None:
+        self.endpoint = endpoint.rstrip("/")
+        self.app_id = app_id
+        self.app_secret = app_secret
+        self.timeout = timeout if timeout > 0 else 10.0
+        self.retry_count = max(0, retry_count)
+        self.retry_wait = retry_wait if retry_wait > 0 else 0.2
+        self.user_agent = user_agent or "wz-opensdk/python"
+        self.log = logger or logging.getLogger("wzopensdk")
+        self.clock = clock or (lambda: int(time.time()))
+        if http_client is not None:
+            self.http = http_client
+            self._owns_client = False
+        else:
+            self.http = httpx.Client(
+                timeout=self.timeout,
+                proxy=proxy_url,
+                verify=not insecure_skip_verify,
+            )
+            self._owns_client = True
+
+    def invoke(
+        self,
+        method: str,
+        path: str,
+        operation: str,
+        incoming: Any,
+        decode: Callable[[Any], T],
+    ) -> T:
+        business = paramx.to_params(incoming)
+        wait = self.retry_wait
+        attempts = self.retry_count + 1
+        last: WzOpenError | None = None
+        for attempt in range(attempts):
+            if attempt > 0:
+                time.sleep(wait)
+                wait *= 2
+            try:
+                return self._attempt_once(method, path, operation, business, decode)
+            except WzOpenError as exc:
+                last = exc
+                if not self._should_retry(exc) or attempt == attempts - 1:
+                    raise
+        raise last or WzOpenError("request failed")
+
+    def invoke_map(self, method: str, path: str, operation: str, incoming: Any) -> dict[str, Any] | None:
+        return self.invoke(method, path, operation, incoming, lambda data: data)
+
+    def invoke_void(self, method: str, path: str, operation: str, incoming: Any) -> None:
+        self.invoke(method, path, operation, incoming, lambda data: data)
+
+    def _attempt_once(
+        self,
+        method: str,
+        path: str,
+        operation: str,
+        business: dict[str, Any],
+        decode: Callable[[Any], T],
+    ) -> T:
+        payload = dict(business)
+        payload["app_id"] = self.app_id
+        payload["timestamp"] = self.clock()
+        payload["sign"] = signer.sign(payload, self.app_secret)
+
+        method = method.upper()
+        url = self.endpoint + path
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": self.user_agent,
+        }
+        request_kwargs: dict[str, Any] = {
+            "headers": headers,
+            "timeout": self.timeout,
+        }
+        if method in {"GET", "HEAD"}:
+            qs = paramx.encode_query(payload)
+            if qs:
+                url = f"{url}?{qs}"
+        else:
+            request_kwargs["json"] = payload
+            headers["Content-Type"] = "application/json"
+
+        try:
+            resp = self.http.request(method, url, **request_kwargs)
+        except httpx.TimeoutException as exc:
+            self.log.error(
+                "open api request failed method=%s path=%s operation=%s err=%s",
+                method,
+                path,
+                operation,
+                exc,
+            )
+            raise WzOpenError(f"request timed out: {exc}") from exc
+        except httpx.HTTPError as exc:
+            self.log.error(
+                "open api request failed method=%s path=%s operation=%s err=%s",
+                method,
+                path,
+                operation,
+                exc,
+            )
+            raise WzOpenError(f"network error: {exc}") from exc
+
+        status = resp.status_code
+        trace_id = _response_trace_id(resp)
+        if status < 200 or status >= 300:
+            self._log_failure(method, path, operation, status, trace_id)
+            raise WzOpenAPIError.http_status(status, operation, trace_id)
+
+        try:
+            env = resp.json()
+        except json.JSONDecodeError as exc:
+            raise WzOpenError(f"decode envelope: {exc}") from exc
+        if not isinstance(env, dict):
+            raise WzOpenError("decode envelope: not an object")
+
+        code = int(env.get("code") or 0)
+        if code != CODE_SUCCESS:
+            raise WzOpenAPIError(status, code, str(env.get("message") or ""), operation, trace_id)
+
+        self._log_success(method, path, operation, status, trace_id)
+        data = env.get("data")
+        return decode(data)
+
+    def _log_success(self, method: str, path: str, operation: str, status: int, trace_id: str) -> None:
+        if trace_id:
+            self.log.info(
+                "open api request method=%s path=%s operation=%s status=%s traceId=%s",
+                method,
+                path,
+                operation,
+                status,
+                trace_id,
+            )
+            return
+        self.log.info(
+            "open api request method=%s path=%s operation=%s status=%s",
+            method,
+            path,
+            operation,
+            status,
+        )
+
+    def _log_failure(self, method: str, path: str, operation: str, status: int, trace_id: str) -> None:
+        if trace_id:
+            self.log.error(
+                "open api request failed method=%s path=%s operation=%s status=%s traceId=%s",
+                method,
+                path,
+                operation,
+                status,
+                trace_id,
+            )
+            return
+        self.log.error(
+            "open api request failed method=%s path=%s operation=%s status=%s",
+            method,
+            path,
+            operation,
+            status,
+        )
+
+    def _should_retry(self, err: WzOpenError) -> bool:
+        if isinstance(err, WzOpenAPIError):
+            return err.status >= 500
+        cause = err.__cause__
+        return isinstance(cause, httpx.HTTPError)
+
+
+def _response_trace_id(resp: httpx.Response) -> str:
+    return (resp.headers.get(HEADER_B3_TRACE_ID) or "").strip()

wzopensdk/_internal/params.py

@@ -0,0 +1,52 @@
+"""Convert request models to signed parameter maps and GET query strings."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, is_dataclass
+from typing import Any
+from urllib.parse import quote
+
+from wzopensdk._internal import signer
+
+
+def to_params(value: Any) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if isinstance(value, dict):
+        raw = value
+    elif is_dataclass(value) and not isinstance(value, type):
+        raw = asdict(value)
+    elif hasattr(value, "__dict__"):
+        raw = {k: v for k, v in vars(value).items() if not k.startswith("_")}
+    else:
+        raw = {}
+    out: dict[str, Any] = {}
+    for key, item in raw.items():
+        if signer.is_blank(item):
+            continue
+        out[str(key)] = item
+    return out
+
+
+def encode_query(params: dict[str, Any]) -> str:
+    if not params:
+        return ""
+    parts: list[str] = []
+    for key in sorted(params.keys()):
+        value = params[key]
+        if signer.is_blank(value):
+            continue
+        items = _as_slice(value)
+        if items is not None:
+            q_key = key if key.endswith("[]") else key + "[]"
+            for item in items:
+                parts.append(f"{quote(q_key, safe='')}={quote(item, safe='')}")
+            continue
+        parts.append(f"{quote(str(key), safe='')}={quote(signer.stringify(value), safe='')}")
+    return "&".join(parts)
+
+
+def _as_slice(value: Any) -> list[str] | None:
+    if isinstance(value, (list, tuple)):
+        return [signer.stringify(item) for item in value if not signer.is_blank(item)]
+    return None

wzopensdk/_internal/signer.py

@@ -0,0 +1,96 @@
+"""HMAC-SHA256 signing aligned with api-open AuthLogic."""
+
+from __future__ import annotations
+
+import hmac
+import math
+from hashlib import sha256
+from typing import Any, Mapping
+
+KEY_SIGN = "sign"
+
+
+def content(params: Mapping[str, Any] | None) -> str:
+    if not params:
+        return ""
+    keys: list[str] = []
+    for key, value in params.items():
+        if key == KEY_SIGN:
+            continue
+        if is_blank(value):
+            continue
+        keys.append(str(key))
+    keys.sort()
+    return "&".join(f"{key}={stringify(params[key])}" for key in keys)
+
+
+def sum_hmac(text: str, secret: str) -> str:
+    digest = hmac.new(secret.encode("utf-8"), text.encode("utf-8"), sha256).hexdigest()
+    return digest.upper()
+
+
+def sign(params: Mapping[str, Any], secret: str) -> str:
+    return sum_hmac(content(params), secret)
+
+
+def is_blank(value: Any) -> bool:
+    if value is None:
+        return True
+    if isinstance(value, str):
+        return value == ""
+    if isinstance(value, (bytes, bytearray)):
+        return len(value) == 0
+    if isinstance(value, dict):
+        return len(value) == 0
+    if isinstance(value, (list, tuple, set)):
+        return len(value) == 0
+    return False
+
+
+def stringify(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "1" if value else ""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        return format_float(value)
+    if isinstance(value, (list, tuple)):
+        return ",".join(flatten(value))
+    return str(value)
+
+
+def format_float(f: float) -> str:
+    if math.isnan(f):
+        return "NaN"
+    if math.isinf(f):
+        return "+Inf" if f > 0 else "-Inf"
+    if f == math.trunc(f) and math.isfinite(f) and -(2**63) <= f <= 2**63 - 1:
+        return str(int(f))
+    s = format(f, ".15f").rstrip("0")
+    return s.rstrip(".")
+
+
+def flatten(values: Any) -> list[str]:
+    out: list[str] = []
+    for v in values:
+        if is_blank(v):
+            continue
+        if isinstance(v, (list, tuple)):
+            out.extend(flatten(v))
+            continue
+        out.append(stringify(v))
+    return out
+
+
+def clone_without_sign(params: Mapping[str, Any] | None) -> dict[str, Any]:
+    out = dict(params) if params else {}
+    out.pop(KEY_SIGN, None)
+    return out
+
+
+def sign_key(key: str) -> str:
+    return key[:-2] if key.endswith("[]") else key

wzopensdk/callback.py

@@ -0,0 +1,66 @@
+"""Callback-log domain models and service."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from wzopensdk._internal.http import HttpInvoker
+
+
+@dataclass
+class CallbackLogRequest:
+    charge_id: str | None = None
+
+
+@dataclass
+class CallbackLogEntry:
+    id: int = 0
+    charge_id: int = 0
+    path: str = ""
+    status: int = 0
+    http_status_code: int = 0
+    err_code: int = 0
+    err_msg: str = ""
+    req: str = ""
+    rep: str = ""
+    created_at: str = ""
+    updated_at: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> CallbackLogEntry:
+        data = data or {}
+        return cls(
+            id=int(data.get("id") or 0),
+            charge_id=int(data.get("chargeId") or 0),
+            path=str(data.get("path") or ""),
+            status=int(data.get("status") or 0),
+            http_status_code=int(data.get("httpStatusCode") or 0),
+            err_code=int(data.get("errCode") or 0),
+            err_msg=str(data.get("errMsg") or ""),
+            req=str(data.get("req") or ""),
+            rep=str(data.get("rep") or ""),
+            created_at=str(data.get("createdAt") or ""),
+            updated_at=str(data.get("updatedAt") or ""),
+        )
+
+
+@dataclass
+class CallbackRetryFinishOrderRequest:
+    charge_id: int | None = None
+
+
+class CallbackService:
+    def __init__(self, http: HttpInvoker) -> None:
+        self._http = http
+
+    def log(self, req: CallbackLogRequest) -> list[CallbackLogEntry]:
+        def decode(data: Any) -> list[CallbackLogEntry]:
+            if not isinstance(data, list):
+                return []
+            return [CallbackLogEntry.from_dict(item) for item in data if isinstance(item, dict)]
+
+        return self._http.invoke("GET", "/open/callback/log", "callback.log", req, decode)
+
+    def retry_finish_order(self, req: CallbackRetryFinishOrderRequest) -> None:
+        self._http.invoke_void("POST", "/open/callback/retry/finish_order", "callback.retry_finish_order", req)

wzopensdk/charge.py

@@ -0,0 +1,34 @@
+"""Charge domain models and service."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from wzopensdk._internal.http import HttpInvoker
+
+
+@dataclass
+class ChargeStartRequest:
+    device_num: str | None = None
+    device_port: int | None = None
+    charge_id: int | None = None
+    charge_mode: int | None = None
+    total_fee: int | None = None
+
+
+@dataclass
+class ChargeStopRequest:
+    device_num: str | None = None
+    device_port: int | None = None
+    charge_id: int | None = None
+
+
+class ChargeService:
+    def __init__(self, http: HttpInvoker) -> None:
+        self._http = http
+
+    def start(self, req: ChargeStartRequest) -> None:
+        self._http.invoke_void("POST", "/open/charge/start", "charge.start", req)
+
+    def stop(self, req: ChargeStopRequest) -> None:
+        self._http.invoke_void("POST", "/open/charge/stop", "charge.stop", req)

wzopensdk/client.py

@@ -0,0 +1,71 @@
+"""Shared runtime. Business methods live on the service attributes."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Callable
+
+import httpx
+
+from wzopensdk._internal.http import HttpInvoker
+from wzopensdk.callback import CallbackService
+from wzopensdk.charge import ChargeService
+from wzopensdk.device import DeviceService
+from wzopensdk.endpoints import Endpoints
+from wzopensdk.errors import WzOpenConfigError
+from wzopensdk.invoice import InvoiceService
+from wzopensdk.renew import RenewService
+
+
+class WzOpenClient:
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        app_id: str,
+        app_secret: str,
+        timeout: float = 10.0,
+        retry_count: int = 0,
+        retry_wait: float = 0.2,
+        user_agent: str = "wz-opensdk/python",
+        proxy_url: str | None = None,
+        insecure_skip_verify: bool = False,
+        logger: logging.Logger | None = None,
+        http_client: httpx.Client | None = None,
+        clock: Callable[[], int] | None = None,
+    ) -> None:
+        if not (endpoint or "").strip():
+            raise WzOpenConfigError(WzOpenConfigError.MISSING_ENDPOINT)
+        if not (app_id or "").strip():
+            raise WzOpenConfigError(WzOpenConfigError.MISSING_APP_ID)
+        if app_secret == "" or app_secret is None:
+            raise WzOpenConfigError(WzOpenConfigError.MISSING_APP_SECRET)
+
+        http = HttpInvoker(
+            endpoint=endpoint,
+            app_id=app_id,
+            app_secret=app_secret,
+            timeout=timeout,
+            retry_count=retry_count,
+            retry_wait=retry_wait,
+            user_agent=user_agent,
+            proxy_url=proxy_url,
+            insecure_skip_verify=insecure_skip_verify,
+            logger=logger,
+            http_client=http_client,
+            clock=clock,
+        )
+        self.device = DeviceService(http)
+        self.charge = ChargeService(http)
+        self.renew = RenewService(http)
+        self.invoice = InvoiceService(http)
+        self.callback = CallbackService(http)
+
+    @classmethod
+    def from_env(cls) -> WzOpenClient:
+        return cls(
+            endpoint=os.environ.get("WZ_OPEN_ENDPOINT") or Endpoints.TEST,
+            app_id=os.environ.get("WZ_OPEN_APP_ID") or "",
+            app_secret=os.environ.get("WZ_OPEN_APP_SECRET") or "",
+        )

wzopensdk/device.py

@@ -0,0 +1,312 @@
+"""Device domain models and service."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from wzopensdk._internal.http import HttpInvoker
+
+
+@dataclass
+class Device:
+    id: float = 0
+    device_num: str = ""
+    iot_phone: str = ""
+    device_type: float = 0
+    maturity_at: str = ""
+    created_at: str = ""
+    updated_at: str = ""
+    specification: dict[str, Any] = field(default_factory=dict)
+    status: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> Device:
+        data = data or {}
+        spec = data.get("specification")
+        status = data.get("status")
+        return cls(
+            id=float(data.get("id") or 0),
+            device_num=str(data.get("deviceNum") or ""),
+            iot_phone=str(data.get("iotPhone") or ""),
+            device_type=float(data.get("deviceType") or 0),
+            maturity_at=str(data.get("maturityAt") or ""),
+            created_at=str(data.get("createdAt") or ""),
+            updated_at=str(data.get("updatedAt") or ""),
+            specification=spec if isinstance(spec, dict) else {},
+            status=status if isinstance(status, dict) else {},
+        )
+
+
+@dataclass
+class DeviceAddRequest:
+    device_num: str | None = None
+
+
+@dataclass
+class DeviceAddResult:
+    device_id: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> DeviceAddResult:
+        data = data or {}
+        return cls(device_id=str(data.get("deviceId") or ""))
+
+
+@dataclass
+class DeviceNumRequest:
+    device_num: str | None = None
+
+
+@dataclass
+class DeviceFindListRequest:
+    page: int | None = None
+    page_size: int | None = None
+    device_type: int | None = None
+    device_num: str | None = None
+    iot_phone: str | None = None
+
+
+@dataclass
+class DeviceFindListResult:
+    count: float = 0
+    list: list[dict[str, Any]] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> DeviceFindListResult:
+        data = data or {}
+        items = data.get("list")
+        return cls(
+            count=float(data.get("count") or 0),
+            list=list(items) if isinstance(items, list) else [],
+        )
+
+
+@dataclass
+class DeviceFindMultiRequest:
+    device_nums: list[str] | None = None
+
+
+@dataclass
+class DeviceSaveModeRequest:
+    charge_mode: int | None = None
+    device_num: str | None = None
+    charge_type: str | None = None
+    charge_value: str | list[str] | None = None
+    max_power: int | None = None
+    start_fee: int | None = None
+    max_pay_fee: int | None = None
+    payment_value: str | list[str] | None = None
+    time_value: str | list[str] | None = None
+    work_charge: int | None = None
+    work_charge_fourdigit: int | None = None
+    power_value: str | None = None
+    price_value: str | None = None
+    check_time: int | None = None
+    inc_time: int | None = None
+    type: int | None = None
+    count_mode: int | None = None
+    display_delay: str | None = None
+    is_not_disturb: str | None = None
+    not_disturb_start: str | None = None
+    not_disturb_end: str | None = None
+    not_disturb_volume: int | None = None
+    is_outage: int | None = None
+    auto_off_wait_time: int | None = None
+    auto_off_lower_power: int | None = None
+    floating_charge_time: str | None = None
+    floating_charge_power: int | None = None
+    whether_refund: int | None = None
+    is_free_charge: int | None = None
+    detect_time: int | None = None
+    is_pkvy: str | None = None
+    pkvy_time_value: str | None = None
+    pkvy_price_value: str | None = None
+    pkvy_service_type: str | None = None
+    pkvy_service_value_at_work: str | None = None
+    pkvy_service_value_at_time: str | None = None
+    pkvy_service_value_at_num: str | None = None
+
+
+@dataclass
+class DeviceSaveCarModeRequest:
+    charge_mode: int | None = None
+    volume: int | None = None
+    parking_word: str | None = None
+    time_value: str | None = None
+    price_value: str | None = None
+    total_value: str | None = None
+    device_num: str | None = None
+
+
+@dataclass
+class DeviceStateRequest:
+    device_num: str | None = None
+    port_fields: list[str] | None = None
+
+
+@dataclass
+class DeviceState:
+    is_online: bool = False
+    csq: int = 0
+    connection_type: int = 0
+    state: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> DeviceState:
+        data = data or {}
+        state = data.get("state")
+        return cls(
+            is_online=bool(data.get("isOnline")),
+            csq=int(data.get("csq") or 0),
+            connection_type=int(data.get("connectionType") or 0),
+            state=state if isinstance(state, dict) else {},
+        )
+
+
+@dataclass
+class DeviceStateListRequest:
+    device_nums: list[str] | None = None
+    port_fields: list[str] | None = None
+
+
+@dataclass
+class DeviceRestartRequest:
+    device_nums: list[str] | None = None
+    type: int | None = None
+
+
+@dataclass
+class DeviceOfflineRequest:
+    device_nums: list[str] | None = None
+
+
+@dataclass
+class DeviceOfflineProfitRequest:
+    device_nums: list[str] | None = None
+    coin: int | None = None
+    card: int | None = None
+
+
+@dataclass
+class DevicePortErrorRequest:
+    device_num: str | None = None
+    device_port: str | None = None
+    is_error: str | None = None
+
+
+@dataclass
+class DeviceOnlineLogRequest:
+    device_num: str | None = None
+    page: int | None = None
+    limit: int | None = None
+
+
+@dataclass
+class DeviceOnlineLogResult:
+    logs: list[dict[str, Any]] = field(default_factory=list)
+    count: float = 0
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> DeviceOnlineLogResult:
+        data = data or {}
+        logs = data.get("logs")
+        return cls(
+            logs=list(logs) if isinstance(logs, list) else [],
+            count=float(data.get("count") or 0),
+        )
+
+
+class DeviceService:
+    def __init__(self, http: HttpInvoker) -> None:
+        self._http = http
+
+    def add(self, req: DeviceAddRequest) -> DeviceAddResult:
+        return self._http.invoke("POST", "/open/device/add", "device.add", req, DeviceAddResult.from_dict)
+
+    def delete(self, req: DeviceNumRequest) -> None:
+        self._http.invoke_void("GET", "/open/device/del", "device.delete", req)
+
+    def find_one(self, req: DeviceNumRequest) -> Device:
+        return self._http.invoke("GET", "/open/device/findOne", "device.find_one", req, Device.from_dict)
+
+    def find_list(self, req: DeviceFindListRequest) -> DeviceFindListResult:
+        return self._http.invoke("GET", "/open/device/findList", "device.find_list", req, DeviceFindListResult.from_dict)
+
+    def find_multi(self, req: DeviceFindMultiRequest) -> dict[str, Any] | None:
+        return self._http.invoke_map("POST", "/open/device/findMultiDevices", "device.find_multi", req)
+
+    def save_mode(self, req: DeviceSaveModeRequest) -> None:
+        self._http.invoke_void("POST", "/open/device/saveMode", "device.save_mode", req)
+
+    def save_car_mode(self, req: DeviceSaveCarModeRequest) -> None:
+        self._http.invoke_void("POST", "/open/device/saveMode", "device.save_car_mode", req)
+
+    def get_mode(self, req: DeviceNumRequest) -> dict[str, Any] | None:
+        return self._http.invoke_map("GET", "/open/device/getMode", "device.get_mode", req)
+
+    def get_car_mode(self, req: DeviceNumRequest) -> dict[str, Any] | None:
+        return self._http.invoke_map("GET", "/open/device/getMode", "device.get_car_mode", req)
+
+    def get_setting_not_disturb_info(self, req: DeviceNumRequest) -> dict[str, Any] | None:
+        return self._http.invoke_map(
+            "GET", "/open/device/getDeviceSettingNotDisturbInfo", "device.setting.not_disturb", req
+        )
+
+    def get_setting_online_card_info(self, req: DeviceNumRequest) -> dict[str, Any] | None:
+        return self._http.invoke_map(
+            "GET", "/open/device/getDeviceSettingOnlineCardInfo", "device.setting.online_card", req
+        )
+
+    def get_setting_offline_card_info(self, req: DeviceNumRequest) -> dict[str, Any] | None:
+        return self._http.invoke_map(
+            "GET", "/open/device/getDeviceSettingOfflineCardInfo", "device.setting.offline_card", req
+        )
+
+    def get_setting_safety_info(self, req: DeviceNumRequest) -> dict[str, Any] | None:
+        return self._http.invoke_map("GET", "/open/device/getDeviceSettingSafetyInfo", "device.setting.safety", req)
+
+    def get_setting_coin_info(self, req: DeviceNumRequest) -> dict[str, Any] | None:
+        return self._http.invoke_map("GET", "/open/device/getDeviceSettingCoinInfo", "device.setting.coin", req)
+
+    def get_setting_user_info(self, req: DeviceNumRequest) -> dict[str, Any] | None:
+        return self._http.invoke_map("GET", "/open/device/getDeviceSettingUserInfo", "device.setting.user", req)
+
+    def get_mode_time_info(self, req: DeviceNumRequest) -> dict[str, Any] | None:
+        return self._http.invoke_map("GET", "/open/device/getDeviceModeTimeInfo", "device.mode.time", req)
+
+    def get_mode_time1_info(self, req: DeviceNumRequest) -> dict[str, Any] | None:
+        return self._http.invoke_map("GET", "/open/device/getDeviceModeTime1Info", "device.mode.time2", req)
+
+    def get_mode_work_info(self, req: DeviceNumRequest) -> dict[str, Any] | None:
+        return self._http.invoke_map("GET", "/open/device/getDeviceModeWorkInfo", "device.mode.work", req)
+
+    def get_mode_work1_info(self, req: DeviceNumRequest) -> dict[str, Any] | None:
+        return self._http.invoke_map("GET", "/open/device/getDeviceModeWork1Info", "device.mode.work2", req)
+
+    def get_mode_power_info(self, req: DeviceNumRequest) -> dict[str, Any] | None:
+        return self._http.invoke_map("GET", "/open/device/getDeviceModePowerInfo", "device.mode.power", req)
+
+    def get_mode_power1_info(self, req: DeviceNumRequest) -> dict[str, Any] | None:
+        return self._http.invoke_map("GET", "/open/device/getDeviceModePower1Info", "device.mode.power2", req)
+
+    def get_state(self, req: DeviceStateRequest) -> DeviceState:
+        return self._http.invoke("GET", "/open/device/state", "device.state.get", req, DeviceState.from_dict)
+
+    def list_state(self, req: DeviceStateListRequest) -> dict[str, Any] | None:
+        return self._http.invoke_map("GET", "/open/device/state/list", "device.state.list", req)
+
+    def restart(self, req: DeviceRestartRequest) -> None:
+        self._http.invoke_void("POST", "/open/device/state/restart", "device.state.restart", req)
+
+    def offline(self, req: DeviceOfflineRequest) -> None:
+        self._http.invoke_void("POST", "/open/device/state/offline", "device.state.offline", req)
+
+    def set_offline_profit(self, req: DeviceOfflineProfitRequest) -> None:
+        self._http.invoke_void("POST", "/open/device/state/offline_profit", "device.state.offline_profit", req)
+
+    def set_port_error(self, req: DevicePortErrorRequest) -> None:
+        self._http.invoke_void("POST", "/open/device/state/port/error", "device.state.port_error", req)
+
+    def online_log(self, req: DeviceOnlineLogRequest) -> DeviceOnlineLogResult:
+        return self._http.invoke("GET", "/open/device/log/online_log", "device.log.online", req, DeviceOnlineLogResult.from_dict)

wzopensdk/endpoints.py

@@ -0,0 +1,6 @@
+"""Open-platform base URLs."""
+
+
+class Endpoints:
+    TEST = "https://dev-api-open.wanzhuangkj.com"
+    PROD = "https://api-open.wanzhuangkj.com"

wzopensdk/errors.py

@@ -0,0 +1,47 @@
+"""SDK exceptions."""
+
+from __future__ import annotations
+
+
+class WzOpenError(Exception):
+    """Base SDK error."""
+
+
+class WzOpenConfigError(WzOpenError):
+    """Invalid constructor configuration."""
+
+    MISSING_ENDPOINT = "endpoint is required"
+    MISSING_APP_ID = "app id is required"
+    MISSING_APP_SECRET = "app secret is required"
+
+
+class WzOpenAPIError(WzOpenError):
+    """HTTP non-2xx or envelope code != 1."""
+
+    def __init__(self, status: int, code: int, message: str, operation: str, trace_id: str = "") -> None:
+        self.status = status
+        self.code = code
+        self.api_message = message
+        self.operation = operation
+        self.trace_id = (trace_id or "").strip()
+        if message:
+            text = f"wzopensdk: {operation}: http {status} code {code}: {message}"
+        else:
+            text = f"wzopensdk: {operation}: http {status} code {code}"
+        super().__init__(text)
+
+    @classmethod
+    def http_status(cls, status: int, operation: str, trace_id: str = "") -> WzOpenAPIError:
+        texts = {
+            400: "Bad Request",
+            401: "Unauthorized",
+            403: "Forbidden",
+            404: "Not Found",
+            408: "Request Timeout",
+            429: "Too Many Requests",
+            500: "Internal Server Error",
+            502: "Bad Gateway",
+            503: "Service Unavailable",
+            504: "Gateway Timeout",
+        }
+        return cls(status, status, texts.get(status, f"HTTP {status}"), operation, trace_id)

wzopensdk/invoice.py

@@ -0,0 +1,84 @@
+"""Invoice domain models and service."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from wzopensdk._internal.http import HttpInvoker
+
+
+@dataclass
+class InvoiceTitle:
+    buyer_name: str = ""
+    buyer_tax_num: str = ""
+    notify_email: str = ""
+    is_cron: int = 0
+    cron_job: str = ""
+    created_at: str = ""
+    updated_at: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> InvoiceTitle:
+        data = data or {}
+        return cls(
+            buyer_name=str(data.get("buyerName") or ""),
+            buyer_tax_num=str(data.get("buyerTaxNum") or ""),
+            notify_email=str(data.get("notifyEmail") or ""),
+            is_cron=int(data.get("isCron") or 0),
+            cron_job=str(data.get("cronJob") or ""),
+            created_at=str(data.get("createdAt") or ""),
+            updated_at=str(data.get("updatedAt") or ""),
+        )
+
+
+@dataclass
+class InvoiceSetTitleRequest:
+    buyer_name: str | None = None
+    buyer_tax_num: str | None = None
+    notify_email: str | None = None
+    is_cron: int | None = None
+    cron_job: str | None = None
+
+
+@dataclass
+class InvoicePendingAmount:
+    amount: int = 0
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> InvoicePendingAmount:
+        data = data or {}
+        return cls(amount=int(data.get("amount") or 0))
+
+
+@dataclass
+class InvoiceRecordsRequest:
+    page: str | None = None
+    limit: str | None = None
+
+
+@dataclass
+class InvoiceIssueRequest:
+    price: int | None = None
+
+
+class InvoiceService:
+    def __init__(self, http: HttpInvoker) -> None:
+        self._http = http
+
+    def title(self) -> InvoiceTitle:
+        return self._http.invoke("GET", "/open/invoice/getInvoiceTitle", "invoice.title.get", None, InvoiceTitle.from_dict)
+
+    def set_title(self, req: InvoiceSetTitleRequest) -> None:
+        self._http.invoke_void("POST", "/open/invoice/setInvoiceTitle", "invoice.title.set", req)
+
+    def pending_amount(self) -> InvoicePendingAmount:
+        return self._http.invoke(
+            "GET", "/open/invoice/getPendingAmount", "invoice.pending_amount", None, InvoicePendingAmount.from_dict
+        )
+
+    def records(self, req: InvoiceRecordsRequest) -> dict[str, Any] | None:
+        return self._http.invoke_map("GET", "/open/invoice/getInvoiceRecords", "invoice.records", req)
+
+    def issue(self, req: InvoiceIssueRequest) -> dict[str, Any] | None:
+        return self._http.invoke_map("POST", "/open/invoice/issueInvoice", "invoice.issue", req)

wzopensdk/renew.py

@@ -0,0 +1,61 @@
+"""Renew domain models and service."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from wzopensdk._internal.http import HttpInvoker
+
+
+@dataclass
+class RenewExpireListRequest:
+    page: int | None = None
+    limit: str | None = None
+
+
+@dataclass
+class RenewCreateOrderRequest:
+    out_trade_no: str | None = None
+    device_nums: list[str] | None = None
+
+
+@dataclass
+class RenewCreateOrderResult:
+    qr_code: str = ""
+    trans_amt: str = ""
+    trans_stat: str = ""
+    resp_code: str = ""
+    resp_desc: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> RenewCreateOrderResult:
+        data = data or {}
+        return cls(
+            qr_code=str(data.get("qrCode") or ""),
+            trans_amt=str(data.get("transAmt") or ""),
+            trans_stat=str(data.get("transStat") or ""),
+            resp_code=str(data.get("respCode") or ""),
+            resp_desc=str(data.get("respDesc") or ""),
+        )
+
+
+@dataclass
+class RenewStatusRequest:
+    out_trade_no: str | None = None
+
+
+class RenewService:
+    def __init__(self, http: HttpInvoker) -> None:
+        self._http = http
+
+    def expire_device_list(self, req: RenewExpireListRequest) -> dict[str, Any] | None:
+        return self._http.invoke_map("GET", "/open/renew/getCompanyExpireDeviceList", "renew.expire_list", req)
+
+    def create_order(self, req: RenewCreateOrderRequest) -> RenewCreateOrderResult:
+        return self._http.invoke(
+            "POST", "/open/renew/createCompanyRenewOrder", "renew.create_order", req, RenewCreateOrderResult.from_dict
+        )
+
+    def status(self, req: RenewStatusRequest) -> dict[str, Any] | None:
+        return self._http.invoke_map("GET", "/open/renew/getCompanyRenewStatus", "renew.status", req)