Pipedrive Toolkit Free

免费版Pipedrive工具通过API支持销售商机、联系人、组织和活动的只读查询与搜索，助力快速检索销售信息。

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环境变量

配置环境变量

bash

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

60秒上手

bash

# 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：

text

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

商机查询

bash

# 列出所有商机
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))
"

联系人查询

bash

# 列出联系人
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))
"

组织查询

bash

# 列出组织
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))
"

活动查询

bash

# 列出活动
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))
"

管道与阶段

bash

# 列出所有管道
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))
"

分页查询

bash

# 使用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))
"

查询参数说明

参数	适用资源	说明
status	deals	过滤状态：open/won/lost/deleted/all_not_deleted
filter_id	deals, persons	使用已保存的过滤器ID
stage_id	deals	按阶段过滤
user_id	deals, activities	按用户过滤
type	activities	活动类型：call/meeting/task/email
done	activities	完成状态：0(未完成)/1(已完成)
start	所有列表	分页起始位置（默认0）
limit	所有列表	每页数量（默认100）
sort	所有列表	排序字段和方向（如add_time DESC）

最佳实践

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代理服务	在线服务	必需	注册账户并获取API Key
Pipedrive账户	在线账户	必需	在Pipedrive官网注册
Pipedrive OAuth连接	认证连接	必需	在代理服务中创建
Python	运行时	必需	系统通常自带或从官网安装
LLM API	API	必需	由Agent平台内置LLM提供

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

错误处理

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达	执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案

输出格式

json

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