nuonuo-sdk 0.2.0__tar.gz

nuonuo_sdk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qingdao Ohm Network Technology Co., Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nuonuo_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: nuonuo-sdk
+Version: 0.2.0
+Summary: Python SDK for Nuonuo Open Platform invoicing APIs
+Author-email: "Qingdao Ohm Network Technology Co., Ltd." <kevin@odoomommy.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/jellyfrank/nuonuo-sdk
+Project-URL: Documentation, https://jss.com.cn/open/
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3,>=2.31
+Requires-Dist: simplejson>=3.19
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: build>=1; extra == "test"
+Dynamic: license-file
+
+# 诺诺开放平台 Python SDK
+
+青岛欧姆维护的第三方 `nuonuo-sdk`，导入名 `nuonuo`，独立于 Odoo，要求 Python 3.10+。
+采用与发票云 SDK 一致的客户端／业务服务风格。诺诺官方也提供 Python 示例；本库在核对该示例协议的基础上提供可安装包、认证、业务方法、错误处理与离线测试，并非官方 SDK。
+
+## 安装与查询
+
+```bash
+pip install nuonuo-sdk==0.2.0
+```
+
+生产依赖建议固定已验证版本。源码安装也可固定完整提交 SHA。
+
+```python
+import os
+from nuonuo import Nuonuo, PRODUCTION_URL, SANDBOX_URL
+
+with Nuonuo(
+    app_key=os.environ['NUONUO_APP_KEY'],
+    app_secret=os.environ['NUONUO_APP_SECRET'],
+    access_token=os.environ['NUONUO_ACCESS_TOKEN'],
+    tax_number=os.environ.get('NUONUO_TAX_NUMBER', ''),  # 第三方应用必填授权商户税号
+    base_url=SANDBOX_URL,  # 正式环境使用 PRODUCTION_URL，凭据也必须匹配环境
+) as client:
+    pending = client.invoice.pending(extension_num='0')
+    # 使用已经持久保存的原业务单号查询；需应用具有此接口权限。
+    result = client.invoice.query(order_nos=['your-existing-order-no'])
+```
+
+文档标明 `100188` 等部分接口不支持沙箱；不能假定每个方法都能在沙箱联调。
+`100075` 是最近 72 小时内的极速开票待开票列表，不是直接开票接口。
+
+## 认证
+
+自用型应用首次获取：
+
+```python
+with Nuonuo(app_key='your-app-key', app_secret='your-app-secret') as client:
+    token_data = client.get_merchant_token()
+    # 将完整 token_data 写入应用自己的安全存储，后续实例使用 access_token 初始化。
+```
+
+获取成功后会更新当前实例 token。自用型应用在到期前显式再次调用 `get_merchant_token()`。
+官方说明 token 默认有效 24 小时、30 天内调用上限 50 次；可配置永久有效。
+本库不猜测永久 token 的 expires_in 表示，不自动申请或刷新。调用方按账号和环境共享持久化令牌、协调刷新锁并根据返回期限调度；勿每个请求重新取 token。
+
+服务商／第三方应用：
+
+```python
+url = client.authorization_url('https://your-app.example/callback', state='secure-random-state')
+# 让用户完成授权，服务端核验回调 state 后：
+token_data = client.exchange_code(code, tax_number, 'https://your-app.example/callback')
+# 保存 access_token、refresh_token、userId、expires_in。刷新时 client_id 是 userId：
+new_token_data = client.refresh_isv_token(refresh_token, user_id)
+```
+
+授权码一次性使用；不要对不确定结果自动重试交换。刷新后安全保存新令牌，保留原 userId（刷新响应可能不返回它）。
+每个实例对应一个应用、环境及商户，不跨线程共享实例；重建 ISV 实例时同时传入对应税号。
+
+## 业务接口
+
+所有返回值均为完整字典，保留 `code`、`describe`、`result`。业务错误也原样返回，不凭通用成功码自动抛异常。
+
+| 方法 | 文档 ID | 用途 |
+| --- | --- | --- |
+| `client.invoice.pending(extension_num=None)` | 100075 | 极速开票待开票列表 |
+| `client.invoice.query(serial_nos=[...])` 或 `query(order_nos=[...])` | 100188 | 开票结果，1–50 个标识 |
+| `client.invoice.pdf_url(data)` | 100185 | 获取 PDF 地址，不下载 |
+| `client.invoice.inspect(data)` | 100136 | 发票查验，可能消耗额度 |
+| `client.invoice.cancel(data)` | 100166 | 对符合条件的发票作废 |
+| `client.invoice.redeliver(data)` | 100249 | 明确调用时向短信／邮箱重新交付 |
+| `client.invoice.issue_red(data)` | 101018 | 微信／支付宝联用蓝票的全额冲红 |
+| `client.nst.issue(order)` | 100607 | 诺税通 SaaS 请求开票 |
+| `client.nst.query(order_nos=[...], include_details=True)` | 专用测试账号实测 | 诺税通 SaaS 开票结果，1–50 个标识 |
+| `client.nst.list_invoices(data)` | 100595 | 诺税通 SaaS 发票列表 |
+| `client.call(method, data)` | 按实际接口 | 其他开放平台 API 通用入口 |
+
+`data` 使用官方字段名，区分大小写。除待开票、结果查询外，业务方法为薄封装，字段必填、长度、税目、金额一致性、红票资格等由调用方按当前接口文档校验。金额可传 `Decimal`，不会先转换为 float；响应 JSON 数值也保留 Decimal。官方标为 String 的金额字段仍应传字符串。
+
+诺税通 SaaS 开票要求对应产品资质与接口授权，`nst.issue` 接受 **order 内部字段**，自动包装成 `{"order": ...}`，不可重复嵌套。调用前保存 `orderNo`（每企业唯一）、完整请求及业务状态，按官方文档填写购销方、明细、`invoiceDate`、`invoiceType` 等字段。不提供可直接运行的真实开票样例，以免将演示数据提交为税票。
+`invoice.issue_red` 不是适用所有数电票的通用冲红入口；完整红字确认单流程不在本版业务封装内。
+
+## 下载票文件
+
+`from nuonuo.documents import download_document`，调用
+`download_document(url, allowed_hosts={"inv.jss.com.cn"}, kind="pdf")` 返回 `Document(name, mimetype, data)`。
+调用前校验查询结果中的订单、购销方、票种与金额，再使用接口返回的文件地址。
+允许域名由管理员确认，不从返回 URL 自动加入；仅 HTTPS、无重定向、单文件最多 10 MB，
+不携带应用凭据、netrc 凭据或继承代理配置。支持 PDF/OFD/XML；文件头检查不替代税票验真。
+
+## 签名、错误与恢复
+
+- 按官方 Python 2.0.0 示例：固定路径 `/open/v1/services`，Base64(HMAC-SHA1)，UTF-8 JSON 原文参与签名。公共参数放查询串，业务 JSON 放请求体；nonce 为文档要求的 8 位正整数。
+- 每次请求自动产生 32 位 `senid`，也可通过各方法的 `senid=` 显式传入。它是通信标识，不等同于业务幂等键。
+- 不自动重试业务请求，也不在 token 错误后自动刷新重发；默认连接／读取超时分别为 5／30 秒，拒绝 HTTP 重定向。
+- `TransportError`：网络或非 2xx HTTP；`ProtocolError`：无效 JSON／响应结构；`AuthenticationError`：未设置 token 或获取失败。异常文本不包含凭据、URL 或远端原始报文。
+- `E0000`、`S0000` 等业务码含义取决于接口。开票“提交成功”仅代表受理；根据原单号／流水号查询最终开票状态。
+- 超时、响应丢失或解析失败表示结果未知。先查询原业务单，不生成新订单号自动补开；如果仍不确定，交由业务核实。
+- SDK 不记录请求／返回值。返回字典含税票和个人信息，调用方审计时应脱敏。
+
+## 开发与验证
+
+```bash
+python -m pip install -e '.[test]'
+python -m pytest -q
+python -m build
+```
+
+离线测试使用合成数据，覆盖官方签名向量、实际发送字节、认证参数、金额精度、错误和防重复提交行为。
+GitHub Actions 配置 Python 3.10–3.14。2026-09-22 使用诺诺确认只产生测试数据的专用账号，
+已通过列表查询、单张数电普通蓝票提交、原订单结果查询和 PDF/OFD 下载。
+该测试账号使用正式网关；不能仅凭网关域名判定账号会否产生真实税票。
+历史 Juhui 沙箱配置的 `070601` 记录保留供排查，当前账号已通过验签及业务调用。
+详见 [沙箱联调记录](docs/sandbox-validation.md)。
+
+接口取证、文档版本和已知边界见 [docs/api-contract.md](docs/api-contract.md)。

