Salesforce 커넥터
Salesforce 커넥터
Salesforce CRM을 Tajo를 통해 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 org (모든 에디션)
- Salesforce Setup에서 구성된 Connected App
- Salesforce 사용자 프로파일에서 활성화된 API 액세스
- API 액세스가 있는 Brevo 계정
- Tajo 계정
인증
OAuth 2.0 Web Server Flow (권장)
사용자 인증이 포함된 프로덕션 통합에 가장 적합합니다.
# 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}"Username-Password Flow
사용자 상호작용 없이 서버 간 통합에 사용합니다.
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는 username-password flow에서 비밀번호에 보안 토큰을 추가해야 합니다. Setup > My Personal Information > Reset My Security Token에서 토큰을 재설정하세요.
설정
기본 설정
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 | WhatsApp/SMS 메시징용 SMS 속성에 매핑됩니다 |
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 리소스
| Method | 엔드포인트 | 설명 |
|---|---|---|
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
| Method | 엔드포인트 | 설명 |
|---|---|---|
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 long-polling |
| PushTopic | SOQL 기반 토픽으로 레코드 변경 구독 |
| Change Data Capture | 세분화된 필드 수준 변경 사항 스트리밍 |
| Platform Events | 커스텀 이벤트 기반 아키텍처 |
이벤트
레코드 이벤트 (Change Data Capture)
| 이벤트 | 트리거 | 사용 사례 |
|---|---|---|
ContactChangeEvent | 연락처 생성/업데이트/삭제 | 실시간 연락처 동기화 |
LeadChangeEvent | 리드 생성/업데이트/전환 | 리드 라이프사이클 추적 |
OpportunityChangeEvent | 기회 단계 변경 | 거래 파이프라인 자동화 |
AccountChangeEvent | 계정 레코드 수정 | 회사 데이터 동기화 |
Platform Events
| 이벤트 | 트리거 | 사용 사례 |
|---|---|---|
Lead_Converted__e | 리드가 연락처로 전환됨 | 전환 후 육성 |
Deal_Won__e | 기회가 closed-won | 고객 온보딩 플로우 |
Deal_Lost__e | 기회가 closed-lost | 재참여 캠페인 |
코드 예제
커넥터 초기화
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: composite 요청당 25개 하위 요청
API 사용량 모니터링
Salesforce Setup > System Overview에서 API 사용량을 모니터링하세요. Tajo는 API 제한을 절약하기 위해 대규모 동기화에 bulk 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 토큰 새로 고침 로직을 구현하세요
- composite 요청 사용 - 관련 API 호출을 결합하여 요청 수를 줄이세요
- 샌드박스에서 먼저 테스트 - 프로덕션 배포 전에 Salesforce 샌드박스 org를 사용하세요
보안
- OAuth 2.0 - 여러 grant type을 지원하는 업계 표준 인증
- IP 제한 - Salesforce는 로그인 IP 범위와 신뢰할 수 있는 IP 설정을 지원합니다
- TLS 1.2+ - 모든 API 통신은 TLS 1.2 이상으로 암호화됩니다
- 필드 수준 보안 - 프로파일별 세분화된 필드 액세스 제어
- 세션 관리 - 구성 가능한 세션 타임아웃 및 동시 세션 제한