企业供应商项目接口接入教程：参数、请求示例与分页返回解读

做企业画像或供应链调研时，经常需要知道一家企业名下有哪些供应商项目关系。企业供应商项目接口就是按企业全称分页查询这类关系。本文从第一次调用写起：要准备什么、最小请求怎么发、返回值怎么看。

一、适用场景

• 供应链调研：按企业全称拉取供应商项目列表，做关系梳理。
• 企业画像：把供应商项目数据接入内部企业档案页。
• 风控辅助：对合作方做上下游关系核对。
• 数据看板：按企业维度分页拉取，沉淀到数仓做分析。

适用前提是手里有准确的企业全称。接口按companyName匹配，名称不准确会直接影响结果。

二、接口能力边界

需要注意两点：第一，pageSize上限是 20，想一次拉更多数据只能靠翻页；第二，查不到数据不代表调用失败，要按空数组处理，而不是当异常。

三、请求参数与鉴权

参数共三个：

鉴权方式是请求头Authorization: Bearer 你的Key，Key 在控制台复制。请求方法为POST，参数以 JSON 传递。

四、最小请求示例

下面是一个可复制的 curl 模板，YOUR_API_KEY与查询参数请替换为你自己的内容。

curl -X POST 'https://v1.apizero.cn/api/company-suppliers' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -d '{ "companyName": "某某科技有限公司", "pageNo": 1, "pageSize": 20 }'

几点说明：

• Authorization头必须是Bearer加 Key，中间有空格。
• pageSize不要超过 20，超出后的行为以文档为准。
• 企业名称建议原样传入，不要自行加后缀或简称。

对应的 Python 调用示例：

import requests def fetch_suppliers(company_name: str, page_no: int, page_size: int, api_key: str) -> dict: page_size = min(page_size, 20) resp = requests.post( "https://v1.apizero.cn/api/company-suppliers", headers={ "Content-Type": "application/json", "Authorization": f"Bearer {api_key}", }, json={ "companyName": company_name, "pageNo": page_no, "pageSize": page_size, }, timeout=10, ) resp.raise_for_status() return resp.json()

五、返回值解读

成功时，data中保留业务字段，并额外包含fetched_at与api：

• records：当前页的数据数组，没有数据时为空数组。
• fetched_at：本次数据的抓取时间，适合做数据新鲜度标记。
• api：标识数据来源接口，便于多接口聚合时区分。

分页相关字段（如总条数、总页数）素材未明确给出，以文档为准。在字段未确认前，翻页建议采用“取到空数组即停止”的策略，而不是依赖总页数。

一个防御式解析示例：

def parse_page(payload: dict) -> tuple: data = payload.get("data") or {} records = data.get("records") if not isinstance(records, list): return [], False fetched_at = data.get("fetched_at") api = data.get("api") return records, bool(records)

翻页循环可以这样写：每页取 20 条，records为空就退出，同时设置最大页数上限防止死循环。

六、常见错误与排查

“空数组”和“调用失败”要区分处理：前者是业务结果，后者才是异常。把空结果当错误重试只会浪费调用次数。

七、工程化注意事项

• 名称规范化：入库前对企业全称做统一清洗，避免同一企业多条记录。
• 分页策略：固定pageSize=20，以空records作为终止条件，并设最大页数保护。
• 重试边界：只对超时和 5xx 做有限次重试，参数错误与空结果不重试。
• 数据新鲜度：保存fetched_at，展示时标注抓取时间，避免用户误以为是实时数据。
• 来源标记：保留api字段，多数据源聚合时便于溯源。
• 缓存：同一企业短时间内重复查询可命中缓存，降低重复调用。

参考文档

• 接口文档