nuonuo_sdk-0.2.0/README.md

@@ -0,0 +1,116 @@
+# 诺诺开放平台 Python SDK
+
+青岛欧姆维护的第三方 `nuonuo-sdk`，导入名 `nuonuo`，独立于 Odoo，要求 Python 3.10+。
+采用与发票云 SDK 一致的客户端／业务服务风格。诺诺官方也提供 Python 示例；本库在核对该示例协议的基础上提供可安装包、认证、业务方法、错误处理与离线测试，并非官方 SDK。
+
+## 安装与查询
+
+```bash
+pip install nuonuo-sdk==0.2.0
+```
+
+生产依赖建议固定已验证版本。源码安装也可固定完整提交 SHA。
+
+```python
+import os
+from nuonuo import Nuonuo, PRODUCTION_URL, SANDBOX_URL
+
+with Nuonuo(
+    app_key=os.environ['NUONUO_APP_KEY'],
+    app_secret=os.environ['NUONUO_APP_SECRET'],
+    access_token=os.environ['NUONUO_ACCESS_TOKEN'],
+    tax_number=os.environ.get('NUONUO_TAX_NUMBER', ''),  # 第三方应用必填授权商户税号
+    base_url=SANDBOX_URL,  # 正式环境使用 PRODUCTION_URL，凭据也必须匹配环境
+) as client:
+    pending = client.invoice.pending(extension_num='0')
+    # 使用已经持久保存的原业务单号查询；需应用具有此接口权限。
+    result = client.invoice.query(order_nos=['your-existing-order-no'])
+```
+
+文档标明 `100188` 等部分接口不支持沙箱；不能假定每个方法都能在沙箱联调。
+`100075` 是最近 72 小时内的极速开票待开票列表，不是直接开票接口。
+
+## 认证
+
+自用型应用首次获取：
+
+```python
+with Nuonuo(app_key='your-app-key', app_secret='your-app-secret') as client:
+    token_data = client.get_merchant_token()
+    # 将完整 token_data 写入应用自己的安全存储，后续实例使用 access_token 初始化。
+```
+
+获取成功后会更新当前实例 token。自用型应用在到期前显式再次调用 `get_merchant_token()`。
+官方说明 token 默认有效 24 小时、30 天内调用上限 50 次；可配置永久有效。
+本库不猜测永久 token 的 expires_in 表示，不自动申请或刷新。调用方按账号和环境共享持久化令牌、协调刷新锁并根据返回期限调度；勿每个请求重新取 token。
+
+服务商／第三方应用：
+
+```python
+url = client.authorization_url('https://your-app.example/callback', state='secure-random-state')
+# 让用户完成授权，服务端核验回调 state 后：
+token_data = client.exchange_code(code, tax_number, 'https://your-app.example/callback')
+# 保存 access_token、refresh_token、userId、expires_in。刷新时 client_id 是 userId：
+new_token_data = client.refresh_isv_token(refresh_token, user_id)
+```
+
+授权码一次性使用；不要对不确定结果自动重试交换。刷新后安全保存新令牌，保留原 userId（刷新响应可能不返回它）。
+每个实例对应一个应用、环境及商户，不跨线程共享实例；重建 ISV 实例时同时传入对应税号。
+
+## 业务接口
+
+所有返回值均为完整字典，保留 `code`、`describe`、`result`。业务错误也原样返回，不凭通用成功码自动抛异常。
+
+| 方法 | 文档 ID | 用途 |
+| --- | --- | --- |
+| `client.invoice.pending(extension_num=None)` | 100075 | 极速开票待开票列表 |
+| `client.invoice.query(serial_nos=[...])` 或 `query(order_nos=[...])` | 100188 | 开票结果，1–50 个标识 |
+| `client.invoice.pdf_url(data)` | 100185 | 获取 PDF 地址，不下载 |
+| `client.invoice.inspect(data)` | 100136 | 发票查验，可能消耗额度 |
+| `client.invoice.cancel(data)` | 100166 | 对符合条件的发票作废 |
+| `client.invoice.redeliver(data)` | 100249 | 明确调用时向短信／邮箱重新交付 |
+| `client.invoice.issue_red(data)` | 101018 | 微信／支付宝联用蓝票的全额冲红 |
+| `client.nst.issue(order)` | 100607 | 诺税通 SaaS 请求开票 |
+| `client.nst.query(order_nos=[...], include_details=True)` | 专用测试账号实测 | 诺税通 SaaS 开票结果，1–50 个标识 |
+| `client.nst.list_invoices(data)` | 100595 | 诺税通 SaaS 发票列表 |
+| `client.call(method, data)` | 按实际接口 | 其他开放平台 API 通用入口 |
+
+`data` 使用官方字段名，区分大小写。除待开票、结果查询外，业务方法为薄封装，字段必填、长度、税目、金额一致性、红票资格等由调用方按当前接口文档校验。金额可传 `Decimal`，不会先转换为 float；响应 JSON 数值也保留 Decimal。官方标为 String 的金额字段仍应传字符串。
+
+诺税通 SaaS 开票要求对应产品资质与接口授权，`nst.issue` 接受 **order 内部字段**，自动包装成 `{"order": ...}`，不可重复嵌套。调用前保存 `orderNo`（每企业唯一）、完整请求及业务状态，按官方文档填写购销方、明细、`invoiceDate`、`invoiceType` 等字段。不提供可直接运行的真实开票样例，以免将演示数据提交为税票。
+`invoice.issue_red` 不是适用所有数电票的通用冲红入口；完整红字确认单流程不在本版业务封装内。
+
+## 下载票文件
+
+`from nuonuo.documents import download_document`，调用
+`download_document(url, allowed_hosts={"inv.jss.com.cn"}, kind="pdf")` 返回 `Document(name, mimetype, data)`。
+调用前校验查询结果中的订单、购销方、票种与金额，再使用接口返回的文件地址。
+允许域名由管理员确认，不从返回 URL 自动加入；仅 HTTPS、无重定向、单文件最多 10 MB，
+不携带应用凭据、netrc 凭据或继承代理配置。支持 PDF/OFD/XML；文件头检查不替代税票验真。
+
+## 签名、错误与恢复
+
+- 按官方 Python 2.0.0 示例：固定路径 `/open/v1/services`，Base64(HMAC-SHA1)，UTF-8 JSON 原文参与签名。公共参数放查询串，业务 JSON 放请求体；nonce 为文档要求的 8 位正整数。
+- 每次请求自动产生 32 位 `senid`，也可通过各方法的 `senid=` 显式传入。它是通信标识，不等同于业务幂等键。
+- 不自动重试业务请求，也不在 token 错误后自动刷新重发；默认连接／读取超时分别为 5／30 秒，拒绝 HTTP 重定向。
+- `TransportError`：网络或非 2xx HTTP；`ProtocolError`：无效 JSON／响应结构；`AuthenticationError`：未设置 token 或获取失败。异常文本不包含凭据、URL 或远端原始报文。
+- `E0000`、`S0000` 等业务码含义取决于接口。开票“提交成功”仅代表受理；根据原单号／流水号查询最终开票状态。
+- 超时、响应丢失或解析失败表示结果未知。先查询原业务单，不生成新订单号自动补开；如果仍不确定，交由业务核实。
+- SDK 不记录请求／返回值。返回字典含税票和个人信息，调用方审计时应脱敏。
+
+## 开发与验证
+
+```bash
+python -m pip install -e '.[test]'
+python -m pytest -q
+python -m build
+```
+
+离线测试使用合成数据，覆盖官方签名向量、实际发送字节、认证参数、金额精度、错误和防重复提交行为。
+GitHub Actions 配置 Python 3.10–3.14。2026-09-22 使用诺诺确认只产生测试数据的专用账号，
+已通过列表查询、单张数电普通蓝票提交、原订单结果查询和 PDF/OFD 下载。
+该测试账号使用正式网关；不能仅凭网关域名判定账号会否产生真实税票。
+历史 Juhui 沙箱配置的 `070601` 记录保留供排查，当前账号已通过验签及业务调用。
+详见 [沙箱联调记录](docs/sandbox-validation.md)。
+
+接口取证、文档版本和已知边界见 [docs/api-contract.md](docs/api-contract.md)。

