Geliştiriciler

İK entegrasyonu: REST API, webhook ve MCP

Teamso'yu kullandığınız sistemlere bağlayın. İşe giriş, işten çıkış ve organizasyon değişiklikleri webhook ile anında gider; REST API ile veri okuyup yazarsınız; Teamso MCP ile yapay zekâ asistanları yetkiniz kadar işlem yapar.

{
  "eventId": "8f0c2a4e-...",
  "eventType": "EMPLOYEE_HIRED",
  "companyId": "...",
  "createdAt": "2026-11-02T09:30:00",
  "data": {
    "userId": "...",
    "fullName": "Ayşe Yılmaz",
    "email": "[email protected]",
    "branch": "Merkez",
    "department": "Finans",
    "position": "Uzman",
    "manager": "Mert Şahin",
    "hireDate": "2026-11-03T00:00:00",
    "customFields": {}
  }
}

X-Teamso-Event
X-Teamso-Delivery-Id
X-Teamso-Timestamp
X-Teamso-Signature

Örnek webhook gövdesi (standart biçim) ve istekle gelen başlıklar

Üç yol

Teamso'ya nasıl bağlanılır?

REST API

Teamso web ve mobil uygulamasının kullandığı API'yi kişisel erişim token'ıyla çağırın. Token, sahibinin güncel yetkileriyle çalışır.

Yetki rolden gelir; iptal edilen token bir sonraki istekte geçersizdir
Parola, oturum ve güvenlik ayarı uçları token'a kapalı
Şirketin IP kısıtı token'lı istekte de uygulanır

Webhook

Olay olduğunda Teamso sizin adresinize imzalı bir istek gönderir. Ulaşmazsa artan aralıklarla yeniden dener.

HMAC-SHA256 imza
Yeniden deneme: 1 dk, 5 dk, 30 dk, 2 sa, 6 sa
Standart JSON ya da şablonlu özel istek

Teamso MCP

Claude, Cursor ve MCP destekleyen diğer istemcilerden izin talebi, onay, rapor ve kılavuz araması.

Barındırılan adres ya da npm paketi
Yazma işlemleri önce önizleme ve onay ister
Kullanıcının kendi yetkisiyle çalışır

MCP dokümanı

Webhook olayları

Hangi olaylar gönderilir?

Abonelik oluştururken dinlemek istediğiniz olayları seçersiniz. Çalışan olayları şirket ayarlarından, PDKS olayları PDKS ayarlarından yönetilir.

Çalışan ve takdir olayları

Olay	Ne zaman gönderilir
`EMPLOYEE_HIRED`	Çalışan işe başladı (tekil kayıt, Excel ya da e-karşılama ile)
`EMPLOYEE_TERMINATED`	Çalışanın işten çıkışı kaydedildi
`EMPLOYEE_TERMINATION_CANCELLED`	İşten çıkış iptal edildi ya da çalışan yeniden işe alındı
`EMPLOYEE_ORG_UPDATED`	Şube, departman, pozisyon ya da yönetici değişti; güncel durum ve eski/yeni değerler birlikte gelir
`BADGE_AWARDED`	Rozet verildi (gizli rozette mesaj gönderilmez)

PDKS olayları

Olay	Ne zaman gönderilir
`attendance.created`	Giriş ya da çıkış kaydı oluştu
`anomaly.detected`	Anomali algılandı (ör. geç kalma, uzun mola)
`security.violation`	Güvenlik ihlali (ör. sahte konum)
`excuse.submitted`	Çalışan mazeret yazdı
`excuse.resolved`	Mazeret karara bağlandı
`qr.locked`	Geç kalan çalışan için QR kilitlendi

Olay adları üründeki adlarla birebirdir; yeni olay eklendiğinde bu tablo da güncellenir.

Geliştirici notu

İmzayı doğrulayın, aynı olayı iki kez işlemeyin

Her istek, aboneliğin gizli anahtarıyla ham gövdenin HMAC-SHA256 imzasını (onaltılık) X-Teamso-Signature başlığında taşır. Teslim en az bir kez yapılır: aynı X-Teamso-Delivery-Id ikinci kez gelirse yok sayın.

Kaydetmeden önce gönderilecek isteğin önizlemesi
Özel biçim: POST, PUT ya da GET; JSON ya da form gövdesi; şablonlu alanlar
Başarısız teslimler gönderim geçmişinde hata mesajıyla, tek tıkla yeniden gönderilir
Yönlendirmeler (3xx) izlenmez, kendinden imzalı sertifika kabul edilmez

