Pipedrive工具（免费版）

通过API驱动AI Agent查询Pipedrive销售数据，实现商机、联系人、组织和活动的快速检索。免费版提供只读查询功能，满足销售日常信息获取需求。

概述

Pipedrive是一款专注于销售流程管理的CRM工具，但在命令行集成和自动化查询场景下，直接调用API需要处理OAuth认证和Token刷新等复杂逻辑。本Skill通过API代理服务管理OAuth认证，让AI Agent能够通过简单的API调用查询销售数据。

免费版聚焦只读查询能力，提供商机、联系人、组织、活动和管道的列表与搜索功能，适合销售人员快速获取客户和商机信息。

核心能力

核心功能执行

用input_params参数进行配置。

输入: 用户提供核心功能执行所需的指令和必要参数。 处理: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回核心功能执行的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置。

输入: 用户提供参数配置与调用所需的指令和必要参数。 处理: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回参数配置与调用的响应数据,包含状态码、结果和日志。

• 执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置。

输入: 用户提供结果处理与输出所需的指令和必要参数。 处理: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回结果处理与输出的响应数据,包含状态码、结果和日志。

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：Pipedrive、销售数据的免费工、支持商机、联系人、组织的查询与搜索、工具免费版是一款、面向销售数据管理、的命令行辅助、Skill、Agent、能够通过、API、中的商机、组织和活动数据、实现销售信息的快、速检索和展示、核心能力、商机列表与搜索、联系人查询、组织查询、活动列表、管道与阶段查看、当前用户信息、Use、when、模型调用、智能对话、LLM、应用时使用、不适用于需要、确定性的关键决策等。

使用场景

场景一：商机快速查询

销售人员在外出途中通过AI Agent快速查询当前open状态的商机列表，了解跟进优先级。

场景二：客户信息检索

通过姓名或邮箱搜索联系人信息，快速获取客户背景和历史活动记录。

场景三：管道概览查看

查看所有销售管道和阶段分布，了解整体销售漏斗状态。

快速开始

前置条件

1. 已注册API代理服务账户并获取API Key
2. 已创建Pipedrive OAuth连接
3. 已设置API Key环境变量

配置环境变量

# 设置API代理服务的API Key
export MATON_API_KEY="your_api_key_here"

60秒上手

# 1. 列出所有open商机
python -c "
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/pipedrive/api/v1/deals?status=open')
req.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
"
# ...
# 2. 搜索联系人
python -c "
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/pipedrive/api/v1/persons/search?term=john')
req.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
"
# ...
# 3. 查看管道列表
python -c "
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/pipedrive/api/v1/pipelines')
req.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
"

示例

基础URL与认证

所有请求通过API代理服务转发到Pipedrive API，代理自动注入OAuth Token：

基础URL: https://api.maton.ai/pipedrive/{原生API路径}
认证头:  Authorization: Bearer $MATON_API_KEY

商机查询

# 列出所有商机
python -c "
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/pipedrive/api/v1/deals')
req.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
"
# ...
# 按状态过滤
# status: open, won, lost, deleted, all_not_deleted
python -c "
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/pipedrive/api/v1/deals?status=open&limit=50')
req.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
"
# ...
# 查看指定商机详情
python -c "
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/pipedrive/api/v1/deals/123')
req.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
"
# ...
# 搜索商机
python -c "
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/pipedrive/api/v1/deals/search?term=enterprise')
req.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
"

联系人查询

# 列出联系人
python -c "
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/pipedrive/api/v1/persons?limit=50')
req.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
"
# ...
# 查看联系人详情
python -c "
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/pipedrive/api/v1/persons/123')
req.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
"
# ...
# 搜索联系人
python -c "
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/pipedrive/api/v1/persons/search?term=john')
req.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
"

组织查询

# 列出组织
python -c "
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/pipedrive/api/v1/organizations')
req.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
"
# ...
# 查看组织详情
python -c "
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/pipedrive/api/v1/organizations/456')
req.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
"

