Scoutello API
Scoutello API, bir kuruluşun kişilerini, görevlerini, protokollerini, fırsatlarını, projelerini, kilometre taşlarını ve etkinliklerini iki yönlü olarak senkronize etmek için kullanılan sunucudan sunucuya bir API'dir. Ayrıca salt okunur giden e-posta geçmişi, atanabilir üye araması ve varlık türüne göre etiket keşfi sunar. Artımlı GET/list rotaları ve idempotent toplu upsert işlemleri, bu sürümdeki senkronizasyonun temel yapı taşlarıdır. Silme işlemleri veya web kancaları sunulmaz.
API temel URL'si:
https://admin.scoutello.com/api/v1
Bu URL, Organization settings → Developer/API bölümünde de gösterilir. OpenAPI belgesine şu adresten erişilebilir:
https://admin.scoutello.com/api/v1/openapi.json
Anahtar oluşturma ve koruma
Modüler kuruluşlarda, anahtarın gerekli kapsamlarına ek olarak CRM modülünün etkin olması gerekir. Geçerli bir anahtar, eksik bir modülü etkinleştiremez. CRM erişimi kullanılamadığında istekler, module_not_active hata koduyla HTTP 403 döndürür. Kuruluş yönetimi, CRM'yi Subscription bölümünden inceleyebilir veya etkinleştirebilir; erişim etkinleştirildikten sonra yeniden deneyin.
Kuruluş yönetimi, Organization settings → Developer/API bölümünden bir entegrasyon ve API anahtarı oluşturabilir. Anahtarın tamamı yalnızca bir kez gösterilir. İletişim kutusunu kapatmadan önce anahtarı bir gizli bilgi yöneticisine kopyalayın; Scoutello anahtarın tamamını tekrar gösteremez.
- Her harici sistem ve ortam için ayrı bir entegrasyon ve anahtar kullanın.
- Yalnızca ilgili sistemin ihtiyaç duyduğu kapsamları verin.
- Anahtarı hiçbir zaman tarayıcı koduna, URL'ye, kaynak denetimine, günlük kayıtlarına, destek mesajlarına veya istemci tarafı depolamaya koymayın.
- Anahtarları belirli aralıklarla yenileyin. Etkin bir entegrasyon yenilendiğinde yeni anahtar hemen çalışır; önceki anahtar, harici sistemin kesinti olmadan geçiş yapabilmesi için en fazla 15 dakika daha geçerli kalır. Daha önce belirlenmiş bir sona erme tarihi varsa bu tarih geçerliliğini korur; dolayısıyla önceki anahtar daha erken çalışmayı durdurabilir.
- Bir anahtarın açığa çıkmış olabileceğini düşünüyorsanız yenilemeden önce entegrasyonu duraklatın. Duraklatma, entegrasyonun tüm anahtarlarını geçici olarak reddeder. Duraklatılmış durumdayken yapılan yenilemede örtüşme olmaz: önceki anahtar devre dışı kalır, yeni anahtar ise entegrasyon yeniden başlatılana kadar devre dışı kalır.
- Harici bir sistemin bağlantısını keserken entegrasyonun tamamını kalıcı olarak iptal edin. İptal işlemi entegrasyona ait tüm anahtarları devre dışı bırakır ve geri alınamaz.
Kimliği doğrulanan her istekte anahtarı gönderin:
Authorization: Bearer YOUR_API_KEY
Bearer kimlik doğrulaması tercih edilir. Authorization ayarlayamayan istemciler bunun yerine x-api-key kullanabilir. Her iki üst bilgiyi birlikte göndermeyin; her iki üst bilgide farklı değerler bulunan istekler reddedilir.
API, arka uç istemcileri için tasarlanmıştır ve farklı kaynaklardan tarayıcı erişimini etkinleştirmez.
Bir anahtarı yapılandırdıktan sonra entegrasyonu, kuruluşu, kapsamları ve anahtar sınırlarını doğrulamak için GET /whoami kullanın; kullanıcıların kişisel verileri alınmaz.
Kapsamlar
| Kapsam | İzin verilenler |
|---|---|
contacts.read | Kişileri listeleme ve alma. Kuruluş hesabı ve erişim yetkisine sahip üye kişileri hariç tutulur. |
contacts.write | Kişi ekleme veya güncelleme işlemlerini doğrulama ve uygulama. |
tasks.read | Özel olmayan görevleri listeleme ve alma. |
tasks.write | Görev ekleme veya güncelleme işlemlerini doğrulama ve uygulama. |
protocols.read | Özel olmayan protokolleri listeleme ve alma. |
protocols.write | Protokol ekleme veya güncelleme işlemlerini doğrulama ve uygulama. |
opportunities.read | Fırsatları listeleme ve alma. |
opportunities.write | Fırsat ekleme veya güncelleme işlemlerini doğrulama ve uygulama. |
projects.read | Projeleri listeleme ve alma. |
projects.write | Proje ve katılımcı ekleme veya güncelleme işlemlerini doğrulama ve uygulama. |
milestones.read | Proje kilometre taşlarını listeleme ve alma. |
milestones.write | Kilometre taşı ekleme veya güncelleme işlemlerini doğrulama ve uygulama. |
members.read | Kabul edilmiş üyeleri yalnızca üye Customer ID'si, User ID'si ve görünen adıyla listeleme. |
events.read | Etkinlikleri ve temel takvimleri listeleme ve alma. |
events.write | Etkinlik ekleme veya güncelleme işlemlerini doğrulama ve uygulama. |
mails.read | Kuruluşa ait gönderilmiş ve başarısız giden e-postaların geçmişini okuma. |
mail-drafts.read | Bu entegrasyonun bağımsız e-posta onay taslaklarını ve teslimat durumunu okuma. |
mail-drafts.write | İnsan onayı için e-posta taslakları hazırlama veya düzeltme; hiçbir zaman onaylama ya da gönderme. |
tags.read | Desteklenen varlık türleri için seçilebilir etiketleri keşfetme. |
Özel görevler ve protokoller bu API tarafından hiçbir zaman döndürülmez. Eksik kapsam, yetkilendirme hatası döndürür; boş sonuç olarak değerlendirilmez.
Üye olmayan bir CRM kişisi, bir Scoutello oturum açma hesabına bağlı olsa bile okunabilir ve referans gösterilebilir. Yanıt yalnızca kuruluşun CRM alanlarını içerir; User kimliği veya erişim alanlarını kesinlikle içermez. Rolü, izinleri, daveti, kabul durumu veya kuruluş hesabı durumu olan kişiler gizli kalır. Oturum açma hesabına bağlı bir kişiyi düzenlemek yasaktır (protected_contact); başka hiçbir alan değişmese bile bu yasak, CRM alanları için de geçerlidir. Görevden ya da protokolden mevcut ve okunabilir bir kişiye referans vermek için contacts.write, yalnızca externalId, scoutelloId ve isteğe bağlı externalUpdatedAt ile harici bağlantısını oluşturabilir. Bağlantı meta verilerine yönelik sonraki güncellemelerde externalId ve isteğe bağlı externalUpdatedAt kullanılır; bağlantı kurulduktan sonra başlangıç scoutelloId alanı çıkarılır. Bu işlem kişiyi veya User'ı hiçbir zaman değiştirmez. Kabul edilmiş üye ataması ayrı members.read görünümü kullanılarak yapılır.
Yeni anahtarlar sctl_api_ önekini kullanır ve yalnızca contacts.write ile başlar. Diğer tüm kapsamlar, anahtar oluşturulurken veya döndürülürken kuruluş yöneticisinin açıkça vermesi gereken izinlerdir. Mevcut kimlik bilgileri geçerli kapsamlarını korur ve geçerliliklerini sürdürür.
Projeye bağlı kişiler ve e-posta taslakları
Kişi upsert işlemleri, isteğe bağlı projectScoutelloId / projectExternalId ve companyScoutelloId / companyExternalId çiftlerini kabul eder (her çiftten birini seçin). Kişi, şirket ilişkisi ve proje üyeliği her öğe için atomik olarak kaydedilir. Proje üyeliği eklemek için projects.write gerekir; belirtilmeyen referanslar diğer ilişkileri ve üyelikleri korur. Kişi ayrıntılarının okunması, projects.read verildiğinde projectParticipations bilgisini içerir. Satış projesi aracıları, bir kişiyi yeniden kullansalar bile proje referansını açıkça eklemelidir.
Bağımsız taslaklar, iş akışı çalıştırılmadan mevcut insan onayı sistemini kullanır:
| Yöntem | Yol | Amaç |
|---|---|---|
| GET | /mail-drafts | Entegrasyonun sahip olduğu sayfalandırılmış taslaklar; isteğe bağlı projectScoutelloId ve status filtreleri. |
| GET | /mail-drafts/{scoutelloId} | Geçerli sürüm, inceleme bağlantısı, içerik karması, onay/gönderim durumu ve nihai e-posta kimliği. |
| GET | /mail-drafts/external/{externalId} | Kararlı bir entegrasyon harici kimliğini arama. |
| POST | /mail-drafts/batch-upsert | Taslak hazırlığını doğrulama veya uygulama. |
Taslak hazırlığı için mail-drafts.write, contacts.read ve projects.write gerekir. Referans verilen kişi proje katılımcısı olur. Onaylayan kişi, e-posta düzenleme iznine sahip, kabul edilmiş bir kuruluş üyesi olmalıdır. Gönderen seçimi, bu üyenin izin verilen mevcut kuruluş veya kişisel gönderen ayarlarını kullanır; rastgele From adresleri kabul edilmez.
{
"mode": "validate",
"records": [{
"externalId": "sales:indoor:outreach:museum:v1",
"expectedVersion": 0,
"project": { "externalId": "sales:indoor" },
"contact": { "externalId": "sales:indoor:museum:person" },
"approverScoutelloUserId": "ACCEPTED_MEMBER_USER_ID",
"senderScope": "organization",
"content": {
"to": ["verified-recipient@example.com"],
"subject": "Indoor tour proposal",
"body": "The intended email copy only.",
"notes": "Internal research and review context; not sent."
}
}]
}
mode: "apply" ile yeniden göndermeden önce her doğrulama sonucunu inceleyin. Dönen kimliği okuyarak reviewUrl, draftVersion, contentHash, status, dispatchStatus ve mailScoutelloId bilgilerini alın. expectedVersion: 0 yalnızca oluşturma işlemi için, revizyonlarda ise dönen geçerli sürümü kullanın. Bağlam ve onaylayan kişi değiştirilemez; incelenmiş/gönderilmiş taslaklar, içeriği değiştirilmiş istekleri reddeder. Aynı isteklerin tekrarlanması özgün taslağı döndürür.
Taslaklar, proje/kişi E-posta sekmelerinde ve kontrol panelindeki onay bildirimlerinde görünür. API hazırlığı, bildirim e-postaları da dâhil olmak üzere hiçbir e-posta göndermez; mevcut iş akışı bildirim e-postası davranışı değişmez. Atanan kişi alıcıları, konuyu, gövdeyi ve desteklenen ekleri düzenleyebilir, sürümü kaydedebilir ve ardından Onayla ve gönder seçeneğini kullanabilir. Entegrasyonlar onaylama veya gönderim işlemi gerçekleştiremez. Başarısız ya da belirsiz gönderimler hiçbir zaman körlemesine yeniden denenmez. Protokol tabanlı taslakları dönüştürürken protokolleri koruyun ve bunların yerine geçen kaynaklara çapraz referans verin.
MCP erişimi
Aynı Scoutello API anahtarı ve kapsamları, akış özellikli HTTP MCP uç noktasıyla kullanılabilir:
https://admin.scoutello.com/api/v1/mcp
MCP istemcisini Authorization: Bearer YOUR_API_KEY gönderecek şekilde yapılandırın. Eski /api/mcp URL'si yol uyumluluğu takma adı olarak kullanılmaya devam eder, ancak yeni istemciler sürümlendirilmiş uç noktayı kullanmalıdır. Önceki sctl_mcp_ kimlik bilgileri kabul edilmez; bunların yerine bir Scoutello API entegrasyon anahtarı kullanın.
MCP araçları doğrudan REST sözleşmesine eşlenir ve aynı çalışma zamanı şemalarını, kiracı denetimlerini, entegrasyon yaşam döngüsünü, hız sınırını ve hizmet yöntemlerini kullanır. Örneğin contacts_list, contacts_get, contacts_get_by_external_id ve contacts_batch_upsert dört kişi rotasını yansıtır. Aynı düzen görevler, protokoller, fırsatlar, projeler, kilometre taşları ve etkinlikler için de geçerlidir; posta mails_list ve mails_get araçlarını, üyeler members_list aracını, etiketler ise tags_list aracını sunar.
Sunucu yalnızca geçerli anahtarın kapsamlarının izin verdiği araçları duyurur. contacts.read kapsamına sahip bir anahtar, kişi okuma araçlarını keşfedebilir ancak contacts_batch_upsert aracını keşfedemez; contacts.write kapsamına sahip bir anahtar toplu güncelleme aracına erişebilir ancak okuma araçlarına erişemez. whoami her zaman kullanılabilir. Yazma araçları, REST eşdeğerleriyle aynı anlık etkilere sahiptir; bu nedenle bir çağrının toplu işlemi uygulamadan önce incelemesi gerektiğinde mode: "validate" kullanın.
MCP ayrıca sunucudan sunucuya çalışır ve kaynaklar arası tarayıcı erişimini etkinleştirmez. JSON-RPC aktarımı özel bir URL gerektirir; bu nedenle kimlik doğrulama ve veri davranışı ortak olsa da tek bir REST kaynak URL'sini paylaşamaz.
Eksiksiz istemci yapılandırması, doğrulama, araç eşlemesi ve sorun giderme talimatları için MCP entegrasyon kılavuzuna bakın.
Kayıtları okuma
Kişiler, görevler, protokoller, fırsatlar, projeler, kilometre taşları ve etkinlikler aynı okuma rotalarını kullanır:
GET /contacts?limit=50&updatedSince=2026-09-01T00:00:00.000Z
GET /contacts/{scoutelloId}
GET /contacts/external/{externalId}
Diğer senkronizasyon kaynakları için contacts ifadesini tasks, protocols, opportunities, projects, milestones veya events ile değiştirin. Kayıt bu entegrasyon tarafından bağlandığında externalId bir okuma DTO'sunda görünür.
Bir liste yanıtı şu kapsayıcı yapıya sahiptir:
{
"data": [],
"page": {
"nextCursor": null,
"hasMore": false,
"snapshotAt": "2026-09-01T12:00:00.000Z"
},
"requestId": "request-id"
}
limit 1 ile 100 arasında olmalıdır. Sonuçlar, herkese açık API gösteriminin değiştiği etkin zamana, ardından Scoutello ID'sine göre sıralanır. Entegrasyon bağlantısı meta verileri değiştiğinde bu etkin zaman, döndürülen varlığın updatedAt değerinden daha sonraki bir zaman olabilir. İmleçler opaktır: olduğu gibi saklayıp gönderin ve içeriklerinden anlam çıkarmayın.
İlk yanıt, bu geçiş için snapshotAt değerini sabitler. Başka bir artımlı okuma başlatmadan önce nextCursor değerini, hasMore false olana kadar takip edin. Bu, sayfalama sırasında değişen kayıtların mevcut geçişi istikrarsız hâle getirmesini önler.
Artımlı senkronizasyon için her imleç sayfasını tüketin ve ardından bu geçişin snapshotAt değerini üst sınır zaman damgası olarak kaydedin. Sonraki geçişte bu değeri ISO 8601 biçimindeki updatedSince değeri olarak gönderin. Alt sınır kapsayıcıdır; bu nedenle tamamlanmış bir anlık görüntünün yeniden denenmesi sınırdaki kayıtları döndürebilir, ancak bu kayıtların atlanmasına yol açmaz.
Tek kayıt yanıtı şu kapsayıcı yapıya sahiptir:
{
"data": {},
"requestId": "request-id"
}
Tek kişi yanıtları ayrıca bir relations dizisi içerir. Her ilişki, Scoutello ilişki kimliğini, oluşturulma zamanını, türü, notları ve connectedFrom ile
connectedTo kişi referanslarını korur. Kişi referansları, mevcut olduğunda Scoutello ID'sini ve bu entegrasyondaki harici ID'yi içerir. API'nin kuruluş erişimi gizlilik sınırı dışında bırakılan kişiler ilişkiler üzerinden gösterilmez.
Kişi listesi yanıtı daha kısa tutulur ve ilişkileri içermez; ilişki ayrıntıları gerektiğinde tek kişi rotalarından birini kullanın.
İş filtreleri ve imleç kapsamı
Kişi listeleri search, type (person, company, supplier, other), status ve tagIds değerlerini kabul eder. Arama metni kırpılır, büyük/küçük harfe duyarsızdır ve 200 karakter / boşlukla ayrılmış 10 belirteçle sınırlıdır. Her belirteç firstName, lastName veya companyName değerlerinden en az birinde bulunmalıdır; buna lastName içinde saklanan eski şirket adları da dahildir. % ve _ gibi karakterler olduğu gibi eşleştirilir. Etiketlerde herhangi biri eşleştirmesi kullanılır ve 1–50 ID kabul edilir. Sağlanan tüm filtreler AND ile birleştirilir. REST, etiket ID'lerini yinelenen parametreler olarak kodlar; MCP ise bir dizi sağlar:
GET /contacts?search=Hamburg%20Hotel&type=company&status=prospect&tagIds=tag-one&tagIds=tag-two
Kişi imleçleri kuruluş, entegrasyon ve tüm filtrelere bağlıdır. Her sayfada filtreleri koruyun; filtre değiştirilirse imleç reddedilir. Etiket sırası/yinelemeleri ile arama belirteçlerinin sırası, büyük/küçük harf kullanımı ve boşlukları etkin filtreyi değiştirmez.
İş listesi rotaları aşağıdaki ek filtreleri kabul eder; diğer kaynak/alan kombinasyonları reddedilir:
| Kaynak | Filtreler |
|---|---|
| Görevler | projectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter |
| Protokoller | projectScoutelloId, milestoneScoutelloId, status (draft veya final) |
| Fırsatlar | projectScoutelloId, stage, ownerScoutelloUserId |
| Projeler | status, assignedContactScoutelloId |
| Kilometre taşları | projectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter |
dueBefore hariçtir; dueAfter dahildir. Görevin son tarihini veya kilometre taşının bitiş tarihini karşılaştırırlar; bu tarihe sahip olmayan kayıtlarla eşleşmezler. Zaman dilimi içeren ISO tarih-saatleri gönderin. Tüm filtreler sayfalandırmadan önce uygulanır. Bir imleci tam olarak aynı filtrelerle (updatedSince dâhil) ve aynı kuruluş/entegrasyonla devam ettirin. Sayfa boyutu değişebilir. Kapsamlandırılmamış eski imleçler, bu sürümden sonra kaydedilmiş en son zaman damgasından yeniden başlatılmalıdır.
Projeler, kilometre taşları, atamalar ve notlar
GET /members (MCP members_list) standart sayfalandırmayı kullanır ve members.read gerektirir. scoutelloId (üye Customer kimliği), scoutelloUserId (User kimliği) ve displayName döndürür. Yalnızca rolü bulunan, kabul edilmiş kuruluş üyeleri görünür; arama e-posta adreslerini veya izinleri açığa çıkarmaz.
Görevler assignedScoutelloUserIds kabul eder; fırsatlar ownerScoutelloUserId kullanır. Projeler ve kilometre taşları assignedContacts: [{"scoutelloId":"member-customer-id"}] kullanır. Atamalar, kimlik bilgilerinin kuruluşundaki kabul edilmiş üyeleri gerektirir. Atamaların gönderilmemesi mevcut atamaları değiştirmez; [] bunları temizler. Proje, kilometre taşı, görev ve protokol içe aktarımları sessizdir: atama bildirimleri veya iletişimleri göndermezler.
assignedContacts olayı, okunabilir CRM kişilerini ve üye Customer kimliğiyle sağlanan kabul edilmiş üyeleri destekler. Kabul edilmiş üyeler, normal CRM kişi referansları veya harici bağlantı hedefleri olarak kullanılamaz; ekip sorumluluğu için üye atama alanını kullanın.
name ve projectScoutelloId ya da projectExternalId ile kilometre taşları oluşturun. Bunlar description (Markdown), status (open, in_progress, completed, closed), nullable startDate/endDate, varsayılan değeri 0 olan order ve assignedContacts özelliklerini destekler. Bitiş tarihleri başlangıç tarihlerinden önce olamaz. Her kilometre taşının entegrasyon kapsamında sabit bir harici bağlantısı vardır. Projesi API üzerinden değiştirilemez. Oluşturma ve güncelleme işlemleri, ad ile açıklamayı kuruluşun diline yerelleştirir.
Görevler ve protokoller, proje, kilometre taşı ve fırsat referanslarını <entity>ScoutelloId veya <entity>ExternalId olarak kabul eder; örneğin milestoneExternalId. null ile temizleme işlemi de dahil olmak üzere her ilişki için yalnızca bir yazım biçimi kullanın. Tüm ilişkiler kimlik bilgilerinin kuruluşuna ait olmalıdır. Yalnızca kilometre taşı referansı verilmesi projeyi belirler; çakışan bir proje veya kilometre taşı korunurken projenin açıkça temizlenmesi reddedilir. Projeye sahip bağlı bir fırsat, çalışmanın projesiyle eşleşmelidir. Belirtilmeyen ilişkiler mevcut değerleri korur; açıkça belirtilen null, kalan bağlam geçerliyse ilişkiyi temizler. Okuma işlemleri her iki kimlik yazım biçimini ve görev atamalarını gösterir.
Görev planlama ve iş akışları
Görev status, sabit bir enum değil, görevin geçerli iş akışındaki bir durumun değişmez anahtarıdır. tasks.read kapsamını kullanarak GET /task-workflows ile kullanılabilir kuruluş ve proje iş akışlarını okuyun. Her durum; anahtarını, etiketini, yaşam döngüsü type değerini (backlog, unstarted, started, completed veya cancelled), rengini, sırasını, varsayılan durum işaretini ve arşiv durumunu içerir. Proje girişleri, kuruluş iş akışının devralınıp devralınmadığını belirtir. İş akışı yapılandırması yönetim panelinden yönetilmeye devam eder.
Görevler nullable priority (low, medium, high veya urgent) ve estimatedEffortMinutes ile birlikte nullable startDate ve dueDate değerlerini kabul eder. Görev okumaları, normalleştirilmiş statusType değerini, üst görev referansını, kompakt alt görev referanslarını ve blockedBy / blocks referanslarını içerir.
Bir seviyeli bir alt görevi parentTaskScoutelloId veya parentTaskExternalId ile oluşturun ya da güncelleyin; null görevi üst düzey göreve dönüştürür. Bağımlılıklar, blockedBy ve blocks alanlarında { "scoutelloId": "..." } veya { "externalId": "..." } referans dizileri kullanır. İlişki alanlarının gönderilmemesi mevcut ilişkileri korur; boş bir bağımlılık dizisi ilgili yöndeki bağımlılıkları temizler. API; iç içe alt görevleri, üst görev-alt görev bağımlılıklarını, kuruluşlar arası bağımlılıkları, yinelenen kayıtları, kendine referansları ve doğrudan ya da geçişli döngüleri reddeder.
Görev listesi filtreleri tam eşleşen bir iş akışı status, yaşam döngüsü statusType, priority, parentState (top_level, subtask veya parent) ve blockedState (blocked, blocking veya unblocked) değerlerini kabul eder.
Protokoller ayrıca status: "draft" | "final" değerini kabul eder (yeni kayıtlar varsayılan olarak final değerini alır). Yeni bir protokol için type, date ve bir kişi ya da geçerli bir proje/dönüm noktası bağlamı gerekir. contactExternalId: null, kişi bilgilerini yalnızca proje/dönüm noktası bağlamı korunuyorsa temizler. Böylece dahili proje notları, müşteri uydurmaya gerek kalmadan oluşturulabilir ve okunabilir. Taslak/son durum, notun durumunu açıklar ve hiçbir zaman iletişim göndermez. Özel görevler ve protokoller erişilemez olmaya devam eder.
Proje katılımcıları
Proje participants, örneğin bir contact referansına göre anahtarlanan eklemeli güncellemeleri içerir:
{
"externalId": "gtm:hotels",
"participants": [{
"contact": {"scoutelloId": "prospect-contact-id"},
"role": "Potential pilot",
"notes": "Existing warm lead; qualify the next step.",
"groupScoutelloId": null
}]
}
Katılımcılar, bir projeyle ilişkili potansiyel müşterileri/müşterileri tanımlar; sorumlu ekip üyeleri atamalarla belirtilir. Katılımcıların gönderilmemesi, boş bir dizi gönderilmesi ve katılımcı alanlarının gönderilmemesi mevcut verileri korur. null, role, notes veya groupScoutelloId alanlarını temizler. Tek bir yükte çözümlenen kişilerin yinelenen kayıtları reddedilir. Gruplar önceden seçilen projeye ait olmalıdır; okuma sonuçlarında participantGroups (kimlik/ad) ile katılımcı kimlikleri, kişiler, rol, notlar ve grup kimliği yer alır. Katılımcıları kaldırma veya grup oluşturma işlemleri şu anda kontrol panelinden kullanılabilir.
Kayıtları toplu güncelleme
Kaynağın toplu rotasını kullanarak en fazla 100 kayıt yazın:
POST /contacts/batch-upsert
Content-Type: application/json
{
"mode": "apply",
"records": [
{
"externalId": "record-123",
"externalUpdatedAt": "2026-09-01T11:45:00.000Z",
"type": "person",
"firstName": "Alex",
"lastName": "Example",
"email": "alex@example.com"
}
]
}
Görev toplu işlemleri, üst görev ve bağımlılık ilişkilerini uygulamadan önce görev kayıtlarını çözümler. Bu iki aşamalı işlem sayesinde bir üst görev, engelleyici veya engellenen görev; kayıt sırasından bağımsız olarak aynı toplu işlemde oluşturulan başka bir göreve harici kimliğiyle referans verebilir.
Her kaynağın alanları ve doğrulama kısıtları için OpenAPI belgesini kullanın. Her kaydın 1 ile 200 karakter arasında, kararlı bir externalId değeri olmalıdır. Bu değeri opak bir teknik tanımlayıcı olarak değerlendirin: e-posta adresi, ad, API gizli anahtarı veya başka kişisel veriler kullanmayın. externalUpdatedAt isteğe bağlıdır, ancak kaynak sistem güvenilir bir değişiklik zaman damgası sağlıyorsa kullanılması önemle önerilir.
İstek gövtesi 1 MiB ile sınırlıdır. mode varsayılan olarak apply değerini kullanır:
applykabul edilen kayıtları doğrular ve yazar.validateyazma işlemi gerçekleştirmeden aynı doğrulama ve eşleştirmeyi yapar vewould_*sonuçlarını döndürür.
Kişi içe aktarımları için matchByEmail istekte true olarak ayarlanabilir. Varsayılan değer false şeklindedir; harici kimlik daha güvenli varsayılan kimlik sınırıdır.
Atlanan alanlar mevcut değeri korur. Açıkça belirtilen bir null, null değer alabilen bir alanı temizler; sağlanan boş atama/etiket dizisi ise ilgili ilişkiyi temizler. Proje participants, eklemeli upsert işlemleridir: boş dizi kadroyu değiştirmez. Kişi, görev, fırsat ve etkinlik etiket yazma işlemlerinde Scoutello etiket kimlikleri kullanılır. İlişki harici kimlikleri yalnızca mevcut entegrasyona ait bağlantılar üzerinden çözümlenir; sahiplik veya sorumluluk için kullanılan Scoutello kullanıcı kimlikleri, mevcut kuruluşun kabul edilmiş üyelerini belirtmelidir.
Fırsat oluşturma işlemleri bir hesap veya kişi gerektirir; kaybedilen fırsatlar için kayıp nedeni de zorunludur. Parasal tutarlar tam sayı sent cinsinden kullanılır. Proje ve etkinlik adları ile açıklamaları kuruluşun yapılandırılmış dilinde okunur ve yazılır. Etkinlik yazma işlemleri açık tarihleri ve hariç tutmalar içeren günlük, haftalık veya aylık yinelenmeyi destekler; yayımlanan görünürlük katmanları Scoutello'nun yasal hazırlık kontrollerine tabi olmaya devam eder. API; etkinlik bileti satışı, katılımcılar, medya, şablonlar, bültenler, iş birlikleri veya diğer gelişmiş etkinlik yönetimi denetimlerini sunmaz.
Etiketleri keşfet
tagIds değerini sağlamadan önce etiketler uç noktasını kullanın:
GET /tags?entity=events&type=category
entity zorunludur ve contacts, tasks, opportunities veya events değerlerini kabul eder. Bu değer, karşılık gelen kayıtlı etiket ilgi düzeyine eşlenir. type isteğe bağlıdır ve category veya attribute değerlerini kabul eder. Seçilebilir kategoriler kuruluşa ait veya genel olabilir; seçilebilir özellikler Scoutello'nun özenle düzenlenmiş genel özellik kümesinden gelir. Sonuçlar, kuruluş diline yerelleştirilmiş adı belirten scoutelloId, type ve relevancy değerlerini içerir. Kuruluşlar arası, yanlış ilgi düzeyine sahip veya seçilebilir olmayan etiket kimlikleri, ilgili toplu işlem öğesinin reddedilmesine neden olur.
Giden e-posta geçmişini okuma
Posta geçmişi salt okunurdur:
GET /mails?updatedSince=2026-09-01T00:00:00.000Z
GET /mails/{scoutelloId}
Yalnızca kuruluşa ait ve sent veya failed durumundaki postalar döndürülür. Yanıtlar; yaygın olarak saklanan üst bilgileri ve gövdeyi, BCC'yi, durumu ve zaman damgalarını, proje/etkinlik/bülten referanslarını, ek kimliklerini ve türlerini, ayrıca alıcıların teslim edilme/açılma/tıklanma/geri dönme/şikâyet/reddedilme istatistiklerinin toplamlarını içerir. Taslaklar, kuyruğa alınmış veya planlanmış postalar, alıcı bazındaki satırlar, oluşturulmuş anlık görüntüler, sağlayıcıdan gelen ham hatalar ve ek indirme URL'leri hiçbir zaman sunulmaz. Daha sonraki bir alıcı teslimat güncellemesi, postanın etkin senkronizasyon zaman damgasını ileri alır; böylece posta artımlı okumalarda yeniden görünür. Posta yazma rotaları yoktur.
Bir uygulama sonucu created, updated, linked, unchanged, stale_ignored veya rejected olabilir. Doğrulamada would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale veya rejected kullanılır. Geçerli bir toplu istek, tek tek kayıtlar reddedilse bile HTTP 200 döndürür; bu nedenle her öğeyi ve yanıt özetini mutlaka inceleyin. Bir hatanın incelenmesi için Scoutello desteğine başvururken yanıtı requestId olarak saklayın.
Zaman damgaları ve çakışmalar
externalUpdatedAt mevcut olduğunda Scoutello, toplu işlemin geri kalanını başarısız kılmadan eski değişiklikleri reddetmek için bunu kullanır. stale_ignored sonucu, daha eski yük için nihaidir; daha yeni bir sürüm göndermeye karar vermeden önce güncel kaydı alın.
Zaman damgalarını UTC ISO 8601 değerleri olarak değerlendirin. Özgün hassasiyetlerini koruyun ve bir senkronizasyon işinin gerçekleştiği zamanı, kaynak kaydının değiştirilme zamanıyla değiştirmeyin.
İdempotensi
İdempotensi sınırı, entegrasyon ile externalId arasındadır. Scoutello, kanonik yük karmasını ve isteğe bağlı externalUpdatedAt değerini karşılaştırır; bu nedenle aynı kaydın yeniden denenmesi yinelenen kayıtlar oluşturmaz ve unchanged döndürebilir.
externalUpdatedAt ile aynı zaman damgası ve yük unchanged, daha eski bir zaman damgası stale_ignored olur; aynı zaman damgasının farklı bir yükle kullanılması ise sürüm çakışmasıdır. Daha önce hiç zaman damgası kabul etmemiş bir bağlantı için aynı zaman damgası olmayan yük unchanged olarak kalırken, değişen bir yük geliş sırasına göre uygulanır. Bir bağlantı zaman damgasını kabul ettikten sonra, externalUpdatedAt içermeyen değişmiş bir yük sürüm çakışması olarak reddedilir; böylece sürümlendirilmemiş veriler sürümlendirilmiş durumu geçersiz kılamaz. Kaynak değişiklik zaman damgalarının özellikle önerilmesinin nedeni budur.
Denetim kaydı
Kabul edilen API oluşturma, güncelleme ve yalnızca bağlantı kurmaya yönelik senkronizasyon işlemleri, Scoutello değişiklik günlüklerinde kaynak olarak Public API ile görünür ve sorumlu entegrasyonla ilişkilendirilir. Operasyonel çalıştırma özetlerinde sorun giderme amacıyla istek kimlikleri ve toplu sonuç sayıları saklanır; kayıt yükleri veya API gizli anahtarları saklanmaz.
Hatalar ve yeniden denemeler
İstek düzeyindeki hatalar şu kapsayıcıyı kullanır:
{
"error": {
"code": "error_code",
"message": "Safe error message",
"requestId": "request-id",
"details": {}
}
}
HTTP 429 ve geçici 5xx yanıtlarını üstel bekleme ve rastgelelik kullanarak yeniden deneyin. Mevcut olduğunda Retry-After değerine uyun. Ağ hataları, Scoutello bir isteği kabul ettikten sonra gerçekleşmiş olabilir; her kayıt harici kimlik ve kanonik yük üzerinden idempotent olduğundan aynı grubun yeniden gönderilmesi güvenlidir. İsteği değiştirmeden kimlik doğrulama, yetkilendirme, doğrulama, sürüm çakışması veya tekil rejected sonuçlarını otomatik olarak yeniden denemeyin.
Önerilen iki yönlü senkronizasyon döngüsü
- Kurulum sırasında
/whoamiçağrısını yapın ve beklenen kuruluşu ve kapsamları doğrulayın. - Son tamamlanan yüksek su işaretinden bu yana değişen her sayfayı okuyun ve bu değişiklikleri harici sisteme idempotent şekilde uygulayın.
- Harici değişiklikleri, kararlı harici kimlikler ve kaynak sistemdeki değişiklik zaman damgalarını kullanarak
/batch-upsertadresine gönderin. - Kontrol noktalarını yalnızca tüm sayfalar ve öğe sonuçları işlendiğinde kalıcı hâle getirin.
- Çakışmaları kaynak sistemin sahiplik kurallarına göre çözün; boş kayıtlar göndererek silme işlemlerini taklit etmeyin.
Scoutello, bu ilk sürümde kasıtlı olarak herkese açık bir silme rotası sunmaz. Belgelenmiş bir yaşam döngüsü işlemi kullanıma sunulana kadar silme veya arşivleme politikalarını API dışında yönetin.
İnsan incelemesi için sosyal medya gönderileri
Sosyal medya API'si, gönderileri adı belirtilen bir insan inceleyici için hazırlar. Bunları onaylayamaz veya yayımlayamaz. REST ve MCP aynı kapsamları ve hizmeti kullanır.
| Kapsam | /api/v1 altındaki uç noktalar |
|---|---|
social-channels.read | GET /social-channels |
social-posts.read | GET /social-posts, GET /social-posts/{scoutelloId} |
social-post-drafts.read | GET /social-post-drafts, GET /social-post-drafts/{scoutelloId}, GET /social-post-drafts/external/{externalId} |
social-post-drafts.write | POST /social-post-drafts/batch-upsert, POST /social-media/uploads, POST /social-media/uploads/{assetId}/finalize |
Yeni kapsamlar açıkça verilmelidir. Mevcut kimlik bilgileri ek erişim kazanmaz. Üye kullanıcı kimliklerini keşfetmek için members.read kullanın ve gönderme iznine sahip bir inceleyici seçin (newsletter.edit). Taslaklar için CRM kişisi veya proje gerekmez.
{
"mode": "apply",
"records": [{
"externalId": "campaign:autumn:launch",
"expectedVersion": 0,
"approverScoutelloUserId": "REVIEWER_USER_ID",
"content": {
"title": "Autumn launch",
"publishMode": "schedule",
"scheduledAt": "2026-10-01T09:00:00+02:00",
"variants": [{
"channelId": "CHANNEL_SCOUTELLO_ID",
"content": "Explore the autumn collection.",
"settings": {},
"mediaIds": ["FINALIZED_ASSET_ID"]
}]
}
}]
}
Onaylandığında yayımlamak için publishMode: "now" ve scheduledAt: null kullanın. Her kanal varyantı, metnin tamamını, ayarları ve sıralı medya kimliklerini içerir.
Kanal keşfi, desteklenen biçimleri, sınırları ve ayarları döndürür. Şu anda desteklenen kanallar LinkedIn profilleri/sayfaları, Facebook, Instagram ve Threads'tir.
Instagram medya gerektirir. Bir varyant en fazla on görsel veya video kabul eder.
Toplu işlemler, mevcut 1 MiB istek sınırı içinde en fazla 100 benzersiz harici kimlik kabul eder. mode: "validate", taslakları kaydetmeden, varlıkları yüklemeden, bildirim oluşturmadan veya iş kuyruğa eklemeden referansları ve sürümleri kontrol eder. Uygulama sonuçları kimlikleri, inceleme bağlantılarını, sürümleri ve kayıt bazında sonuçları içerir. Kısmi hatalar, başarıyla işlenen kardeş kayıtları geri almaz. Bildirim hatası, kaydedilen inceleme URL'sini içeren bir uyarı döndürür.
Bekleyen bir taslağı düzenlemeden önce güncel draftVersion öğesini alın. Aynı yeniden denemeler idempotenttir ve daha sonra yapılan insan düzenlemelerini korur. İnceleyenler yerinde değiştirilemez. Onay veya ret sonrasında başka bir teklif için yeni bir harici kimlik kullanın.
Taslak okumaları, çağrıyı yapan entegrasyonla sınırlıdır; gönderi geçmişi, kuruluşta Scoutello tarafından oluşturulup kalıcı olarak kaydedilen dashboard, script ve eski Scoutello gönderileri dâhil tüm kampanyaları kapsar. Harici kanal geçmişi içe aktarılmaz.
Listeler standart limit, cursor ve updatedSince parametrelerini kullanır. Gönderiler ve taslaklar ayrıca channelId, status, after, before ve search öğelerini kabul eder; sonraki imleç sayfalarında tüm filtreleri koruyun.
Tarih filtreleri yayımlama zamanına uygulanır (hemen bekleyen taslaklar için oluşturulma zamanına). Taslak status filtreleri onay durumuna göre uygular; gönderi status filtreleri kampanya veya kanal teslimat durumuyla eşleşir. Okumalarda son bilinen teslimat durumu, kanal bazındaki hatalar, herkese açık bağlantılar ve mutabakat zaman damgaları sunulur. Taslakların artımlı okumaları kampanya teslimatındaki değişiklikleri de yansıtır.
Medya yükleme
POST /social-media/uploadsöğesiniclientUploadId,filename,contentTypevesizeile birlikte bayt cinsinden ve orijinal baytların küçük harfli onaltılıksha256değeriyle çağırın. Desteklenen türler PNG, JPEG, WebP, MP4, WebM, QuickTime ve M4V'dir. Yükleme üst sınırı 500 MiB'dir.- Orijinal baytları, döndürülen
upload.urladresine HTTPPUTile, bu adresin başlıklarını kullanarak gönderin. Yükleme URL'leri 15 dakika sonra geçersiz olur. Aynı dosya için yapılan yeniden denemelerdeclientUploadIddeğerini yeniden kullanın; süresi dolmuş oturumlar veya farklı dosyalar için yeni bir kimlik gerekir. POST /social-media/uploads/{assetId}/finalizeöğesini{}JSON gövdesiyle çağırın. Sonlandırma işlemi boyutu, türü, imzayı ve sağlama toplamını kontrol eder, özel bir kopyayı sabitler vemediaIdsiçin varlık kimliğini döndürür. Sonlandırma işleminin tekrarlanması güvenlidir.
Yükleme sahipliği kuruluş ve entegrasyona bağlıdır. Taslaklar, kuruluşlarına ait sonlandırılmış varlıklara başvurabilir. Önizleme URL'leri geçicidir; bunları yenilemek için taslağı yeniden alın. Sonlandırılmış nesneler için hiçbir zaman yükleme URL'si verilmez.
İnsan incelemesi ve teslimat
İncelemeyi yapan kişi bir kontrol paneli bildirimi alır ve gönderiyi Postings üzerinden veya inceleme URL'siyle açabilir. Düzenleme, başka bir değiştirilemez sürüm oluşturur. Onaylama, görüntülenen sürümü ve içerik karmasını kullanır; üyeliği, kanalları ve varlıkları yeniden kontrol eder ve atomik olarak kalıcı bir kampanya oluşturur. Önerilen zaman geçtiyse incelemeyi yapan kişinin açıkça yeni bir zaman kaydetmesi veya onay sırasında yayınlamayı seçmesi gerekir.
Kuyruk yeniden denemelerinde kampanya ve platform makbuzları yeniden kullanılır. Onaylanan kampanyalar yerinde düzenlenemez. Kontrol paneli üzerinden iptal etmek, onay geçmişini ve medyayı korur; iptal işlemi etkin bir gönderimi kesintiye uğratamaz. Onayın gerçek platform teslimatından ayrımını yapmak için taslağı veya kampanyayı yoklayın.