2026'da HubSpot API Nasıl Kullanılır?

Kısaca

HubSpot API'si, geliştiricilerin CRM, pazarlama, satış ve hizmet merkezleriyle programlı olarak entegre olmasını sağlar. OAuth 2.0 ve özel uygulama kimlik doğrulaması kullanır, kişiler, şirketler, anlaşmalar, destek talepleri ve daha fazlası için RESTful uç noktaları sunar ve abonelik katmanına göre hız sınırları uygular. Bu kılavuz, kimlik doğrulama kurulumunu, temel uç noktaları, web kancalarını ve üretim entegrasyon stratejilerini kapsar.

Giriş

HubSpot 194.000'den fazla müşteri hesabını ve milyarlarca CRM kaydını yönetmektedir. CRM entegrasyonları, pazarlama otomasyonu veya satış araçları geliştiren geliştiriciler için HubSpot API entegrasyonu isteğe bağlı değil, 7 milyondan fazla kullanıcıya ulaşmak için esastır.

İşte gerçek: İşletmeler, sistemler arasında manuel veri girişiyle haftalık 15-20 saat kaybediyor. Sağlam bir HubSpot API entegrasyonu, kişiler arası senkronizasyonu, anlaşma güncellemelerini, pazarlama iş akışlarını ve platformlar arası raporlamayı otomatikleştirir.

HubSpot API'si Nedir?

HubSpot, CRM verilerine ve pazarlama otomasyon özelliklerine erişim için RESTful bir API sağlar. API şunları yönetir:

• Kişiler, şirketler, anlaşmalar, destek talepleri ve özel nesneler
• Pazarlama e-postaları ve açılış sayfaları
• Satış hatları ve dizileri
• Hizmet destek talepleri ve konuşmalar
• Analitik ve raporlama
• İş akışları ve otomasyon
• Dosyalar ve varlıklar

Temel Özellikler

API Mimariye Genel Bakış

HubSpot, sürümlü REST API'leri kullanır:

https://api.hubapi.com/

API Sürümlerinin Karşılaştırması

Önemli: HubSpot, API anahtarı kimlik doğrulamasını OAuth 2.0 ve özel uygulamalar lehine kullanımdan kaldırdı. Tüm entegrasyonları hemen taşıyın.

Başlarken: Kimlik Doğrulama Kurulumu

Adım 1: HubSpot Geliştirici Hesabınızı Oluşturun

API'ye erişmeden önce:

1. HubSpot Geliştirici Portalı'nı ziyaret edin
2. HubSpot hesabınızla oturum açın (veya yeni bir hesap oluşturun)
3. Geliştirici kontrol panelinde Uygulamalar'a gidin
4. Uygulama oluştur'a tıklayın

Adım 2: Kimlik Doğrulama Yöntemini Seçin

HubSpot iki kimlik doğrulama yöntemini destekler:

Adım 3: Özel Uygulama Kurulumu (Dahili Entegrasyonlar İçin Önerilir)

Tek portal erişimi için özel bir uygulama oluşturun:

1. Ayarlar > Entegrasyonlar > Özel Uygulamalar'a gidin
2. Özel bir uygulama oluştur'a tıklayın
3. Kapsamları yapılandırın:

contacts
crm.objects.companies
crm.objects.deals
crm.objects.tickets
automation
webhooks

1. Erişim belirteci oluşturun
2. Kopyalayın ve güvenli bir şekilde saklayın

# .env dosyası
HUBSPOT_ACCESS_TOKEN="pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
HUBSPOT_PORTAL_ID="12345678"

Adım 4: OAuth 2.0 Kurulumu (Çok Kiracılı Uygulamalar İçin)

Çoklu portal erişimi için OAuth'ı yapılandırın:

1. Uygulamalar > Uygulama oluştur'a gidin
2. Kimlik doğrulama ayarlarını yapılandırın:

const HUBSPOT_CLIENT_ID = process.env.HUBSPOT_CLIENT_ID;
const HUBSPOT_CLIENT_SECRET = process.env.HUBSPOT_CLIENT_SECRET;
const HUBSPOT_REDIRECT_URI = process.env.HUBSPOT_REDIRECT_URI;

