Synchronizacja klientów

Automatycznie synchronizuj dane klientów z Twojej platformy e-commerce do kontaktów Brevo. Ten skill zapewnia, że lista kontaktów Brevo zawsze odzwierciedla aktualną bazę klientów.

Przegląd

Właściwość	Wartość
Kategoria	Synchronizacja danych
Status	Stabilny
Wersja	2.1
Wyzwalacze	`customer_created`, `customer_updated`, `customer_deleted`
Działania	Utwórz kontakt, Zaktualizuj kontakt, Usuń kontakt

Jak to działa

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]

Wykrywanie zdarzeń: Nasłuchuje zdarzeń cyklu życia klienta z Twojej platformy
Mapowanie danych: Mapuje pola platformy na atrybuty kontaktów Brevo
Synchronizacja API: Tworzy, aktualizuje lub usuwa kontakty przez API Brevo
Obsługa błędów: Ponawia nieudane operacje z wykładniczym cofnięciem

Konfiguracja

Podstawowa konfiguracja

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

    # Mapowanie pól platformy na atrybuty Brevo
    field_mapping:
      email: email
      firstName: FIRSTNAME
      lastName: LASTNAME
      phone: SMS

    # Opcje synchronizacji
    options:
      sync_mode: realtime  # or batch
      delete_behavior: soft  # or hard
      list_id: 5  # Dodaj do tej listy

Mapowanie pól

Mapuj pola klientów swojej platformy na atrybuty kontaktów Brevo:

Domyślne mapowania pól

Parameter	Type	Description
`email` required	string	Adres e-mail klienta. Używany jako unikalny identyfikator w Brevo.
`firstName` optional	string	Imię klienta. Mapuje na atrybut FIRSTNAME. Default: `FIRSTNAME`
`lastName` optional	string	Nazwisko klienta. Mapuje na atrybut LASTNAME. Default: `LASTNAME`
`phone` optional	string	Numer telefonu w formacie E.164. Mapuje na atrybut SMS dla WhatsApp/SMS. Default: `SMS`
`acceptsMarketing` optional	boolean	Status zgody marketingowej. Kontroluje status subskrypcji e-mail. Default: `true`

Atrybuty niestandardowe

Dodaj niestandardowe mapowania atrybutów dla danych e-commerce:

field_mapping:
  # Pola standardowe
  email: email
  firstName: FIRSTNAME

  # Niestandardowe atrybuty e-commerce
  totalOrders: TOTAL_ORDERS
  totalSpent: TOTAL_SPENT
  lastOrderDate: LAST_ORDER_DATE
  customerTier: CUSTOMER_TIER
  tags: TAGS

Tip

Najpierw utwórz atrybuty: Atrybuty niestandardowe muszą zostać utworzone w Brevo, zanim będą mogły być synchronizowane. Użyj panelu Brevo lub API, aby je utworzyć.

Wyzwalacze

customer_created

Uruchamiany, gdy nowy klient zostaje utworzony w Twojej platformie.

{
  "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

Uruchamiany, gdy informacje o kliencie zostają zmodyfikowane.

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

customer_deleted

Uruchamiany, gdy klient zostaje usunięty z Twojej platformy.

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

Działania

Utwórz kontakt

Tworzy nowy kontakt w Brevo, gdy klient zostaje utworzony.

Utwórz nowy kontakt na koncie Brevo

Query Parameters

Parameter	Description
email string required	Adres e-mail kontaktu
attributes object optional	Atrybuty kontaktu
listIds array optional	Identyfikatory list, do których dodać kontakt
updateEnabled boolean optional	Aktualizuj, jeśli kontakt istnieje Default: `false`

Responses

201 Kontakt utworzony pomyślnie

400 Nieprawidłowe parametry żądania

409 Kontakt już istnieje

Zaktualizuj kontakt

Aktualizuje istniejący kontakt, gdy dane klienta się zmieniają.

Zaktualizuj atrybuty istniejącego kontaktu

Path Parameters

Parameter	Description
identifier string required	Adres e-mail lub identyfikator kontaktu

Query Parameters

Parameter	Description
attributes object optional	Atrybuty do zaktualizowania
listIds array optional	Listy, do których dodać kontakt
unlinkListIds array optional	Listy, z których usunąć kontakt

Responses

204 Kontakt zaktualizowany pomyślnie

400 Nieprawidłowe parametry żądania

404 Nie znaleziono kontaktu

Usuń kontakt

Usuwa kontakt, gdy klient zostaje usunięty.

Trwale usuń kontakt z Brevo

Path Parameters

Parameter	Description
identifier string required	Adres e-mail lub identyfikator kontaktu

Responses

204 Kontakt usunięty pomyślnie

404 Nie znaleziono kontaktu

Przykłady kodu

JavaScript (Node.js)

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

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

// Włącz skill synchronizacji klientów
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
  }
});

// Ręcznie uruchom synchronizację
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']
)

# Włącz skill synchronizacji klientów
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
    }
})

# Ręcznie uruchom synchronizację
tajo.skills.trigger('customer-sync', {
    'event': 'customer_updated',
    'data': {
        'email': '[email protected]',
        'total_orders': 10,
        'total_spent': 1250.00
    }
})

Monitorowanie

Panel stanu synchronizacji

Monitoruj wydajność synchronizacji w panelu Tajo:

Wskaźnik sukcesu synchronizacji: Odsetek udanych synchronizacji
Średnie opóźnienie: Czas od zdarzenia do aktualizacji Brevo
Wskaźnik błędów: Nieudane próby synchronizacji
Głębokość kolejki: Oczekujące operacje synchronizacji

Powiadomienia webhook

Otrzymuj powiadomienia o zdarzeniach synchronizacji:

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

Rozwiązywanie problemów

Typowe problemy

Kontakt już istnieje (409)

Włącz updateEnabled: true w konfiguracji, aby aktualizować istniejące kontakty zamiast generować błąd.

Błąd	Przyczyna	Rozwiązanie
`Contact already exists`	Kontakt z tym adresem e-mail już istnieje	Włącz `updateEnabled: true`
`Invalid attribute`	Atrybut nie istnieje w Brevo	Najpierw utwórz atrybut w Brevo
`Rate limit exceeded`	Zbyt wiele żądań API	Użyj trybu synchronizacji wsadowej
`Invalid email format`	Nieprawidłowy format adresu e-mail	Sprawdzaj poprawność e-maili przed synchronizacją

Tryb debugowania

Włącz szczegółowe logowanie do rozwiązywania problemów:

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

Powiązane Skills

Zdarzenia zamówień – Synchronizuj dane zamówień
Katalog produktów – Synchronizuj dane produktów
Zdarzenia koszyka – Śledź aktywność koszyka

Następne kroki

Skonfiguruj mapowania pól dla swojej platformy
Skonfiguruj atrybuty niestandardowe w Brevo
Włącz synchronizację w czasie rzeczywistym dla natychmiastowych aktualizacji

Synchronizacja klientów