Pipedrive

通过托管的 OAuth 认证访问 Pipedrive API。管理销售CRM工作流程中的交易、人员、组织、活动、管道等。

快速开始

# 列出交易
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.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))
EOF

基础URL

https://gateway.maton.ai/pipedrive/{原生-api-路径}

替换{native-api-path}为实际的 Pipedrive API 端点路径。网关将请求代理到api.pipedrive.com并自动注入您的 OAuth 令牌。

认证

所有请求都需要在 Authorization 头中包含 Maton API 密钥：

Authorization: Bearer $MATON_API_KEY

环境变量：将您的 API 密钥设置为MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

获取您的 API 密钥

1. 登录或创建账户，访问maton.ai
2. 前往maton.ai/settings
3. 复制您的API密钥

连接管理

请在以下网址管理您的Pipedrive OAuth连接https://ctrl.maton.ai。

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=pipedrive&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'pipedrive'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "pipedrive",
    "metadata": {}
  }
}

在浏览器中打开返回的url以完成OAuth授权。

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

如果您有多个Pipedrive连接，请使用Maton-Connection请求头来指定要使用哪一个。

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/pipedrive/api/v1/deals')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果省略，网关将使用默认（最早）的活动连接。

API 参考

交易

列出交易

GET /pipedrive/api/v1/deals

查询参数：

• 状态- 按状态筛选：开放,已赢得,已丢失,已删除,所有未删除
• 筛选器ID- 使用的筛选器ID
• 阶段ID- 按阶段筛选
• 用户ID- 按用户筛选
• start- 分页起始位置（默认 0）
• limit- 每页条目数（默认 100）
• sort- 排序字段和顺序（例如，add_time DESC）

示例：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.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))
EOF

获取交易

GET /pipedrive/api/v1/deals/{id}

创建交易

POST /pipedrive/api/v1/deals
Content-Type: application/json

{
  "title": "新企业交易",
  "value": 50000,
  "currency": "USD",
  "person_id": 123,
  "org_id": 456,
  "stage_id": 1,
  "expected_close_date": "2025-06-30"
}

更新交易

PUT /pipedrive/api/v1/deals/{id}
Content-Type: application/json

{
  "title": "更新后的交易标题",
  "value": 75000,
  "status": "won"
}

删除交易

DELETE /pipedrive/api/v1/deals/{id}

搜索交易

GET /pipedrive/api/v1/deals/search?term=enterprise

人员（联系人）

列出人员

GET /pipedrive/api/v1/persons

查询参数：

• filter_id- 过滤器 ID
• start- 分页起始位置
• limit- 每页项目数
• sort- 排序字段和顺序

获取联系人

GET /pipedrive/api/v1/persons/{id}

创建联系人

POST /pipedrive/api/v1/persons
Content-Type: application/json

{
  "name": "John Doe",
  "email": ["john@example.com"],
  "phone": ["+1234567890"],
  "org_id": 456,
  "visible_to": 3
}

更新联系人

PUT /pipedrive/api/v1/persons/{id}
Content-Type: application/json

{
  "name": "John Smith",
  "email": ["john.smith@example.com"]
}

删除联系人

DELETE /pipedrive/api/v1/persons/{id}

搜索联系人

GET /pipedrive/api/v1/persons/search?term=john

组织

列出组织

GET /pipedrive/api/v1/organizations

获取组织

GET /pipedrive/api/v1/organizations/{id}

创建组织

POST /pipedrive/api/v1/organizations
Content-Type: application/json

{
  "name": "Acme Corporation",
  "address": "123 Main St, City, Country",
  "visible_to": 3
}

更新组织

PUT /pipedrive/api/v1/organizations/{id}
Content-Type: application/json

{
  "name": "Acme Corp International"
}

删除组织

DELETE /pipedrive/api/v1/organizations/{id}

活动

列出活动

GET /pipedrive/api/v1/activities

查询参数：