nuonuo_sdk-0.2.0/nuonuo/__init__.py

@@ -0,0 +1,6 @@
+from .client import Nuonuo, PRODUCTION_URL, SANDBOX_URL
+from .exceptions import AuthenticationError, NuonuoError, ProtocolError, TransportError
+
+__version__ = '0.2.0'
+__all__ = ['Nuonuo', 'PRODUCTION_URL', 'SANDBOX_URL', 'NuonuoError',
+           'AuthenticationError', 'ProtocolError', 'TransportError']

nuonuo_sdk-0.2.0/nuonuo/client.py

@@ -0,0 +1,169 @@
+"""Synchronous, instance-scoped Nuonuo client. No implicit retries or token requests."""
+import secrets
+import time
+import uuid
+from collections.abc import Mapping
+from urllib.parse import urlencode, urlsplit
+
+import requests
+import simplejson as json
+
+from .exceptions import AuthenticationError, ProtocolError, TransportError
+from .invoice import Invoice, Nst
+from .signing import sign
+
+PRODUCTION_URL = 'https://sdk.nuonuo.com/open/v1/services'
+SANDBOX_URL = 'https://sandbox.nuonuocs.cn/open/v1/services'
+TOKEN_URL = 'https://open.nuonuo.com/accessToken'
+AUTHORIZE_URL = 'https://open.nuonuo.com/authorize'
+
+
+def _https_url(value, path=None):
+    parsed = urlsplit(value)
+    if (parsed.scheme != 'https' or not parsed.hostname or parsed.username
+            or parsed.password or parsed.query or parsed.fragment
+            or (path and parsed.path != path)):
+        raise ValueError('Expected an HTTPS endpoint with no credentials, query or fragment')
+    return value
+
+
+def _text(value, name):
+    if not isinstance(value, str) or not value.strip() or '\r' in value or '\n' in value:
+        raise ValueError(f'{name} must be a non-empty, single-line string')
+    return value
+
+
+class Nuonuo:
+    """One instance per application, environment and authorized merchant.
+
+    Tokens are acquired explicitly because the platform limits token requests.
+    Persist token responses in the caller's secret store; reuse across workers.
+    """
+
+    def __init__(self, app_key, app_secret, *, access_token=None, tax_number='',
+                 base_url=PRODUCTION_URL, token_url=TOKEN_URL, timeout=(5, 30)):
+        self.app_key = _text(app_key, 'app_key')
+        self._app_secret = _text(app_secret, 'app_secret')
+        self.base_url = _https_url(base_url, '/open/v1/services')
+        self.token_url = _https_url(token_url)
+        self.tax_number = _text(tax_number, 'tax_number') if tax_number else ''
+        values = timeout if isinstance(timeout, tuple) else (timeout,)
+        if len(values) not in (1, 2) or any(not isinstance(v, (int, float)) or not 0 < v < float('inf') for v in values):
+            raise ValueError('timeout must contain positive finite seconds')
+        self.timeout = timeout
+        self._session = requests.Session()
+        self._access_token = None
+        if access_token is not None:
+            self.set_access_token(access_token)
+        self.invoice = Invoice(self)
+        self.nst = Nst(self)
+
+    def _post(self, url, **kwargs):
+        try:
+            response = self._session.post(
+                url, timeout=self.timeout, allow_redirects=False, **kwargs,
+            )
+        except requests.RequestException:
+            raise TransportError('Network request failed; remote outcome may be unknown') from None
+        try:
+            if not 200 <= response.status_code < 300:
+                raise TransportError(f'Unexpected HTTP status {response.status_code}; no retry performed')
+            try:
+                data = json.loads(response.content, use_decimal=True)
+            except (ValueError, UnicodeError):
+                raise ProtocolError('Response is not valid JSON') from None
+            if not isinstance(data, dict):
+                raise ProtocolError('Expected a JSON object')
+            return data
+        finally:
+            response.close()
+
+    def _token_request(self, fields):
+        data = self._post(self.token_url, data=fields)
+        token = data.get('access_token')
+        if not isinstance(token, str) or not token.strip() or '\r' in token or '\n' in token:
+            raise AuthenticationError('Token endpoint returned no valid access token')
+        self.set_access_token(token)
+        return data
+
+    def set_access_token(self, token):
+        """Install a persisted or freshly obtained token without an HTTP request."""
+        self._access_token = _text(token, 'access_token')
+
+    def get_merchant_token(self):
+        """Self-use application token. Caller manages expiry and shared persistence."""
+        return self._token_request({
+            'client_id': self.app_key, 'client_secret': self._app_secret,
+            'grant_type': 'client_credentials',
+        })
+
+    def authorization_url(self, redirect_uri, state):
+        """Caller must verify returned state before exchanging the authorization code."""
+        return AUTHORIZE_URL + '?' + urlencode({
+            'appKey': self.app_key, 'response_type': 'code',
+            'redirect_uri': _text(redirect_uri, 'redirect_uri'),
+            'state': _text(state, 'state'),
+        })
+
+    def exchange_code(self, code, tax_number, redirect_uri):
+        """Exchange a one-use ISV authorization code and bind this merchant."""
+        tax_number = _text(tax_number, 'tax_number')
+        data = self._token_request({
+            'client_id': self.app_key, 'client_secret': self._app_secret,
+            'grant_type': 'authorization_code', 'code': _text(code, 'code'),
+            'taxNum': tax_number, 'redirect_uri': _text(redirect_uri, 'redirect_uri'),
+        })
+        self.tax_number = tax_number
+        return data
+
+    def refresh_isv_token(self, refresh_token, user_id):
+        """client_id is the authorized user's userId, NOT appKey, for refresh."""
+        return self._token_request({
+            'client_id': _text(user_id, 'user_id'), 'client_secret': self._app_secret,
+            'grant_type': 'refresh_token',
+            'refresh_token': _text(refresh_token, 'refresh_token'),
+        })
+
+    def call(self, method, data, *, senid=None):
+        """Return the full business envelope, including error codes, unchanged.
+
+        senid identifies transport requests, not a substitute for order identity.
+        There is deliberately no auto-refresh, retry, or success-code guessing.
+        """
+        _text(method, 'method')
+        if not isinstance(data, Mapping):
+            raise TypeError('data must be a mapping of official API fields')
+        if not self._access_token:
+            raise AuthenticationError('Set or explicitly acquire an access token first')
+        if senid is None:
+            senid = uuid.uuid4().hex
+        if not isinstance(senid, str) or len(senid) != 32 or not senid.isascii() or not senid.isalnum():
+            raise ValueError('senid must contain 32 ASCII letters or digits')
+        content = json.dumps(dict(data), ensure_ascii=False, separators=(',', ':'),
+                             use_decimal=True, allow_nan=False)
+        # simplejson permits non-finite Decimal values; strict parse catches them too.
+        json.loads(content, allow_nan=False)
+        timestamp = str(int(time.time()))
+        nonce = str(10_000_000 + secrets.randbelow(90_000_000))
+        result = self._post(
+            self.base_url,
+            params={'senid': senid, 'nonce': nonce, 'timestamp': timestamp, 'appkey': self.app_key},
+            headers={
+                'Content-Type': 'application/json; charset=UTF-8',
+                'X-Nuonuo-Sign': sign(self._app_secret, self.app_key, senid, nonce, content, timestamp),
+                'accessToken': self._access_token, 'userTax': self.tax_number, 'method': method,
+            },
+            data=content.encode('utf-8'),
+        )
+        if not isinstance(result.get('code'), (str, int)):
+            raise ProtocolError('Response has no business code')
+        return result
+
+    def close(self):
+        self._session.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

