Hazır bordro aktarımlarının dışında bir şey kurmanız gerekiyorsa — kendi İK sisteminiz, bir veri ambarı ya da bir iç pano — API ve webhook bunun yüzeyi.
OpenAPI dokümantasyonu
Uçlar, istek ve yanıt şemaları ve örnekler OpenAPI olarak yayınlanır. Bu, dokümantasyonun el yazması bir metin değil, makine okunur bir sözleşme olması anlamına gelir: istemci kodunuzu şemadan üretebilirsiniz.
Webhook: olayı siz sormayın, biz söyleyelim
Düzenli aralıklarla veri çekmek yerine, ilgilendiğiniz olay gerçekleştiğinde kendi uç noktanıza bildirim alırsınız. Dönem kapanışı, onaylanan izin, uyum uyarısı gibi olaylar bu şekilde taşınır.
Toplu veri aktarımı
Tek seferlik ya da dönemsel aktarımlar için Excel içe aktarımı vardır: personel, açılış izin bakiyeleri ve geçmiş hareketler. Eski sisteminizden geçerken en çok kullanılan yol budur; bir API istemcisi yazmaya gerek kalmaz.
Erişim ve yetki
API erişimi müşteri hesabına bağlıdır ve kapsamı sınırlıdır: bir anahtar, ait olduğu hesabın dışındaki hiçbir veriye erişemez. Her çağrı denetim izine düşer.
Kimlik doğrulama ve kapsam
Her kurumun kendi API'si ve kendi veritabanı vardır; API anahtarı yalnızca ait olduğu kurumun API'sine erişir. Anahtarın kapsamı ayrıca sunucuda uygulanır, yalnızca belgede yazmaz.
API nerede çalışır
Kurumun API'si bulutumuzda, kuruma ayrılmış bir sunucuda, kurumun yerel ağında ya da kurumun seçtiği başka bir sunucuda çalışabilir. Entegrasyonunuz her durumda aynı OpenAPI sözleşmesini kullanır. Ayrıntılar kurulum seçenekleri sayfasında.
Her çağrı denetim izine düşer: hangi anahtar, hangi uca, ne zaman. Bir anahtar sızdığında yapılacak ilk şey onu iptal etmektir ve bu panelden tek işlemdir.
Hız sınırı ve sayfalama
Uçlar hız sınırına tabidir; sınır aşıldığında 429 döner ve ne zaman tekrar denenebileceği başlıkta yazar. Büyük listeler keyset sayfalama ile döner, yani veri büyüdükçe sayfa gezinmesi yavaşlamaz.
Toplu veri çekerken önerilen yol, tam liste yerine değişiklik akışını dinlemektir: webhook ile olay geldiğinde yalnız değişeni çekersiniz.
Webhook'u güvenli kurmak
Bildirimin bizden geldiğini doğrulamak için imza başlığı gönderilir; uç noktanız bu imzayı doğrulamadan gövdeye güvenmemelidir. Uç noktanız yanıt vermezse bildirim artan aralıklarla yeniden denenir.
Uç noktanızın hızlı yanıt vermesi önerilir: işi kuyruğa alın ve hemen 200 dönün. Uzun süren bir işlemi bildirimin içinde yapmak, yeniden denemelere ve yinelenen kayıtlara yol açar.
Sürüm ve geriye dönük uyum
Uçlar sürümlüdür ve var olan bir alanın anlamı değişmez. Yeni alanlar eklenebilir, bu yüzden istemciniz tanımadığı alanları yok saymalıdır — katı şema doğrulaması yapan bir istemci ilk eklemede kırılır.
Bir uç kaldırılacaksa önceden duyurulur ve geçiş süresi tanınır. Dokümantasyon OpenAPI olarak yayınlandığı için değişiklikleri şema karşılaştırmasıyla da izleyebilirsiniz.