external_id ile CRM şirketlerinizi Hipcall'a senkronize edin

Genel Bakış

Çoğu işletme, kanonik şirket kayıtlarını zaten bir CRM veya ERP’de tutar. Bu kayıtları Hipcall’a aktarmak; temsilcilerinizin, çevirici sistemlerinizin ve raporlarınızın, satış ve finans ekiplerinizin güvendiği aynı veriler üzerinde çalışması anlamına gelir — kimsenin satırları elle kopyalamasına gerek kalmadan.

Bu rehber, Hipcall REST API ve external_id alanını kullanarak şirketleri nasıl senkronize tutacağınızı gösterir. Her Hipcall şirketini oluşturma sırasında kendi birincil anahtarınızla işaretler, daha sonra aynı anahtarla sorgular ve Hipcall’ın sayısal kimliğini hiçbir zaman önbelleğe almadan güncelleme yaparsınız.

Nasıl Çalışır

external_id, her şirket ve kişi üzerinde bulunan bir karakter dizisi alanıdır (en fazla 255 karakter). Bu alan size aittir — Hipcall onu üretmez veya yorumlamaz. Akılda tutulması gereken üç kural:

• Hipcall hesabınız içinde benzersiz olmalıdır. Aynı hesaptaki iki şirket bir external_id değerini paylaşamaz.
• Kaynaklar arasında bağımsızdır. Aynı karakter dizisi, aynı hesaptaki bir şirketi ve bir kişiyi ayrı ayrı tanımlayabilir.
• Hesaplar arasında izole edilmiştir. Farklı Hipcall hesapları çakışma olmadan aynı "123" değerini kullanabilir.

Bu özellikler yerinde olduğunda, senkronizasyon her kayıt için tek bir tekrar eden karara indirgenir: Hipcall’da bu external_id zaten var mı? Varsa güncelle. Yoksa oluştur.

Senkronizasyon Akışı

flowchart TD
    A[CRM'inizde şirket değişti] --> B[GET /companies/by-external-id/:crm_id]
    B --> C{Bulundu mu?}
    C -- 404 Hayır --> D[POST /companies + external_id ile]
    C -- 200 Evet --> E[PATCH /companies/:hipcall_id]
    D --> F[Senkronize edildi]
    E --> F

Adım 1: Hipcall API Token Alın

Hipcall’a giriş yapın ve Hesap > Entegrasyonlar > REST API bölümüne gidin. Bir kişisel erişim token’ı oluşturun ve kopyalayın — Hipcall onu yalnızca bir kez gösterir.

Token’ı her istekte Bearer kimlik bilgisi olarak gönderin:

Authorization: Bearer YOUR_API_TOKEN

Aşağıdaki tüm uç noktalar /api/v3 altındadır.

Adım 2: external_id ile Şirket Oluşturun

CRM’inizde yeni bir şirket göründüğünde, eşleşen Hipcall kaydını oluşturun ve onu CRM’inizin birincil anahtarıyla işaretleyin.

Uç nokta:

POST /api/v3/companies
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

İstek gövdesi:

{
  "name": "Yıldız Teknoloji AŞ",
  "external_id": "ERP-9876",
  "website_url": "https://yildizteknoloji.com.tr",
  "custom_url": "https://crm.sirketiniz.com/sirketler/9876",
  "emails": [
    { "email": "info@yildizteknoloji.com.tr", "order": 0 }
  ],
  "phones": [
    { "country": "TR", "number": "+908508850000", "order": 0 }
  ]
}

Yanıt (201 Created):

{
  "data": {
    "id": 42,
    "name": "Yıldız Teknoloji AŞ",
    "external_id": "ERP-9876",
    "website_url": "https://yildizteknoloji.com.tr",
    "custom_url": "https://crm.sirketiniz.com/sirketler/9876",
    "emails": [
      { "email": "info@yildizteknoloji.com.tr", "order": 0 }
    ],
    "phones": [
      { "country": "TR", "number": "+908508850000", "order": 0 }
    ]
  }
}

Hipcall’ın external_id alanını nasıl normalize ettiğine dair birkaç not:

• Baştaki ve sondaki boşluklar kırpılır.
• Boş bir karakter dizisi null olarak saklanır.
• JSON tam sayısı (örneğin 9876) "9876" karakter dizisine dönüştürülür. CRM’inizden hangi formatta gelirse gelsin gönderin — Hipcall dönüşümü kendisi yapar.

Adım 3: external_id ile Şirket Sorgulayın

Tüm bu deseni mümkün kılan uç nokta budur. Hipcall’ın oluşturma sırasında döndürdüğü sayısal kimliği hatırlamak yerine, şirketi kendi tanımlayıcınızla sorgulayın.

Uç nokta:

GET /api/v3/companies/by-external-id/ERP-9876
Authorization: Bearer YOUR_API_TOKEN

Yanıt (200 OK):

{
  "data": {
    "id": 42,
    "name": "Yıldız Teknoloji AŞ",
    "external_id": "ERP-9876",
    "website_url": "https://yildizteknoloji.com.tr",
    "custom_url": "https://crm.sirketiniz.com/sirketler/9876",
    "emails": [...],
    "phones": [...]
  }
}

Yanıt (404 Not Found) — hesabınızda bu external_id ile eşleşen bir şirket yok:

{
  "errors": {
    "detail": "Not Found"
  }
}

Bir senkronizasyon iş akışında bu 404 hata değildir — oluşturma sinyalidir. Aşağıdaki Hepsini bir araya getirelim bölümüne bakın.

Adım 4: Şirketi Güncelleyin

Adım 3’te şirketi bulduktan sonra, onu Hipcall sayısal kimliğiyle güncelleyin. Yalnızca değiştirmek istediğiniz alanları PATCH edin.

PATCH /api/v3/companies/42
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "website_url": "https://yeni.yildizteknoloji.com.tr"
}

