İzin360 Entegrasyon API'si

Bordro, İK, ERP ve BI sistemlerinizi İzin360'a bağlamak için üç yol vardır:

Taban adres: https://<alan-adınız>/api/v1. Tüm yanıtlar JSON (UTF-8); hatalar RFC 9457 application/problem+json biçiminde ve makine-okunur code alanı taşır.

---

1. API anahtarı

Oluşturma: İzin360 › Ayarlar › Entegrasyonlar › API anahtarları (yalnız şirket sahibi). Anahtar yalnız bir kez gösterilir; güvenli bir kasada saklayın. Anahtar sayısı planınızla sınırlıdır.

Kullanım: her istekte başlık:

X-Api-Key: iz_<…>

ya da Authorization: ApiKey iz_<…>.

Kapsamlar (anahtar oluşturulurken seçilir; en az yetki ilkesi):

Kapsam dışı istek: 403 integration.scope_missing. Geçersiz/iptal edilmiş/süresi dolmuş anahtar: 401. API anahtarı kullanıcı uçlarını açamaz; kullanıcı oturumu da entegrasyon uçlarını açamaz.

Hız sınırı: planınızın dakika başına istek sınırı; aşımda 429 ve Retry-After başlığı.

Güvenlik: anahtarı istemci tarafı koda (tarayıcı, mobil uygulama) koymayın; sızdığından şüphelenirseniz hemen iptal edip yenisini oluşturun. Anahtarın son kullanım zamanı panelde görünür.

2. Uçlar

2.1 Çalışanlar — GET /integration/employees?includeInactive=false

[
  {
    "id": "0192…", "personnelNo": "1001", "fullName": "Ayşe Yılmaz", "email": "[email protected]",
    "departmentName": "Muhasebe", "teamName": null,
    "companyStartDate": "2021-03-01", "isActive": true, "offboardingDate": null
  }
]

TCKN ve ücret bilgisi bu uçtan dönmez.

2.2 İzinler — GET /integration/leave-requests?from=2026-10-01&to=2026-10-31&state=Approved,Taken

from/to aralığıyla kesişen talepler (en çok 400 gün). state varsayılanı Approved,Taken; diğer değerler: Submitted, InApproval, Rejected, Cancelled, Withdrawn.

[
  {
    "id": "0192…", "employeeId": "0192…", "personnelNo": "1001",
    "leaveTypeCode": "annual_leave", "leaveTypeName": "Yıllık Ücretli İzin", "isPaid": true,
    "startDate": "2026-10-12", "endDate": "2026-10-16", "startHalf": "FullDay", "endHalf": "FullDay",
    "totalDays": 5, "state": "Approved", "resolvedAt": "2026-10-05T09:14:02+03:00"
  }
]

totalDays şirketinizin çalışma takvimine göre izinden düşen gündür (hafta tatili ve resmî tatiller hariç; yarım günler 0,5).

2.3 Bakiyeler — GET /integration/balances

[ { "employeeId": "0192…", "personnelNo": "1001", "annualLeaveRemaining": 14.5, "annualLeavePending": 2 } ]

Yıllık izin bakiyesi uygulamadaki bakiye ekranıyla aynı defterden gelir; kullanılmayan yıllık izin zamanaşımına uğramaz (İş K. m.59).

2.4 Bordro dosyası — GET /integration/payroll-export?period=2026-10&format=csv

Uygulamadaki Raporlar › Bordro aktarımı ile aynı dosya: dönemle kesişen izinler döneme kırpılır ve yeniden sayılır. period şirketinizin bordro dönem tipine (takvim ayı ya da 26–25) uyar; alternatif olarak start/end. format: csv (UTF-8 BOM, ; ayraç) ya da xlsx. "SGK eksik gün kodu" sütunu öneridir — bordro uzmanınızca teyit edilmelidir.

3. Webhook'lar

Kurulum: Ayarlar › Entegrasyonlar › Webhook'lar (şirket sahibi). Yalnız https:// adresleri ve genel internet adresleri kabul edilir. İmza sırrı (whsec_…) yalnız oluşturma ve döndürme anında gösterilir.

Olaylar: izin360.leave.submitted.v1, …leave.approved.v1, …leave.rejected.v1, …leave.withdrawn.v1, …leave.cancelled.v1, …leave.taken.v1, izin360.employee.offboarded.v1, test için izin360.webhook.test.v1 (güncel liste: GET /api/v1/webhooks/event-types).

İstek: POST, gövde CloudEvents biçiminde JSON; başlıklar:

Yük asgaridir: kimlikler, sicil no, tarihler, gün sayısı, durum. Ad ve serbest metin gerekçe yoktur; sağlıkla ilgili izin türleri {"code":"private","name":"İzinli"} olarak maskelenir (KVKK m.6).

Doğrulama örneği (Node.js):

import crypto from "node:crypto";

export function verify(rawBody, headers, secret) {
  const ts = headers["x-izin360-timestamp"];
  const sig = headers["x-izin360-signature"]; // "v1=…"
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // 5 dk tekrar oynatma penceresi
  const expected = "v1=" + crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  const a = Buffer.from(sig ?? ""), b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Teslim: 2xx yanıtı başarı sayılır; 10 sn zaman aşımı. Başarısızlıkta üstel bekleme ile 8 kez yeniden denenir (en çok ~6 saat aralık); art arda 15 başarısızlıkta abonelik otomatik kapatılır ve panelden yeniden açılabilir. Teslimat geçmişi panelde görünür.

4. iCal aboneliği

Her kullanıcı kendi izinleri için (yöneticiler isterse ekibi için) kişisel bir takvim adresi oluşturur: Ayarlar › Takvim aboneliği. Adres gizli bir anahtar içerir; paylaşmayın, sızdıysa döndürün. Sağlık türleri takvimde her zaman "İzinli" görünür. Takvim uygulamaları adresi genellikle 15 dakika–birkaç saatte bir yeniler.

5. Hata kodları (seçme)