Bu rehberde: Zoho CRM hesabınızı bağlarsınız. CRM'e yaz kutusu adayları Leads modülüne e-postaya göre ekler veya günceller; Zoho CRM kutusu Lead oluşturur, kayda not ekler ve kayıt arar. Hesabınız hangi veri merkezinde olursa olsun (US, EU, IN, AU, JP, CA…) otomatik algılanır.
⏱ 5 dakika (platformun Zoho istemcisi kayıtlıysa)
Kimlik kartı#
| Alan | Değer |
|---|
| Sağlayıcı anahtarı | ZOHO_CRM (kutu: Zoho CRM, app.zohoCrm) |
| Kategori | CRM |
| Kimlik doğrulama | Zoho ile oturum açma (OAuth 2.0, çoklu veri merkezi) |
| Kapsam | Organizasyon bazlı (bir bağlantı = bir Zoho CRM organizasyonu) |
| Webhook | Hayır |
| Kullanan kutular | CRM'e yaz (leads.crmSync), Zoho CRM (app.zohoCrm) |
| İşlemler | Lead oluştur, Not ekle, Kayıt ara |
Ne işe yarar?#
CRM'e yaz (aday senkronu)#
- Hedef boş veya
Leads → Leads modülü; Contacts → Contacts modülü.
- Zoho'nun upsert işlemi kullanılır (
duplicate_check_fields: Email): aynı e-postalı kayıt varsa güncellenir, yoksa eklenir. E-postası olmayan aday aktarılmaz.
- Yeni kayıtta Zoho zorunlu alan eksik derse (
MANDATORY_NOT_FOUND) bir kez daha denenir: Last_Name e-postanın @ öncesiyle, Leads'te Company [not provided] ile doldurulur. Mevcut kayıt güncellenirken bu varsayılanlar asla yazılmaz.
| OrqLabs alanı | Zoho alanı (Leads) |
|---|
email | Email |
firstName, lastName (veya name → bölünür) | First_Name, Last_Name |
company | Company |
phone, mobile | Phone, Mobile |
title / jobTitle | Designation (Contacts'ta Title) |
website, city, country, industry | Website, City, Country, Industry |
source / leadSource | Lead_Source |
status | Lead_Status |
description / notes | Description |
Büyük harfle başlayan anahtarlar API adı olarak aynen gönderilir (Annual_Revenue, Ozel_Alan). Field mapping ile kendi eşlemenizi yazabilirsiniz.
Zoho CRM kutusu#
| İşlem | Açıklama |
|---|
| Lead oluştur | Leads modülüne yeni kayıt (e-posta, ad, soyad, şirket, telefon, unvan, web sitesi, kaynak, açıklama + Ek alanlar JSON) |
| Not ekle | Leads, Contacts, Accounts veya Deals kaydına not; kayıt ID verilmezse Lead/Contact e-postayla bulunur |
| Kayıt ara | E-posta, telefon, kelime veya Zoho ölçütü ((Lead_Status:equals:Contacted)) ile arama; en fazla 200 kayıt |
Ön koşullar#
- API erişimi olan bir Zoho CRM sürümü (günlük API kredisi sürüme ve kullanıcı sayısına göre değişir).
- Bağlanan kullanıcının Leads / Contacts modüllerinde okuma-yazma yetkisi.
Adım adım kurulum#
A) OrqLabs'ta bağlama#
- Entegrasyonlar → Zoho CRM → Bağla.
- Zoho hesabınızla oturum açın → izinleri onaylayın (Accept).
- Zoho, OrqLabs'a hesabınızın veri merkezini bildirir (
accounts-server, location); sonraki tüm çağrılar o merkeze gider.
- Kart Zoho CRM – Şirket Adı adıyla görünür. Bağlantıyı test et ile organizasyonu doğrulayın.
- İş akışında CRM'e yaz kutusunu ekleyin → Bağlı hesap: Zoho CRM → Target: boş (Leads) veya
Contacts.
Bu adımlar OrqLabs'ı işleten taraf tarafından bir kez yapılır.
- api-console.zoho.com → Add Client → Server-based Applications.
- Client Name:
OrqLabs, Homepage URL: https://orqlabs.com, Authorized Redirect URIs: https://api.orqlabs.com/api/v1/integrations/oauth/zoho_crm/callback → Create.
- Client ID →
ZOHO_CLIENT_ID, Client Secret → ZOHO_CLIENT_SECRET.
- Settings → Multi-DC: istemciyi kullanacağınız tüm veri merkezlerini açın (US, EU, IN, AU, CN, JP, CA, SA, UK) ve tüm veri merkezlerinde aynı client secret seçeneğini kullanın. OrqLabs tek bir
ZOHO_CLIENT_SECRET saklar; merkez başına farklı gizli anahtar desteklenmez.
- Kapsamlar istek anında gönderilir; konsolda ayrıca seçmeniz gerekmez:
ZohoCRM.modules.ALL, ZohoCRM.settings.fields.READ, ZohoCRM.org.READ.
- API sunucusunu iki ortam değişkeniyle yeniden başlatın.
Güvenlik#
- Kod değişimi ve yenileme istekleri yalnızca Zoho'nun kendi hesap sunucularına (
accounts.zoho.com, .eu, .in, .com.au, .com.cn, .jp, .sa, .uk, accounts.zohocloud.ca) gönderilir; geri dönüşte farklı bir adres gelirse bağlantı reddedilir ve gizli anahtar hiçbir yere gönderilmez.
- API çağrıları yalnızca Zoho'nun
www.zohoapis.* alan adlarına yapılır.
İzinler ve kapsamlar#
| Kapsam | Neden gerekli |
|---|
ZohoCRM.modules.ALL | Leads / Contacts kayıtları, notlar, arama |
ZohoCRM.settings.fields.READ | Modül alanlarının okunması |
ZohoCRM.org.READ | Organizasyon adı ve kimliği (kartta görünen hesap) |
Sık karşılaşılan hatalar#
| Hata | Olası neden | Çözüm |
|---|
invalid_client (bağlanırken) | Hesabınızın veri merkezi istemcide açık değil | Platform yöneticisi Multi-DC ayarında merkezi açmalı |
FORBIDDEN – OAUTH_SCOPE_MISMATCH | Bağlantı eski kapsamlarla yapılmış | Yeniden yetkilendir |
AUTH – INVALID_TOKEN | Yenileme anahtarı iptal edildi | Yeniden yetkilendir |
INVALID – MANDATORY_NOT_FOUND [alan] | Organizasyona özel zorunlu alan boş | Field mapping veya Ek alanlar ile doldurun |
INVALID – DUPLICATE_DATA | Benzersiz alan başka kayıtta kullanılıyor | Mevcut kaydı güncelleyin veya alanı değiştirin |
RATE_LIMIT – TOO_MANY_REQUESTS | Günlük API kredisi doldu | Akış sıklığını azaltın |
Sonraki adım#