---
title: "Konektor HubSpot"
description: "Kompletny przewodnik integracji HubSpot CRM do synchronizacji kontaktów, firm, transakcji, zgłoszeń i danych marketingowych z Brevo przez Tajo."
url: https://tajo.io/pl/docs/connectors/crm/hubspot/
markdown: https://tajo.io/pl/docs/connectors/crm/hubspot.md
lang: pl-PL
robots: noindex
---

Poproś o wcześniejszy dostęp

Podaj imię i firmowy adres e-mail. Wyślemy Ci link potwierdzający prośbę o dostęp do Tajo.

# Konektor HubSpot

Status konektora: W trakcie W budowie. Jeszcze niezweryfikowany.

| Pole źródłowe | Pole docelowe | Przykładowa wartość |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Połącz swój HubSpot CRM z Brevo przez Tajo, aby uzyskać dwukierunkową synchronizację kontaktów, śledzenie transakcji, dane o zaangażowaniu i ujednoliconą automatyzację marketingu na obu platformach.

## Przegląd

| Właściwość | Wartość |
| --- | --- |
| **Platforma** | HubSpot |
| **Kategoria** | CRM |
| **Poziom konfiguracji** | Średni |
| **Integracja oficjalna** | Nie |
| **Synchronizowane dane** | Kontakty, Firmy, Transakcje, Zgłoszenia, Zdarzenia |
| **Bazowy URL API** | `https://api.hubapi.com` |

## Funkcje

- **Dwukierunkowa synchronizacja kontaktów** - Utrzymuj kontakty zsynchronizowane między HubSpot a Brevo w czasie rzeczywistym
- **Śledzenie lejka transakcji** - Synchronizuj etapy i wartości transakcji dla segmentacji opartej na przychodach
- **Synchronizacja danych firm** - Powiąż kontakty z rekordami firm i danymi firmograficznymi
- **Integracja zgłoszeń** - Śledź zgłoszenia pomocy technicznej dla oceny kondycji klientów
- **Śledzenie zaangażowania** - Synchronizuj otwierania e-maili, kliknięcia, spotkania, rozmowy i notatki
- **Obsługa obiektów niestandardowych** - Mapuj obiekty niestandardowe HubSpot na atrybuty Brevo
- **Wyzwalacze workflow** - Używaj zmian etapu cyklu życia w HubSpot do wyzwalania automatyzacji Brevo
- **Zdarzenia webhook** - Powiadomienia w czasie rzeczywistym o zmianach danych CRM

## Wymagania wstępne

Zanim zaczniesz, upewnij się, że masz:

1. Konto HubSpot (Free, Starter, Professional lub Enterprise)
2. Prywatną lub OAuth aplikację HubSpot z wymaganymi zakresami
3. Konto Brevo z dostępem do API
4. Konto Tajo

## Uwierzytelnianie

### Token dostępu aplikacji prywatnej (zalecane)

Utwórz aplikację prywatną w HubSpot, aby uzyskać bezpośredni dostęp do API z granularną kontrolą zakresów.

1. Przejdź do HubSpot Settings > Integrations > Private Apps
2. Utwórz nową aplikację prywatną
3. Skonfiguruj wymagane zakresy
4. Skopiuj token dostępu

```bash
curl -X GET "https://api.hubapi.com/crm/v3/objects/contacts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
```

### OAuth 2.0

Użyj OAuth 2.0 do integracji wielokontowych wymagających autoryzacji użytkownika.

```bash
# Authorization URL
https://app.hubspot.com/oauth/authorize?client_id={client_id}&scope=crm.objects.contacts.read&redirect_uri={redirect_uri}
```

#### Wymagane zakresy

```
crm.objects.contacts.read
crm.objects.contacts.write
crm.objects.companies.read
crm.objects.deals.read
crm.objects.deals.write
crm.objects.custom.read
crm.schemas.custom.read
```

## Konfiguracja

### Podstawowa konfiguracja

```yaml
connectors:
  hubspot:
    enabled: true
    access_token: "${HUBSPOT_ACCESS_TOKEN}"

    # Data sync options
    sync:
      contacts: true
      companies: true
      deals: true
      tickets: true
      engagements: true

    # Sync direction
    direction: bidirectional  # or 'hubspot_to_brevo' | 'brevo_to_hubspot'

    # List assignment in Brevo
    lists:
      all_contacts: 10
      qualified_leads: 11
      customers: 12
```

### Mapowanie pól

Mapuj właściwości HubSpot na atrybuty kontaktów Brevo:

#### Domyślne mapowania