external_id değerinin kendisini de değiştirebilirsiniz — örneğin yukarı akış CRM bir kaydı yeniden anahtarladığında:

{ "external_id": "ERP-9999" }

Veya null göndererek tamamen temizleyebilirsiniz:

{ "external_id": null }

Hepsini Bir Araya Getirelim: Idempotent Senkronizasyon Döngüsü

Senkronizasyon işinin CRM’inizdeki her değişen şirket için çalıştırdığı döngü şudur:

crm'inizdeki her şirket için:
    yanit = GET /api/v3/companies/by-external-id/{crm_id}

    eğer yanit.status == 404 ise:
        POST /api/v3/companies  { external_id: crm_id, ...alanlar }

    aksi halde yanit.status == 200 ise:
        PATCH /api/v3/companies/{yanit.data.id}  { ...değişen_alanlar }

Yarış koşulu yedeği (422 Unprocessable Entity). Eğer iki senkronizasyon işi aynı anda çalışırsa, her ikisi de aynı external_id için 404 görebilir ve her ikisi de POST çağrısı yapabilir. İkinci POST şu yanıtı döndürür:

{
  "errors": {
    "external_id": ["has already been taken"]
  }
}

external_id hatası içeren herhangi bir 422 yanıtını, sorgula-sonra-PATCH yoluna geri dönme sinyali olarak değerlendirin. Birleşik akış — sorgulama, oluştur-veya-güncelle, çakışmada güncellemeye geri düşme — tamamen idempotenttir. Senkronizasyonu güvenle istediğiniz kadar tekrar oynatabilirsiniz.

Kişiler Hakkında Bir Not

Aynı desen kişiler için de çalışır. POST /api/v3/contacts external_id kabul eder ve GET /api/v3/contacts/by-external-id/:external_id kişiyi döndürür. Şirket ve kişi external_id ad alanları bir hesap içinde bağımsızdır, yani aynı karakter dizisi çakışma olmadan hem bir şirketi hem de bir kişiyi tanımlayabilir.

Kullanılan Araçlar

Araç	Amaç
REST API	Tüm istekler v3 REST API’yi Bearer token ile kullanır
external_id alanı	CRM’inizin birincil anahtarını Hipcall şirket kaydı üzerinde taşır
external_id ile sorgulama uç noktası	GET /api/v3/companies/by-external-id/:external_id — yan eşleştirme tablosu ihtiyacını ortadan kaldırır

Sonraki Adımlar

• REST API belgeleri — şirketler, kişiler ve mevcut tüm uç noktalar için tam şema
• Webkancaları — ters yön için şirket değişiklik olaylarına abone olun (Hipcall → kendi CRM’iniz)