elecredit 0.1.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- elecredit-0.1.1/PKG-INFO +292 -0
- elecredit-0.1.1/README.md +274 -0
- elecredit-0.1.1/elecredit/__init__.py +63 -0
- elecredit-0.1.1/elecredit/__main__.py +4 -0
- elecredit-0.1.1/elecredit/_version.py +2 -0
- elecredit-0.1.1/elecredit/cli.py +348 -0
- elecredit-0.1.1/elecredit/client.py +650 -0
- elecredit-0.1.1/elecredit/credentials.py +42 -0
- elecredit-0.1.1/elecredit/endpoints.py +71 -0
- elecredit-0.1.1/elecredit/envelope.py +213 -0
- elecredit-0.1.1/elecredit/errors.py +121 -0
- elecredit-0.1.1/elecredit/redact.py +27 -0
- elecredit-0.1.1/elecredit/signature.py +103 -0
- elecredit-0.1.1/elecredit.egg-info/PKG-INFO +292 -0
- elecredit-0.1.1/elecredit.egg-info/SOURCES.txt +32 -0
- elecredit-0.1.1/elecredit.egg-info/dependency_links.txt +1 -0
- elecredit-0.1.1/elecredit.egg-info/entry_points.txt +2 -0
- elecredit-0.1.1/elecredit.egg-info/requires.txt +12 -0
- elecredit-0.1.1/elecredit.egg-info/top_level.txt +1 -0
- elecredit-0.1.1/pyproject.toml +63 -0
- elecredit-0.1.1/setup.cfg +4 -0
- elecredit-0.1.1/tests/test_base_url.py +74 -0
- elecredit-0.1.1/tests/test_cli.py +353 -0
- elecredit-0.1.1/tests/test_client_integration.py +80 -0
- elecredit-0.1.1/tests/test_endpoints.py +94 -0
- elecredit-0.1.1/tests/test_errors.py +123 -0
- elecredit-0.1.1/tests/test_judicial_all.py +229 -0
- elecredit-0.1.1/tests/test_judicial_params.py +96 -0
- elecredit-0.1.1/tests/test_judicial_summary.py +147 -0
- elecredit-0.1.1/tests/test_product_payload.py +124 -0
- elecredit-0.1.1/tests/test_redact.py +38 -0
- elecredit-0.1.1/tests/test_retry.py +119 -0
- elecredit-0.1.1/tests/test_signature.py +94 -0
- elecredit-0.1.1/tests/test_version.py +34 -0
elecredit-0.1.1/PKG-INFO
ADDED
|
@@ -0,0 +1,292 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: elecredit
|
|
3
|
+
Version: 0.1.1
|
|
4
|
+
Summary: Elecredit 企业风控数据 Python SDK — 10 端点:工商模糊/深度、大中小微划型、税务信用、行政处罚、司法 12 种 type、限消人员、股权图谱、招投标、实控人,支持 MD5+SHA256 签名与通用 post
|
|
5
|
+
Author: Elecredit Contributors
|
|
6
|
+
License: MIT
|
|
7
|
+
Requires-Python: >=3.10
|
|
8
|
+
Description-Content-Type: text/markdown
|
|
9
|
+
Requires-Dist: typer<1,>=0.12
|
|
10
|
+
Requires-Dist: rich<14,>=13
|
|
11
|
+
Requires-Dist: python-dotenv<2,>=1.0
|
|
12
|
+
Requires-Dist: requests<3,>=2.31
|
|
13
|
+
Provides-Extra: dev
|
|
14
|
+
Requires-Dist: pytest<10,>=8; extra == "dev"
|
|
15
|
+
Requires-Dist: pytest-cov<7,>=5; extra == "dev"
|
|
16
|
+
Requires-Dist: ruff<1,>=0.5; extra == "dev"
|
|
17
|
+
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "dev"
|
|
18
|
+
|
|
19
|
+
# Elecredit Python SDK
|
|
20
|
+
|
|
21
|
+
企业风控数据 Python SDK,提供 **10 个**端点便捷方法:工商模糊/深度查询、大中小微划型、税务信用、行政处罚、
|
|
22
|
+
司法(12 种 type)、限消人员、企业股权图谱、招投标(B04)、实控人(P0020019)。
|
|
23
|
+
10 个端点与 Node CLI 的 10 个子命令、`docs/api/elecredit` 的 10 篇契约**三处一一对应**(有跨端一致性测试守着)。
|
|
24
|
+
|
|
25
|
+
## 安装
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
cd sdks/python
|
|
29
|
+
pip install -e ".[dev]"
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
或直接使用(纯标准库模式,无需安装):
|
|
33
|
+
|
|
34
|
+
```python
|
|
35
|
+
import sys; sys.path.insert(0, "sdk")
|
|
36
|
+
from elecredit import ElecreditClient, fuzzy, graph
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## 快速开始
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
from elecredit import ElecreditClient
|
|
43
|
+
|
|
44
|
+
client = ElecreditClient.from_env()
|
|
45
|
+
|
|
46
|
+
client.fuzzy(ent_name="贵州茅台")
|
|
47
|
+
client.deep(ent_name="贵州茅台")
|
|
48
|
+
client.scale(ent_info="贵州茅台")
|
|
49
|
+
client.tax(entity_name="贵州茅台", type="satpartyXin")
|
|
50
|
+
client.admin_punishment(ent_info="贵州茅台")
|
|
51
|
+
client.judicial(entity_name="贵州茅台", type="ktgg", range="20") # D11:entityName + 单值 type
|
|
52
|
+
client.xgbzxr(pers_name="许家印", id_no="110101195804261234")
|
|
53
|
+
client.graph(ent_info="贵州茅台", level="2") # 60s 超时
|
|
54
|
+
client.bidding(ent_info="贵州茅台") # B04 招投标(SDK 独有,不在 REST 契约内)
|
|
55
|
+
client.actual_controller(ent_info="国家电网有限公司") # P0020019 实控人(同上)
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
或用模块级便捷函数(从环境变量读凭据):
|
|
59
|
+
|
|
60
|
+
```python
|
|
61
|
+
import os
|
|
62
|
+
os.environ["ELECREDIT_APP_ID"] = "..."
|
|
63
|
+
os.environ["ELECREDIT_APP_KEY"] = "..."
|
|
64
|
+
|
|
65
|
+
from elecredit import fuzzy, graph
|
|
66
|
+
result = fuzzy(ent_name="贵州茅台")
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### 网关地址(公网 / 内网)
|
|
70
|
+
|
|
71
|
+
`from_env()` 按「显式入参 > `ELECREDIT_BASE_URL` > `https://api.elecredit.com`」解析网关地址:
|
|
72
|
+
|
|
73
|
+
```python
|
|
74
|
+
from elecredit import ElecreditClient
|
|
75
|
+
|
|
76
|
+
public = ElecreditClient.from_env() # 公网默认
|
|
77
|
+
internal = ElecreditClient(app_id="...", app_key="...",
|
|
78
|
+
base_url="http://<内部网关>/...") # 内网
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
内网只换 host:签名 `sn + ts + body + appKey` 与紧凑中文 JSON 逐字节不变,
|
|
82
|
+
`tests/test_base_url.py` 对此逐字节锁住。两个实务前置条件:签名用毫秒时间戳,机器时钟不同步会吃
|
|
83
|
+
`SYS002`;出口 IP 变化后需服务商加白,否则 `SYS006`。
|
|
84
|
+
|
|
85
|
+
### 端点口径:三端一致(10 端点)
|
|
86
|
+
|
|
87
|
+
| 端口 | 对应物 |
|
|
88
|
+
|------|--------|
|
|
89
|
+
| Python SDK | `ENDPOINTS` 10 项(`Endpoint` NamedTuple,含产品码)+ `ElecreditClient` 10 个便捷方法 + `elecredit-py <cmd>` 10 个子命令 |
|
|
90
|
+
| Node CLI | `remoteCapabilities` 10 个描述符 → `elecredit-py <group> <name>` 10 个子命令 |
|
|
91
|
+
| REST 契约 | `docs/api/elecredit/` 10 篇端点文档 |
|
|
92
|
+
|
|
93
|
+
三处由 `sdks/typescript/tests/endpoint-contract-consistency.test.ts` 交叉校验(id、路径、文档三向对齐),
|
|
94
|
+
避免再出现「代码 10 个、文档 8 个」这类漂移。
|
|
95
|
+
|
|
96
|
+
仍可用通用 `post()` 直达任意路径(含未注册端点),返回完整信封:
|
|
97
|
+
|
|
98
|
+
```python
|
|
99
|
+
client.post("/enterprise/biddingYPageWh", {"entInfo": "贵州茅台"}) # B04(等同 client.bidding(...))
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
两个端点的实测坑(已写进代码注释、`docs/api` 与 `docs/wiki/08`):
|
|
103
|
+
|
|
104
|
+
| 端点 | 坑 |
|
|
105
|
+
|------|-----|
|
|
106
|
+
| `B04 /enterprise/biddingYPageWh` | 参数名必须是 `entInfo` —— 传 `entName` 报 `400 企业信息不能为空` |
|
|
107
|
+
| `P0020019 /saic/SaicinvWh` | **路径大小写敏感**:`SaicInvWh` 返回 `SYS044 资源不存在`,可用的是小写 w 的 `SaicinvWh`;参数名同样是 `entInfo`。历史提交 4a5d9eb 把大小写改反了,端点因此长期打不通,且因为无凭据时集成测试整体 skip,一直没被发现 |
|
|
108
|
+
|
|
109
|
+
### 产品码解包(`product_payload`)
|
|
110
|
+
|
|
111
|
+
上游把业务体再包一层:`resultData = {"<产品码>Status": ..., "<产品码>Data": {...}}`,
|
|
112
|
+
产品码各端点不同(完整对照见 `ENDPOINTS[key].product_code` 与
|
|
113
|
+
[docs/api/elecredit/README.md](../../docs/api/elecredit/README.md))。
|
|
114
|
+
|
|
115
|
+
```python
|
|
116
|
+
from elecredit import product_payload, detect_product_code
|
|
117
|
+
|
|
118
|
+
raw = client.query("judicial", raw=True, entityName="贵州茅台") # 完整信封
|
|
119
|
+
product_payload(raw) # 自动探测产品码 → 内层业务体
|
|
120
|
+
product_payload(raw, "P0030089") # 也可精确指定
|
|
121
|
+
|
|
122
|
+
# 便捷方法返回的本来就是 resultData,可直接喂进去:
|
|
123
|
+
product_payload(client.judicial(entity_name="贵州茅台"))
|
|
124
|
+
|
|
125
|
+
detect_product_code(raw) # "P0030089";与注册表比对可发现上游改码
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
- **不传产品码时按结构探测**(匹配 `^P\d+Data$`),因此**上游换了产品码也不会失效** ——
|
|
129
|
+
不必再写 `result_data.get("P0030089Data") or ...` 这类硬编码兜底。
|
|
130
|
+
- 未命中返回 `{}`,**永不抛异常**;`resultData` 是 JSON 字符串时也照样解。
|
|
131
|
+
- `query()` 的默认返回**未改动**(仍是 `resultData`),以上均为纯新增。
|
|
132
|
+
|
|
133
|
+
### 司法数据汇总(`judicial_summary`)
|
|
134
|
+
|
|
135
|
+
D11 的 `type` 是**单值**、不支持逗号多选,而聚合返回的 `detailList` 里 `annoType` 是空串 ——
|
|
136
|
+
想按类型分组取明细只能逐类型扇出(12 次调用)。这个函数是那个扇出的**第一步**单独拿出来用:
|
|
137
|
+
**1 次调用**拿到「各类型有多少条 / 多少页」。
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
from elecredit import judicial_summary
|
|
141
|
+
|
|
142
|
+
s = judicial_summary("恒大地产集团有限公司")
|
|
143
|
+
s["totalCount"] # 52713
|
|
144
|
+
s["totalPage"] # 5272(按默认每页 10 条算)
|
|
145
|
+
s["types"]["ktgg"] # {"count": 16723, "pages": 1673}
|
|
146
|
+
s["types"]["pccz"] # {"count": 0, "pages": 0}
|
|
147
|
+
s["meta"] # 原始 detailListMeta,未识别字段不丢
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
- `types` **恒定包含 12 项**(合法类型见 `elecredit.client.D11_TYPES`):上游对无数据的类型
|
|
151
|
+
可能返回空串、也可能**整个键缺失**,两种都归一为 0;计数在上游是**字符串**,这里统一为 `int`。
|
|
152
|
+
- 查无司法数据(业务码 `001`)返回全 0 汇总,**不抛异常**。
|
|
153
|
+
- 要明细再逐类型取:`judicial("恒大地产集团有限公司", type="ktgg", page_no="1", range="20")`
|
|
154
|
+
(`range` 上限 20,`pageNo` 超出总页数会返回 `999 系统异常`)。
|
|
155
|
+
|
|
156
|
+
### 多类型明细扇出(`judicial_all`)
|
|
157
|
+
|
|
158
|
+
`judicial_summary` 只给计数;要**每个非空类型都有代表记录**就得逐类型取 —— `judicial_all` 把这套编排包好了:
|
|
159
|
+
|
|
160
|
+
```python
|
|
161
|
+
r = judicial_all("恒大地产集团有限公司") # 默认:每类型 1 页
|
|
162
|
+
r["calls"] # 7 = 1 次汇总 + 6 个「有数据」的类型各 1 页
|
|
163
|
+
r["byType"]["ktgg"] # 该类型取到的记录列表(12 个键恒定)
|
|
164
|
+
r["fetched"] # {"ktgg": 20, ...} 各类型实际取到的条数(已去重)
|
|
165
|
+
r["truncated"] # True = 有类型没取全(计数 > 已取页数 × range)
|
|
166
|
+
r["errors"] # {};单类型失败只记录,不影响其它类型
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
- **省调用的关键**:先读 `detailListMeta`,**计数为 0 的类型直接跳过**(恒大 12 个类型里只有 6 个有数据 → 7 次而不是 13 次)。
|
|
170
|
+
- **自动夹紧页数**:`max_pages` 会按该类型的总页数收敛,避免 `pageNo` 超界返回 `999 系统异常`。
|
|
171
|
+
- **跨类型按 `entryId` 去重**(实测同一类型的同一页里就会出现重复记录);没有 `entryId` 时退回稳定序列化。
|
|
172
|
+
- ⚠️ **计费**:每次分页都是一次计费调用。`max_pages` 会成倍放大(上限 100),返回值里的 `calls` 是实际次数。
|
|
173
|
+
- `concurrency=1`(默认)串行;>1 用线程池并发,注意限流 `SYS008` 与计费峰值。
|
|
174
|
+
|
|
175
|
+
> 顺带一个实测发现:**聚合调用(不传 `type`)返回的记录自带 `type` 字段**(`annoType` 才是空串)。
|
|
176
|
+
> 所以"只想要第一屏混合明细"时不必扇出 —— 1 次 `judicial()` + 按记录的 `type` 自行分桶即可;
|
|
177
|
+
> 扇出的价值在于"每个类型都要有代表记录"(例如 `fygg` 共 2420 条,聚合首页只出现 1 条)。
|
|
178
|
+
|
|
179
|
+
## CLI
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
export ELECREDIT_APP_ID=...
|
|
183
|
+
export ELECREDIT_APP_KEY=...
|
|
184
|
+
|
|
185
|
+
pip install -e .
|
|
186
|
+
elecredit-py capabilities # 列出 10 个端点元数据
|
|
187
|
+
elecredit-py fuzzy --ent-name 贵州茅台
|
|
188
|
+
elecredit-py bidding --ent-info 贵州茅台
|
|
189
|
+
elecredit-py actual-controller --ent-info 国家电网有限公司
|
|
190
|
+
elecredit-py graph --ent-info 贵州茅台 --level 2 --output graph.json
|
|
191
|
+
elecredit-py xgbzxr --pers-name 许家印 --id-no 110101195804261234
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
## 凭据探测
|
|
195
|
+
|
|
196
|
+
| 优先级 | 来源 |
|
|
197
|
+
|--------|------|
|
|
198
|
+
| 1 | `ElecreditClient(app_id=..., app_key=...)` 显式传入 |
|
|
199
|
+
| 2 | 环境变量 `ELECREDIT_APP_ID` + `ELECREDIT_APP_KEY` |
|
|
200
|
+
| 3 | `.env` 文件(项目根 `./.env` 或 `~/.elecredit/.env`,自动加载) |
|
|
201
|
+
|
|
202
|
+
## 错误分类
|
|
203
|
+
|
|
204
|
+
| 异常 | code | 含义 |
|
|
205
|
+
|------|------|------|
|
|
206
|
+
| `AuthError` | SYS001/SYS003 | 签名错或凭据无效 |
|
|
207
|
+
| **`BillingError`** | **SYS005** | **签名通过,余额不足(正常业务响应)** |
|
|
208
|
+
| `RateLimitError` | SYS008 | 频率限制 |
|
|
209
|
+
| `ValidationError` | HTTP 4xx | 参数错误 |
|
|
210
|
+
| `UpstreamError` | HTTP 5xx/NETWORK | 上游异常或超时 |
|
|
211
|
+
|
|
212
|
+
**关键**:`SYS005 余额不足` = 签名正确、凭据有效、API 可达。充值后拿真实数据。
|
|
213
|
+
|
|
214
|
+
## 签名算法
|
|
215
|
+
|
|
216
|
+
```
|
|
217
|
+
sn = uuid.uuid4().hex
|
|
218
|
+
ts = str(int(time.time() * 1000))
|
|
219
|
+
body = json.dumps(obj, ensure_ascii=False, separators=(",", ":"))
|
|
220
|
+
signStr = sn + ts + body + appKey
|
|
221
|
+
signature = MD5(signStr).hex()
|
|
222
|
+
|
|
223
|
+
# 签名放 HTTP Header(不是 body)
|
|
224
|
+
Content-Type: application/json
|
|
225
|
+
app-id: <appId>
|
|
226
|
+
timestamp: <ts>
|
|
227
|
+
request-sn: <sn>
|
|
228
|
+
signature: <md5_hex>
|
|
229
|
+
sign-type: MD5
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
## 测试
|
|
233
|
+
|
|
234
|
+
```bash
|
|
235
|
+
cd sdks/python
|
|
236
|
+
|
|
237
|
+
# 单元测试(纯 mock,不需要凭据)
|
|
238
|
+
pytest tests/ -v
|
|
239
|
+
|
|
240
|
+
# 签名黄金样本(硬编码了生产凭据,验证算法正确)
|
|
241
|
+
python -m elecredit.signature
|
|
242
|
+
|
|
243
|
+
# 集成测试(需要真实凭据)
|
|
244
|
+
ELECREDIT_APP_ID=... ELECREDIT_APP_KEY=... \
|
|
245
|
+
pytest tests/test_integration.py -v -s
|
|
246
|
+
|
|
247
|
+
# lint
|
|
248
|
+
ruff check elecredit/ tests/
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
## 项目结构
|
|
252
|
+
|
|
253
|
+
```
|
|
254
|
+
elecredit/
|
|
255
|
+
├── __init__.py 公共 API
|
|
256
|
+
├── __main__.py python -m elecredit
|
|
257
|
+
├── _version.py
|
|
258
|
+
├── client.py ElecreditClient 主类
|
|
259
|
+
├── signature.py 签名算法(含黄金样本自测试)
|
|
260
|
+
├── endpoints.py 10 端点注册表(与 Node CLI / docs 契约对齐)
|
|
261
|
+
├── errors.py 异常层次
|
|
262
|
+
├── envelope.py 响应信封 + 错误分类
|
|
263
|
+
├── credentials.py 凭据探测链
|
|
264
|
+
└── cli.py Typer CLI
|
|
265
|
+
|
|
266
|
+
tests/
|
|
267
|
+
├── conftest.py sys.path 注入项目根
|
|
268
|
+
├── test_signature.py 签名黄金样本
|
|
269
|
+
├── test_errors.py 错误码分类
|
|
270
|
+
├── test_endpoints.py ENDPOINTS 注册表
|
|
271
|
+
├── test_product_payload.py 产品码解包与探测
|
|
272
|
+
├── test_judicial_params.py D11 参数构造与校验
|
|
273
|
+
├── test_judicial_summary.py D11 汇总视图 judicial_summary
|
|
274
|
+
├── test_judicial_all.py D11 扇出 judicial_all
|
|
275
|
+
├── test_cli.py Typer CLI:选项 → 客户端调用映射、错误分类 exit code
|
|
276
|
+
├── test_version.py 版本号一致性
|
|
277
|
+
└── test_client_integration.py 生产集成测试(mark: integration,需真实凭据)
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
## 依赖
|
|
281
|
+
|
|
282
|
+
- **运行时**:typer + rich + python-dotenv + requests(都是可选兜底,urllib 也能跑)
|
|
283
|
+
- **零 pip install 模式**:仅用标准库
|
|
284
|
+
|
|
285
|
+
## 生产验证
|
|
286
|
+
|
|
287
|
+
端点均通过过签名校验(账户无余额时返回 `SYS005`、有余额时返回 `000`/`001`,都说明签名已通过):
|
|
288
|
+
```python
|
|
289
|
+
# 跑一遍黄金样本验证签名算法
|
|
290
|
+
from elecredit.signature import verify_golden_sample
|
|
291
|
+
print(verify_golden_sample()) # True
|
|
292
|
+
```
|
|
@@ -0,0 +1,274 @@
|
|
|
1
|
+
# Elecredit Python SDK
|
|
2
|
+
|
|
3
|
+
企业风控数据 Python SDK,提供 **10 个**端点便捷方法:工商模糊/深度查询、大中小微划型、税务信用、行政处罚、
|
|
4
|
+
司法(12 种 type)、限消人员、企业股权图谱、招投标(B04)、实控人(P0020019)。
|
|
5
|
+
10 个端点与 Node CLI 的 10 个子命令、`docs/api/elecredit` 的 10 篇契约**三处一一对应**(有跨端一致性测试守着)。
|
|
6
|
+
|
|
7
|
+
## 安装
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
cd sdks/python
|
|
11
|
+
pip install -e ".[dev]"
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
或直接使用(纯标准库模式,无需安装):
|
|
15
|
+
|
|
16
|
+
```python
|
|
17
|
+
import sys; sys.path.insert(0, "sdk")
|
|
18
|
+
from elecredit import ElecreditClient, fuzzy, graph
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## 快速开始
|
|
22
|
+
|
|
23
|
+
```python
|
|
24
|
+
from elecredit import ElecreditClient
|
|
25
|
+
|
|
26
|
+
client = ElecreditClient.from_env()
|
|
27
|
+
|
|
28
|
+
client.fuzzy(ent_name="贵州茅台")
|
|
29
|
+
client.deep(ent_name="贵州茅台")
|
|
30
|
+
client.scale(ent_info="贵州茅台")
|
|
31
|
+
client.tax(entity_name="贵州茅台", type="satpartyXin")
|
|
32
|
+
client.admin_punishment(ent_info="贵州茅台")
|
|
33
|
+
client.judicial(entity_name="贵州茅台", type="ktgg", range="20") # D11:entityName + 单值 type
|
|
34
|
+
client.xgbzxr(pers_name="许家印", id_no="110101195804261234")
|
|
35
|
+
client.graph(ent_info="贵州茅台", level="2") # 60s 超时
|
|
36
|
+
client.bidding(ent_info="贵州茅台") # B04 招投标(SDK 独有,不在 REST 契约内)
|
|
37
|
+
client.actual_controller(ent_info="国家电网有限公司") # P0020019 实控人(同上)
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
或用模块级便捷函数(从环境变量读凭据):
|
|
41
|
+
|
|
42
|
+
```python
|
|
43
|
+
import os
|
|
44
|
+
os.environ["ELECREDIT_APP_ID"] = "..."
|
|
45
|
+
os.environ["ELECREDIT_APP_KEY"] = "..."
|
|
46
|
+
|
|
47
|
+
from elecredit import fuzzy, graph
|
|
48
|
+
result = fuzzy(ent_name="贵州茅台")
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### 网关地址(公网 / 内网)
|
|
52
|
+
|
|
53
|
+
`from_env()` 按「显式入参 > `ELECREDIT_BASE_URL` > `https://api.elecredit.com`」解析网关地址:
|
|
54
|
+
|
|
55
|
+
```python
|
|
56
|
+
from elecredit import ElecreditClient
|
|
57
|
+
|
|
58
|
+
public = ElecreditClient.from_env() # 公网默认
|
|
59
|
+
internal = ElecreditClient(app_id="...", app_key="...",
|
|
60
|
+
base_url="http://<内部网关>/...") # 内网
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
内网只换 host:签名 `sn + ts + body + appKey` 与紧凑中文 JSON 逐字节不变,
|
|
64
|
+
`tests/test_base_url.py` 对此逐字节锁住。两个实务前置条件:签名用毫秒时间戳,机器时钟不同步会吃
|
|
65
|
+
`SYS002`;出口 IP 变化后需服务商加白,否则 `SYS006`。
|
|
66
|
+
|
|
67
|
+
### 端点口径:三端一致(10 端点)
|
|
68
|
+
|
|
69
|
+
| 端口 | 对应物 |
|
|
70
|
+
|------|--------|
|
|
71
|
+
| Python SDK | `ENDPOINTS` 10 项(`Endpoint` NamedTuple,含产品码)+ `ElecreditClient` 10 个便捷方法 + `elecredit-py <cmd>` 10 个子命令 |
|
|
72
|
+
| Node CLI | `remoteCapabilities` 10 个描述符 → `elecredit-py <group> <name>` 10 个子命令 |
|
|
73
|
+
| REST 契约 | `docs/api/elecredit/` 10 篇端点文档 |
|
|
74
|
+
|
|
75
|
+
三处由 `sdks/typescript/tests/endpoint-contract-consistency.test.ts` 交叉校验(id、路径、文档三向对齐),
|
|
76
|
+
避免再出现「代码 10 个、文档 8 个」这类漂移。
|
|
77
|
+
|
|
78
|
+
仍可用通用 `post()` 直达任意路径(含未注册端点),返回完整信封:
|
|
79
|
+
|
|
80
|
+
```python
|
|
81
|
+
client.post("/enterprise/biddingYPageWh", {"entInfo": "贵州茅台"}) # B04(等同 client.bidding(...))
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
两个端点的实测坑(已写进代码注释、`docs/api` 与 `docs/wiki/08`):
|
|
85
|
+
|
|
86
|
+
| 端点 | 坑 |
|
|
87
|
+
|------|-----|
|
|
88
|
+
| `B04 /enterprise/biddingYPageWh` | 参数名必须是 `entInfo` —— 传 `entName` 报 `400 企业信息不能为空` |
|
|
89
|
+
| `P0020019 /saic/SaicinvWh` | **路径大小写敏感**:`SaicInvWh` 返回 `SYS044 资源不存在`,可用的是小写 w 的 `SaicinvWh`;参数名同样是 `entInfo`。历史提交 4a5d9eb 把大小写改反了,端点因此长期打不通,且因为无凭据时集成测试整体 skip,一直没被发现 |
|
|
90
|
+
|
|
91
|
+
### 产品码解包(`product_payload`)
|
|
92
|
+
|
|
93
|
+
上游把业务体再包一层:`resultData = {"<产品码>Status": ..., "<产品码>Data": {...}}`,
|
|
94
|
+
产品码各端点不同(完整对照见 `ENDPOINTS[key].product_code` 与
|
|
95
|
+
[docs/api/elecredit/README.md](../../docs/api/elecredit/README.md))。
|
|
96
|
+
|
|
97
|
+
```python
|
|
98
|
+
from elecredit import product_payload, detect_product_code
|
|
99
|
+
|
|
100
|
+
raw = client.query("judicial", raw=True, entityName="贵州茅台") # 完整信封
|
|
101
|
+
product_payload(raw) # 自动探测产品码 → 内层业务体
|
|
102
|
+
product_payload(raw, "P0030089") # 也可精确指定
|
|
103
|
+
|
|
104
|
+
# 便捷方法返回的本来就是 resultData,可直接喂进去:
|
|
105
|
+
product_payload(client.judicial(entity_name="贵州茅台"))
|
|
106
|
+
|
|
107
|
+
detect_product_code(raw) # "P0030089";与注册表比对可发现上游改码
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
- **不传产品码时按结构探测**(匹配 `^P\d+Data$`),因此**上游换了产品码也不会失效** ——
|
|
111
|
+
不必再写 `result_data.get("P0030089Data") or ...` 这类硬编码兜底。
|
|
112
|
+
- 未命中返回 `{}`,**永不抛异常**;`resultData` 是 JSON 字符串时也照样解。
|
|
113
|
+
- `query()` 的默认返回**未改动**(仍是 `resultData`),以上均为纯新增。
|
|
114
|
+
|
|
115
|
+
### 司法数据汇总(`judicial_summary`)
|
|
116
|
+
|
|
117
|
+
D11 的 `type` 是**单值**、不支持逗号多选,而聚合返回的 `detailList` 里 `annoType` 是空串 ——
|
|
118
|
+
想按类型分组取明细只能逐类型扇出(12 次调用)。这个函数是那个扇出的**第一步**单独拿出来用:
|
|
119
|
+
**1 次调用**拿到「各类型有多少条 / 多少页」。
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
from elecredit import judicial_summary
|
|
123
|
+
|
|
124
|
+
s = judicial_summary("恒大地产集团有限公司")
|
|
125
|
+
s["totalCount"] # 52713
|
|
126
|
+
s["totalPage"] # 5272(按默认每页 10 条算)
|
|
127
|
+
s["types"]["ktgg"] # {"count": 16723, "pages": 1673}
|
|
128
|
+
s["types"]["pccz"] # {"count": 0, "pages": 0}
|
|
129
|
+
s["meta"] # 原始 detailListMeta,未识别字段不丢
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
- `types` **恒定包含 12 项**(合法类型见 `elecredit.client.D11_TYPES`):上游对无数据的类型
|
|
133
|
+
可能返回空串、也可能**整个键缺失**,两种都归一为 0;计数在上游是**字符串**,这里统一为 `int`。
|
|
134
|
+
- 查无司法数据(业务码 `001`)返回全 0 汇总,**不抛异常**。
|
|
135
|
+
- 要明细再逐类型取:`judicial("恒大地产集团有限公司", type="ktgg", page_no="1", range="20")`
|
|
136
|
+
(`range` 上限 20,`pageNo` 超出总页数会返回 `999 系统异常`)。
|
|
137
|
+
|
|
138
|
+
### 多类型明细扇出(`judicial_all`)
|
|
139
|
+
|
|
140
|
+
`judicial_summary` 只给计数;要**每个非空类型都有代表记录**就得逐类型取 —— `judicial_all` 把这套编排包好了:
|
|
141
|
+
|
|
142
|
+
```python
|
|
143
|
+
r = judicial_all("恒大地产集团有限公司") # 默认:每类型 1 页
|
|
144
|
+
r["calls"] # 7 = 1 次汇总 + 6 个「有数据」的类型各 1 页
|
|
145
|
+
r["byType"]["ktgg"] # 该类型取到的记录列表(12 个键恒定)
|
|
146
|
+
r["fetched"] # {"ktgg": 20, ...} 各类型实际取到的条数(已去重)
|
|
147
|
+
r["truncated"] # True = 有类型没取全(计数 > 已取页数 × range)
|
|
148
|
+
r["errors"] # {};单类型失败只记录,不影响其它类型
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
- **省调用的关键**:先读 `detailListMeta`,**计数为 0 的类型直接跳过**(恒大 12 个类型里只有 6 个有数据 → 7 次而不是 13 次)。
|
|
152
|
+
- **自动夹紧页数**:`max_pages` 会按该类型的总页数收敛,避免 `pageNo` 超界返回 `999 系统异常`。
|
|
153
|
+
- **跨类型按 `entryId` 去重**(实测同一类型的同一页里就会出现重复记录);没有 `entryId` 时退回稳定序列化。
|
|
154
|
+
- ⚠️ **计费**:每次分页都是一次计费调用。`max_pages` 会成倍放大(上限 100),返回值里的 `calls` 是实际次数。
|
|
155
|
+
- `concurrency=1`(默认)串行;>1 用线程池并发,注意限流 `SYS008` 与计费峰值。
|
|
156
|
+
|
|
157
|
+
> 顺带一个实测发现:**聚合调用(不传 `type`)返回的记录自带 `type` 字段**(`annoType` 才是空串)。
|
|
158
|
+
> 所以"只想要第一屏混合明细"时不必扇出 —— 1 次 `judicial()` + 按记录的 `type` 自行分桶即可;
|
|
159
|
+
> 扇出的价值在于"每个类型都要有代表记录"(例如 `fygg` 共 2420 条,聚合首页只出现 1 条)。
|
|
160
|
+
|
|
161
|
+
## CLI
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
export ELECREDIT_APP_ID=...
|
|
165
|
+
export ELECREDIT_APP_KEY=...
|
|
166
|
+
|
|
167
|
+
pip install -e .
|
|
168
|
+
elecredit-py capabilities # 列出 10 个端点元数据
|
|
169
|
+
elecredit-py fuzzy --ent-name 贵州茅台
|
|
170
|
+
elecredit-py bidding --ent-info 贵州茅台
|
|
171
|
+
elecredit-py actual-controller --ent-info 国家电网有限公司
|
|
172
|
+
elecredit-py graph --ent-info 贵州茅台 --level 2 --output graph.json
|
|
173
|
+
elecredit-py xgbzxr --pers-name 许家印 --id-no 110101195804261234
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
## 凭据探测
|
|
177
|
+
|
|
178
|
+
| 优先级 | 来源 |
|
|
179
|
+
|--------|------|
|
|
180
|
+
| 1 | `ElecreditClient(app_id=..., app_key=...)` 显式传入 |
|
|
181
|
+
| 2 | 环境变量 `ELECREDIT_APP_ID` + `ELECREDIT_APP_KEY` |
|
|
182
|
+
| 3 | `.env` 文件(项目根 `./.env` 或 `~/.elecredit/.env`,自动加载) |
|
|
183
|
+
|
|
184
|
+
## 错误分类
|
|
185
|
+
|
|
186
|
+
| 异常 | code | 含义 |
|
|
187
|
+
|------|------|------|
|
|
188
|
+
| `AuthError` | SYS001/SYS003 | 签名错或凭据无效 |
|
|
189
|
+
| **`BillingError`** | **SYS005** | **签名通过,余额不足(正常业务响应)** |
|
|
190
|
+
| `RateLimitError` | SYS008 | 频率限制 |
|
|
191
|
+
| `ValidationError` | HTTP 4xx | 参数错误 |
|
|
192
|
+
| `UpstreamError` | HTTP 5xx/NETWORK | 上游异常或超时 |
|
|
193
|
+
|
|
194
|
+
**关键**:`SYS005 余额不足` = 签名正确、凭据有效、API 可达。充值后拿真实数据。
|
|
195
|
+
|
|
196
|
+
## 签名算法
|
|
197
|
+
|
|
198
|
+
```
|
|
199
|
+
sn = uuid.uuid4().hex
|
|
200
|
+
ts = str(int(time.time() * 1000))
|
|
201
|
+
body = json.dumps(obj, ensure_ascii=False, separators=(",", ":"))
|
|
202
|
+
signStr = sn + ts + body + appKey
|
|
203
|
+
signature = MD5(signStr).hex()
|
|
204
|
+
|
|
205
|
+
# 签名放 HTTP Header(不是 body)
|
|
206
|
+
Content-Type: application/json
|
|
207
|
+
app-id: <appId>
|
|
208
|
+
timestamp: <ts>
|
|
209
|
+
request-sn: <sn>
|
|
210
|
+
signature: <md5_hex>
|
|
211
|
+
sign-type: MD5
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
## 测试
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
cd sdks/python
|
|
218
|
+
|
|
219
|
+
# 单元测试(纯 mock,不需要凭据)
|
|
220
|
+
pytest tests/ -v
|
|
221
|
+
|
|
222
|
+
# 签名黄金样本(硬编码了生产凭据,验证算法正确)
|
|
223
|
+
python -m elecredit.signature
|
|
224
|
+
|
|
225
|
+
# 集成测试(需要真实凭据)
|
|
226
|
+
ELECREDIT_APP_ID=... ELECREDIT_APP_KEY=... \
|
|
227
|
+
pytest tests/test_integration.py -v -s
|
|
228
|
+
|
|
229
|
+
# lint
|
|
230
|
+
ruff check elecredit/ tests/
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
## 项目结构
|
|
234
|
+
|
|
235
|
+
```
|
|
236
|
+
elecredit/
|
|
237
|
+
├── __init__.py 公共 API
|
|
238
|
+
├── __main__.py python -m elecredit
|
|
239
|
+
├── _version.py
|
|
240
|
+
├── client.py ElecreditClient 主类
|
|
241
|
+
├── signature.py 签名算法(含黄金样本自测试)
|
|
242
|
+
├── endpoints.py 10 端点注册表(与 Node CLI / docs 契约对齐)
|
|
243
|
+
├── errors.py 异常层次
|
|
244
|
+
├── envelope.py 响应信封 + 错误分类
|
|
245
|
+
├── credentials.py 凭据探测链
|
|
246
|
+
└── cli.py Typer CLI
|
|
247
|
+
|
|
248
|
+
tests/
|
|
249
|
+
├── conftest.py sys.path 注入项目根
|
|
250
|
+
├── test_signature.py 签名黄金样本
|
|
251
|
+
├── test_errors.py 错误码分类
|
|
252
|
+
├── test_endpoints.py ENDPOINTS 注册表
|
|
253
|
+
├── test_product_payload.py 产品码解包与探测
|
|
254
|
+
├── test_judicial_params.py D11 参数构造与校验
|
|
255
|
+
├── test_judicial_summary.py D11 汇总视图 judicial_summary
|
|
256
|
+
├── test_judicial_all.py D11 扇出 judicial_all
|
|
257
|
+
├── test_cli.py Typer CLI:选项 → 客户端调用映射、错误分类 exit code
|
|
258
|
+
├── test_version.py 版本号一致性
|
|
259
|
+
└── test_client_integration.py 生产集成测试(mark: integration,需真实凭据)
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
## 依赖
|
|
263
|
+
|
|
264
|
+
- **运行时**:typer + rich + python-dotenv + requests(都是可选兜底,urllib 也能跑)
|
|
265
|
+
- **零 pip install 模式**:仅用标准库
|
|
266
|
+
|
|
267
|
+
## 生产验证
|
|
268
|
+
|
|
269
|
+
端点均通过过签名校验(账户无余额时返回 `SYS005`、有余额时返回 `000`/`001`,都说明签名已通过):
|
|
270
|
+
```python
|
|
271
|
+
# 跑一遍黄金样本验证签名算法
|
|
272
|
+
from elecredit.signature import verify_golden_sample
|
|
273
|
+
print(verify_golden_sample()) # True
|
|
274
|
+
```
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
"""Elecredit 企业风控数据 Python SDK.
|
|
2
|
+
|
|
3
|
+
10 端点:工商模糊/深度查询、大中小微划型、税务信用、行政处罚、
|
|
4
|
+
司法(12 种 type)、限消人员、企业股权图谱、招投标(B04)、实控人(P0020019)。
|
|
5
|
+
支持 MD5 / SHA256 两种签名;含通用 post()(任意路径、返回完整信封)。
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
import warnings as _warnings
|
|
9
|
+
|
|
10
|
+
from elecredit._version import __version__
|
|
11
|
+
from elecredit.client import ElecreditClient
|
|
12
|
+
from elecredit.endpoints import ENDPOINTS, Endpoint, endpoint_product_code
|
|
13
|
+
from elecredit.envelope import detect_product_code, product_payload
|
|
14
|
+
from elecredit.errors import (
|
|
15
|
+
AuthError,
|
|
16
|
+
BillingError,
|
|
17
|
+
ElecreditError,
|
|
18
|
+
RateLimitError,
|
|
19
|
+
UpstreamError,
|
|
20
|
+
ValidationError,
|
|
21
|
+
)
|
|
22
|
+
from elecredit.signature import GOLDEN_SAMPLE, sign_request, verify_golden_sample
|
|
23
|
+
|
|
24
|
+
# `python -m elecredit.signature`(文档与 CI 都在用的自测试命令)会触发 runpy 的
|
|
25
|
+
# RuntimeWarning:「found in sys.modules after import of package」——因为本包在 __init__
|
|
26
|
+
# 阶段已导入过 signature 子模块。这是预期的导入顺序,不是缺陷。该警告由 runpy 在
|
|
27
|
+
# **子模块代码执行之前**发出,因此只能在这里(父包导入阶段)精确屏蔽掉,
|
|
28
|
+
# 否则每次跑自测试都会先打一行吓人的告警。
|
|
29
|
+
_warnings.filterwarnings(
|
|
30
|
+
"ignore",
|
|
31
|
+
message=r".*found in sys\.modules after import of package.*",
|
|
32
|
+
category=RuntimeWarning,
|
|
33
|
+
)
|
|
34
|
+
|
|
35
|
+
# ── 模块级便捷函数 ──────────────────────────────────────────────────────
|
|
36
|
+
|
|
37
|
+
def _global_client():
|
|
38
|
+
from elecredit.client import ElecreditClient
|
|
39
|
+
return ElecreditClient.from_env()
|
|
40
|
+
|
|
41
|
+
def fuzzy(ent_name: str, **kw): return _global_client().fuzzy(ent_name=ent_name, **kw)
|
|
42
|
+
def deep(**kw): return _global_client().deep(**kw)
|
|
43
|
+
def scale(ent_info: str): return _global_client().scale(ent_info)
|
|
44
|
+
def tax(entity_name: str, **kw): return _global_client().tax(entity_name=entity_name, **kw)
|
|
45
|
+
def admin_punishment(ent_info, **kw): return _global_client().admin_punishment(ent_info, **kw)
|
|
46
|
+
def judicial(entity_name=None, **kw): return _global_client().judicial(entity_name, **kw)
|
|
47
|
+
def judicial_summary(entity_name=None, **kw): return _global_client().judicial_summary(entity_name, **kw)
|
|
48
|
+
def judicial_all(entity_name=None, **kw): return _global_client().judicial_all(entity_name, **kw)
|
|
49
|
+
def xgbzxr(pers_name, id_no): return _global_client().xgbzxr(pers_name, id_no)
|
|
50
|
+
def graph(ent_info, **kw): return _global_client().graph(ent_info, **kw)
|
|
51
|
+
def bidding(ent_info, **kw): return _global_client().bidding(ent_info, **kw)
|
|
52
|
+
def actual_controller(ent_info, **kw): return _global_client().actual_controller(ent_info, **kw)
|
|
53
|
+
|
|
54
|
+
__all__ = [
|
|
55
|
+
"__version__",
|
|
56
|
+
"ElecreditClient",
|
|
57
|
+
"ENDPOINTS", "Endpoint", "endpoint_product_code",
|
|
58
|
+
"product_payload", "detect_product_code",
|
|
59
|
+
"fuzzy", "deep", "scale", "tax", "admin_punishment", "judicial", "judicial_summary",
|
|
60
|
+
"judicial_all", "xgbzxr", "graph", "bidding", "actual_controller",
|
|
61
|
+
"ElecreditError", "AuthError", "BillingError", "RateLimitError", "ValidationError", "UpstreamError",
|
|
62
|
+
"sign_request", "verify_golden_sample", "GOLDEN_SAMPLE",
|
|
63
|
+
]
|