| Parameter | Type | Description |
| --- | --- | --- |
| `email` required | string | E-mail kontaktu (główny identyfikator) |
| `firstname` optional | string | Mapuje się na atrybut FIRSTNAME w Brevo |
| `lastname` optional | string | Mapuje się na atrybut LASTNAME w Brevo |
| `phone` optional | string | Mapuje się na atrybut SMS dla WhatsApp/SMS |
| `company` optional | string | Nazwa powiązanej firmy |
| `lifecyclestage` optional | string | Etap cyklu życia HubSpot (subscriber, lead, MQL, SQL, customer) |
| `hs_lead_status` optional | string | Status kwalifikacji leada |
| `hubspot_owner_id` optional | string | ID przypisanego właściciela sprzedaży |

#### Niestandardowe mapowanie właściwości

```yaml
field_mapping:
  # Standard fields
  email: email
  firstname: FIRSTNAME
  lastname: LASTNAME
  phone: SMS

  # CRM fields
  lifecyclestage: LIFECYCLE_STAGE
  hs_lead_status: LEAD_STATUS
  company: COMPANY_NAME

  # Deal metrics
  hs_total_deal_value: DEAL_VALUE
  num_associated_deals: DEAL_COUNT

  # Custom properties
  preferred_channel: PREFERRED_CHANNEL
  customer_segment: SEGMENT
```

## Endpointy API

### Obiekty CRM

| Metoda | Endpoint | Opis |
| --- | --- | --- |
| `GET` | `/crm/v3/objects/contacts` | Lista kontaktów |
| `POST` | `/crm/v3/objects/contacts` | Utwórz kontakt |
| `PATCH` | `/crm/v3/objects/contacts/{id}` | Aktualizuj kontakt |
| `GET` | `/crm/v3/objects/companies` | Lista firm |
| `GET` | `/crm/v3/objects/deals` | Lista transakcji |
| `POST` | `/crm/v3/objects/deals` | Utwórz transakcję |
| `GET` | `/crm/v3/objects/tickets` | Lista zgłoszeń |

### Powiązania

| Metoda | Endpoint | Opis |
| --- | --- | --- |
| `GET` | `/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}` | Pobierz powiązania |
| `PUT` | `/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}` | Utwórz powiązanie |

### Zaangażowanie

| Metoda | Endpoint | Opis |
| --- | --- | --- |
| `GET` | `/crm/v3/objects/calls` | Lista rozmów telefonicznych |
| `GET` | `/crm/v3/objects/emails` | Lista zaangażowań e-mailowych |
| `GET` | `/crm/v3/objects/meetings` | Lista spotkań |
| `GET` | `/crm/v3/objects/notes` | Lista notatek |
| `GET` | `/crm/v3/objects/tasks` | Lista zadań |

## Zdarzenia

### Zdarzenia kontaktów

| Zdarzenie | Wyzwalacz | Zastosowanie |
| --- | --- | --- |
| `contact.creation` | Nowy kontakt utworzony | Wyzwalacz serii powitalnej |
| `contact.propertyChange` | Właściwość kontaktu zaktualizowana | Synchronizacja atrybutów |
| `contact.merge` | Kontakty scalone | Obsługa deduplikacji |
| `contact.deletion` | Kontakt usunięty | Czyszczenie w Brevo |

### Zdarzenia transakcji

| Zdarzenie | Wyzwalacz | Zastosowanie |
| --- | --- | --- |
| `deal.creation` | Nowa transakcja utworzona | Powiadomienie sprzedażowe |
| `deal.propertyChange` | Zmiana etapu transakcji | Automatyzacja lejka |
| `deal.deletion` | Transakcja usunięta | Raportowanie przychodów |

### Zdarzenia firm

| Zdarzenie | Wyzwalacz | Zastosowanie |
| --- | --- | --- |
| `company.creation` | Nowa firma dodana | Marketing oparty na koncie |
| `company.propertyChange` | Dane firmy zaktualizowane | Synchronizacja firmograficzna |

## Przykłady kodu

### Inicjalizacja konektora

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

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

// Connect HubSpot
await tajo.connectors.connect('hubspot', {
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN
});
```

### Uruchom synchronizację kontaktów

```javascript
// Full bidirectional sync
await tajo.connectors.sync('hubspot', {
  type: 'full',
  resources: ['contacts', 'companies', 'deals'],
  direction: 'bidirectional',
  since: '2023-01-01'
});