nuonuo_sdk-0.2.0/nuonuo/documents.py

@@ -0,0 +1,52 @@
+"""Bounded downloads; allow-list is administrator configuration, never vendor input."""
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+
+import requests
+
+from .exceptions import ProtocolError, TransportError
+
+MAX_BYTES = 10 * 1024 * 1024
+
+
+@dataclass(frozen=True)
+class Document:
+    name: str
+    mimetype: str
+    data: bytes
+
+
+def download_document(url, *, allowed_hosts, kind='pdf'):
+    """Download one PDF/OFD/XML without credentials or redirects (10 MB limit)."""
+    kinds = {'pdf': 'application/pdf', 'ofd': 'application/ofd', 'xml': 'application/xml'}
+    if kind not in kinds:
+        raise ValueError('Unsupported document kind')
+    parsed = urlsplit(url)
+    hosts = {host.strip().lower() for host in allowed_hosts if host.strip()}
+    if (parsed.scheme != 'https' or not parsed.hostname or parsed.hostname.lower() not in hosts
+            or parsed.username or parsed.password or parsed.port not in (None, 443) or parsed.fragment):
+        raise ValueError('Document URL is not allowed')
+    try:
+        with requests.Session() as session:
+            session.trust_env = False  # Never inherit netrc credentials or proxy settings.
+            with session.get(url, timeout=(5, 30), stream=True, allow_redirects=False) as response:
+                if response.status_code != 200:
+                    raise TransportError('Document download failed')
+                chunks, size = [], 0
+                for chunk in response.iter_content(64 * 1024):
+                    size += len(chunk)
+                    if size > MAX_BYTES:
+                        raise ProtocolError('Document exceeds 10 MB')
+                    chunks.append(chunk)
+    except requests.RequestException:
+        raise TransportError('Document download failed') from None
+    content = b''.join(chunks)
+    if not content:
+        raise ProtocolError('Empty document')
+    if kind == 'pdf' and not content.startswith(b'%PDF-'):
+        raise ProtocolError('Response is not PDF')
+    if kind == 'ofd' and not content.startswith(b'PK'):
+        raise ProtocolError('Response is not an OFD container')
+    if kind == 'xml' and not content.lstrip(b'\xef\xbb\xbf \r\n\t').startswith(b'<'):
+        raise ProtocolError('Response is not XML')
+    return Document('invoice.' + kind, kinds[kind], content)

nuonuo_sdk-0.2.0/nuonuo/exceptions.py

