Salesforce 连接器
Salesforce 连接器
通过 Tajo 将您的 Salesforce CRM 连接到 Brevo,实现企业级联系人同步、线索管理、商机跟踪以及由 CRM 数据驱动的营销自动化。
概览
| 属性 | 值 |
|---|---|
| 平台 | Salesforce |
| 类别 | CRM |
| 设置复杂度 | 高级 |
| 官方集成 | 是 |
| 同步数据 | 联系人、线索、账户、商机、事件 |
| API 基础 URL | https://yourInstance.salesforce.com/services/data/vXX.0 |
功能
- 双向联系人/线索同步 - 将 Salesforce 联系人和线索与 Brevo 联系人列表同步
- 商机跟踪 - 映射交易阶段和金额,用于基于收入的客户细分
- 账户层级 - 同步公司账户,用于 Brevo 中的基于账户的营销
- 自定义对象映射 - 将 Salesforce 自定义对象映射到 Brevo 属性和事件
- 活动成员同步 - 将 Salesforce 活动成员与 Brevo 列表同步
- 活动跟踪 - 同步任务、事件和邮件活动,用于参与度评分
- 实时流式传输 - 使用 Salesforce Streaming API 实现即时数据更新
- SOQL 查询支持 - 使用自定义 SOQL 查询筛选同步数据
前提条件
开始之前,请确保您已具备:
- 具有 API 访问权限的 Salesforce 组织(任何版本)
- 在 Salesforce 设置中配置的已连接应用
- 为您的 Salesforce 用户配置文件启用 API 访问
- 具有 API 访问权限的 Brevo 账户
- Tajo 账户
认证
OAuth 2.0 Web 服务器流程(推荐)
最适合需要用户授权的生产集成。
# Step 1: Authorizehttps://login.salesforce.com/services/oauth2/authorize? response_type=code& client_id={consumer_key}& redirect_uri={callback_url}
# Step 2: Exchange code for tokenscurl -X POST https://login.salesforce.com/services/oauth2/token \ -d "grant_type=authorization_code" \ -d "code={auth_code}" \ -d "client_id={consumer_key}" \ -d "client_secret={consumer_secret}" \ -d "redirect_uri={callback_url}"用户名-密码流程
适用于无需用户交互的服务器到服务器集成。
curl -X POST https://login.salesforce.com/services/oauth2/token \ -d "grant_type=password" \ -d "client_id={consumer_key}" \ -d "client_secret={consumer_secret}" \ -d "username={username}" \ -d "password={password}{security_token}"安全令牌
在用户名-密码流程中,Salesforce 要求在密码后附加安全令牌。从”设置 > 我的个人信息 > 重置我的安全令牌”重置令牌。
配置
基础设置
connectors: salesforce: enabled: true instance_url: "https://yourorg.my.salesforce.com" api_version: "v59.0" auth: type: oauth2 consumer_key: "${SF_CONSUMER_KEY}" consumer_secret: "${SF_CONSUMER_SECRET}" refresh_token: "${SF_REFRESH_TOKEN}"
# Data sync options sync: contacts: true leads: true accounts: true opportunities: true campaigns: true
# Sync direction direction: salesforce_to_brevo
# Brevo list assignment lists: all_leads: 15 qualified_leads: 16 customers: 17字段映射
将 Salesforce 字段映射到 Brevo 联系人属性:
默认映射
| Parameter | Type | Description |
|---|---|---|
Email required | string | 联系人/线索邮箱(Brevo 的唯一标识符) |
FirstName optional | string | 映射到 Brevo 中的 FIRSTNAME 属性 |
LastName optional | string | 映射到 Brevo 中的 LASTNAME 属性 |
Phone optional | string | 映射到 SMS 属性,用于 WhatsApp/短信消息 |
Account.Name optional | string | 关联的账户/公司名称 |
LeadSource optional | string | 线索获取来源 |
StageName optional | string | 用于交易跟踪的商机阶段 |
OwnerId optional | string | 分配的销售代表,用于路由 |
自定义字段映射
field_mapping: # Standard fields Email: email FirstName: FIRSTNAME LastName: LASTNAME Phone: SMS
# CRM fields LeadSource: LEAD_SOURCE Lead_Score__c: LEAD_SCORE Account.Name: COMPANY_NAME Account.Industry: INDUSTRY
# Opportunity fields Amount: DEAL_VALUE StageName: DEAL_STAGE CloseDate: EXPECTED_CLOSE_DATE
# Custom fields Preferred_Channel__c: PREFERRED_CHANNEL Customer_Tier__c: VIP_TIERAPI 端点
REST API 资源
| 方法 | 端点 | 描述 |
|---|---|---|
GET | /services/data/vXX.0/sobjects/Contact | 查询联系人 |
POST | /services/data/vXX.0/sobjects/Contact | 创建联系人 |
PATCH | /services/data/vXX.0/sobjects/Contact/{id} | 更新联系人 |
GET | /services/data/vXX.0/sobjects/Lead | 查询线索 |
GET | /services/data/vXX.0/sobjects/Account | 查询账户 |
GET | /services/data/vXX.0/sobjects/Opportunity | 查询商机 |
GET | /services/data/vXX.0/query?q={SOQL} | 执行 SOQL 查询 |
POST | /services/data/vXX.0/composite/sobjects | 批量创建/更新 |
Bulk API
| 方法 | 端点 | 描述 |
|---|---|---|
POST | /services/data/vXX.0/jobs/ingest | 创建批量摄入任务 |
PUT | /services/data/vXX.0/jobs/ingest/{jobId}/batches | 上传批量数据 |
GET | /services/data/vXX.0/jobs/ingest/{jobId} | 检查任务状态 |
Streaming API
| 端点 | 描述 |
|---|---|
/cometd/XX.0 | CometD 长轮询,用于实时事件 |
| PushTopic | 通过基于 SOQL 的主题订阅记录变更 |
| Change Data Capture | 流式传输细粒度字段级变更 |
| Platform Events | 自定义事件驱动架构 |
事件
记录事件(Change Data Capture)
| 事件 | 触发条件 | 使用场景 |
|---|---|---|
ContactChangeEvent | 联系人创建/更新/删除 | 实时联系人同步 |
LeadChangeEvent | 线索创建/更新/转化 | 线索生命周期跟踪 |
OpportunityChangeEvent | 商机阶段变更 | 交易管道自动化 |
AccountChangeEvent | 账户记录修改 | 公司数据同步 |
Platform Events
| 事件 | 触发条件 | 使用场景 |
|---|---|---|
Lead_Converted__e | 线索转化为联系人 | 转化后培育 |
Deal_Won__e | 商机成功成交 | 客户入门流程 |
Deal_Lost__e | 商机丢失 | 赢回活动 |
代码示例
初始化连接器
import { TajoClient } from '@tajo/sdk';
const tajo = new TajoClient({ apiKey: process.env.TAJO_API_KEY, brevoApiKey: process.env.BREVO_API_KEY});
// Connect Salesforceawait tajo.connectors.connect('salesforce', { instanceUrl: 'https://yourorg.my.salesforce.com', consumerKey: process.env.SF_CONSUMER_KEY, consumerSecret: process.env.SF_CONSUMER_SECRET, refreshToken: process.env.SF_REFRESH_TOKEN});使用 SOQL 筛选同步联系人
// Sync only qualified leads from Salesforceawait tajo.connectors.sync('salesforce', { type: 'filtered', resources: ['leads'], filter: "SELECT Id, Email, FirstName, LastName, LeadScore__c FROM Lead WHERE Status = 'Qualified' AND Email != null", brevoListId: 16});
// Check sync statusconst status = await tajo.connectors.status('salesforce');console.log(status);// {// connected: true,// lastSync: '2024-01-15T10:30:00Z',// contactsSynced: 18400,// leadsSynced: 7200,// opportunitiesSynced: 3100// }实时流式传输
// Subscribe to Salesforce Change Data Captureawait tajo.connectors.stream('salesforce', { channels: [ '/data/ContactChangeEvent', '/data/LeadChangeEvent', '/data/OpportunityChangeEvent' ], handler: async (event) => { console.log(`Change detected: ${event.entity} ${event.changeType}`); // Automatically synced to Brevo by Tajo }});速率限制
Salesforce REST API 限制取决于您的版本和许可证数量:
| 版本 | 每 24 小时 API 请求数 |
|---|---|
| Developer | 15,000 |
| Enterprise | 每用户许可证 1,000(最少 15,000) |
| Unlimited | 每用户许可证 5,000(最少 15,000) |
| Performance | 每用户许可证 5,000(最少 15,000) |
附加限制:
- 并发 API 限制:25 个长时间运行的请求
- Bulk API:每 24 小时 15,000 批次
- Streaming API:每天 2,000 个事件(可增加)
- Composite API:每个复合请求 25 个子请求
API 使用监控
在 Salesforce 设置 > 系统概览中监控 API 使用情况。Tajo 对大型同步使用 Bulk API,以节省您的 API 限制。
故障排除
常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| INVALID_SESSION_ID | 令牌已过期 | 自动刷新 OAuth 令牌 |
| REQUEST_LIMIT_EXCEEDED | 达到每日 API 限制 | 使用 Bulk API 或降低同步频率 |
| FIELD_INTEGRITY_EXCEPTION | 必填字段缺失 | 在配置中映射所有必填字段 |
| DUPLICATES_DETECTED | 重复规则已激活 | 配置重复处理偏好 |
| INSUFFICIENT_ACCESS | 缺少对象权限 | 在 Salesforce 配置文件中授予 API 访问权限 |
调试模式
启用详细日志记录:
connectors: salesforce: debug: true log_level: verbose log_api_calls: true测试连接
tajo connectors test salesforce# ✓ OAuth token valid# ✓ Contacts accessible# ✓ Leads accessible# ✓ Accounts accessible# ✓ Opportunities accessible# ✓ Bulk API enabled最佳实践
- 大型同步使用 Bulk API - 对超过 2,000 条记录的数据集切换到 Bulk API 2.0
- 实施 Change Data Capture - 使用 CDC 进行实时同步,而非轮询
- 只映射所需字段 - 仅同步必要字段,降低 API 使用量
- 处理令牌刷新 - 实现自动 OAuth 令牌刷新逻辑
- 使用复合请求 - 合并相关 API 调用以减少请求次数
- 先在沙盒中测试 - 在生产部署前使用 Salesforce 沙盒组织
安全
- OAuth 2.0 - 支持多种授权类型的行业标准授权
- IP 限制 - Salesforce 支持登录 IP 范围和受信任 IP 设置
- TLS 1.2+ - 所有 API 通信使用最低 TLS 1.2 加密
- 字段级安全 - 按配置文件进行细粒度字段访问控制
- 会话管理 - 可配置的会话超时和并发会话限制