Brevo 커넥터

Brevo 커넥터

Brevo 계정을 Tajo에 연결하여 통합된 연락처 관리, 이메일, SMS, WhatsApp에서의 트랜잭션 메시징, 포괄적인 마케팅 자동화를 구현하십시오.

개요

기능

• 다중 채널 메시징 - 통합 API로 트랜잭션 이메일, SMS, WhatsApp 전송
• 연락처 관리 - 맞춤 속성으로 연락처 생성, 업데이트, 세그먼트화
• 마케팅 캠페인 - 프로그래매틱하게 이메일 캠페인 생성 및 전송
• 이벤트 추적 - Brevo Tracker를 통해 맞춤 이벤트 및 웹사이트 활동 추적
• 이커머스 동기화 - 맞춤 캠페인을 위한 제품, 주문, 카트 데이터 동기화
• 로열티 프로그램 - 로열티 구독, 포인트, 멤버 데이터 관리
• 웹훅 지원 - 트랜잭션, 마케팅, CRM 이벤트에 대한 실시간 이벤트 알림
• Conversations - 실시간 채팅 위젯 통합 및 프로그래매틱 메시지 관리

사전 요구 사항

시작하기 전에 다음이 준비되어 있는지 확인하십시오.

1. Brevo 계정 (Free, Starter, Business, 또는 Enterprise 요금제)
2. Brevo Settings > API Keys에서 생성한 API 키
3. API 접근이 가능한 Tajo 계정
4. 이메일 전송을 위한 확인된 발신자 도메인

인증

Brevo는 두 가지 인증 방법을 지원합니다.

API 키 인증 (권장)

각 요청과 함께 api-key 헤더에 API 키를 포함하십시오. 직접 통합 및 서버-서버 통신에 가장 적합합니다.

curl -X GET "https://api.brevo.com/v3/account" \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

OAuth 2.0 인증

위임된 접근 및 사용자별 권한이 필요한 조직 내 사설 통합에는 OAuth 2.0을 사용하십시오. OAuth는 정의된 유효 기간을 가진 토큰 기반 시스템을 제공합니다.

구성

기본 설정

connectors:
  brevo:
    enabled: true
    api_key: "${BREVO_API_KEY}"
    api_version: "v3"

    # 데이터 동기화 옵션
    sync:
      contacts: true
      campaigns: true
      transactional: true
      events: true
      ecommerce: true

    # 목록 할당
    lists:
      all_customers: 5
      newsletter: 6
      buyers: 7

필드 매핑

데이터 필드를 Brevo 연락처 속성에 매핑합니다.

맞춤 속성 매핑

field_mapping:
  # 표준 필드
  email: email
  first_name: FIRSTNAME
  last_name: LASTNAME
  phone: SMS

  # 마케팅 필드
  opt_in: OPT_IN
  signup_source: SIGNUP_SOURCE
  preferred_language: LANGUAGE

  # 이커머스 지표
  orders_count: ORDER_COUNT
  total_spent: TOTAL_REVENUE
  last_order_date: LAST_ORDER_DATE

  # 로열티 필드
  loyalty_tier: VIP_TIER
  loyalty_points: LOYALTY_POINTS

API 엔드포인트

핵심 엔드포인트

이커머스 엔드포인트

캠페인 엔드포인트

이벤트

트랜잭션 이벤트

이커머스 이벤트

코드 예제

커넥터 초기화

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

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

// Brevo 계정 연결
await tajo.connectors.connect('brevo', {
  apiKey: process.env.BREVO_API_KEY
});

트랜잭션 이메일 전송

// Brevo를 통해 트랜잭션 이메일 전송
await tajo.brevo.sendTransactionalEmail({
  to: [{ email: '[email protected]', name: 'John Doe' }],
  templateId: 12,
  params: {
    ORDER_ID: '12345',
    ORDER_TOTAL: '$59.99',
    DELIVERY_DATE: '2024-02-15'
  }
});

연락처 동기화

// Brevo로 연락처 대량 가져오기
await tajo.connectors.sync('brevo', {
  type: 'full',
  resources: ['contacts'],
  options: {
    listIds: [5, 6],
    updateExisting: true,
    emptyContactsAttributes: false
  }
});

// 동기화 상태 확인
const status = await tajo.connectors.status('brevo');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsSynced: 25400,
//   campaignsSent: 142,
//   eventsTracked: 89320
// }

맞춤 이벤트 추적

// 연락처에 대한 맞춤 이벤트 추적
await tajo.brevo.trackEvent({
  email: '[email protected]',
  event: 'product_purchased',
  eventdata: {
    id: 'txn_98765',
    data: {
      product_name: 'Premium Widget',
      price: 49.99,
      currency: 'USD'
    }
  }
});

속도 제한

Brevo는 요금제에 따라 세 가지 티어에 걸쳐 속도 제한을 적용합니다.

문제 해결

일반적인 문제

디버그 모드

자세한 로깅 활성화:

connectors:
  brevo:
    debug: true
    log_level: verbose
    log_webhooks: true

연결 테스트

tajo connectors test brevo
# ✓ API 연결 성공
# ✓ Contacts API 접근 가능
# ✓ 트랜잭션 이메일 준비됨
# ✓ SMS 전송 구성됨
# ✓ 웹훅 등록됨

모범 사례

1. API 키 교체 사용 - 보안을 위해 API 키를 주기적으로 교체
2. 웹훅 검증 구현 - 사용자 이름/비밀번호 인증으로 웹훅 서명 검증
3. 연락처 가져오기 배치 처리 - 개별 API 호출 대신 대규모 데이터 세트에 대량 가져오기 사용
4. 속도 제한 모니터링 - 429 오류를 피하려면 속도 제한 헤더 확인
5. 이벤트 추적 사용 - 포괄적인 고객 행동 데이터를 위해 Brevo Tracker 구현
6. 적절한 발신자 인증 설정 - 최적의 배달률을 위해 SPF, DKIM, DMARC 구성

보안

• API 키 인증 - api-key 헤더를 통한 시크릿 토큰 기반 접근
• OAuth 2.0 - 사설 통합을 위한 토큰 기반 위임 접근
• 웹훅 확인 - 안전한 웹훅 호출을 위한 사용자 이름 및 비밀번호 인증
• TLS 암호화 - 전송 중 암호화된 모든 API 통신
• IP 허용 목록 - Enterprise 요금제에서 선택적 IP 제한 사용 가능

관련 리소스

• Brevo API 문서
• Brevo 인증 가이드
• Brevo 속도 제한
• Shopify 커넥터
• 고객 동기화 스킬
• Brevo Contacts API