---
title: "Salesforce 커넥터"
description: "Salesforce CRM을 Tajo를 통해 Brevo와 연동하여 리드, 연락처, 계정, 기회, 커스텀 오브젝트를 동기화하는 완벽 가이드입니다."
url: https://tajo.io/kr/docs/connectors/crm/salesforce/
markdown: https://tajo.io/kr/docs/connectors/crm/salesforce.md
lang: ko-KR
robots: noindex
---

Tajo 사전 이용 신청

이름과 회사 이메일 주소를 입력하세요. Tajo 이용 신청을 확인할 수 있는 링크를 이메일로 보내드립니다.

# Salesforce 커넥터

커넥터 상태: 예정 아직 구축되지 않았습니다. Tajo는 현재 이 커넥터를 실행하지 않습니다.

| 원본 필드 | 대상 필드 | 예시 값 |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

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 쿼리로 동기화할 데이터를 필터링합니다

## 사전 준비 사항

시작하기 전에 다음 사항이 준비되어 있어야 합니다.

1. API 액세스가 있는 Salesforce org (모든 에디션)
2. Salesforce Setup에서 구성된 Connected App
3. Salesforce 사용자 프로파일에서 활성화된 API 액세스
4. API 액세스가 있는 Brevo 계정
5. Tajo 계정

## 인증

### OAuth 2.0 Web Server Flow (권장)

사용자 인증이 포함된 프로덕션 통합에 가장 적합합니다.

```bash
# Step 1: Authorize
https://login.salesforce.com/services/oauth2/authorize?
  response_type=code&
  client_id={consumer_key}&
  redirect_uri={callback_url}

# Step 2: Exchange code for tokens
curl -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

사용자 상호작용 없이 서버 간 통합에 사용합니다.

```bash
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에서 토큰을 재설정하세요.

## 설정

### 기본 설정

```yaml
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 | 라우팅을 위한 담당 영업 담당자 |

#### 커스텀 필드 매핑

```yaml
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_TIER
```

## API 엔드포인트

### 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 | 재참여 캠페인 |

## 코드 예제

### 커넥터 초기화

```javascript
import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

// Connect Salesforce
await 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 필터를 사용한 연락처 동기화

```javascript
// Sync only qualified leads from Salesforce
await 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 status
const status = await tajo.connectors.status('salesforce');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsSynced: 18400,
//   leadsSynced: 7200,
//   opportunitiesSynced: 3100
// }
```

### 실시간 스트리밍

```javascript
// Subscribe to Salesforce Change Data Capture
await 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 액세스를 부여하세요 |

### 디버그 모드

상세 로깅 활성화:

```yaml
connectors:
  salesforce:
    debug: true
    log_level: verbose
    log_api_calls: true
```

### 연결 테스트

```bash
tajo connectors test salesforce
# ✓ OAuth token valid
# ✓ Contacts accessible
# ✓ Leads accessible
# ✓ Accounts accessible
# ✓ Opportunities accessible
# ✓ Bulk API enabled
```

## 모범 사례

1. **대량 동기화에 Bulk API 사용** - 2,000개 이상의 레코드 데이터셋에는 Bulk API 2.0으로 전환하세요
2. **Change Data Capture 구현** - 폴링 대신 CDC를 사용해 실시간 동기화하세요
3. **필요한 필드만 매핑** - 필수 필드만 동기화하여 API 사용량을 줄이세요
4. **토큰 새로 고침 처리** - 자동 OAuth 토큰 새로 고침 로직을 구현하세요
5. **composite 요청 사용** - 관련 API 호출을 결합하여 요청 수를 줄이세요
6. **샌드박스에서 먼저 테스트** - 프로덕션 배포 전에 Salesforce 샌드박스 org를 사용하세요

## 보안

- **OAuth 2.0** - 여러 grant type을 지원하는 업계 표준 인증
- **IP 제한** - Salesforce는 로그인 IP 범위와 신뢰할 수 있는 IP 설정을 지원합니다
- **TLS 1.2+** - 모든 API 통신은 TLS 1.2 이상으로 암호화됩니다
- **필드 수준 보안** - 프로파일별 세분화된 필드 액세스 제어
- **세션 관리** - 구성 가능한 세션 타임아웃 및 동시 세션 제한

## 관련 리소스

- [Salesforce REST API Documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/intro_rest.htm)
- [Salesforce Bulk API 2.0 Guide](https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/asynch_api_intro.htm)
- [HubSpot 커넥터](https://tajo.io/kr/docs/connectors/crm/hubspot)
- [Customer Sync Skill](https://tajo.io/kr/docs/skills/data-sync/customer-sync)
- [Brevo Contacts API](https://tajo.io/kr/docs/contact-management)