@@ -0,0 +1,17 @@
+"""Errors deliberately omit URLs, credentials and remote response bodies."""
+
+
+class NuonuoError(Exception):
+    """Base SDK error."""
+
+
+class TransportError(NuonuoError):
+    """Outcome may be unknown; never blindly repeat an invoice submission."""
+
+
+class ProtocolError(NuonuoError):
+    """The remote response did not follow the expected JSON contract."""
+
+
+class AuthenticationError(NuonuoError):
+    """Token endpoint rejected the request or returned no token."""

nuonuo_sdk-0.2.0/nuonuo/invoice.py

@@ -0,0 +1,79 @@
+"""Thin business wrappers preserve official field spelling and business responses."""
+from collections.abc import Mapping
+
+
+class Invoice:
+    def __init__(self, client):
+        self._client = client
+
+    def pending(self, extension_num=None, *, senid=None):
+        """100075: speed-billing requests within the platform's 72-hour window."""
+        data = {} if extension_num is None else {'extensionNum': str(extension_num)}
+        return self._client.call('nuonuo.speedBilling.querySpeedBilling', data, senid=senid)
+
+    def query(self, *, serial_nos=None, order_nos=None, include_details=False, senid=None):
+        """100188: query up to 50 existing order numbers OR invoice serials."""
+        if bool(serial_nos) == bool(order_nos):
+            raise ValueError('Provide either serial_nos or order_nos')
+        values = serial_nos if serial_nos else order_nos
+        if (not isinstance(values, (list, tuple)) or not 1 <= len(values) <= 50
+                or any(not isinstance(v, str) or not v.strip() for v in values)):
+            raise ValueError('Provide 1 to 50 non-empty string identifiers')
+        data = {'serialNos' if serial_nos else 'orderNos': list(values),
+                'isOfferInvoiceDetail': '1' if include_details else '0'}
+        return self._client.call('nuonuo.ElectronInvoice.queryInvoiceResult', data, senid=senid)
+
+    def pdf_url(self, data, *, senid=None):
+        """100185: return the PDF URL envelope; does not download the file."""
+        return self._client.call('nuonuo.ElectronInvoice.getPDF', data, senid=senid)
+
+    def inspect(self, data, *, senid=None):
+        """100136: invoice authenticity inspection; may consume paid quota."""
+        return self._client.call('nuonuo.electronInvoice.invoiceInspection', data, senid=senid)
+
+    def cancel(self, data, *, senid=None):
+        """100166: cancel an eligible issued invoice."""
+        return self._client.call('nuonuo.electronInvoice.invoiceCancellation', data, senid=senid)
+
+    def redeliver(self, data, *, senid=None):
+        """100249: explicitly send an existing invoice via provider email/SMS."""
+        return self._client.call('nuonuo.ElectronInvoice.deliveryInvoice', data, senid=senid)
+
+    def issue_red(self, data, *, senid=None):
+        """101018: full red reversal, only for supported WeChat/Alipay linked blue invoices."""
+        return self._client.call('nuonuo.ElectronInvoice.unifiedfastInvoiceRed', data, senid=senid)
+
+
+class Nst:
+    """Separate Nuoshuitong SaaS product; requires corresponding entitlement."""
+
+    def __init__(self, client):
+        self._client = client
+
+    def issue(self, order, *, senid=None):
+        """100607: submit official order fields; persist order identity BEFORE calling."""
+        if not isinstance(order, Mapping):
+            raise TypeError('order must be a mapping of official order fields')
+        order_no = order.get('orderNo')
+        if not isinstance(order_no, str) or not order_no.strip() or len(order_no) > 64:
+            raise ValueError('Persist a non-empty orderNo of at most 64 characters before submission')
+        return self._client.call('nuonuo.OpeMplatform.requestBillingNew', {'order': order}, senid=senid)
+
+    def list_invoices(self, data, *, senid=None):
+        """100595: paginated invoice list; caller supplies official filter fields."""
+        return self._client.call('nuonuo.OpeMplatform.queryInvoiceList', data, senid=senid)
+
+    def query(self, *, serial_nos=None, order_nos=None, include_details=False, senid=None):
+        """NST result lookup verified against the authorized test account.
+
+        The payload matches the invoice result query, but the product namespace differs.
+        """
+        if bool(serial_nos) == bool(order_nos):
+            raise ValueError('Provide either serial_nos or order_nos')
+        values = serial_nos if serial_nos else order_nos
+        if (not isinstance(values, (list, tuple)) or not 1 <= len(values) <= 50
+                or any(not isinstance(v, str) or not v.strip() for v in values)):
+            raise ValueError('Provide 1 to 50 non-empty string identifiers')
+        data = {'serialNos' if serial_nos else 'orderNos': list(values),
+                'isOfferInvoiceDetail': '1' if include_details else '0'}
+        return self._client.call('nuonuo.OpeMplatform.queryInvoiceResult', data, senid=senid)

nuonuo_sdk-0.2.0/nuonuo/signing.py

@@ -0,0 +1,14 @@
+"""Nuonuo /open/v1/services signature, matching the official Python sample."""
+import base64
+import hashlib
+import hmac
+
+
+def sign(secret, app_key, senid, nonce, content, timestamp):
+    """Sign the exact Unicode JSON text subsequently sent as UTF-8 bytes."""
+    message = (
+        f"a=services&l=v1&p=open&k={app_key}&i={senid}"
+        f"&n={nonce}&t={timestamp}&f={content}"
+    )
+    digest = hmac.new(secret.encode('utf-8'), message.encode('utf-8'), hashlib.sha1).digest()
+    return base64.b64encode(digest).decode('ascii')

