补全客户数据
为你的客户列表补充企业数据。
你有一份公司名称、城市或登记号的列表,想为其补充官方企业数据。你只需要 fetch-organization;无需先搜索。
匹配公司
每位客户发送一个请求,使用你掌握的最佳信息。登记法院和登记号最好,因为它们是唯一的。如果没有,请使用带法律形式的公司名称和城市。我们的示例请求按名称和城市查找 Hetzner Online GmbH(Ansbach HRB 6089)。
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode 'q=Hetzner Online GmbH Gunzenhausen'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-organization", headers={"x-api-key": "YOUR_API_KEY"}, params={ "q": "Hetzner Online GmbH Gunzenhausen", }, ) data = response.json()
const url = new URL("https://handelsregister.ai/api/v1/fetch-organization"); url.searchParams.append("q", "Hetzner Online GmbH Gunzenhausen"); const response = await fetch(url, { headers: { "x-api-key": "YOUR_API_KEY" }, }); const data = await response.json();
1{2 "entity_id": "94eb910fef13f94585c48c263fa446d4",3 "name": "Hetzner Online GmbH",4 "status": "ACTIVE",5 "registration": {6 "court": "Ansbach",7 "register_type": "HRB",8 "register_number": "6089"9 },10 "address": {11 "house_number": "25",12 "street": "Industriestraße",13 "postal_code": "91710",14 "city": "Gunzenhausen",15 "county": "Weißenburg-Gunzenhausen",16 "state": "Bayern",17 "country": "DEU",18 "coordinates": {19 "latitude": 49.12483,20 "longitude": 10.7805221 }22 },23 "meta": {24 "request_credit_cost": 5,25 "credits_remaining": 14526 }27}
请将响应与你的数据核对,例如 address 中的邮政编码或城市。名称常见时,否则可能返回一家同名公司。
将 entity_id 与你的客户一起保存。之后所有的获取、文件、Signals 和监控都基于这个标识符。
ai_search=on-default);它额外收取 20 积分,即使没有匹配。
获取大量公司
fetch-organization 允许 每分钟 60 次请求。请均匀地逐个发送请求。遇到 HTTP 429 时,等待 Retry-After 中的秒数。如果需要更多,Enterprise 提供更高的限制,见价格。
为每个请求提供一个 Idempotency-Key,例如客户编号。如果你在 24 小时内用相同的键和相同的参数重复请求,则不收费。
遇到 HTTP 408(请求耗时过长)时,API 不收费,AI 模式也不收费。遇到状态 500 或更高的错误时,只收取 AI 模式(如果你选择了)。请稍后用相同的 Idempotency-Key 重试。
该脚本读取 customers.csv,列为 id、name、city 和 register。register 列包含带法院的登记号,如 Ansbach HRB 6089,或为空。脚本写出一份含 entity_id、登记法院和登记号的副本,并统计所用积分。
import csv import time import requests API = "https://handelsregister.ai/api/v1/fetch-organization" HEADERS = {"x-api-key": "YOUR_API_KEY", "Accept": "application/json"} PER_MINUTE = 60 # fetch-organization 的限制 def lookup(row): # 登记法院加登记号是唯一的;否则用名称和城市 q = row["register"] or f'{row["name"]} {row["city"]}' headers = {**HEADERS, "Idempotency-Key": f'customer-{row["id"]}'} for attempt in range(5): response = requests.get(API, params={"q": q}, headers=headers, timeout=120) if response.status_code == 429: time.sleep(int(response.headers.get("Retry-After", "10"))) elif response.status_code in (408, 500, 502, 503, 504): time.sleep(30 * (attempt + 1)) else: break return response spent = 0 with open("customers.csv", newline="") as source, open("customers_enriched.csv", "w", newline="") as target: reader = csv.DictReader(source) writer = csv.DictWriter(target, fieldnames=reader.fieldnames + ["entity_id", "register_court", "register_number"]) writer.writeheader() for row in reader: response = lookup(row) if response.status_code == 402: print("积分不足,运行已停止") break data = response.json() spent += data.get("meta", {}).get("request_credit_cost", 0) if response.status_code == 200: registration = data.get("registration") or {} row["entity_id"] = data["entity_id"] row["register_court"] = registration.get("court") row["register_number"] = f'{registration.get("register_type")} {registration.get("register_number")}' writer.writerow(row) time.sleep(60 / PER_MINUTE) print(f"已用:{spent} 积分")
24 小时内第二次运行不收费。此时响应带有 Idempotency-Status: replayed,request_credit_cost 为 0。
1{2 "entity_id": "94eb910fef13f94585c48c263fa446d4",3 "name": "Hetzner Online GmbH",4 "meta": {5 "request_credit_cost": 0,6 "credits_remaining": 1457 }8}
enrich,可对 CSV、JSON 和 Excel 文件进行现成的数据补全。
控制费用
事先用价格表估算:每家公司基本数据 5 积分,再加上每个功能的价格。每次匹配都收取基本数据的费用。没有数据的功能不收费,因此实际费用往往更低。附加费不是功能:AI 模式即使没有匹配也收费,实时模式在每次成功获取时收费。
| 项目 | 积分 |
|---|---|
| 含基本数据的公司档案 | 5 |
| 每个功能,仅在返回数据时 | 1 至 80 |
| AI 模式,即使没有匹配结果 | +20 |
| 实时模式,每次成功的实时获取 | +10 |
限制:每分钟 60 次请求。
一次请求实际消耗的积分,见每个响应中的 meta.request_credit_cost。
请求的费用见 meta.request_credit_cost,剩余余额见 meta.credits_remaining。像上面的脚本那样边运行边累计费用。
每次请求前,API 会检查你的余额是否足以支付可能的最高价格。如果不够,API 返回 HTTP 402 且不收费。脚本随后停止。
你可以随时通过 account 免费查看余额和用量。
常见陷阱
- 没有法院的登记号:如果你的数据只有“HRB 6089”,API 找不到公司。请补上登记法院,或使用名称和城市。
- 一个键,一个请求:相同的
Idempotency-Key配不同的参数会返回 HTTP 422。请求改变时,请使用新键。 - 键的格式:允许最多 128 个由字母、数字和
. _ : -组成的字符,以字母或数字开头。其他格式的键会被 API 忽略。此时请求在没有此保护的情况下运行。 - 超时:使用实时模式或许多功能时,请求耗时更长。请将客户端的超时设置为至少 120 秒。