// Check sync status
const status = await tajo.connectors.status('hubspot');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsSynced: 34200,
//   companiesSynced: 5100,
//   dealsSynced: 2340
// }
```

### Obsługa zdarzeń webhook

```javascript
// Handle HubSpot webhook notifications
app.post('/webhooks/hubspot', async (req, res) => {
  const signature = req.get('X-HubSpot-Signature-v3');

  // Verify webhook signature
  if (!verifyHubSpotSignature(req.body, signature)) {
    return res.status(401).send('Unauthorized');
  }

  for (const event of req.body) {
    await tajo.connectors.handleWebhook('hubspot', {
      eventType: event.subscriptionType,
      objectId: event.objectId,
      propertyName: event.propertyName,
      propertyValue: event.propertyValue
    });
  }

  res.status(200).send('OK');
});
```

## Limity API

HubSpot stosuje limity szybkości na aplikację prywatną lub OAuth:

| Plan | Limit | Limit burst |
| --- | --- | --- |
| Free/Starter | 100 żądań/10 sekund | 150 żądań/10 sekund |
| Professional | 150 żądań/10 sekund | 200 żądań/10 sekund |
| Enterprise | 200 żądań/10 sekund | 250 żądań/10 sekund |
| Dodatek API | 200 żądań/10 sekund | 250 żądań/10 sekund |

Dodatkowe limity:

- **Search API**: 5 żądań/sekundę na aplikację
- **Operacje wsadowe**: 100 rekordów na żądanie wsadowe
- **Dzienny limit**: 500 000 żądań/dzień (aplikacje OAuth)

Obsługa limitów API

HubSpot zwraca odpowiedź `429 Too Many Requests` po przekroczeniu limitów. Używaj wykładniczego wycofania i monitoruj nagłówki `X-HubSpot-RateLimit-*`.

## Rozwiązywanie problemów

### Typowe problemy

| Problem | Przyczyna | Rozwiązanie |
| --- | --- | --- |
| 401 Unauthorized | Wygasły lub nieprawidłowy token | Wygeneruj ponownie token aplikacji prywatnej lub odśwież token OAuth |
| Kontakt nie zsynchronizowany | Brak właściwości e-mail | Kontakty HubSpot wymagają e-maila do synchronizacji z Brevo |
| Duplikaty kontaktów | Brak reguły deduplikacji | Skonfiguruj reguły scalania w HubSpot |
| Webhook nie odebrany | Subskrypcja nieaktywna | Zarejestruj ponownie subskrypcje webhook |
| Właściwość nie zmapowana | Właściwość niestandardowa nie utworzona | Najpierw utwórz właściwość w HubSpot |

### Tryb debug

Włącz szczegółowe logowanie:

```yaml
connectors:
  hubspot:
    debug: true
    log_level: verbose
    log_webhooks: true
```

### Test połączenia

```bash
tajo connectors test hubspot
# ✓ API connection successful
# ✓ Contacts readable
# ✓ Companies readable
# ✓ Deals readable
# ✓ Webhooks registered
```

## Najlepsze praktyki

1. **Używaj aplikacji prywatnych zamiast kluczy API** - Klucze API są przestarzałe; używaj aplikacji prywatnych dla lepszego bezpieczeństwa
2. **Ostrożnie wdrażaj synchronizację dwukierunkową** - Unikaj nieskończonych pętli, śledząc źródło synchronizacji
3. **Mapuj etapy cyklu życia** - Używaj etapów cyklu życia HubSpot do segmentowania kontaktów w Brevo
4. **Wsadowe żądania API** - Używaj endpointów wsadowych dla operacji zbiorczych, aby pozostać w ramach limitów
5. **Monitoruj dostarczanie webhooków** - Skonfiguruj logikę ponownych prób i obsługę nieudanych dostarczeń
6. **Używaj synchronizacji przyrostowej** - Synchronizuj tylko zmienione rekordy używając właściwości `lastmodifieddate`

## Bezpieczeństwo

- **Tokeny aplikacji prywatnych** - Tokeny dostępu z granularnym zakresem uprawnień
- **OAuth 2.0** - Branżowy standard autoryzacji z rotacją tokenów odświeżania
- **Podpisy webhook** - Weryfikacja podpisu oparta na HMAC (v3)
- **Szyfrowanie TLS** - Cała komunikacja API zaszyfrowana podczas transmisji
- **Uprawnienia z zakresu** - Minimalny wymagany dostęp zakresowy na integrację

## Powiązane zasoby

- [Dokumentacja HubSpot API](https://developers.hubspot.com/docs/api/overview)
- [Przewodnik uwierzytelniania HubSpot](https://developers.hubspot.com/docs/api/working-with-oauth)
- [Konektor Salesforce](https://tajo.io/pl/docs/connectors/crm/salesforce)
- [Skill synchronizacji klientów](https://tajo.io/pl/docs/skills/data-sync/customer-sync)
- [Brevo Contacts API](https://tajo.io/pl/docs/contact-management)