고객 동기화

이커머스 플랫폼에서 Brevo 연락처로 고객 데이터를 자동 동기화합니다. 이 스킬은 Brevo 연락처 목록이 항상 현재 고객 기반을 반영하도록 보장합니다.

개요

속성	값
카테고리	Data Sync
상태	Stable
버전	2.1
트리거	`customer_created`, `customer_updated`, `customer_deleted`
액션	연락처 생성, 연락처 업데이트, 연락처 삭제

작동 방식

graph LR
    A[E-commerce Platform] -->|Customer Event| B[Customer Sync Skill]
    B -->|Map Data| C[Field Mapping]
    C -->|API Call| D[Brevo Contacts API]
    D -->|Success| E[Contact Updated]
    D -->|Error| F[Retry Queue]

이벤트 감지: 플랫폼에서 발생하는 고객 라이프사이클 이벤트를 수신합니다
데이터 매핑: 플랫폼 필드를 Brevo 연락처 속성에 매핑합니다
API 동기화: Brevo API를 통해 연락처를 생성, 업데이트 또는 삭제합니다
오류 처리: 지수 백오프로 실패한 작업을 재시도합니다

구성

기본 설정

skills:
  customer-sync:
    enabled: true
    source: shopify  # or woocommerce, magento, custom

    # Map platform fields to Brevo attributes
    field_mapping:
      email: email
      firstName: FIRSTNAME
      lastName: LASTNAME
      phone: SMS

    # Sync options
    options:
      sync_mode: realtime  # or batch
      delete_behavior: soft  # or hard
      list_id: 5  # Add to this list

필드 매핑

플랫폼의 고객 필드를 Brevo 연락처 속성에 매핑합니다.

기본 필드 매핑

Parameter	Type	Description
`email` required	string	고객 이메일 주소. Brevo에서 고유 식별자로 사용됩니다.
`firstName` optional	string	고객의 이름. FIRSTNAME 속성에 매핑됩니다. Default: `FIRSTNAME`
`lastName` optional	string	고객의 성. LASTNAME 속성에 매핑됩니다. Default: `LASTNAME`
`phone` optional	string	E.164 형식의 전화번호. WhatsApp/SMS를 위한 SMS 속성에 매핑됩니다. Default: `SMS`
`acceptsMarketing` optional	boolean	마케팅 수신 동의 상태. 이메일 구독 상태를 제어합니다. Default: `true`

사용자 정의 속성

이커머스 데이터를 위한 사용자 정의 속성 매핑을 추가합니다.

field_mapping:
  # Standard fields
  email: email
  firstName: FIRSTNAME

  # Custom e-commerce attributes
  totalOrders: TOTAL_ORDERS
  totalSpent: TOTAL_SPENT
  lastOrderDate: LAST_ORDER_DATE
  customerTier: CUSTOMER_TIER
  tags: TAGS

Tip

속성을 먼저 생성하세요: 사용자 정의 속성은 동기화하기 전에 Brevo에서 먼저 생성되어야 합니다. Brevo 대시보드 또는 API를 사용하여 생성하세요.

트리거

customer_created

플랫폼에서 새 고객이 생성될 때 발생합니다.