nuonuo_sdk-0.2.0/nuonuo_sdk.egg-info/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: nuonuo-sdk
+Version: 0.2.0
+Summary: Python SDK for Nuonuo Open Platform invoicing APIs
+Author-email: "Qingdao Ohm Network Technology Co., Ltd." <kevin@odoomommy.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/jellyfrank/nuonuo-sdk
+Project-URL: Documentation, https://jss.com.cn/open/
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3,>=2.31
+Requires-Dist: simplejson>=3.19
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: build>=1; extra == "test"
+Dynamic: license-file
+
+# 诺诺开放平台 Python SDK
+
+青岛欧姆维护的第三方 `nuonuo-sdk`，导入名 `nuonuo`，独立于 Odoo，要求 Python 3.10+。
+采用与发票云 SDK 一致的客户端／业务服务风格。诺诺官方也提供 Python 示例；本库在核对该示例协议的基础上提供可安装包、认证、业务方法、错误处理与离线测试，并非官方 SDK。
+
+## 安装与查询
+
+```bash
+pip install nuonuo-sdk==0.2.0
+```
+
+生产依赖建议固定已验证版本。源码安装也可固定完整提交 SHA。
+
+```python
+import os
+from nuonuo import Nuonuo, PRODUCTION_URL, SANDBOX_URL
+
+with Nuonuo(
+    app_key=os.environ['NUONUO_APP_KEY'],
+    app_secret=os.environ['NUONUO_APP_SECRET'],
+    access_token=os.environ['NUONUO_ACCESS_TOKEN'],
+    tax_number=os.environ.get('NUONUO_TAX_NUMBER', ''),  # 第三方应用必填授权商户税号
+    base_url=SANDBOX_URL,  # 正式环境使用 PRODUCTION_URL，凭据也必须匹配环境
+) as client:
+    pending = client.invoice.pending(extension_num='0')
+    # 使用已经持久保存的原业务单号查询；需应用具有此接口权限。
+    result = client.invoice.query(order_nos=['your-existing-order-no'])
+```
+
+文档标明 `100188` 等部分接口不支持沙箱；不能假定每个方法都能在沙箱联调。
+`100075` 是最近 72 小时内的极速开票待开票列表，不是直接开票接口。
+
+## 认证
+
+自用型应用首次获取：
+
+```python
+with Nuonuo(app_key='your-app-key', app_secret='your-app-secret') as client:
+    token_data = client.get_merchant_token()
+    # 将完整 token_data 写入应用自己的安全存储，后续实例使用 access_token 初始化。
+```
+
+获取成功后会更新当前实例 token。自用型应用在到期前显式再次调用 `get_merchant_token()`。
+官方说明 token 默认有效 24 小时、30 天内调用上限 50 次；可配置永久有效。
+本库不猜测永久 token 的 expires_in 表示，不自动申请或刷新。调用方按账号和环境共享持久化令牌、协调刷新锁并根据返回期限调度；勿每个请求重新取 token。
+
+服务商／第三方应用：
+
+```python
+url = client.authorization_url('https://your-app.example/callback', state='secure-random-state')
+# 让用户完成授权，服务端核验回调 state 后：
+token_data = client.exchange_code(code, tax_number, 'https://your-app.example/callback')
+# 保存 access_token、refresh_token、userId、expires_in。刷新时 client_id 是 userId：
+new_token_data = client.refresh_isv_token(refresh_token, user_id)
+```
+
+授权码一次性使用；不要对不确定结果自动重试交换。刷新后安全保存新令牌，保留原 userId（刷新响应可能不返回它）。
+每个实例对应一个应用、环境及商户，不跨线程共享实例；重建 ISV 实例时同时传入对应税号。
+
+## 业务接口
+
+所有返回值均为完整字典，保留 `code`、`describe`、`result`。业务错误也原样返回，不凭通用成功码自动抛异常。
+
+| 方法 | 文档 ID | 用途 |
+| --- | --- | --- |
+| `client.invoice.pending(extension_num=None)` | 100075 | 极速开票待开票列表 |
+| `client.invoice.query(serial_nos=[...])` 或 `query(order_nos=[...])` | 100188 | 开票结果，1–50 个标识 |
+| `client.invoice.pdf_url(data)` | 100185 | 获取 PDF 地址，不下载 |
+| `client.invoice.inspect(data)` | 100136 | 发票查验，可能消耗额度 |
+| `client.invoice.cancel(data)` | 100166 | 对符合条件的发票作废 |
+| `client.invoice.redeliver(data)` | 100249 | 明确调用时向短信／邮箱重新交付 |
+| `client.invoice.issue_red(data)` | 101018 | 微信／支付宝联用蓝票的全额冲红 |
+| `client.nst.issue(order)` | 100607 | 诺税通 SaaS 请求开票 |
+| `client.nst.query(order_nos=[...], include_details=True)` | 专用测试账号实测 | 诺税通 SaaS 开票结果，1–50 个标识 |
+| `client.nst.list_invoices(data)` | 100595 | 诺税通 SaaS 发票列表 |
+| `client.call(method, data)` | 按实际接口 | 其他开放平台 API 通用入口 |
+
+`data` 使用官方字段名，区分大小写。除待开票、结果查询外，业务方法为薄封装，字段必填、长度、税目、金额一致性、红票资格等由调用方按当前接口文档校验。金额可传 `Decimal`，不会先转换为 float；响应 JSON 数值也保留 Decimal。官方标为 String 的金额字段仍应传字符串。
+
+诺税通 SaaS 开票要求对应产品资质与接口授权，`nst.issue` 接受 **order 内部字段**，自动包装成 `{"order": ...}`，不可重复嵌套。调用前保存 `orderNo`（每企业唯一）、完整请求及业务状态，按官方文档填写购销方、明细、`invoiceDate`、`invoiceType` 等字段。不提供可直接运行的真实开票样例，以免将演示数据提交为税票。
+`invoice.issue_red` 不是适用所有数电票的通用冲红入口；完整红字确认单流程不在本版业务封装内。
+
+## 下载票文件
+
+`from nuonuo.documents import download_document`，调用
+`download_document(url, allowed_hosts={"inv.jss.com.cn"}, kind="pdf")` 返回 `Document(name, mimetype, data)`。
+调用前校验查询结果中的订单、购销方、票种与金额，再使用接口返回的文件地址。
+允许域名由管理员确认，不从返回 URL 自动加入；仅 HTTPS、无重定向、单文件最多 10 MB，
+不携带应用凭据、netrc 凭据或继承代理配置。支持 PDF/OFD/XML；文件头检查不替代税票验真。
+
+## 签名、错误与恢复
+
+- 按官方 Python 2.0.0 示例：固定路径 `/open/v1/services`，Base64(HMAC-SHA1)，UTF-8 JSON 原文参与签名。公共参数放查询串，业务 JSON 放请求体；nonce 为文档要求的 8 位正整数。
+- 每次请求自动产生 32 位 `senid`，也可通过各方法的 `senid=` 显式传入。它是通信标识，不等同于业务幂等键。
+- 不自动重试业务请求，也不在 token 错误后自动刷新重发；默认连接／读取超时分别为 5／30 秒，拒绝 HTTP 重定向。
+- `TransportError`：网络或非 2xx HTTP；`ProtocolError`：无效 JSON／响应结构；`AuthenticationError`：未设置 token 或获取失败。异常文本不包含凭据、URL 或远端原始报文。
+- `E0000`、`S0000` 等业务码含义取决于接口。开票“提交成功”仅代表受理；根据原单号／流水号查询最终开票状态。
+- 超时、响应丢失或解析失败表示结果未知。先查询原业务单，不生成新订单号自动补开；如果仍不确定，交由业务核实。
+- SDK 不记录请求／返回值。返回字典含税票和个人信息，调用方审计时应脱敏。
+
+## 开发与验证
+
+```bash
+python -m pip install -e '.[test]'
+python -m pytest -q
+python -m build
+```
+
+离线测试使用合成数据，覆盖官方签名向量、实际发送字节、认证参数、金额精度、错误和防重复提交行为。
+GitHub Actions 配置 Python 3.10–3.14。2026-09-22 使用诺诺确认只产生测试数据的专用账号，
+已通过列表查询、单张数电普通蓝票提交、原订单结果查询和 PDF/OFD 下载。
+该测试账号使用正式网关；不能仅凭网关域名判定账号会否产生真实税票。
+历史 Juhui 沙箱配置的 `070601` 记录保留供排查，当前账号已通过验签及业务调用。
+详见 [沙箱联调记录](docs/sandbox-validation.md)。
+
+接口取证、文档版本和已知边界见 [docs/api-contract.md](docs/api-contract.md)。