• 类型- 活动类型（例如：电话、会议、任务、邮件）
• 完成状态- 按完成状态筛选（0 或 1）
• 用户ID- 按用户筛选
• 开始日期- 按开始日期筛选
• 结束日期- 按结束日期筛选

获取活动

GET /pipedrive/api/v1/activities/{id}

创建活动

POST /pipedrive/api/v1/activities
Content-Type: application/json

{
  "subject": "后续电话",
  "type": "通话",
  "due_date": "2025-03-15",
  "due_time": "14:00",
  "duration": "00:30",
  "deal_id": 789,
  "person_id": 123,
  "note": "讨论合同条款"
}

更新活动

PUT /pipedrive/api/v1/activities/{id}
Content-Type: application/json

{
  "done": 1,
  "note": "已完成 - 客户同意条款"
}

删除活动

DELETE /pipedrive/api/v1/activities/{id}

销售管线

列出销售管线

GET /pipedrive/api/v1/pipelines

获取销售管线

GET /pipedrive/api/v1/pipelines/{id}

阶段

列出阶段

GET /pipedrive/api/v1/stages

查询参数：

• pipeline_id- 按管道筛选

获取阶段

GET /pipedrive/api/v1/stages/{id}

备注

列出备注

GET /pipedrive/api/v1/notes

查询参数：

• deal_id- 按交易筛选
• person_id- 按人员筛选
• org_id- 按组织筛选

创建备注

POST /pipedrive/api/v1/notes
Content-Type: application/json

{
  "content": "会议记录：讨论了定价和时间线",
  "deal_id": 789,
  "pinned_to_deal_flag": 1
}

用户

列出用户

GET /pipedrive/api/v1/users

获取当前用户

GET /pipedrive/api/v1/users/me

代码示例

JavaScript

const headers = {
  'Authorization': `Bearer ${process.env.MATON_API_KEY}`
};

// 列出未完成交易
const deals = await fetch(
  'https://gateway.maton.ai/pipedrive/api/v1/deals?status=open',
  { headers }
).then(r => r.json());

// 创建交易
await fetch(
  'https://gateway.maton.ai/pipedrive/api/v1/deals',
  {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      title: '新交易',
      value: 10000,
      currency: 'USD'
    })
  }
);

Python

import os
import requests

headers = {'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}

# 列出进行中的交易
deals = requests.get(
    'https://gateway.maton.ai/pipedrive/api/v1/deals',
    headers=headers,
    params={'status': 'open'}
).json()

# 创建一笔交易
response = requests.post(
    'https://gateway.maton.ai/pipedrive/api/v1/deals',
    headers=headers,
    json={
        'title': 'New Deal',
        'value': 10000,
        'currency': 'USD'
    }
)

备注

• ID 为整数
• 邮箱和电话字段接受数组以存储多个值
• visible_to值：1 (仅所有者可见), 3 (整个公司可见), 5 (所有者的可见性群组), 7 (整个公司及可见性群组)
• 交易状态：进行中,已成交,已失败,已删除
• 使用start和limit进行分页
• 自定义字段通过其 API 密钥支持（例如，abc123_custom_field）
• 重要提示：使用 curl 命令时，如果 URL 中包含方括号（fields[],sort[],records[]），请使用curl -g以禁用通配符解析
• 重要提示：将 curl 输出通过管道传递给jq或其他命令时，在某些 shell 环境中，像$MATON_API_KEY这样的环境变量可能无法正确展开。通过管道传递时，您可能会收到“无效的 API 密钥”错误。

错误处理

故障排除：API 密钥问题

1. 检查MATON_API_KEY环境变量是否已设置：

echo $MATON_API_KEY

2. 通过列出连接来验证 API 密钥是否有效：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

故障排除：无效的应用名称

1. 确保您的 URL 路径以pipedrive开头。例如：

• 正确：https://gateway.maton.ai/pipedrive/api/v1/deals
• 错误：https://gateway.maton.ai/api/v1/deals

资源

• Pipedrive API 概述
• 交易
• 人员
• 组织
• 活动
• 管道
• 阶段
• 备注
• Maton 社区
• Maton 支持