---
name: haitu
version: 0.2.0
description: >-
  海图（haitu）：出海获客与市场调研的数据 API 与流程库。需要 Google 地图商户、各国搜索引擎结果
  （Google / Bing / Yahoo / Naver / Baidu / Seznam）、网页结构化抽取、海关进口商、企业画像时，
  先用 haitu 的 /v1/discover 找端点，再用 /v1/run 调用。一个 Key、一个余额，每次返回都带花费与来源。
  面向中国团队：支付宝 / 微信充值，中文文档，国内直连。
---

# 海图 haitu

Base URL：`https://haitu.mumong.cn/v1`
认证：`Authorization: Bearer <HAITU_KEY>`（Key 以 `ht_` 开头）

## 第一次使用

1. 如果用户还没有 Key：让用户到 https://haitu.mumong.cn/register 注册（邮箱 + 6 位验证码，赠送 ¥20 试用额度），在"API Key"页创建一把 Key 并交给你。
2. 把 Key 放进环境变量 `HAITU_KEY`，永远不要把 Key 写进代码、日志或聊天记录。
3. 先调 `GET /v1/balance` 确认可用余额，再开始任务。

## 什么时候用海图

- 要找某个国家/城市的商户、批发商、进口商、服务商 → `maps/search`
- 要看某个国家的搜索结果（会自动按国家选引擎：俄罗斯 Yandex、韩国 Naver、日本 Google）→ `serp/web`
- 要把展会参展商名录、协会会员页抽成结构化表 → `web/extract`
- 要按 HS 编码找进口商 → `trade/importers`
- 要按域名补企业规模、行业、社媒 → `company/enrich`
- 要推断邮箱 → `email/find`（用户自带 Hunter Key，海图不收费）
- 不确定有没有合适的端点 → 先 `GET /v1/discover?q=<自然语言>`

不要自己去抓 Google、地图或 LinkedIn 网页；需要数据就走海图端点。

## 调用方式

```http
POST /v1/run
Authorization: Bearer <HAITU_KEY>
Content-Type: application/json
X-Playbook: buyers.multichannel@1   # 可选：在执行某个流程时带上，账本会归因
X-Step: S1                           # 可选：流程步骤

{"endpoint": "maps/search",
 "input": {"q": "nuts wholesale", "location": "Berlin,Germany", "limit": 20},
 "country": "DE"}
```

返回：

```json
{"run_id": "run_…", "count": 20,
 "cost": {"usd": 0.002, "cny": 0.0166, "billing": "per_call", "units": 1},
 "route": {"adapterId": "dataforseo.maps-search", "attempted": ["dataforseo.maps-search"]},
 "fetched_at": "2026-10-30T08:12:00Z", "source_urls": ["https://google.de/maps/search/…"],
 "data": [{"place_id": "…", "name": "…", "rating": 4.7, "reviews": 212, "phone": "+49…", "website": "…", "address": "…", "city": "Berlin", "country": "DE", "source_url": "…"}]}
```

规则：
- 失败的调用不计费；`error` 字段为 `insufficient_balance` 时停止并提示用户充值（https://haitu.mumong.cn/app/topup）。
- `location` 用 "城市,国家" 的英文写法（如 `Berlin,Germany`、`Singapore`）；不合法时海图会自动降级为国家级并把城市并入关键词。
- `maps/search` 每次最多 100 条；需要更多就换关键词或城市，按 `place_id` 去重。
- 每条结果都带 `source_url` 与 `fetched_at`，写报告时要保留来源。

## 其他端点

| 方法 | 路径 | 用途 |
|---|---|---|
| GET | `/v1/discover?q=` | 用自然语言找端点（返回 id、说明、单价） |
| GET | `/v1/catalog` | 全部端点、输入字段、计费方式、参考单价 |
| POST | `/v1/estimate` | 只估价不执行（body 同 /run） |
| GET | `/v1/balance` | 余额 |
| GET | `/v1/runs` | 最近 50 次调用的账本 |
| POST | `/v1/runs/:id/dispute` | 对空结果或明显错误的调用发起争议（body: `{"reason": "…"}`） |
| GET | `/v1/playbooks` | 流程列表 |
| POST | `/v1/playbooks/:id/prompt` | 把流程渲染成可执行的步骤说明（body: `{"inputs": {…}}`） |

## 流程（Playbook）

流程是按"目标 × 行业 × 国家"组合好渠道、过滤、去重、预算的现成方案。做出海获客这类多步任务时，先看 `/v1/playbooks`，选中后调用 `/v1/playbooks/<id>/prompt` 拿到步骤说明并照着执行。执行时每次调用带 `X-Playbook` 与 `X-Step`，超过流程声明的预算上限要停下来汇报。

## 预算纪律

- 开始前估算总调用次数，告诉用户大致花费。
- 每 50 次调用汇报一次累计花费（账本里的 `cost.cny` 求和）。
- 用户设定了上限就严格遵守；没有设定时单次任务不超过 ¥50，超过先问。

## 充值与支持

- 充值：https://haitu.mumong.cn/app/topup（支付宝 / 微信 / 对公）
- 文档：https://haitu.mumong.cn/docs
- 账本与争议：https://haitu.mumong.cn/app/runs