API ve Entegrasyon: İzin ve Masraf Verinizi Kendi Sisteminize Çekin
Firma Ayarları'ndan bir anahtar üretin ve izin, masraf ve çalışan verinizi kendi raporlama veya muhasebe sisteminize okuyun. Yüzey salt-okumadır; hiçbir uç veri yazmaz.
Kısa Cevap: Entegrasyon API'si, bir yazılımın içindeki veriyi başka bir sistemin programatik olarak okumasını sağlayan arayüzdür. empuno'nun sunduğu yüzey bilinçli olarak dardır ve bunu saklamaz: /api/company/v1 altında yalnızca on adet GET ucu bulunur, hiçbiri veri yazmaz, kayıt oluşturmaz veya bir işlem tetiklemez. Kapsam üç veri kümesidir — çalışan künyesi (asgari roster), izinler ve masraflar. Kimlik doğrulama firma başına üretilen bir API anahtarıyla yapılır; anahtar panelden oluşturulur, ham hâli yalnızca bir kez gösterilir ve istendiğinde iptal edilir. Dokümantasyon /api-docs adresinde, makine okunur hâli /api-docs.txt ve /api-docs/openapi.json adreslerindedir.
Neler Sunar
-
On uçtan oluşan salt-okuma REST yüzeyi
— Anahtar doğrulama, çalışan listesi ve tekil çalışan, izinler, tekil izin ve izin türleri, masraflar, tekil masraf, fiş görseli ve masraf kategorileri. Hepsi GET; yazma ucu yoktur ve olmadığı için de yanlışlıkla veri bozma riski taşımaz.
-
Anahtar özeti saklanır, kendisi değil
— Anahtar "emp_live_" önekiyle üretilir ve veritabanında yalnızca sha256 özeti tutulur. Ham anahtar oluşturma anında bir kez gösterilir; sonrasında hiçbir ekranda, hiçbir yetkideki kullanıcıya tekrar gösterilemez. Listede yalnızca maskeli hâli görünür.
-
İptal edilebilir ve izlenebilir anahtar
— Her anahtarın son kullanım zamanı ve son çağrının geldiği IP kaydedilir; kullanılmayan veya sızdığından şüphelenilen anahtar tek tıkla iptal edilir. İptal anında geçersizleşir ve o anahtarla yapılan çağrılar yetkisiz yanıt alır.
-
Sayfalama ve gerçek filtreler
— Liste uçları sayfalıdır (sayfa boyutu en fazla 100) ve yanıtın meta bloğunda toplam kayıt ile son sayfa döner. İzinler duruma, çalışana ve izin türüne; masraflar duruma, çalışana ve kategoriye göre, ikisi de tarih aralığına göre filtrelenir.
-
Üç yüzeyde tek kaynaktan dokümantasyon
— İnsan için /api-docs, ajanlar ve komut satırı için düz metin /api-docs.txt, araç ve istemci üretimi için OpenAPI 3.1 şeması /api-docs/openapi.json. Üçü de aynı tanımdan üretilir, bu yüzden birbirinden geri kalmaz.
-
Anahtar başına hız sınırı
— Sınır IP'ye değil anahtara bağlıdır — aynı firma birden çok sunucudan çağırabilir. Dakikada 120, saatte 3000 istek serbesttir; aşıldığında istek reddedilir, veri sessizce eksik dönmez.
-
Hassas alanlar bilinçli olarak dışarıda
— Çalışan ucu yalnızca kimliği çözmeye yeten asgari veriyi döndürür: personel numarası, ad-soyad, departman, pozisyon, durum ve işe giriş tarihi. Kimlik numarası, maaş, banka ve adres bilgisi dönmez; izin kayıtlarında tıbbi belge dosyaları paylaşılmaz.
-
Fiş görseline denetimli erişim
— Masraf fişine ait görsel, anahtar ve firma sahipliği doğrulandıktan sonra kısa ömürlü imzalı bir adrese yönlendirilerek verilir. İşlenmiş veya orijinal varyantı seçebilirsiniz; kalıcı ve herkese açık bir dosya bağlantısı üretilmez.
Nasıl Çalışır
-
Anahtarı panelden üretin — Firma Ayarları ekranındaki API sekmesinden anahtara bir ad verip oluşturun. Ham anahtar ekranda bir kez gösterilir — kopyalayıp kendi sisteminizin gizli değer deposuna koyun. Aynı anda en fazla 25 aktif anahtar tutulabilir.
-
Anahtarı doğrulayın — İlk çağrıyı /me ucuna yapın: anahtarın geçerli olduğunu, bağlı firmayı ve hız sınırınızı görürsünüz. Anahtar isteğe "Authorization: Bearer" başlığıyla gönderilir.
-
Veriyi çekin — İzinleri ve masrafları tarih aralığı, durum ve çalışan filtreleriyle sayfa sayfa okuyun; kayıtlardaki çalışan kimliğini roster ucundan isim ve departmana çözün. Referans veriler (izin türleri, masraf kategorileri) ayrı uçlardan gelir.
-
İstemcinizi üretin, anahtarı yönetin — OpenAPI şemasından kendi dilinizde istemci üretebilirsiniz. Entegrasyon değiştiğinde eski anahtarı iptal edip yenisini oluşturun; son kullanım bilgisi hangi anahtarın hâlâ çalıştığını gösterir.
Sıkça Sorulan Sorular
İK programı API'si ne işe yarar?
Verinin panelden dışarı elle taşınmasını gereksiz kılar. Tipik kullanım, izin ve masraf kayıtlarının şirketin kendi raporlama panosuna, veri ambarına veya muhasebe yazılımına düzenli olarak okunmasıdır. Alternatifi her ay ekrandan indirilen dosyaları tekrar tekrar yüklemektir; bu hem gecikmeli hem hataya açık bir yöntemdir. API ile aynı veri, kesildiği yerden ve makine okunur biçimde alınır.
Hangi uçlar var, kapsam tam olarak nedir?
On GET ucu vardır. Genel: /me (anahtar doğrulama ve bağlı firma). Çalışanlar: /employees ve /employees/{id}. İzinler: /leaves, /leaves/{id} ve /leave-types. Masraflar: /expenses, /expenses/{id}, /expenses/{id}/receipt ve /expense-categories. Bunların dışında bir uç yoktur; bordro, PDKS, zimmet, avans, işe alım ve icra verisi için API ucu bulunmaz. Kapsam ilerleyen sürümlerde genişleyebilir, ancak burada yazan liste bugün gerçekten çalışan uçların tamamıdır.
API ile veri yazabilir, izin veya masraf oluşturabilir miyim?
Hayır. Yüzeyin tamamı salt-okumadır ve bu bir eksiklik değil, açık bir tasarım kararıdır. İzin ve masraf kayıtları onay akışı, bakiye hesabı ve belge yükümlülüğü gibi kuralların içinden geçerek oluşur; bunları atlayan bir yazma ucu, sistemin kendi iç tutarlılığını dışarıdan bozulabilir hâle getirir. Kayıt oluşturma bu nedenle panel ve mobil uygulama üzerinden yapılır, API yalnızca sonucu okur.
Webhook veya olay bildirimi var mı?
Hayır. Bir izin onaylandığında veya masraf durumu değiştiğinde sizin sunucunuza bildirim gönderen bir yapı bulunmuyor. Entegrasyon, belirli aralıklarla sorgulama yöntemiyle kurulur: liste uçlarındaki tarih aralığı ve durum filtreleriyle son dönemi çeker, kayıtların güncellenme zamanına bakarak kendi tarafınızda değişeni ayırt edersiniz. Hız sınırı bu kullanım için rahatça yeterlidir.
SAP, e-Bildirge, e-fatura veya tek oturum açma (SSO) entegrasyonu var mı?
Hayır. Hazır bir kurumsal kaynak planlama, muhasebe veya bordro yazılımı bağlayıcısı bulunmuyor; SAML veya OAuth ile tek oturum açma desteklenmiyor. empuno SGK e-Bildirge sistemine bağlanmaz, muhtasar ve prim hizmet beyannamesi üretmez, e-fatura ve e-arşiv göndermez — bu sınırların tamamı /mevzuat-uyumu sayfasında ayrıca yazılıdır. Elinizdeki tek entegrasyon aracı bu salt-okuma API'sidir ve bir sisteme veri aktarmak istiyorsanız bağlayıcıyı kendi tarafınızda yazarsınız.
Anahtarı kim oluşturabilir?
API anahtarları granüler izin sisteminde ayrı bir modüldür ve varsayılan olarak firma yöneticisine açıktır. Mali müşavirinize verilen muhasebeci yetki setinde bu modül bulunmaz; muhasebeci masraf ve izin verisini panelden görür, ama dışarı veri akıtacak bir anahtar üretemez. Yetki ayrı tutulur çünkü anahtar, panel oturumundan bağımsız ve süresiz çalışan bir erişim aracıdır.
Anahtarı kaybedersem ne yapmalıyım?
Ham anahtar tekrar gösterilemez; veritabanında yalnızca geri döndürülemez özeti saklandığı için sistemin kendisi de onu okuyamaz. Yapılacak şey eski anahtarı iptal edip yenisini oluşturmak ve entegrasyonunuzdaki gizli değeri güncellemektir. Bu, unutulmuş bir anahtarın kullanımda kalmasını engellediği için güvenlik açısından zaten tercih edilen yoldur.
Kaç anahtar üretebilirim, ne zaman ayrı anahtar kullanmalıyım?
Aynı anda en fazla 25 aktif anahtar tutulabilir. Pratikte her entegrasyon için ayrı bir anahtar üretmek doğru yaklaşımdır: raporlama panosu, muhasebe aktarımı ve deneme ortamı ayrı anahtarlar kullanırsa birini iptal etmek diğerlerini durdurmaz, son kullanım bilgisi de hangi entegrasyonun hâlâ çalıştığını gösterir.
Hız sınırı nedir, aşarsam ne olur?
Anahtar başına dakikada 120, saatte 3000 istek serbesttir. Sınır bilinçli olarak IP'ye değil anahtara bağlanmıştır; aynı firma birden çok sunucudan çağırdığında ceza yemez, sızmış tek bir anahtar da tüm firmayı kilitleyemez. Sınır aşıldığında istek açık bir hata koduyla reddedilir; kısmi veya sessizce eksik veri dönmez, bu yüzden çekim işiniz yanlış sonuçla tamamlanmış görünmez.
Bir anahtar başka firmanın verisini görebilir mi?
Hayır. Anahtar üretildiği firmaya bağlıdır ve her istekte firma yeniden çözülür; tekil kayıt uçlarında istenen kaydın o firmaya ait olduğu ayrıca doğrulanır. Başka bir firmanın kayıt kimliği istenirse "bulunamadı" yanıtı döner — kaydın var olup olmadığı bilgisi bile sızmaz. Anahtara bağlı firma pasife alınmışsa erişim tamamen kapanır.
Mobil uygulamanın kullandığı API ile aynı mı?
Değil. Çalışanın mobil uygulaması kişisel oturum belirteciyle çalışır ve yalnızca o çalışanın kendi verisine erişir; entegrasyon anahtarı o yüzeye giremez. Company API ise firma düzeyinde ve salt-okumadır. İkisinin ayrı tutulmasının sebebi yetki sınırlarının farklı olmasıdır: biri "kendi izin talebimi göreyim", diğeri "firmanın izin kayıtlarını raporlayayım" sorusunu cevaplar.
Dokümantasyonu görmek için hesap açmam gerekiyor mu?
Hayır. Dokümantasyon herkese açıktır: /api-docs adresinde uçların tamamını örnek yanıtlarıyla, /api-docs.txt adresinde düz metin olarak, /api-docs/openapi.json adresinde ise OpenAPI 3.1 şeması olarak inceleyebilirsiniz. Böylece entegrasyonun size yeteceğine hesap açmadan, kod yazmadan karar verebilirsiniz.
Entegrasyonu satın almadan deneyebilir miyim?
Evet. Ücretsiz hesap açıp anahtarınızı üretebilir ve tüm uçları kendi verinizle deneyebilirsiniz; API için ek bir ücret veya üst paket koşulu yoktur. Kurulum ve taahhüt gerekmez.
API ve Entegrasyon ne kadar, aylık maliyeti nedir?
empuno çalışan başına aylık $1,00 olarak fiyatlanır ve API ve Entegrasyon bu fiyata dahildir. Modül modül satın alma, paket kademesi veya "Pro / Enterprise" ayrımı yoktur: bütün modüller her hesaba dahildir, dolayısıyla bu modülün ayrı bir ücreti yoktur. İlk 2 kullanıcı süresiz ücretsizdir — bu bir deneme süresi değildir. Ücretlendirme yalnızca bu sınırın üzerine çıkıldığında başlar; faturalanan en az kullanıcı sayısı 3, yani ücretli plana geçen bir işletmenin aylık alt sınırı $3,00. Çalışan sayınız düşerse fatura da düşer. Liste fiyatı USD cinsindendir; ödeme sırasında tutar işlem anındaki kur üzerinden yerel para biriminize çevrilerek tahsil edilir, bu nedenle sabit bir Türk Lirası tutarı yayınlamıyoruz. Ekip büyüklüğüne göre aylık ve yıllık toplamları /fiyatlandirma sayfasındaki tabloda görebilirsiniz.
Verinizi kendi sisteminize bugün bağlayın
Anahtarı bir dakikada üretin, /api-docs adresindeki örnekle ilk çağrınızı yapın — izin ve masraf veriniz kendi panonuzda görünsün.
Ücretsiz Başla
Diğer Özellikler