{
  "event": "customer_created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "cust_12345",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Smith",
    "phone": "+1234567890",
    "acceptsMarketing": true,
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

customer_updated

고객 정보가 수정될 때 발생합니다.

{
  "event": "customer_updated",
  "timestamp": "2024-01-15T14:45:00Z",
  "data": {
    "id": "cust_12345",
    "email": "[email protected]",
    "changes": {
      "phone": {
        "old": null,
        "new": "+1234567890"
      }
    }
  }
}

customer_deleted

플랫폼에서 고객이 제거될 때 발생합니다.

{
  "event": "customer_deleted",
  "timestamp": "2024-01-15T16:00:00Z",
  "data": {
    "id": "cust_12345",
    "email": "[email protected]",
    "deletedAt": "2024-01-15T16:00:00Z"
  }
}

액션

연락처 생성

고객이 생성되면 Brevo에 새 연락처를 생성합니다.

Brevo 계정에 새 연락처를 생성합니다

Query Parameters

Parameter	Description
email string required	연락처 이메일 주소
attributes object optional	연락처 속성
listIds array optional	연락처를 추가할 리스트 ID
updateEnabled boolean optional	연락처가 존재하는 경우 업데이트 Default: `false`

Responses

201 연락처 생성 성공

400 잘못된 요청 매개변수

409 연락처가 이미 존재합니다

연락처 업데이트

고객 데이터가 변경되면 기존 연락처를 업데이트합니다.

기존 연락처의 속성을 업데이트합니다

Path Parameters

Parameter	Description
identifier string required	이메일 또는 연락처 ID

Query Parameters

Parameter	Description
attributes object optional	업데이트할 속성
listIds array optional	연락처를 추가할 리스트
unlinkListIds array optional	연락처를 제거할 리스트

Responses

204 연락처 업데이트 성공

400 잘못된 요청 매개변수

404 연락처를 찾을 수 없음

연락처 삭제

고객이 삭제되면 연락처를 제거합니다.

Brevo에서 연락처를 영구적으로 삭제합니다

Path Parameters

Parameter	Description
identifier string required	이메일 또는 연락처 ID

Responses

204 연락처 삭제 성공

404 연락처를 찾을 수 없음

코드 예제

JavaScript (Node.js)

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

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

// Enable customer sync skill
await tajo.skills.enable('customer-sync', {
  source: 'shopify',
  fieldMapping: {
    email: 'email',
    firstName: 'FIRSTNAME',
    lastName: 'LASTNAME',
    totalOrders: 'TOTAL_ORDERS',
    totalSpent: 'TOTAL_SPENT'
  },
  options: {
    syncMode: 'realtime',
    listId: 5
  }
});

// Manually trigger a sync
await tajo.skills.trigger('customer-sync', {
  event: 'customer_created',
  data: {
    email: '[email protected]',
    firstName: 'Jane',
    lastName: 'Smith'
  }
});

Python

from tajo import TajoClient

tajo = TajoClient(
    api_key=os.environ['TAJO_API_KEY'],
    brevo_api_key=os.environ['BREVO_API_KEY']
)

# Enable customer sync skill
tajo.skills.enable('customer-sync', {
    'source': 'woocommerce',
    'field_mapping': {
        'email': 'email',
        'first_name': 'FIRSTNAME',
        'last_name': 'LASTNAME',
        'total_orders': 'TOTAL_ORDERS'
    },
    'options': {
        'sync_mode': 'realtime',
        'list_id': 5
    }
})

# Manually trigger a sync
tajo.skills.trigger('customer-sync', {
    'event': 'customer_updated',
    'data': {
        'email': '[email protected]',
        'total_orders': 10,
        'total_spent': 1250.00
    }
})

모니터링

동기화 상태 대시보드

Tajo 대시보드에서 동기화 성능을 모니터링합니다.

동기화 성공률: 성공한 동기화의 비율
평균 지연 시간: 이벤트 발생부터 Brevo 업데이트까지의 시간
오류율: 실패한 동기화 시도
큐 깊이: 대기 중인 동기화 작업

Webhook 알림

동기화 이벤트에 대한 알림을 수신합니다.

notifications:
  webhook_url: https://your-app.com/webhooks/tajo
  events:
    - sync_completed
    - sync_failed
    - batch_completed

문제 해결

일반적인 문제

연락처가 이미 존재함 (409)

실패하는 대신 기존 연락처를 업데이트하려면 구성에서 updateEnabled: true를 활성화하세요.

오류	원인	해결 방법
`Contact already exists`	해당 이메일의 연락처가 존재함	`updateEnabled: true` 활성화
`Invalid attribute`	Brevo에 속성이 존재하지 않음	Brevo에 속성을 먼저 생성
`Rate limit exceeded`	API 요청이 너무 많음	배치 동기화 모드 사용
`Invalid email format`	잘못된 형식의 이메일 주소	동기화 전 이메일 검증

디버그 모드

문제 해결을 위해 디버그 로깅을 활성화합니다.

skills:
  customer-sync:
    debug: true
    log_level: verbose

다음 단계

플랫폼에 대한 필드 매핑 구성
Brevo에 사용자 정의 속성 설정
즉각적인 업데이트를 위해 실시간 동기화 활성화

고객 동기화