nuonuo_sdk-0.2.0/nuonuo_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+nuonuo/__init__.py
+nuonuo/client.py
+nuonuo/documents.py
+nuonuo/exceptions.py
+nuonuo/invoice.py
+nuonuo/signing.py
+nuonuo_sdk.egg-info/PKG-INFO
+nuonuo_sdk.egg-info/SOURCES.txt
+nuonuo_sdk.egg-info/dependency_links.txt
+nuonuo_sdk.egg-info/requires.txt
+nuonuo_sdk.egg-info/top_level.txt
+tests/test_sdk.py

nuonuo_sdk-0.2.0/nuonuo_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nuonuo_sdk-0.2.0/nuonuo_sdk.egg-info/requires.txt

@@ -0,0 +1,6 @@
+requests<3,>=2.31
+simplejson>=3.19
+
+[test]
+pytest>=8
+build>=1

nuonuo_sdk-0.2.0/nuonuo_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+nuonuo

nuonuo_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nuonuo-sdk"
+version = "0.2.0"
+description = "Python SDK for Nuonuo Open Platform invoicing APIs"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Qingdao Ohm Network Technology Co., Ltd.", email = "kevin@odoomommy.com"}]
+dependencies = ["requests>=2.31,<3", "simplejson>=3.19"]
+
+[project.urls]
+Repository = "https://github.com/jellyfrank/nuonuo-sdk"
+Documentation = "https://jss.com.cn/open/"
+
+[project.optional-dependencies]
+test = ["pytest>=8", "build>=1"]
+
+[tool.setuptools.packages.find]
+include = ["nuonuo*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

nuonuo_sdk-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nuonuo_sdk-0.2.0/tests/test_sdk.py

@@ -0,0 +1,224 @@
+import base64
+import hashlib
+import hmac
+from decimal import Decimal
+from unittest.mock import Mock
+from urllib.parse import parse_qs, urlsplit
+
+import pytest
+import requests
+import simplejson as json
+
+from nuonuo import Nuonuo, SANDBOX_URL, AuthenticationError, ProtocolError, TransportError
+from nuonuo.signing import sign
+
+
+@pytest.fixture
+def client():
+    with Nuonuo('app', 'secret', access_token='token', tax_number='tax', base_url=SANDBOX_URL) as c:
+        c._session.post = Mock()
+        c._session.post.return_value = response({'code': 'E0000', 'result': {}})
+        yield c
+
+
+def response(data, status=200):
+    r = requests.Response()
+    r.status_code = status
+    r._content = json.dumps(data).encode()
+    r._content_consumed = True
+    return r
+
+
+def test_signature_official_vector():
+    # Frozen against official NNOpenSDK.py get_sign; synthetic credentials only.
+    assert sign('secret', 'app', 'a' * 32, '12345678', '{"name":"中文"}', '1700000000') == '4BzcKzrcoqxPis0W/W3X2ae0uIo='
+
+
+def test_wire_bytes_and_precision(client, monkeypatch):
+    monkeypatch.setattr('nuonuo.client.time.time', lambda: 1700000000)
+    monkeypatch.setattr('nuonuo.client.secrets.randbelow', lambda n: 2345678)
+    client.call('nuonuo.example', {'name': '中文', 'amount': Decimal('123456789.123456789')}, senid='a' * 32)
+    args, kw = client._session.post.call_args
+    assert args == (SANDBOX_URL,)
+    assert kw['params'] == {'appkey': 'app', 'senid': 'a' * 32, 'nonce': '12345678', 'timestamp': '1700000000'}
+    assert kw['data'] == '{"name":"中文","amount":123456789.123456789}'.encode()
+    source = b'a=services&l=v1&p=open&k=app&i=' + b'a' * 32 + b'&n=12345678&t=1700000000&f=' + kw['data']
+    expected = base64.b64encode(hmac.new(b'secret', source, hashlib.sha1).digest()).decode()
+    assert kw['headers']['X-Nuonuo-Sign'] == expected
+    assert kw['headers']['accessToken'] == 'token'
+    assert kw['headers']['userTax'] == 'tax'
+    assert kw['allow_redirects'] is False
+    assert kw['timeout'] == (5, 30)
+
+
+@pytest.mark.parametrize('code', ['E0000', 'S0000', '200', 'S0101', 'E9500', 'invalid_token'])
+def test_business_envelope_not_interpreted_or_retried(client, code):
+    expected = {'code': code, 'describe': '说明', 'result': [1, 2]}
+    client._session.post.return_value = response(expected)
+    assert client.invoice.pending() == expected
+    assert client._session.post.call_count == 1
+
+
+@pytest.mark.parametrize('status', [301, 302, 400, 401, 429, 500])
+def test_http_failure_no_retry(client, status):
+    client._session.post.return_value = response({'secret': 'sensitive'}, status)
+    with pytest.raises(TransportError) as exc:
+        client.invoice.pending()
+    assert 'sensitive' not in str(exc.value)
+    assert client._session.post.call_count == 1
+
+
+def test_timeout_no_retry_or_leaked_credentials(client):
+    client._session.post.side_effect = requests.Timeout('https://secret.example/?accessToken=private')
+    with pytest.raises(TransportError) as exc:
+        client.invoice.pending()
+    assert 'private' not in str(exc.value)
+    assert exc.value.__suppress_context__
+    assert client._session.post.call_count == 1
+
+
+@pytest.mark.parametrize('content', [b'<html>error</html>', b'[]', b'null', b'{}', b'{"code":null}', b'\xff'])
+def test_malformed_response(client, content):
+    client._session.post.return_value._content = content
+    with pytest.raises(ProtocolError):
+        client.invoice.pending()
+
+
+def test_token_contracts(client):
+    client._session.post.return_value = response({'access_token': 'new', 'expires_in': '86400', 'refresh_token': 'r', 'userId': 'u'})
+    assert client.get_merchant_token()['access_token'] == 'new'
+    assert client._session.post.call_args.kwargs['data'] == {
+        'client_id': 'app', 'client_secret': 'secret', 'grant_type': 'client_credentials'}
+    client.exchange_code('code', 'merchant', 'https://example.com/callback')
+    fields = client._session.post.call_args.kwargs['data']
+    assert fields['taxNum'] == 'merchant'
+    assert fields['grant_type'] == 'authorization_code'
+    assert client.tax_number == 'merchant'
+    client.refresh_isv_token('r', 'u')
+    assert client._session.post.call_args.kwargs['data'] == {
+        'client_id': 'u', 'client_secret': 'secret', 'grant_type': 'refresh_token', 'refresh_token': 'r'}
+
+
+def test_token_rejection_does_not_replace_token(client):
+    client._session.post.return_value = response({'error': 'invalid_client', 'error_description': 'sensitive'})
+    with pytest.raises(AuthenticationError) as exc:
+        client.get_merchant_token()
+    assert 'sensitive' not in str(exc.value)
+    assert client._access_token == 'token'
+
+
+def test_authorization_url(client):
+    query = parse_qs(urlsplit(client.authorization_url('https://example.com/cb?a=1&b=2', 'a+b')).query)
+    assert query == {'appKey': ['app'], 'response_type': ['code'], 'redirect_uri': ['https://example.com/cb?a=1&b=2'], 'state': ['a+b']}
+
+
+def test_no_implicit_auth_and_instance_isolation(client):
+    with Nuonuo('other', 'other-secret') as other:
+        other._session.post = Mock()
+        with pytest.raises(AuthenticationError):
+            other.invoice.pending()
+        other._session.post.assert_not_called()
+        other.set_access_token('other-token')
+        assert client._access_token == 'token'
+
+
+@pytest.mark.parametrize('kwargs', [{}, {'order_nos': 'abc'}, {'order_nos': ['']}, {'order_nos': ['a'] * 51}, {'order_nos': ['a'], 'serial_nos': ['b']}])
+def test_query_validation(client, kwargs):
+    with pytest.raises(ValueError):
+        client.invoice.query(**kwargs)
+    client._session.post.assert_not_called()
+
+
+def test_query_shape(client):
+    client.invoice.query(order_nos=['order'], include_details=True)
+    assert json.loads(client._session.post.call_args.kwargs['data']) == {'orderNos': ['order'], 'isOfferInvoiceDetail': '1'}
+
+
+@pytest.mark.parametrize('group,name,method', [
+    ('invoice', 'pdf_url', 'nuonuo.ElectronInvoice.getPDF'),
+    ('invoice', 'inspect', 'nuonuo.electronInvoice.invoiceInspection'),
+    ('invoice', 'cancel', 'nuonuo.electronInvoice.invoiceCancellation'),
+    ('invoice', 'redeliver', 'nuonuo.ElectronInvoice.deliveryInvoice'),
+    ('invoice', 'issue_red', 'nuonuo.ElectronInvoice.unifiedfastInvoiceRed'),
+    ('nst', 'issue', 'nuonuo.OpeMplatform.requestBillingNew'),
+    ('nst', 'list_invoices', 'nuonuo.OpeMplatform.queryInvoiceList'),
+])
+def test_documented_method_mapping(client, group, name, method):
+    getattr(getattr(client, group), name)({'orderNo': 'existing'}, senid='b' * 32)
+    kw = client._session.post.call_args.kwargs
+    assert kw['headers']['method'] == method
+    assert json.loads(kw['data']) == ({'order': {'orderNo': 'existing'}} if name == 'issue' else {'orderNo': 'existing'})
+
+
+@pytest.mark.parametrize('value', [float('nan'), float('inf'), Decimal('NaN'), Decimal('Infinity')])
+def test_reject_nonfinite_money(client, value):
+    with pytest.raises(ValueError):
+        client.call('nuonuo.test', {'amount': value})
+    client._session.post.assert_not_called()
+
+
+@pytest.mark.parametrize('url', ['http://example.com/open/v1/services', 'https://user:pass@example.com/open/v1/services', 'https://example.com/wrong', SANDBOX_URL + '?x=1'])
+def test_endpoint_validation(url):
+    with pytest.raises(ValueError):
+        Nuonuo('a', 'b', base_url=url)
+
+
+@pytest.mark.parametrize('senid', ['', 'a', '中' * 32, '-' * 32])
+def test_senid_validation(client, senid):
+    with pytest.raises(ValueError):
+        client.invoice.pending(senid=senid)
+    client._session.post.assert_not_called()
+
+
+@pytest.mark.parametrize('order', [{}, {'orderNo': ''}, {'orderNo': 'x' * 65}, None])
+def test_issue_requires_persistable_identity(client, order):
+    with pytest.raises((ValueError, TypeError)):
+        client.nst.issue(order)
+    client._session.post.assert_not_called()
+
+
+def test_response_decimal_preserved(client):
+    client._session.post.return_value._content = b'{"code":"E0000","result":{"amount":123.4567890123456789}}'
+    assert client.invoice.pending()['result']['amount'] == Decimal('123.4567890123456789')
+
+
+def test_nst_query_namespace(client):
+    client.nst.query(order_nos=['persisted'], include_details=True)
+    kw = client._session.post.call_args.kwargs
+    assert kw['headers']['method'] == 'nuonuo.OpeMplatform.queryInvoiceResult'
+    assert json.loads(kw['data']) == {'orderNos': ['persisted'], 'isOfferInvoiceDetail': '1'}
+
+
+@pytest.mark.parametrize('kwargs', [{}, {'order_nos': 'a'}, {'order_nos': ['a'] * 51}, {'serial_nos': ['a'], 'order_nos': ['a']}])
+def test_nst_query_validation(client, kwargs):
+    with pytest.raises(ValueError):
+        client.nst.query(**kwargs)
+    client._session.post.assert_not_called()
+
+
+@pytest.mark.parametrize('url', ['http://files.example/a', 'https://evil.example/a', 'https://u:p@files.example/a', 'https://files.example:8443/a'])
+def test_document_host_guard(url):
+    from nuonuo.documents import download_document
+    with pytest.raises(ValueError):
+        download_document(url, allowed_hosts=['files.example'])
+
+
+def test_download_bounded_and_no_redirect(monkeypatch):
+    from nuonuo.documents import download_document
+    from unittest.mock import MagicMock
+    session = MagicMock()
+    monkeypatch.setattr('nuonuo.documents.requests.Session', lambda: session)
+    r = session.__enter__.return_value.get.return_value.__enter__.return_value
+    r.status_code = 200
+    r.iter_content.return_value = [b'%PDF-synthetic']
+    doc = download_document('https://files.example/a', allowed_hosts=['files.example'])
+    assert doc.data == b'%PDF-synthetic'
+    assert session.__enter__.return_value.trust_env is False
+    assert session.__enter__.return_value.get.call_args.kwargs['allow_redirects'] is False
+    r.status_code = 302
+    with pytest.raises(TransportError):
+        download_document('https://files.example/a', allowed_hosts=['files.example'])
+    r.status_code = 200
+    r.iter_content.return_value = [b'x' * (10 * 1024 * 1024 + 1)]
+    with pytest.raises(ProtocolError):
+        download_document('https://files.example/a', allowed_hosts=['files.example'])