// Yetkilendirme URL'sini oluştur
const getAuthUrl = (state) => {
  const params = new URLSearchParams({
    client_id: HUBSPOT_CLIENT_ID,
    redirect_uri: HUBSPOT_REDIRECT_URI,
    scope: 'crm.objects.contacts.read crm.objects.contacts.write',
    state: state,
    optional_scope: 'crm.objects.deals.read'
  });

  return `https://app.hubspot.com/oauth/authorize?${params.toString()}`;
};

Adım 5: Erişim Belirteci İçin Kodu Değiştirme

OAuth geri çağrısını işleyin:

const exchangeCodeForToken = async (code) => {
  const response = await fetch('https://api.hubapi.com/oauth/v1/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: HUBSPOT_CLIENT_ID,
      client_secret: HUBSPOT_CLIENT_SECRET,
      redirect_uri: HUBSPOT_REDIRECT_URI,
      code: code
    })
  });

  const data = await response.json();

  return {
    accessToken: data.access_token,
    refreshToken: data.refresh_token,
    expiresIn: data.expires_in,
    portalId: data.hub_portal_id
  };
};

// Geri çağrıyı işle
app.get('/oauth/callback', async (req, res) => {
  const { code, state } = req.query;

  try {
    const tokens = await exchangeCodeForToken(code);

    // Belirteçleri veritabanında sakla
    await db.installations.create({
      portalId: tokens.portalId,
      accessToken: tokens.accessToken,
      refreshToken: tokens.refreshToken,
      tokenExpiry: Date.now() + (tokens.expiresIn * 1000)
    });

    res.redirect('/success');
  } catch (error) {
    console.error('OAuth hatası:', error);
    res.status(500).send('Kimlik doğrulama başarısız oldu');
  }
});

Adım 6: Erişim Belirtecini Yenileme

Erişim belirteçlerinin süresi 6 saat sonra dolar:

const refreshAccessToken = async (refreshToken) => {
  const response = await fetch('https://api.hubapi.com/oauth/v1/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      client_id: HUBSPOT_CLIENT_ID,
      client_secret: HUBSPOT_CLIENT_SECRET,
      refresh_token: refreshToken
    })
  });

  const data = await response.json();

  return {
    accessToken: data.access_token,
    refreshToken: data.refresh_token, // Her zaman yeni yenileme belirtecini kaydet
    expiresIn: data.expires_in
  };
};

// Geçerli belirteci sağlamak için ara yazılım
const ensureValidToken = async (portalId) => {
  const installation = await db.installations.findByPortalId(portalId);

  // 30 dakika içinde süresi doluyorsa yenile
  if (installation.tokenExpiry < Date.now() + 1800000) {
    const newTokens = await refreshAccessToken(installation.refreshToken);

    await db.installations.update(installation.id, {
      accessToken: newTokens.accessToken,
      refreshToken: newTokens.refreshToken,
      tokenExpiry: Date.now() + (newTokens.expiresIn * 1000)
    });

    return newTokens.accessToken;
  }

  return installation.accessToken;
};

Adım 7: Kimliği Doğrulanmış API Çağrıları Yapma

Yeniden kullanılabilir API istemcisi oluşturun:

const HUBSPOT_BASE_URL = 'https://api.hubapi.com';