import crypto from "node:crypto";

function verify(rawBody, headers, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  const received = headers["x-teamso-signature"] ?? "";
  return (
    received.length === expected.length &&
    crypto.timingSafeEqual(
      Buffer.from(received),
      Buffer.from(expected),
    )
  );
}

Node.js ile imza doğrulama (ham gövdeyle)

Güvenlik

Entegrasyon verisi kontrollü çıkar

Hedef adres denetimi

Webhook adresi kaydedilirken ve her gönderimde çözümlenir; sunucunun kendi ağına (yerel döngü, bağlantı yerel adresler, bulut üst veri ucu) istek gönderilemez. Şirket içi sistemlere VPN üzerinden özel ağ adresiyle ulaşılabilir.

Gizli anahtar ve maskeleme

Her aboneliğin kendi gizli anahtarı vardır; özel istekteki parola ve token gibi değerler şifreli saklanır, ekranda ve gönderim geçmişinde maskeli görünür.

Yetki ve kayıt

Abonelikleri yalnız yetkili kullanıcılar görür ve yönetir. Token'lı API istekleri sahibinin yetkisiyle sınırlıdır; token iptal edildiği an bir sonraki istek reddedilir.

Kullanım örnekleri

Entegrasyonla neler otomatikleşir?

Hesap açma ve kapatma

Çalışan işe başladığında e-posta, Active Directory ya da erişim kontrol sisteminde hesabı açılır; işten çıkışta hesap kapanır. Organizasyon değişikliği departman ve yönetici bilgisini günceller.

Muhasebe ve ERP

Yeni çalışan ve işten çıkış bilgisi muhasebe ya da ERP sistemine aktarılır; bordro sonuçları REST API ile okunur.

Turnike ve vardiya

PDKS giriş-çıkış olayları turnike ya da vardiya planlama sistemine akar; anomali ve güvenlik ihlali olayları ilgili ekibe bildirim olarak iletilir.

Teamso MCP ile yapay zekâ asistanları

Claude ya da Cursor'dan izin onayı, rapor ve kılavuz araması. Ayrıntılar yapay zekâ sayfasında.

Yapay zekâ ile İK MCP dokümanı

Çözüm ortakları

Kurulum ve entegrasyonda çözüm ortaklarımız

Teamso'yu müşterilerine kuran ve kendi sistemlerine bağlayan iş ortakları. Liste ve başvuru çözüm ortakları sayfasında.

Çözüm ortaklarımız

SSS

Entegrasyonlar hakkında sık sorulanlar

API'yi kullanmak için ayrı bir anahtar gerekir mi?

Teamso'da MCP erişimi sayfasından kişisel erişim token'ı oluşturursunuz. Token, sahibinin yetkileriyle çalışır ve istenirse süreli olur; bir kullanıcının aynı anda en çok 10 etkin token'ı olabilir. Parola, oturum ve güvenlik ayarlarıyla ilgili uçlar token'a kapalıdır.

Webhook'u kim tanımlayabilir?

Şirket ayarlarında webhook aboneliklerini görüntüleme ve yönetme yetkisi olan kullanıcılar. Abonelikte adres, dinlenecek olaylar ve gizli anahtar belirlenir; kaydetmeden önce test isteği gönderilebilir.

Hedef sistemim istek almazsa veri kaybolur mu?

Hayır. Teamso 1 dakika, 5 dakika, 30 dakika, 2 saat ve 6 saat aralıklarla yeniden dener; son denemeden sonra teslim başarısız olarak işaretlenir ve gönderim geçmişinden tek tıkla yeniden gönderilir.

Hedef sistemim kendi biçimini istiyorsa?

Özel istek modunda HTTP yöntemini (POST, PUT, GET), gövde biçimini (JSON ya da form) ve alanları şablonla belirlersiniz; ad, soyad, e-posta, şube gibi değişkenler filtrelerle dönüştürülebilir. Gizli değerler şifreli saklanır ve maskeli gösterilir.

İmza nasıl doğrulanır?

Aboneliğin gizli anahtarıyla, isteğin ham gövdesinin HMAC-SHA256 imzasını onaltılık olarak hesaplayın ve X-Teamso-Signature başlığıyla sabit süreli karşılaştırın. Gövdeyi ayrıştırıp yeniden yazmayın; imza ham gövde üzerindedir.

Entegrasyonunuzu birlikte planlayalım

Hangi sistemlere bağlanacağınızı anlatın; olayları ve alanları kurulumda birlikte eşleyelim.

Demo iste