活动查询

# 列出活动
python -c "
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/pipedrive/api/v1/activities')
req.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
"
# ...
# 按类型过滤活动
python -c "
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/pipedrive/api/v1/activities?type=call')
req.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
"
# ...
# 按完成状态过滤
python -c "
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/pipedrive/api/v1/activities?done=0')
req.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
"

管道与阶段

# 列出所有管道
python -c "
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/pipedrive/api/v1/pipelines')
req.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
"
# ...
# 列出阶段（按管道过滤）
python -c "
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/pipedrive/api/v1/stages?pipeline_id=1')
req.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
"

分页查询

# 使用start和limit参数分页
python -c "
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/pipedrive/api/v1/deals?start=0&limit=50&sort=add_time%20DESC')
req.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
"

查询参数说明

最佳实践

1. 使用status过滤提高效率：查询商机时优先用status=open过滤，避免返回大量已关闭数据。
2. 善用搜索功能：通过/search?term=关键词快速定位特定商机或联系人，比遍历列表更高效。
3. 合理设置分页：大数据量查询时使用start和limit分页，每页建议50-100条，避免响应超时。
4. 按活动类型筛选：查看待办活动时用done=0过滤未完成项，聚焦当前需要处理的任务。
5. JSON输出便于解析：API返回JSON格式数据，可配合jq等工具进行字段提取和格式化。

常见问题

Q1: API返回401未授权？

检查MATON_API_KEY环境变量是否正确设置。执行echo $MATON_API_KEY确认值不为空。API Key可在代理服务设置页面获取。

Q2: API返回400缺少Pipedrive连接？

需要先创建Pipedrive OAuth连接。在代理服务管理页面创建连接并完成OAuth授权流程。免费版仅支持查询，连接管理需在网页端操作。

Q3: 查询结果中ID是数字还是字符串？

Pipedrive的资源ID是整数类型。在API调用中直接使用数字（如/deals/123），无需引号包裹。

已知限制

每个账户的请求速率限制为10次/秒。批量查询时注意控制请求频率，避免触发429错误。

Q5: curl命令中URL含括号报错？

URL中包含fields[]或sort[]等括号时，使用curl -g禁用通配符解析。或直接使用Python的urllib方式调用。

• 当前为免费版本,如需完整功能请升级到付费版获取全部能力

依赖说明

运行环境

• Agent平台：支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统：Windows / macOS / Linux
• Python：3.6+（使用urllib标准库，无需额外安装）

依赖详情

API Key 配置

• API代理Key：通过MATON_API_KEY环境变量配置
• 获取方式：在代理服务设置页面创建账户并复制API Key
• Pipedrive OAuth：通过代理服务管理页面创建连接并完成授权
• 禁止：在代码或配置文件中明文写入API Key
• 安全建议：将API Key存储在.env文件中（已加入.gitignore）

可用性分类

• 分类：MD+EXEC（纯Markdown指令，需要exec命令行执行能力）
• 说明：基于Markdown的AI Skill，通过自然语言指令驱动Agent执行Pipedrive API查询操作

免费版限制

本免费体验版限制以下高级功能：

• 商机创建与更新（专业版支持完整的CRUD操作）
• 联系人和组织创建更新（专业版支持创建、更新和删除）
• 活动创建与更新（专业版支持活动管理和完成标记）
• 备注创建（专业版支持添加备注到商机和联系人）
• 批量操作（专业版支持批量创建、更新和数据导入）
• 多连接管理（专业版支持多个Pipedrive账户的连接管理）
• 自定义字段操作（专业版支持读写自定义字段）
• 高级过滤器（专业版支持创建和管理自定义过滤器）

解锁全部功能请使用专业版：pipedrive-toolkit-pro

错误处理

输出格式

{
  "success": true,
  "data": {
    "result": "Pipedrive工具(免费版)处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "pipedrivekit"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}