--- title: "Pipedrive 커넥터" description: "Pipedrive를 Tajo를 통해 Brevo와 연동하여 거래, 연락처, 조직, 파이프라인 데이터를 동기화하는 완벽 가이드입니다." url: https://tajo.io/kr/docs/connectors/crm/pipedrive/ markdown: https://tajo.io/kr/docs/connectors/crm/pipedrive.md lang: ko-KR robots: noindex --- Tajo 사전 이용 신청 이름과 회사 이메일 주소를 입력하세요. Tajo 이용 신청을 확인할 수 있는 링크를 이메일로 보내드립니다. # Pipedrive 커넥터 커넥터 상태: 예정 아직 구축되지 않았습니다. Tajo는 현재 이 커넥터를 실행하지 않습니다. | 원본 필드 | 대상 필드 | 예시 값 | | --- | --- | --- | | `record.id` | `source_id` | `record_1042` | | `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` | | `record.value` | `value` | `sample_value` | Pipedrive를 Tajo를 통해 Brevo에 연결하여 영업 파이프라인과 마케팅 자동화를 이어주세요. 연락처, 거래, 조직, 활동을 동기화하여 CRM 단계 변경에 의해 트리거되는 라이프사이클 캠페인을 구동할 수 있습니다. ## 개요 | 속성 | 값 | | --- | --- | | **플랫폼** | Pipedrive | | **카테고리** | CRM | | **설정 난이도** | 쉬움 | | **공식 통합** | 아니오 | | **동기화되는 데이터** | 연락처(Persons), 거래, 조직, 활동 | | **사용 가능한 스킬** | 8 | ## 주요 기능 - **연락처 동기화** - Pipedrive persons와 Brevo 연락처의 양방향 동기화 - **거래 단계 추적** - 거래 파이프라인 단계 변경을 기반으로 Brevo 자동화를 트리거합니다 - **조직 동기화** - Pipedrive 조직을 Brevo 회사 속성에 매핑합니다 - **활동 추적** - Pipedrive 활동(통화, 이메일, 미팅)을 Brevo 이벤트로 전달합니다 - **커스텀 필드** - Pipedrive 커스텀 필드를 Brevo 연락처 속성에 매핑합니다 - **파이프라인 리포팅** - 마케팅 기여도를 위해 거래 파이프라인 데이터를 가져옵니다 - **리드 동기화** - Pipedrive 리드를 Brevo로 가져와 육성 캠페인에 활용합니다 - **웹훅 자동화** - Pipedrive 웹훅을 통한 실시간 업데이트 ## 사전 준비 사항 시작하기 전에 다음 사항이 준비되어 있어야 합니다. 1. 관리자 액세스 권한이 있는 Pipedrive 계정 2. Pipedrive API Token (Settings > Personal preferences > API에서 확인) 3. OAuth 앱의 경우: Client ID와 Client Secret이 등록된 Pipedrive 앱 4. API 액세스가 가능한 Brevo 계정 5. API 자격 증명이 있는 Tajo 계정 ## 인증 ### API 토큰 가장 간단한 인증 방법입니다. Pipedrive Settings > Personal preferences > 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 ``` ### Person 필드 매핑 Pipedrive person 필드를 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 ``` ### 웹훅 설정 ```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 엔드포인트 | Method | 엔드포인트 | 설명 | | --- | --- | --- | | `GET` | `/v1/persons` | persons 목록 조회 | | `POST` | `/v1/persons` | person 생성 | | `PUT` | `/v1/persons/{id}` | person 업데이트 | | `DELETE` | `/v1/persons/{id}` | person 삭제 | | `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` | 웹훅 생성 | | `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' }); ``` ### Persons를 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'); }); ``` ### Pipedrive 전체 검색 ```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 apps** | 80회/2초 | 액세스 토큰당 | 추가 제한 사항: | 리소스 | 제한 | | --- | --- | | **페이지당** | 최대 500개 레코드 | | **웹훅** | 계정당 40개 | | **대량 삭제** | 요청당 100개 항목 | | **검색** | 표준 요청 제한 | 요청 제한 헤더 Pipedrive는 `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` 헤더를 반환합니다. `X-RateLimit-Remaining`이 0에 가까워지면 백오프를 구현하세요. ## 문제 해결 | 문제 | 원인 | 해결 방법 | | --- | --- | --- | | `401 Unauthorized` | 유효하지 않은 API 토큰 | Pipedrive Settings > API에서 토큰을 재생성하세요 | | `403 Forbidden` | 계정 권한 | API 사용을 위해 계정에 관리자 권한이 있는지 확인하세요 | | persons에 이메일 없음 | 레코드에 이메일 없음 | 동기화 전에 유효한 이메일이 있는 persons만 필터링하세요 | | 커스텀 필드가 매핑되지 않음 | 잘못된 필드 키 | 표시 이름이 아닌 Pipedrive의 필드 키(해시)를 사용하세요 | | 웹훅 수신 안 됨 | 방화벽 차단 | 웹훅 URL이 HTTPS를 통해 공개적으로 액세스 가능한지 확인하세요 | | 중복 persons | 여러 이메일 레코드 | 동기화 전에 Pipedrive의 병합 API를 사용하세요 | | `429 Too Many Requests` | 요청 제한 초과 | `X-RateLimit-Reset` 헤더를 사용해 백오프를 구현하세요 | ## 모범 사례 1. **프로덕션에는 OAuth 사용** - 프로덕션 애플리케이션에는 API 토큰보다 OAuth 2.0을 선호하세요 2. **거래 단계 변경 추적** - 파이프라인 단계 전환 시 웹훅을 사용해 Brevo 자동화를 트리거하세요 3. **커스텀 필드 매핑** - 안정적인 필드 매핑을 위해 이름이 아닌 Pipedrive 커스텀 필드 키를 사용하세요 4. **페이지네이션 처리** - `start` 및 `limit` 파라미터를 사용하고 `more_items_in_collection`을 확인하세요 5. **Recents 엔드포인트 사용** - 전체 내보내기 대신 `/v1/recents`를 폴링하여 증분 동기화하세요 6. **동기화 전 중복 제거** - Brevo로 동기화하기 전에 Pipedrive에서 중복된 persons를 병합하세요 7. **샌드박스 계정 사용** - 통합 테스트를 위해 개발자 샌드박스 계정을 생성하세요 ## 보안 - **API 토큰 인증** - 개인 용도의 간단한 토큰 기반 액세스 - **OAuth 2.0** - 서드파티 애플리케이션을 위한 안전한 위임 액세스 - **HTTPS 전용** - 모든 API 통신에는 TLS 암호화가 필요합니다 - **웹훅 HTTPS** - 웹훅은 HTTPS 엔드포인트에만 전달됩니다 - **역할 기반 액세스** - Pipedrive 권한은 사용자 역할을 따릅니다 - **SOC 2 인증** - Pipedrive는 SOC 2 규정 준수를 유지합니다 - **GDPR 규정 준수** - 데이터 내보내기 및 삭제 요청을 지원합니다 ## 관련 리소스 - [Brevo 커넥터](https://tajo.io/kr/docs/connectors/marketing/brevo) - [Shopify 커넥터](https://tajo.io/kr/docs/connectors/ecommerce/shopify) - [Customer Sync Skill](https://tajo.io/kr/docs/skills/data-sync/customer-sync) - [Brevo Contacts API](https://tajo.io/kr/docs/contact-management)