const hubspotRequest = async (endpoint, options = {}, portalId = null) => {
  const accessToken = portalId ? await ensureValidToken(portalId) : process.env.HUBSPOT_ACCESS_TOKEN;

  const response = await fetch(`${HUBSPOT_BASE_URL}${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
      ...options.headers
    }
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`HubSpot API Hatası: ${error.message}`);
  }

  return response.json();
};

// Kullanım
const contacts = await hubspotRequest('/crm/v3/objects/contacts');

CRM Nesneleriyle Çalışma

Bir Kişi Oluşturma

Bir kişi oluşturun veya güncelleyin:

const createContact = async (contactData) => {
  const contact = {
    properties: {
      email: contactData.email,
      firstname: contactData.firstName,
      lastname: contactData.lastName,
      phone: contactData.phone,
      company: contactData.company,
      website: contactData.website,
      lifecyclestage: contactData.lifecycleStage || 'lead'
    }
  };

  const response = await hubspotRequest('/crm/v3/objects/contacts', {
    method: 'POST',
    body: JSON.stringify(contact)
  });

  return response;
};

// Kullanım
const contact = await createContact({
  email: 'john.doe@example.com',
  firstName: 'John',
  lastName: 'Doe',
  phone: '+1-555-0123',
  company: 'Acme Corp',
  lifecycleStage: 'customer'
});

console.log(`Kişi oluşturuldu: ${contact.id}`);

Kişi Özellikleri

Bir Kişi Alma

Kişiyi kimliğe göre getir:

const getContact = async (contactId) => {
  const response = await hubspotRequest(`/crm/v3/objects/contacts/${contactId}`);
  return response;
};

// Kullanım
const contact = await getContact('12345');
console.log(`${contact.properties.firstname} ${contact.properties.lastname}`);
console.log(`E-posta: ${contact.properties.email}`);

Kişileri Arama

Filtrelerle arama yapın:

const searchContacts = async (searchCriteria) => {
  const response = await hubspotRequest('/crm/v3/objects/contacts/search', {
    method: 'POST',
    body: JSON.stringify({
      filterGroups: searchCriteria,
      properties: ['firstname', 'lastname', 'email', 'company'],
      limit: 100
    })
  });

  return response;
};

// Kullanım - Belirli bir şirketteki kişileri bul
const results = await searchContacts({
  filterGroups: [
    {
      filters: [
        {
          propertyName: 'company',
          operator: 'EQ',
          value: 'Acme Corp'
        }
      ]
    }
  ]
});

results.results.forEach(contact => {
  console.log(`${contact.properties.email}`);
});

Arama Filtresi Operatörleri

Bir Şirket Oluşturma

Şirket kaydı oluşturun:

const createCompany = async (companyData) => {
  const company = {
    properties: {
      name: companyData.name,
      domain: companyData.domain,
      industry: companyData.industry,
      numberofemployees: companyData.employees,
      annualrevenue: companyData.revenue,
      city: companyData.city,
      state: companyData.state,
      country: companyData.country
    }
  };

  const response = await hubspotRequest('/crm/v3/objects/companies', {
    method: 'POST',
    body: JSON.stringify(company)
  });

  return response;
};

// Kullanım
const company = await createCompany({
  name: 'Acme Corporation',
  domain: 'acme.com',
  industry: 'Teknoloji',
  employees: 500,
  revenue: 50000000,
  city: 'San Francisco',
  state: 'CA',
  country: 'ABD'
});

Nesneleri İlişkilendirme

Kişileri şirketlerle bağlayın:

const associateContactWithCompany = async (contactId, companyId) => {
  const response = await hubspotRequest(
    `/crm/v3/objects/contacts/${contactId}/associations/companies/${companyId}`,
    {
      method: 'PUT',
      body: JSON.stringify({
        types: [
          {
            associationCategory: 'HUBSPOT_DEFINED',
            associationTypeId: 1 // Kişi ile Şirket
          }
        ]
      })
    }
  );

  return response;
};

// Kullanım
await associateContactWithCompany('12345', '67890');

İlişkilendirme Türleri

Bir Anlaşma Oluşturma

Satış fırsatı oluşturun:

const createDeal = async (dealData) => {
  const deal = {
    properties: {
      dealname: dealData.name,
      amount: dealData.amount.toString(),
      dealstage: dealData.stage || 'appointmentscheduled',
      pipeline: dealData.pipelineId || 'default',
      closedate: dealData.closeDate,
      dealtype: dealData.type || 'newbusiness',
      description: dealData.description
    }
  };

  const response = await hubspotRequest('/crm/v3/objects/deals', {
    method: 'POST',
    body: JSON.stringify(deal)
  });

  return response;
};

// Kullanım
const deal = await createDeal({
  name: 'Acme Corp - Kurumsal Lisans',
  amount: 50000,
  stage: 'qualification',
  closeDate: '2026-06-30',
  type: 'newbusiness',
  description: 'Kurumsal yıllık abonelik'
});

// Şirket ve kişiyle ilişkilendir
await hubspotRequest(
  `/crm/v3/objects/deals/${deal.id}/associations/companies/${companyId}`,
  { method: 'PUT', body: JSON.stringify({ types: [{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 5 }] }) }
);

await hubspotRequest(
  `/crm/v3/objects/deals/${deal.id}/associations/contacts/${contactId}`,
  { method: 'PUT', body: JSON.stringify({ types: [{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 3 }] }) }
);

Anlaşma Aşamaları (Varsayılan Satış Hattı)

Web Kancaları

Web Kancalarını Yapılandırma

Gerçek zamanlı bildirimler için web kancalarını kurun:

const createWebhook = async (webhookData) => {
  const response = await hubspotRequest('/webhooks/v3/my-app/webhooks', {
    method: 'POST',
    body: JSON.stringify({
      webhookUrl: webhookData.url,
      eventTypes: webhookData.events,
      objectType: webhookData.objectType,
      propertyName: webhookData.propertyName // İsteğe bağlı: özellik değişimine göre filtrele
    })
  });

  return response;
};

// Kullanım
const webhook = await createWebhook({
  url: 'https://myapp.com/webhooks/hubspot',
  events: [
    'contact.creation',
    'contact.propertyChange',
    'company.creation',
    'deal.creation',
    'deal.stageChange'
  ],
  objectType: 'contact'
});

console.log(`Web kancası oluşturuldu: ${webhook.id}`);

Web Kancası Olay Türleri

Web Kancalarını İşleme

const express = require('express');
const crypto = require('crypto');
const app = express();

app.post('/webhooks/hubspot', express.json(), async (req, res) => {
  const signature = req.headers['x-hubspot-signature'];
  const payload = JSON.stringify(req.body);

  // Web kancası imzasını doğrula
  const isValid = verifyWebhookSignature(payload, signature, process.env.HUBSPOT_CLIENT_SECRET);

  if (!isValid) {
    console.error('Geçersiz web kancası imzası');
    return res.status(401).send('Yetkisiz');
  }

  const events = req.body;

  for (const event of events) {
    console.log(`Olay: ${event.eventType}`);
    console.log(`Nesne: ${event.objectType} - ${event.objectId}`);
    console.log(`Özellik: ${event.propertyName}`);
    console.log(`Değer: ${event.propertyValue}`);

    // Uygun işleyiciye yönlendir
    switch (event.eventType) {
      case 'contact.creation':
        await handleContactCreation(event);
        break;
      case 'contact.propertyChange':
        await handleContactUpdate(event);
        break;
      case 'deal.stageChange':
        await handleDealStageChange(event);
        break;
    }
  }

  res.status(200).send('Tamam');
});

function verifyWebhookSignature(payload, signature, clientSecret) {
  const expectedSignature = crypto
    .createHmac('sha256', clientSecret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

Hız Sınırlandırması

Hız Sınırlarını Anlama

HubSpot, abonelik katmanına göre hız sınırları uygular:

Sınırların aşılması, HTTP 429 (Çok Fazla İstek) yanıtlarına yol açar.

Hız Sınırı Başlıkları

Hız Sınırı İşlemesini Uygulama

const makeRateLimitedRequest = async (endpoint, options = {}, maxRetries = 3) => {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await hubspotRequest(endpoint, options);

      // Hız sınırı bilgisini kaydet
      const remaining = response.headers.get('X-HubSpot-RateLimit-Second-Remaining');
      if (remaining < 10) {
        console.warn(`Düşük hız sınırı kaldı: ${remaining}`);
      }

      return response;
    } catch (error) {
      if (error.message.includes('429') && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000;
        console.log(`Hız sınırlandırıldı. ${delay}ms içinde tekrar deneniyor...`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
};

// Hız sınırlayıcı sınıfı
class HubSpotRateLimiter {
  constructor(requestsPerSecond = 90) { // Sınırın altında kal
    this.queue = [];
    this.interval = 1000 / requestsPerSecond;
    this.processing = false;
  }

  async add(requestFn) {
    return new Promise((resolve, reject) => {
      this.queue.push({ requestFn, resolve, reject });
      this.process();
    });
  }

  async process() {
    if (this.processing || this.queue.length === 0) return;
    this.processing = true;

    while (this.queue.length > 0) {
      const { requestFn, resolve, reject } = this.queue.shift();
      try {
        const result = await requestFn();
        resolve(result);
      } catch (error) {
        reject(error);
      }
      if (this.queue.length > 0) {
        await new Promise(r => setTimeout(r, this.interval));
      }
    }
    this.processing = false;
  }
}

Üretim Dağıtım Kontrol Listesi

Canlıya geçmeden önce:

• [ ] Özel uygulama veya OAuth 2.0 kimlik doğrulaması kullanın
• [ ] Belirteçleri güvenli bir şekilde saklayın (şifreli veritabanı)
• [ ] Otomatik belirteç yenilemeyi uygulayın
• [ ] Hız sınırlaması ve istek kuyruğu oluşturun
• [ ] Web kancası uç noktasını HTTPS ile yapılandırın
• [ ] Kapsamlı hata işleme uygulayın
• [ ] Tüm API çağrıları için günlük kaydı ekleyin
• [ ] Hız sınırı kullanımını izleyin
• [ ] Yaygın sorunlar için çalışma kitabı oluşturun

Gerçek Dünya Kullanım Senaryoları

CRM Senkronizasyonu

Bir SaaS şirketi müşteri verilerini senkronize eder:

• Zorluk: Uygulama ve HubSpot arasında manuel veri girişi
• Çözüm: Web kancaları ve API aracılığıyla gerçek zamanlı senkronizasyon
• Sonuç: Sıfır manuel giriş, %100 veri doğruluğu

Potansiyel Müşteri Yönlendirme

Bir pazarlama ajansı potansiyel müşteri dağıtımını otomatikleştirir:

• Zorluk: Yavaş potansiyel müşteri yanıt süreleri
• Çözüm: Web kancası tetiklemeli satış temsilcilerine yönlendirme
• Sonuç: 5 dakikalık yanıt süresi, %40 dönüşüm artışı

Sonuç

HubSpot API'si kapsamlı CRM ve pazarlama otomasyonu yetenekleri sunar. Temel çıkarımlar:

• Çok kiracılı uygulamalar için OAuth 2.0, dahili entegrasyonlar için özel uygulamalar kullanın
• Hız sınırları katmana göre değişir (saniyede 100-400 istek)
• Web kancaları gerçek zamanlı senkronizasyonu etkinleştirir
• CRM nesneleri ilişkilendirmeleri ve özel özellikleri destekler
• Apidog, API testini ve ekip işbirliğini kolaylaştırır

Sıkça Sorulan Sorular Bölümü

HubSpot API'si ile nasıl kimlik doğrularım?

Çok kiracılı uygulamalar için OAuth 2.0'ı veya tek portal entegrasyonları için özel uygulamaları kullanın. API anahtarı kimlik doğrulaması kullanımdan kaldırılmıştır.

HubSpot hız limitleri nelerdir?

Hız limitleri saniyede 100 istekten (Ücretsiz) saniyede 400 isteğe (Kurumsal) kadar değişir; günlük limitler ise 100 bin ile 1 milyon istek arasındadır.

HubSpot'ta nasıl kişi oluştururum?

E-posta, ad, soyad ve herhangi bir özel alan dahil olmak üzere özelliklerle /crm/v3/objects/contacts adresine POST isteği gönderin.

Özel özellikler oluşturabilir miyim?

Evet, herhangi bir nesne türü için özel alanlar oluşturmak üzere Özellikler API'sini kullanın.

HubSpot'ta web kancaları nasıl çalışır?

Uygulama ayarlarınızda web kancalarını yapılandırın. HubSpot, belirtilen olaylar meydana geldiğinde uç noktanıza POST istekleri gönderir.