py_tiehu_sdk
TieHuo 铁虎道闸平台 Python SDK — 32 个完整下行接口
📖 项目简介
py_tiehu_sdk 是 铁虎道闸平台 的 Python SDK 封装,提供自动签名、HTTP 请求发送、响应数据验证、异常统一处理等开箱即用的能力。
核心特性
- 🔐 自动签名 — 按道闸平台 6 步签名规则自动计算 sign,无需手动处理 MD5 拼接
- 🚀 类型安全 — 完整的 Pydantic v2 数据模型 + mypy strict 类型检查
- 📦 零样板 — 只需提供
base_url/app_key/parking_id,即可调用所有接口 - 🌐 httpx 驱动 — 支持 HTTP/2、连接池复用、代理配置、自定义超时
- 🛠 国际主流工具链 — uv 管理依赖、ruff 格式化/Lint、mypy 类型检查
🧱 项目结构
py_tiehu_sdk/
├── pyproject.toml # uv + hatchling 配置,版本动态读取 _version.py
├── uv.lock # 依赖锁文件
├── src/
│ └── py_tiehu_sdk/
│ ├── __init__.py # ✅ 对外统一入口(Provider + Config + 异常 + 响应模型)
│ ├── _version.py # 版本号(pyproject.toml 动态读取)
│ ├── provider.py # ✅ PklotAPIProvider — 对外统一访问入口
│ └── core/
│ └── pklot/
│ ├── __init__.py
│ ├── base/
│ │ ├── __init__.py # ✅ 统一对外导出(Config / 异常 / 模型 / API 基类)
│ │ ├── _config.py # PklotConfig(SDK 全局配置,Pydantic)
│ │ ├── _exceptions.py # SDK 异常体系(PklotError 基类 + 5 种子类)
│ │ ├── _models.py # PklotBaseResponse + PklotCommonResponse
│ │ ├── _signature.py # 🔒 签名算法(内部,不对外暴露)
│ │ └── _api.py # PklotBaseAPI + PklotAPI(请求处理器)
│ └── downstream/
│ ├── __init__.py # ✅ DownstreamAPI 导出
│ └── _api.py # DownstreamAPI(32 个下行业务接口)
├── tests/
│ ├── conftest.py # pytest 配置 + .env 加载 + --integration 开关
│ ├── test_signature.py # 签名算法单元测试
│ ├── test_models.py # 响应模型单元测试
│ ├── test_provider.py # Provider 构造 + 签名注入测试
│ └── test_integration.py # 🔗 真实网络集成测试(需 --integration)
├── scripts/
│ ├── quick_test.py # 快速验证脚本(执行查询类接口并打印返回)
│ └── debug_request.py # Debug 脚本(打印签名计算细节)
├── .env.example # 测试环境配置模板
└── LICENSE # MIT License
目录分层设计
┌──────────────────────────────────────────────────────────────┐
│ py_tiehu_sdk/__init__.py ← 对外唯一入口 │
│ py_tiehu_sdk/provider.py ← Provider 统一入口 │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ core/pklot/base/ 🔧 基础能力层 │
│ ├─ _config.py SDK 全局配置 │
│ ├─ _signature.py 🔒 签名算法(内部) │
│ ├─ _exceptions.py 异常定义 │
│ ├─ _models.py Pydantic 响应模型 │
│ └─ _api.py 请求处理器(签名 + HTTP + 解析) │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ core/pklot/downstream/ 📥 下行业务层 │
│ └─ _api.py DownstreamAPI — 32 个完整接口 │
└──────────────────────────────────────────────────────────────┘
调用链路示意
provider = PklotAPIProvider(config)
resp = provider.downstream_api.query_pklot()
PklotAPIProvider(config)
│
├─ .base_api = PklotAPI(config)
│ └─ 持有 httpx.Client,负责签名 + 请求 + 响应解析
│
└─ .downstream_api = DownstreamAPI(base_api)
└─ .query_pklot()
│
▼
base_api._post_json("queryPklot", {})
│
├─ _build_signed_payload() 自动注入 parkingId / timestamp / sign
├─ httpx.Client.post() 发送 JSON POST
├─ PklotCommonResponse 解析响应 JSON
└─ raise_for_status() status != 1 抛 PklotAPIError
📦 已实现的下行接口(32 个)
车位查询(3)
| 方法名 | 接口路径 | 文档编号 | 说明 |
|---|---|---|---|
query_pklot() |
queryPklot | 1.0 | 获取车场车位信息 |
get_parkinfo() |
getParkinfo | 2.1 | 获取车场详情 |
get_park_device_state() |
getParkDeviceState | 3.3 | 获取设备在线状态 |
临停缴费(4)
| 方法名 | 接口路径 | 文档编号 | 说明 |
|---|---|---|---|
calculating_temp_cost(application_id, plate_number) |
calculatingTempCost | 1.1 | 获取临停应缴金额 |
pay_temp_cost(plate_number, order_no, pay_fee, pay_type, order_id) |
payTempCost | 1.2 | 支付成功通知道闸 |
get_vehicle_information(plate_number) |
getVehicleInformation | 4.4 | 查询车辆在场信息 |
simulate_cla_fee(during_time) |
simulateClaFee | 4.3 | 模拟计算费用(duringTime 单位:分钟) |
车类 / 车型(2)
| 方法名 | 接口路径 | 文档编号 | 说明 |
|---|---|---|---|
get_park_car_type() |
getParkCarType | 1.3 | 获取车类列表 |
get_park_car_model() |
getParkCarModel | 1.4 | 获取车型列表 |
闸机控制(3)
| 方法名 | 接口路径 | 文档编号 | 说明 |
|---|---|---|---|
open_gate(gate_id, status) |
openGate | 2.5 | 远程开关闸(0关/1开/2常开/3常闭) |
get_park_gate() |
getParkGate | 2.4 | 获取通道列表 |
no_plate_qrcode(lane_no, open_id) |
noPlateQRcode | 1.6 | 无牌车扫码进出 |
月卡管理(6)
| 方法名 | 接口路径 | 文档编号 | 说明 |
|---|---|---|---|
pay_monthly(plate_number, amount, start_time, end_time, pay_type) |
payMonthly | 1.5 | 月卡续期 |
save_monthly_rent(emp_name, emp_mobile, plate_number, ...) |
saveMonthlyRent | 2.6 | 增加 / 修改月租 |
del_monthly_rent(plate_number) |
delMonthlyRent | 2.7 | 删除月租 |
get_monthly_rent(plate_number) |
getMonthlyRent | 2.8 | 车牌查月卡详情 |
get_monthly_rent_list(page_index, page_size, plate_number, rent_type) |
getMonthlyRentList | 2.9 | 月卡列表分页 |
del_monthly_rent_list(plate_numbers) |
delMonthlyRentList | 3.0 | 批量删除月租 |
储值充值(1)
| 方法名 | 接口路径 | 文档编号 | 说明 |
|---|---|---|---|
recharge_stored_value(plate_number, pay_fee) |
rechargeStoredValue | 4.1 | 储值车充值 |
访客(2)
| 方法名 | 接口路径 | 文档编号 | 说明 |
|---|---|---|---|
add_visit(plate_number, visitor_name, begin_time, end_time, visitor_count, car_model_id) |
addVisit | 1.7 | 添加访客 |
delete_visit(plate_number) |
deleteVisit | 4.0 | 取消访客(入场前可调用) |
锁车控制(1)
| 方法名 | 接口路径 | 文档编号 | 说明 |
|---|---|---|---|
lock_car(plate_number) |
lockCar | 2.0 | 锁车 / 解锁(连续调用切换状态) |
黑名单(3)
| 方法名 | 接口路径 | 文档编号 | 说明 |
|---|---|---|---|
add_park_black(plate_number, start_time, end_time, status) |
addParkBlack | 2.2 | 增加黑名单 |
del_park_blacklist(plate_number) |
delParkBlacklist | 2.3 | 删除黑名单 |
get_park_black_list(plate_number, page_index, page_size) |
getParkBlackList | 3.5 | 黑名单列表分页 |
商家打折(2)
| 方法名 | 接口路径 | 文档编号 | 说明 |
|---|---|---|---|
discount_rules(seller_no, pwd) |
discountRules | 1.8 | 获取商家打折规则 |
discount_pay(plate_number, seller_no, derate_id, derate_value, seller_id) |
discountPay | 1.9 | 消费打折 |
商家管理(3)
| 方法名 | 接口路径 | 文档编号 | 说明 |
|---|---|---|---|
seller_charge(seller_id, money) |
sellerCharge | 3.7 | 商家充值 |
seller_charge_list(seller_id, parking_nume) |
sellerChargeList | 3.8 | 商家优免记录 |
get_park_seller_list(page_index, page_size) |
getParkSellerList | 3.9 | 车场商家列表分页 |
其他辅助(2)
| 方法名 | 接口路径 | 文档编号 | 说明 |
|---|---|---|---|
upate_plate_info(old_plate_number, new_plate_number, gate_id, record_id) |
upatePlateInfo | 3.4 | 修改车牌号(平台接口名拼写有误,保持原样) |
parking_invoice(order_id, open_id, title_type, buyer_title) |
parkingInvoice | 4.5 | 车场开票 |
🚀 快速开始
前置要求
- Python 3.10 或更高
- uv 包管理器(推荐)或 pip
安装
# 方式一:通过 uv 安装(推荐)
uv add py-tiehu-sdk
# 方式二:通过 pip 安装
pip install py-tiehu-sdk
# 开发模式(本地开发)
git clone <repo-url> py_tiehu_sdk
cd py_tiehu_sdk
uv sync --dev
配置环境变量
复制 .env.example 为 .env,填入你的道闸平台测试参数:
cp .env.example .env
# 然后编辑 .env 填入真实值
.env 内容示例:
# API 基础 URL(去掉 /interface 后缀)
PKLOT_BASE_URL=http://ykt.test.cxyun.net.cn:7303/cxzn
# 道闸平台分配的 appKey(明文,SDK 内部自动 MD5)
PKLOT_APP_KEY=b620f6be42328effc32b982a2b9
# 默认车场 ID
PKLOT_PARKING_ID=5607116888606308222
# HTTP 请求超时(秒)
PKLOT_TIMEOUT=30.0
基本使用
from py_tiehu_sdk import PklotAPIProvider, PklotConfig
# 1. 创建配置(从 .env 读取,或直接硬编码)
config = PklotConfig(
base_url="http://ykt.test.cxyun.net.cn:7303/cxzn",
app_key="your_app_key_here",
parking_id="your_parking_id_here",
)
# 2. 创建 Provider(SDK 统一入口)
provider = PklotAPIProvider(config)
# 3. 调用下行接口
resp = provider.downstream_api.query_pklot()
# 4. 检查结果
if resp.ok:
print("✅ 成功!")
print(f" 总车位 : {resp.Data.get('totalLot')}")
print(f" 空闲车位 : {resp.Data.get('emptyLot')}")
else:
print(f"❌ 失败: {resp.message}")
更多接口调用示例
# 车场详情
resp = provider.downstream_api.get_parkinfo()
# 远程开闸(gate_id 从 get_park_gate 获取)
resp = provider.downstream_api.open_gate(gate_id="G001", status=1)
# 根据车牌查询月卡
resp = provider.downstream_api.get_monthly_rent(plate_number="湘A12345")
# 分页获取月卡列表(支持车牌模糊搜索 + 月卡类型过滤)
resp = provider.downstream_api.get_monthly_rent_list(
page_index=1,
page_size=20,
plate_number="湘A", # 可选
rent_type=1, # 可选(不传默认月租车)
)
# 根据停车时长(分钟)模拟计算费用
resp = provider.downstream_api.simulate_cla_fee(during_time=60)
# 添加访客车
resp = provider.downstream_api.add_visit(
plate_number="湘A12345",
visitor_name="张三",
begin_time="2026-11-18 09:00:00",
end_time="2026-11-18 18:00:00",
visitor_count=-1, # -1 表示不限次数
car_model_id="model_01",
gate_id="G001", # 可选
)
# 增加黑名单
resp = provider.downstream_api.add_park_black(
plate_number="湘A99999",
start_time="2026-11-18 00:00:00",
end_time="2026-12-31 23:59:59",
status=1, # 1=不可进出, 2=可进不可出, 3=可进可出, 4=可出不可进
remark="欠费车辆", # 可选
)
# 月卡续期
resp = provider.downstream_api.pay_monthly(
plate_number="湘A12345",
amount="100",
start_time="2026-11-01 00:00:00",
end_time="2027-10-31 23:59:59",
pay_type=2, # 1=现金, 2=微信, 3=支付宝
)
# 商家打折
resp = provider.downstream_api.discount_pay(
plate_number="湘A12345",
seller_no="store_001",
derate_id="rule_05",
derate_value="5", # 根据规则类型:减金额填元数,减时间填分钟
seller_id="seller_001",
)
复用外部 httpx.Client(连接池复用)
import httpx
from py_tiehu_sdk import PklotAPIProvider, PklotConfig
# 手动管理 httpx.Client,适用于多 SDK 实例共享连接池
with httpx.Client(
proxies={"http://": "http://127.0.0.1:7890"}, # 代理
headers={"User-Agent": "my-app/1.0"},
) as client:
config = PklotConfig(
base_url="http://x.cxyun.net.cn:7303/cxzn",
app_key="xxx",
parking_id="yyy",
)
provider = PklotAPIProvider(config, client=client)
resp = provider.downstream_api.query_pklot()
🔑 签名算法
SDK 内部自动处理签名,调用方无需关心。签名规则(6 步):
原始 params
│ ① sort_params 过滤空值 + 按参数名 ASCII 升序
▼
排序后 params
│ ② 拼接 "key1=value1&key2=value2" → stringA
▼
stringA
│ ③ md5(appKey) → 大写 32 位 md5_app_key
▼
md5_app_key
│ ④ stringA + md5_app_key → stringSignTemp
▼
stringSignTemp
│ ⑤ md5 → 大写 32 位 → sign
▼
sign(最终结果)
自动注入的请求字段
每次 _post_json 调用会自动注入以下三个字段,调用方不需要手动传入:
| 字段 | 来源 | 值 |
|---|---|---|
parkingId |
config.parking_id |
车场 ID |
timestamp |
int(time.time() * 1000) |
13 位毫秒时间戳(2 分钟内有效) |
sign |
generate_sign() 计算 |
大写 32 位签名 |
🧪 测试
运行单元测试(默认,不发真实网络请求)
uv run pytest -v
输出示例:
tests/test_signature.py::TestMd5Uppercase::test_basic PASSED
tests/test_models.py::TestPklotBaseResponse::test_ok_true_with_int PASSED
tests/test_provider.py::TestProvider::test_provider_creation PASSED
...
======================== 20 passed, 6 skipped in 0.08s =========================
运行集成测试(真实网络请求)
前置:
- 复制
.env.example为.env并填入真实值 - 当前出口 IP 必须已在道闸平台白名单内(否则平台返回
status=0, msg=不是白名单)
uv run pytest --integration -v
快速验证脚本
# 执行查询类接口并打印完整返回
uv run python scripts/quick_test.py
# Debug 脚本 — 打印签名计算细节,用于排查签名不匹配问题
uv run python scripts/debug_request.py
代码质量检查
# Ruff 格式化 + Lint
uv run ruff check src tests --fix
# Mypy 类型检查(strict 模式)
uv run mypy src
# 构建发布包(自动从 _version.py 读取版本号)
uv build
📚 异常处理
SDK 定义了统一的异常体系,所有异常都继承自 PklotError:
from py_tiehu_sdk import (
PklotError, # 所有 SDK 异常基类(可以统一捕获)
PklotAPIError, # 平台返回 status != 1 或 HTTP 错误
PklotSignatureError, # 签名生成失败(内部使用)
PklotTimeoutError, # 请求超时
PklotValidationError, # 响应 JSON 解析 / Pydantic 验证失败
)
try:
resp = provider.downstream_api.query_pklot()
except PklotAPIError as e:
print(f"平台错误 [{e.status}]: {e.message}")
except PklotTimeoutError:
print("请求超时,可通过 PklotConfig(timeout=60) 增加超时时间")
except PklotValidationError as e:
print(f"响应格式异常: {e}")
print(f"原始数据: {e.raw_data}")
except PklotError as e:
print(f"SDK 通用错误: {e}")
🧰 工具链
| 工具 | 版本 | 用途 |
|---|---|---|
| uv | ≥ 0.5 | 依赖管理 + 虚拟环境 + 构建 |
| ruff | ≥ 0.5 | 格式化(替代 black)+ Lint(替代 flake8 + isort) |
| mypy | ≥ 1.10 | strict 模式类型检查 |
| hatchling | — | 构建后端(支持动态版本) |
| pytest | ≥ 8 | 单元测试 + 集成测试 |
| pydantic | ≥ 2.7 | 数据验证 + 序列化 |
| httpx | ≥ 0.27 | HTTP 客户端(支持 HTTP/2) |
| python-dotenv | ≥ 1.2 | 加载 .env 配置(dev 依赖) |
🔐 安全说明
- appKey 明文存储 — SDK 内部会自动 MD5 转大写后参与签名,调用方无需任何加密处理
- HTTPS — 建议使用
https://开头的 API 地址,避免 appKey 在明文传输中被劫持 - IP 白名单 — 道闸平台默认校验请求来源 IP,需要在平台管理后台配置白名单
- 签名有效期 — timestamp 对应的毫秒时间戳与道闸服务器时间差不能超过 2 分钟
- 不暴露签名工具 —
generate_sign、md5_uppercase、sort_params为内部方法,不通过__init__.py对外暴露
📄 版本管理
版本号统一在 src/py_tiehu_sdk/_version.py 中维护:
__version__ = "0.1.0"
pyproject.toml 通过 hatchling 动态读取,无需两处重复修改:
[project]
dynamic = ["version"]
[tool.hatch.version]
path = "src/py_tiehu_sdk/_version.py"
expression = "__version__"
📜 License
本项目基于 MIT License 开源。
Metadata
Release files for py-tiehu-sdk 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| py_tiehu_sdk-0.2.1.tar.gz | 94.0 kB | Without provenance | Details for py_tiehu_sdk-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| py_tiehu_sdk-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for py_tiehu_sdk-0.2.1-py3-none-any.whl |
Total release size: 133.5 kB
Release files / py_tiehu_sdk-0.2.1.tar.gz
| Download URL | py_tiehu_sdk-0.2.1.tar.gz |
|---|---|
| Size | 94.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
378d72292514f74411d3238b9344f7280c1b426679caa0e3a8b44fdb16886bef
|
|
BLAKE2b-256 checksum How to use checksums |
5a2b567a3919c6afc5c80f6f34f29c0b473899fdd7e7e6b1f85679eae6cb4ad6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.22
|
Release files / py_tiehu_sdk-0.2.1-py3-none-any.whl
| Download URL | py_tiehu_sdk-0.2.1-py3-none-any.whl |
|---|---|
| Size | 39.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
49987ae6269806226ee796b11930f15deb50a69c19fd8991e108424073179ae6
|
|
BLAKE2b-256 checksum How to use checksums |
eb958df76e0f16a2e00fb4db1a7533e2e80373056c56f279544176a6c06a4478
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.22
|
Security for py-tiehu-sdk 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.