--- title: "Pipedrive 连接器" description: "完整的 Pipedrive 集成指南，通过 Tajo 将交易、联系人、组织和管道数据与 Brevo 同步。" url: https://tajo.io/zh-cn/docs/connectors/crm/pipedrive/ markdown: https://tajo.io/zh-cn/docs/connectors/crm/pipedrive.md lang: zh-CN robots: noindex --- 申请抢先体验 请输入您的名字和公司电子邮箱地址。我们会发送确认 Tajo 访问申请的链接。 # Pipedrive 连接器 连接器状态: 计划中 尚未构建。Tajo 目前不运行此连接器。 | 来源字段 | 目标字段 | 示例值 | | --- | --- | --- | | `record.id` | `source_id` | `record_1042` | | `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` | | `record.value` | `value` | `sample_value` | 通过 Tajo 将 Pipedrive 连接到 Brevo，将您的销售管道与营销自动化打通。同步联系人、交易、组织和活动，以便基于 CRM 阶段变化触发生命周期营销活动。 ## 概览 | 属性 | 值 | | --- | --- | | **平台** | Pipedrive | | **类别** | CRM | | **设置复杂度** | 简单 | | **官方集成** | 否 | | **同步数据** | 人员、交易、组织、活动 | | **可用技能** | 8 | ## 功能 - **联系人同步** - Pipedrive 人员与 Brevo 联系人的双向同步 - **交易阶段跟踪** - 根据交易管道阶段变化触发 Brevo 自动化 - **组织同步** - 将 Pipedrive 组织映射到 Brevo 公司属性 - **活动跟踪** - 将 Pipedrive 活动（通话、邮件、会议）转发为 Brevo 事件 - **自定义字段** - 将 Pipedrive 自定义字段映射到 Brevo 联系人属性 - **管道报告** - 提取交易管道数据用于营销归因 - **线索同步** - 将 Pipedrive 线索导入 Brevo 进行培育活动 - **Webhook 自动化** - 通过 Pipedrive Webhook 实现实时更新 ## 前提条件 开始之前，请确保您已具备： 1. 拥有管理员访问权限的 Pipedrive 账户 2. 您的 Pipedrive API 令牌（在”设置 > 个人偏好 > API”中找到） 3. 对于 OAuth 应用：已注册的 Pipedrive 应用（含客户端 ID 和客户端密钥） 4. 具有 API 访问权限的 Brevo 账户 5. 具有 API 凭据的 Tajo 账户 ## 认证 ### API 令牌 最简单的认证方式。在 Pipedrive 的”设置 > 个人偏好 > API”中找到您的 API 令牌。 ```bash curl "https://api.pipedrive.com/v1/persons?api_token=YOUR_API_TOKEN" ``` ### OAuth 2.0（推荐用于应用） 对于生产应用，请使用 OAuth 2.0： ```bash # Authorization URL https://oauth.pipedrive.com/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI # Token exchange curl -X POST https://oauth.pipedrive.com/oauth/token \ -d "grant_type=authorization_code" \ -d "code=AUTH_CODE" \ -d "redirect_uri=REDIRECT_URI" \ -u "CLIENT_ID:CLIENT_SECRET" ``` 获取访问令牌后： ```bash curl "https://api.pipedrive.com/v1/persons" \ -H "Authorization: Bearer ACCESS_TOKEN" ``` ## 配置 ### 基础设置 ```yaml connectors: pipedrive: enabled: true api_token: "your-pipedrive-api-token" company_domain: "yourcompany" # yourcompany.pipedrive.com # Data sync options sync: persons: true deals: true organizations: true activities: true leads: true # Brevo list assignment lists: all_contacts: 60 qualified_leads: 61 customers: 62 churned: 63 ``` ### 人员字段映射 将 Pipedrive 人员字段映射到 Brevo 联系人属性： ```yaml person_mapping: email: email name: FULLNAME first_name: FIRSTNAME last_name: LASTNAME phone: SMS org_id.name: COMPANY # Deal-related computed fields won_deals_count: WON_DEALS lost_deals_count: LOST_DEALS open_deals_count: OPEN_DEALS closed_deals_count: CLOSED_DEALS total_revenue: LTV # Custom fields (use Pipedrive field key) custom_fields.lead_source: LEAD_SOURCE custom_fields.industry: INDUSTRY custom_fields.company_size: COMPANY_SIZE ``` ### 交易阶段映射 将 Pipedrive 管道阶段映射到 Brevo 列表分配： ```yaml deal_stage_mapping: # stage_id -> brevo_list_id 1: 61 # Lead In 2: 61 # Contact Made 3: 62 # Proposal Made 4: 62 # Negotiations Started "won": 63 # Won -> Customers list "lost": 64 # Lost -> Win-back list ``` ### Webhook 配置 ```yaml webhooks: - event_action: "added" event_object: "person" brevo_event: "contact_created" - event_action: "updated" event_object: "person" brevo_event: "contact_updated" - event_action: "added" event_object: "deal" brevo_event: "deal_created" - event_action: "updated" event_object: "deal" brevo_event: "deal_updated" - event_action: "merged" event_object: "person" brevo_event: "contact_merged" - event_action: "added" event_object: "activity" brevo_event: "activity_logged" ``` ## API 端点 | 方法 | 端点 | 描述 | | --- | --- | --- | | `GET` | `/v1/persons` | 列出人员 | | `POST` | `/v1/persons` | 创建人员 | | `PUT` | `/v1/persons/{id}` | 更新人员 | | `DELETE` | `/v1/persons/{id}` | 删除人员 | | `GET` | `/v1/deals` | 列出交易 | | `POST` | `/v1/deals` | 创建交易 | | `PUT` | `/v1/deals/{id}` | 更新交易 | | `GET` | `/v1/organizations` | 列出组织 | | `POST` | `/v1/organizations` | 创建组织 | | `GET` | `/v1/activities` | 列出活动 | | `POST` | `/v1/activities` | 创建活动 | | `GET` | `/v1/leads` | 列出线索 | | `GET` | `/v1/pipelines` | 列出管道 | | `GET` | `/v1/stages` | 列出管道阶段 | | `GET` | `/v1/itemSearch` | 全局搜索所有项目 | | `POST` | `/v1/webhooks` | 创建 Webhook | | `GET` | `/v1/recents` | 获取最近修改的项目 | ## 代码示例 ### 初始化 Pipedrive 连接器 ```javascript import { TajoClient } from '@tajo/sdk'; const tajo = new TajoClient({ apiKey: process.env.TAJO_API_KEY, brevoApiKey: process.env.BREVO_API_KEY }); // Connect Pipedrive account await tajo.connectors.connect('pipedrive', { apiToken: process.env.PIPEDRIVE_API_TOKEN, companyDomain: 'yourcompany' }); ``` ### 将人员同步到 Brevo ```javascript // Fetch persons from Pipedrive const response = await fetch( `https://api.pipedrive.com/v1/persons?start=0&limit=100&api_token=${API_TOKEN}` ); const { data, additional_data } = await response.json(); // data: [{ id, name, first_name, last_name, email, phone, org_id, ... }] // additional_data.pagination: { start, limit, more_items_in_collection } ``` ### 跟踪交易阶段变化 ```javascript // Webhook handler for deal updates app.post('/webhooks/pipedrive', async (req, res) => { const { meta, current, previous } = req.body; if (meta.object === 'deal' && meta.action === 'updated') { // Detect stage change if (current.stage_id !== previous.stage_id) { await tajo.connectors.handleWebhook('pipedrive', { topic: 'deal.stage_changed', payload: { dealId: current.id, dealTitle: current.title, previousStage: previous.stage_id, newStage: current.stage_id, personId: current.person_id, value: current.value, currency: current.currency } }); } } res.status(200).send('OK'); }); ``` ### 全局搜索 ```javascript // Global search across persons, deals, and organizations const query = encodeURIComponent('jane@example.com'); const response = await fetch( `https://api.pipedrive.com/v1/itemSearch?term=${query}&item_types=person,deal&api_token=${API_TOKEN}` ); const { data } = await response.json(); // Returns matching persons, deals, and organizations ``` ## 速率限制 | 计划 | 限制 | 详情 | | --- | --- | --- | | **Essential** | 80 请求/10 秒 | 每个 API 令牌 | | **Advanced** | 100 请求/10 秒 | 每个 API 令牌 | | **Professional** | 200 请求/10 秒 | 每个 API 令牌 | | **Power** | 200 请求/10 秒 | 每个 API 令牌 | | **Enterprise** | 400 请求/10 秒 | 每个 API 令牌 | | **OAuth 应用** | 80 请求/2 秒 | 每个访问令牌 | 附加限制： | 资源 | 限制 | | --- | --- | | **每页** | 最多 500 条记录 | | **Webhook** | 每账户 40 个 | | **批量删除** | 每次请求 100 条 | | **搜索** | 标准速率限制 | 速率限制响应头 Pipedrive 返回 `X-RateLimit-Limit`、`X-RateLimit-Remaining` 和 `X-RateLimit-Reset` 响应头。当 `X-RateLimit-Remaining` 接近零时，请实施退避策略。 ## 故障排除 | 问题 | 原因 | 解决方案 | | --- | --- | --- | | `401 Unauthorized` | API 令牌无效 | 在 Pipedrive 设置 > API 中重新生成令牌 | | `403 Forbidden` | 账户权限不足 | 确保账户具有 API 使用所需的管理员权限 | | 人员缺少邮箱 | 记录中无邮箱地址 | 在同步前筛选具有有效邮箱的人员 | | 自定义字段无法映射 | 字段键错误 | 使用 Pipedrive 的字段键（哈希值），而非显示名称 | | 未收到 Webhook | 防火墙拦截 | 确保 Webhook URL 可通过 HTTPS 公开访问 | | 重复人员 | 多条邮箱记录 | 在同步前使用 Pipedrive 的合并 API | | `429 Too Many Requests` | 超出速率限制 | 使用 `X-RateLimit-Reset` 响应头实施退避策略 | ## 最佳实践 1. **生产环境使用 OAuth** - 生产应用优先使用 OAuth 2.0，而非 API 令牌 2. **跟踪交易阶段变化** - 使用 Webhook 在管道阶段转换时触发 Brevo 自动化 3. **映射自定义字段** - 使用 Pipedrive 自定义字段键（非名称）进行可靠字段映射 4. **处理分页** - 使用 `start` 和 `limit` 参数，检查 `more_items_in_collection` 5. **使用最近更新端点** - 使用 `/v1/recents` 进行增量同步，避免完整导出 6. **同步前去重** - 在同步到 Brevo 之前，先合并 Pipedrive 中的重复人员 7. **使用沙盒账户** - 创建开发者沙盒账户用于测试集成 ## 安全 - **API 令牌认证** - 基于令牌的简单访问，适合个人使用 - **OAuth 2.0** - 第三方应用的安全委托访问 - **仅 HTTPS** - 所有 API 通信均需要 TLS 加密 - **Webhook HTTPS** - Webhook 仅发送到 HTTPS 端点 - **基于角色的访问** - Pipedrive 权限遵循用户角色 - **SOC 2 认证** - Pipedrive 保持 SOC 2 合规 - **GDPR 合规** - 支持数据导出和删除请求 ## 相关资源 - [Brevo 连接器](https://tajo.io/zh-cn/docs/connectors/marketing/brevo) - [Shopify 连接器](https://tajo.io/zh-cn/docs/connectors/ecommerce/shopify) - [客户同步技能](https://tajo.io/zh-cn/docs/skills/data-sync/customer-sync) - [Brevo 联系人 API](https://tajo.io/zh-cn/docs/contact-management)