Ajan API'si ve empuno CLI

Yönetim panelinde yapabildiğiniz her işlemi yapay zekâ ajanlarınıza ve otomasyonlarınıza açın. Ajan, oluşturduğunuz anahtarla sizin adınıza ve seçtiğiniz yetkilerle çalışır; her yazma işlemi kayıt altına alınır.

Komut
426
Yazma işlemi
247
Modül
28

Nedir?

empuno Ajan API'si ve empuno CLI, yönetim panelinde yapabildiğiniz her işlemi — izin onayı, bordro, vardiya planı, ekipman zimmeti, PDKS, masraf, işe alım, evrak — yapay zekâ ajanlarınıza ve otomasyonlarınıza açar.

İlke panel = API: her panel ekranı ve butonu, panelle birebir aynı doğrulama, iş kuralı ve yetki kontrolünden geçen bir komuttur. Şu an 426 komut (247 yazma işlemi), 28 modül. Panele yeni bir özellik geldiğinde komutu kendiliğinden eklenir; CLI güncellemesi gerekmez.

Hızlı başlangıç (CLI)

CLI npm'de empuno paketidir; tek dosyadır, bağımlılığı yoktur, Node.js 18 veya üstü yeterlidir. Kurmadan npx empuno … ile de çalışır.

Komut adı panel rotasının adıdır (manager. öneki olmadan). Yol parametreleri sırayla verilir; diğer --alan değer bayrakları okuma komutunda sorgu parametresi, yazma komutunda JSON gövdesi olur. --alan @dosya ya da --file alan=dosya multipart yükleme yapar. Çıktı her zaman JSON'dur; çıkış kodu 0 başarı, 1 API hatası, 2 kullanım hatası, 3 ağ hatası, 4 satır hatası (yalnız --strict: istek işlendi ama data.failed > 0).

Sayı dönüşümü (CLI 1.5.0): değerler katalogdaki doğrulama kuralına göre çevrilir — kuralı string, email, date, regex, digits olan alanlar (TC, IBAN, telefon, sicil no) metin gider; kural bilinmiyorsa 10 ve daha uzun haneli tam sayılar metin kalır. --no-coerce dönüşümü tamamen kapatır (eski sürümde TC sayıya çevrilip "must be a string" hatası verebiliyordu).

Ortam değişkenleri: EMPUNO_API_KEY, EMPUNO_URL, EMPUNO_PROFILE, EMPUNO_NO_UPDATE_CHECK=1 (güncelleme uyarısını kapatır; açıkken aynı sürüm için günde bir kez basılır — bayrak: --no-update-check). Birden çok firma için empuno login --profile acme ve --profile acme.

Geçerli değerler: bir alanın kabul ettiği değerleri tahmin etmeyin — empuno reference (ya da GET /api/company/v1/reference/{ad}; adsız çağrı tam listeyi verir): sgk_exit_codes, employee_document_types, equipment_categories, currencies, ticket_kinds, departments, branches, leave_types; bordro için payroll_options, earning_types, deduction_types, payroll_period_statuses, payroll_parameters (--date / --year), payroll_declaration_fields, sgk_document_types, sgk_missing_day_reasons, muhsgk_payment_types, insurance_groups, incentive_codes, attendance_codes, hour_sources, work_schedules; çalışma dönemleri için sgk_workplaces, employment_kinds, sgk_workplace_zone_types; hata kodları agent_errors.

Listeler: okuma komutları --per_page (en fazla 100) ve --page alır; yanıttaki sayfalama bloğu toplamı verir.

bash
# 1) Kur (npm'siz ortamda: curl -fsSL https://empuno.com/cli/empuno.mjs -o ~/.local/bin/empuno && chmod +x ~/.local/bin/empuno)
npm i -g empuno

# 2) Giriş — anahtar: panel → Firma Ayarları → API → Yeni anahtar → Tür: Ajan
echo "emp_live_…" | empuno login --key-stdin

# 3) Keşfet
empuno whoami                          # firma, kimin adına, kaç komut
empuno commands izin                   # anahtar kelimeyle komut ara
empuno describe leave-requests.reject  # parametreler, alanlar, gereken yetki, hız sınırı
empuno reference sgk_exit_codes        # bir alanın geçerli değerleri

# 4) Çalıştır
empuno leave-requests.index --status pending
empuno leave-requests.approve 123
empuno leave-requests.reject 124 --rejection_reason "Yoğun dönem"
empuno employees.documents.store 45 --document_type is_sozlesmesi --file file=./sozlesme.pdf

Ajanınıza verin

Ajanınızın (Claude, ChatGPT, kendi ajanınız) talimatlarına şunu eklemeniz yeterli:

sistem talimatı
empuno İK sistemine `empuno` CLI ile erişimin var.
- Önce `empuno commands <anahtar kelime>` ile komutu bul, `empuno describe <komut>` ile
  yol parametrelerini, alanları ve kuralları öğren; sonra komutu çalıştır.
- Çıktı JSON: okumada `data`, yazmada `ok` / `message` / `redirect.params` (yeni kaydın kimliği).
- 422 → `errors` nesnesindeki alanları düzeltip tekrar dene. 403 → anahtarın yetkisi yetmiyor,
  kullanıcıya hangi yetkinin (`required_permission`) gerektiğini söyle; tekrar deneme.
- Geri alınamaz işlemlerden (silme, bordro kesinleştirme/ödeme, işten çıkış) önce kullanıcıdan onay al.
- Toplu ya da geri alınması zor bir yazmadan önce aynı komutu `--validate` ile dene (hiçbir şey
  kaydedilmez, gidecek e-posta/iş listelenir; HTTP'de `X-Empuno-Dry-Run: 1`).
- Betikte her yazmaya iş anahtarından türetilmiş `--idempotency-key` ver (ör. avans-<sicil>-<dönem>;
  TC gibi kişisel veri koyma); yanıtta `data.id` / `data.results` esastır.
- 500 → işlem yapılmış olabilir: önce okuma komutuyla doğrula; aynı anahtarla tekrar göndermek
  işlemi yeniden yapmaz (409 idempotency_replay_unavailable), yapılmadıysa yeni anahtarla gönder.
- Bordroyu doğrulamak için gerçek dönem açıp profil değiştirmek yerine `payroll.simulate` ve
  `payroll.calculate <YYYY-AA> --dry_run 1` kullan (yan etkisiz); bir rakamın nedenini
  `payroll.employee-slip <YYYY-AA> <çalışan> --explain 1` ile sor. Dönemleri id yerine YYYY-AA ile an;
  409 ambiguous_period gelirse `candidates[]`'tan id seç.
- Grup anahtarıyla çalışıyorsan HER komutta (okuma dahil) `--company <id|slug>` ver; firmalar:
  `empuno companies`. Yanıttaki `meta.company_id` hangi firmada çalıştığını söyler — yazmadan önce doğrula.
- Yapamadığın bir işlem, hata ya da geliştirme önerisi için empuno ekibine talep aç:
  `empuno tickets open "<başlık>" --kind missing_command|bug|feature --body "…"`; yanıtları `empuno tickets --unread` ile kontrol et.
- Belge: https://empuno.com/api-docs/agent.txt

Doğrudan HTTP ile

CLI yalnızca kolaylıktır; her komut düz bir HTTPS isteğidir. Anahtar Authorization: Bearer (veya X-API-Key) başlığında gider; çerez, oturum veya CSRF jetonu gerekmez.

Gövde JSON ya da (dosya varsa) multipart/form-data olabilir. Dosyalı bir güncellemeyi (PUT/PATCH) POST + _method=PUT alanıyla gönderin; multipart gövdede PUT/PATCH desteklenmez (CLI bunu kendisi yapar).

employees.update (PUT ya da PATCH) ve advance-payments.update yalnız gönderdiğiniz alanları yazar; gönderilmeyen alan olduğu gibi kalır, bilerek gönderilen boş değer siler. Örn. yalnız giriş tarihi: empuno employees.update 45 --hire_date 2019-04-01. Diğer güncelleme komutlarında zorunlu alanlar için empuno describe <komut>.

cURL
# Komut kataloğu (yalnız bu anahtarın çağırabildikleri; ?all=1 hepsi)
curl -H "Authorization: Bearer $EMPUNO_API_KEY" https://empuno.com/api/company/v1/catalog

# Okuma komutu: leave-requests.index
curl -H "Authorization: Bearer $EMPUNO_API_KEY" "https://empuno.com/manager/leave-requests?status=pending"

# Yazma komutu: leave-requests.reject
curl -X POST -H "Authorization: Bearer $EMPUNO_API_KEY" -H "Content-Type: application/json" \
     -d '{"rejection_reason":"Yoğun dönem"}' https://empuno.com/manager/leave-requests/124/reject

Güvenli yazma: deneme (dry_run) ve tekrar anahtarı

Deneme (dry_run): her yazma komutu kaydetmeden denenebilir — X-Empuno-Dry-Run: 1 başlığı, gövdede dry_run: true ya da CLI'da --validate (CLI 1.5.0 ve üstü). Komut panelle aynı doğrulama ve iş kurallarından geçer, sonra tüm değişiklikler geri alınır. Yanıt dry_run: true, "Deneme (kaydedilmedi): …" mesajı ve dry_run_report taşır; oluşacak kayıtların kimliği null döner. Okumalarda (GET) dry_run yok sayılır.

KanalDenemede ne olur?
VeritabanıDeğişiklik yapılır ve geri alınır. dry_run_report.changes tablo bazında sayılar verir: inserts satır sayısı, updates / deletes SQL ifadesi sayısı.
E-posta, bildirim, push, kuyruk işiGönderilmez, listelenir: side_effects.mail (alıcı maskeli), notifications, jobs. Kayıttan sonra kuyruğa atılan işler (ör. onay push'u) da listede görünür.
Dosya (belge, fotoğraf, PDF)Taklit edilir: bellekte yazılır, kalıcı depoya gitmez; side_effects.storage listesinde görünür.
Dış servis (AI, çeviri, üçüncü taraf API)Desteklenmez: komut 422 dry_run_unsupported döner (blocked hedefi gösterir), hiçbir şey kaydedilmez, AI kredisi harcanmaz. AI çağıran komutlar baştan reddedilir.
ÖnbellekBu istek için geçici bir depo kullanılır; gerçek önbelleğe dokunulmaz.
Hız sınırıGerçektir: denemeler de sayılır.

Hangi komutun denenebildiği katalogdadır (empuno describe <komut>, GET /api/company/v1/catalog): dry_run = sandbox (çalıştır + geri al), native (komut kendi önizlemesini döndürür; ör. data-migration.*.commit, payroll-items.bulk — satır bazlı results[] ve null kimliklerle) ya da unsupported (gerekçe dry_run_note). Denemeler işlem günlüğüne "Deneme" rozetiyle düşer.

Tekrar anahtarı (Idempotency-Key): ağ kopması ya da betik hatasıyla aynı yazmanın iki kez yapılmasını önler. Yazma isteğine Idempotency-Key: <anahtar> başlığı (ya da gövdede client_request_id; CLI'da --idempotency-key, CLI 1.5.0 ve üstü) ekleyin. Kurallar:

  • Aynı anahtar + aynı içerik, 24 saat içinde → işlem ikinci kez yapılmaz; ilk yanıt "idempotent_replay": true ve Idempotent-Replayed: true başlığıyla döner.
  • Aynı anahtar + FARKLI içerik → 422 idempotency_key_reused (yeni işlem için yeni anahtar).
  • İlk istek hâlâ işleniyorsa → 409 idempotency_in_progress + Retry-After; bekleyip AYNI anahtarla yeniden deneyin (yeni anahtarla değil).
  • Reddedilen istek (4xx: doğrulama, yetki, iş kuralı) anahtarı serbest bırakır: düzeltip aynı anahtarla tekrar gönderebilirsiniz.
  • Bir anahtarla işlem en fazla bir kez yapılır. Sonucu belirsiz istekler aynı anahtarla yeniden ÇALIŞTIRILMAZ, 409 idempotency_replay_unavailable döner: önceki deneme sunucu hatasıyla bittiyse (reason: previous_attempt_failed — komut kaydı yazıp sonra hata vermiş olabilir), ilk istek kilit süresinde bitmediyse (stale_lock; sonradan biterse aynı anahtar kayıtlı yanıtı döndürür) ya da yanıt dosyaysa (not_stored; dosya içeriği saklanmaz). Bu durumda işlemin yapılıp yapılmadığını okuma komutuyla doğrulayın; yapılmadıysa YENİ anahtarla gönderin.
  • Anahtarlar API anahtarı başına ayrıdır; en fazla 120 karakter. Denemeler (dry_run) anahtarı tüketmez.
  • Anahtara kişisel veri koymayın (TC kimlik no, ad soyad, maaş): iş anahtarından türetin, ör. avans-<sicil>-2026-12. Sunucu anahtarı düz metin saklamaz (yalnız özeti), kayıtlı yanıt şifrelidir.
  • Panelden anahtar bazında "Her yazmada tekrar anahtarı zorunlu" açılabilir; açıkken anahtarsız yazma 400 idempotency_key_required alır.
  • Talep ucu (/api/company/v1/tickets) bu katmanın dışındadır ve farklı çalışır: aynı Idempotency-Keyli ya da aynı başlıklı açık bir talep (son 30 gün) varsa YENİ talep açılmaz, mevcut talep döner. Talep komutlarında --validate yoktur (CLI kullanım hatası verir).
  • CLI 1.5.0: --idempotency-key auto anahtarı içerikten üretir — bilerek tekrarlanan işlemlerde (profil değişince yeniden hesaplama, silip yeniden aktarma) kullanmayın, 24 saat boyunca eski yanıt döner. --retry N ağ hatası, 502/503/504 ya da 409 idempotency_in_progress durumunda Retry-After'a uyarak (en çok 10 sn) aynı anahtarla yeniden dener; yazmada yalnız tekrar anahtarıyla çalışır, 500'de yeniden denemez (sonuç belirsiz; okuma komutuyla doğrulayın). empuno migrate birden çok parçada anahtara -1, -2 … ekler.

Eski CLI (1.5.0 öncesi) de güvenlidir: sunucu --validate ve --dry_run true bayraklarını deneme, --idempotency-key <anahtar> ve --client_request_id <anahtar> bayraklarını tekrar anahtarı sayar. Yeni sürümün kolaylıkları (otomatik anahtar, yeniden deneme) için npm i -g empuno@latest.

bash
# Önce dene: hiçbir şey kaydedilmez, gidecek e-posta/iş listelenir
empuno advance-payments.store --employee_id 45 --amount 5000 --installment_count 2 --deduction_period 2026-12 --validate

# Sonra gerçek yazma, iş anahtarıyla (tekrar çalışırsa ikinci kayıt oluşmaz)
empuno advance-payments.store --employee_id 45 --amount 5000 --installment_count 2 --deduction_period 2026-12 \
  --idempotency-key avans-0045-2026-12 --retry 3

# Toplu işlemde satır hatası varsa betik dursun (çıkış kodu 4)
empuno payroll-items.bulk --json @kalemler.json --idempotency-key kalem-2026-12 --strict

# HTTP
curl -X POST -H "Authorization: Bearer $EMPUNO_API_KEY" -H "X-Empuno-Dry-Run: 1" \
     -H "Content-Type: application/json" -d '{"name":"Ar-Ge"}' https://empuno.com/manager/departments
curl -X POST -H "Authorization: Bearer $EMPUNO_API_KEY" -H "Idempotency-Key: dept-arge-2026" \
     -H "Content-Type: application/json" -d '{"name":"Ar-Ge"}' https://empuno.com/manager/departments

Başka sistemden geçiş: geçmiş veriyi yükleyin

Ajanınız eski sistemin geçmişini bir kerede taşıyabilir: ayrılmışlar dahil çalışanlar, izin geçmişi, avanslar ve devreden bakiyeler, ödenmiş masraflar, geçmiş bordrolar, özlük evrakı. Tüm aktarım komutları aynı kurallara uyar:

  • Yan etki yok: davet, e-posta, push bildirimi gitmez; onay akışına girilmez; lisans tüketilmez. Kayıtlar yönetici kaydıdır ve geçmişte gerçekleşmiş sayılır.
  • Çalışanı kendi anahtarınızla verin: her satırda identity_number (TC), employee_number (empuno sicil no), employee_id ya da employee_name ("Ad Soyad"; yalnız firmada tek kişiyle eşleşirse). Önce kimlik aramanız gerekmez.
  • Excel/CSV doğrudan: data-migration.files.parse (kind + file) eski sistemin dışa aktarımını Türkçe başlıklarıyla (TC Kimlik No, Ad Soyad, Brüt, Net Ödenen…) kayıtlara çevirir; tarih, dönem ve 38.000,50 biçimi normalleşir, eksik zorunlu sütun missing_required'da. Dönen records'u ilgili commit'e verin. Yönetici aynı akışı panelde Veri Göçü → Dosyadan Aktar'da yapar.
  • Departman adla: çalışan aktarımında department (ad) verilebilir; bilinmeyen departman açılır, satırın reason'ında yazar.
  • Ada göre eşleme: izin türü (leave_type: ad ya da annual gibi tür anahtarı), masraf kategorisi (category) adla verilebilir; Türkçe büyük/küçük harf farkı önemsizdir. Geçerli değerler: empuno reference.
  • Önce doğrulayın: --validate (HTTP: dry_run: true) aynı işlemi yapar ama hiçbir şey yazmaz; satır sonuçları gerçek çalıştırmayla aynıdır.
  • Tekrar çalıştırmak güvenlidir: aynı kayıt (ve aynı dosya) ikinci kez yüklenmez, skipped döner. Çalışanlarda --on_existing update yalnız gönderilen alanları günceller.
  • Satır bazlı sonuç: yanıtta results[] her satır için created | updated | skipped | failed, oluşan kaydın kimliği ve hata nedeni.
  • Doğrulamada kimlik yok: dry_run yanıtında created satırının id'si null'dır (kayıt geri alındı); gerçek kimlikler yalnız gerçek çalıştırmada döner.
  • Türk sayı biçimi: Logo/Mikro/Excel dışa aktarımındaki 38.000,50 tutarları için CLI'ye --decimal , verin; TC, tarih ve sicil no dokunulmaz.
VeriKomutNot
Çalışanlar (ayrılmışlar dahil)data-migration.employees.commitÇıkış tarihi/kodu, departman, şube, IBAN, SGK sicil/giriş, SGK işyeri (sgk_workplace), iç içe employments[]; TC ile eşler
Çalışma dönemleri (giriş-çıkış, SGK işyeri)data-migration.employments.commitHer satır bir sigortalılık dönemi; kart aynası dönemlerden türetilir, employee_effects[] kıdem/izin etkisini gösterir. Bilinmeyen 26 haneli sicil işyeri olarak açılır
Devreden yıllık izinemployees.leave-opening.update"Şu tarih itibarıyla kalan izin" (çalışan başına tek kayıt); o tarihe kadarki yıldönümleri ve kullanımlar hesaba girmez
İzin geçmişidata-migration.leaves.commitOnaylı geçmiş izin; bakiye hesabına girer
Avanslar + devreden bakiyedata-migration.advances.commitBordro, deduction_period'dan itibaren kalan bakiyeden düşer
Masraflardata-migration.expenses.commitÖdenmiş/onaylı; muhasebeye işlenmiş sayılır
Geçmiş bordrolardata-migration.payroll.commitAyrıca payroll.manage ister. Değerler aynen saklanır (yeniden hesaplanmaz); dönem kilitli "ödendi" açılır
Bordro beyan bilgileridata-migration.payroll.commit + update_fields=declarationAktarılmış aylara APHB/MUHSGK alanları; tutar, net ve kilit değişmez. Dosyadan: kind=payroll_declaration
Özlük evrakıdata-migration.documents.commitİstek başına ≤10 dosya (CLI parçalar); varsayılan yalnız yönetici görür
Aylık puantaj (gün kodları ya da özet)payroll.attendance.commitÇalışan-ay başına tek kayıt; bordroda tek kaynak. Excel: payroll.attendance.parse ya da data-migration.files.parse --kind attendance (+ period, code_map). Ayrıca payroll.manage ister
BES katılımcılarıdata-migration.pension-enrollments.commit (empuno migrate pension)Durum (aktif / ara verdi / caydı / ayrıldı), dahil olma, oran, cayma / ara verme tarihleri, sertifika no — geçmiş durum aynen yazılır. Plan önce pension.plans.store. Dosyadan: kind=pension_enrollments. Ayrıca payroll.manage
Teşvik bilgileri + uygulanan kanundata-migration.incentive-facts.commit (empuno migrate incentive-facts)6 ay sigortasız, İŞKUR, mesleki belge, sosyal yardım, 2828, işsizlik ödeneği kalan gün; Kanun No + Başlangıç → teşvik ataması (aktif). Engellilik oranı profile yazılmaz (uyarı). Dosyadan: kind=incentive_facts. Ayrıca payroll.manage

Geçmiş bordro müşavirin/eski yazılımın hesapladığı tutarlarla gelir; empuno onları yeniden hesaplamaz, yalnız saklar. Her satır bir çalışanın bir ayıdır (period: 2026-09). Zorunlu: gross_total, income_tax_base (o ayın GV matrahı), net_pay. İsteğe bağlı: sgk_days, sgk_employee, unemployment_employee, income_tax_final, stamp_tax_final, sgk_employer, employer_incentive_amount, employer_cost, earnings[] / deductions[] ({name, amount}), cumulative_tax_base. Kalemde earnings[].type (leave_pay | notice | severance | severance_excess = kıdemin tavanı aşan vergili kısmı) ve kalemin kendi vergisi earnings[].income_tax / stamp_tax (MUHSGK 013/015 satırı bu değeri aynen alır); kesintide deductions[].type (advance | garnishment | alimony | tax_debt | bes | union | penalty | rd_retained | other — muhasebe sınıflandırması ad tahminine kalmaz). Dönemler motorun dokunmadığı "ödendi" durumunda açılır ve Aktarıldı etiketi taşır; avans/haciz yeniden mahsup edilmez. Aktarımdan sonra empuno ilk ayı devraldığı kümülatif GV matrahıyla hesaplar — yıl içinde başka işverenden gelenler için cumulative_tax_base (o ay sonundaki kümülatif) verin, yoksa aktarılan aylardan zincirlenir. İçinde empuno bordro dönemi olan ay aktarılmaz (test/taslak dönemiyse önce payroll.destroy <id> --reason "…" ile silin; onaylanmışsa önce payroll.cancel); gelecek ay reddedilir. Net, brütten yasal kesintiler düşülünce 1 TL'den fazla sapıyorsa satır yine yazılır, reason'da uyarı döner. APHB gün alanları tamsayıdır: kesirli sgk_days / rd_days (ör. kısmi süreli 183,75 saat / 7,5 = 24,5) yukarı yuvarlanır (SSİY md. 101/3: "7,5 saatin altındaki çalışmalar 1 güne tamamlanır" → 25), kesirli missing_day_count aşağı; yuvarlama satırın reason'ında yazılır. on_existing=update yanıtında results[].changed[] değişen her alanı verir: beyan alanları kayıt adıyla (sgk_days, employer_incentive_code …), tutarlar fiş kolon adıyla (gross_total, net_pay, sgk_employee_unemployment, additional_deductions_total …), kalemler earnings / deductions.

Beyan alanları (SGK APHB + MUHSGK; hepsi isteğe bağlı, kodlar empuno reference …): employer_incentive_code = APHB kanun no (4–5 hane, 5510 → 05510; açık uçlu — incentive_codes), sgk_document_type (01, 02, 13… — sgk_document_types), missing_day_count + missing_day_reason (01, 03–13, 15–29; 02 artık kullanılmıyor → 21/19/20 — sgk_missing_day_reasons), sgk_occupation_code (9999.99; "2512,1" → 2512.10), sgk_workplace_registration_no (26 hane, yalnız rakam; Excel'de METİN hücresi — firmanın işyeriyle eşleşirse fişe işyeri olarak da bağlanır), sgk_workplace_id / sgk_workplace (id, sicil ya da ad; bulunamazsa satır failed), tax_payment_type (011 | 012 | 014 — muhsgk_payment_types), insurance_group (normal | sgdp | none — insurance_groups), Ar-Ge: rd_law (5746 | 4691), rd_rate, rd_days, rd_income_tax_exemption, rd_stamp_exemption, rd_sgk_support; asgari ücret istisnası mw_income_tax_exemption / mw_stamp_exemption. Alan listesi ve hangi fişte düzenlendiği: empuno reference payroll_declaration_fields. Geçersiz kod yalnız o satırı düşürür (failed + doğru referans).

Kilitli dönemde yalnız beyan: --on_existing update --update_fields declaration aktarılmış ayın mevcut pusulasına yalnız beyan alanlarını yazar; brüt, PEK, primler, kesilen GV/DV, net, kümülatif matrah, kalemler ve dönem durumu DEĞİŞMEZ (kayıttaki tutar alanları yok sayılır, satırın reason'ında yazar). Değişen alanlar results[].changed; aynı istek tekrarlanırsa satır skipped "değişiklik yok". Bu mod dönem açmaz: pusulası olmayan çalışan / aktarılmamış ay failed; empuno'nun hesapladığı ay için payroll.declaration.update önerilir; on_existing=skip ile 422. Tam güncellemede (update_fields yok) önceden girilmiş beyan KOD alanları (kanun no, belge türü, eksik gün/neden, meslek, sicil, ödeme türü, sigorta türü, Ar-Ge kanunu/oranı/günü) ve prim günü korunur; bir kod alanını silmek için açıkça null gönderin. Tutar türü beyan alanları (mw_*, rd_income_tax_exemption, rd_stamp_exemption, rd_sgk_support, employer_incentive_amount) kaydın tutarlarıyla birlikte gelir: tam kayıtta yoksa 0 sayılır (değişen alan results[].changed'de). Kanun no 05746 iken rd_days 0 olamaz (satır failed; boş = tüm prim günü). Prim günü temizlenemez: sgk_days boş/null yok sayılır (reason'da yazar). Dosyadan: data-migration.files.parse --kind payroll_declaration (Kanun No, Belge Türü, Eksik Gün, Eksik Gün Nedeni, Meslek Kodu, İşyeri Sicil No, Ödeme Türü, Sigorta Türü, Ar-Ge…; "Emekli", "YK üyesi" gibi değerler çevrilir) → dönen records'u data-migration.payroll.commit'e on_existing=update, update_fields=declaration ile verin.

Nakil ayında iki işyeri pusulası (aynı vergi no, iki SGK sicili): müşavir aynı çalışan-ay için iki pusula verdiyse ikisini birlikte, her birinde kendi işyeriyle (sgk_workplace_id | sgk_workplace | sgk_workplace_registration_no) ve prim günüyle (sgk_days, zorunlu) gönderin — empuno çalışan başına TEK pusula yazar (GV kümülatifi ve asgari ücret istisnası işveren bazında tek): tutarlar, günler ve kalemler toplanır, işyeri kırılımı sgk_segments[]'e her pusulanın kendi değerleriyle yazılır (prim günü, eksik gün + neden, Ar-Ge günü, kanun no, belge türü, giriş/çıkış, PEK, primler, teşvik, Ar-Ge desteği, GV matrahı, kesilen GV/DV). Mutabakat işyeri başına APHB satırını ve MUHSGK işyeri payını bu değerlerden aynen verir. Pusulanın SGK giriş/çıkışı: sgk_entry_date, sgk_exit_date, sgk_exit_code (Dosyadan Aktar sütunları "İşyeri Giriş Tarihi" / "Giriş Günü", "İşyeri Çıkış Tarihi" / "Çıkış Günü", "İşten Çıkış Kodu"; ayın günü de olur: 16 → dönemin 16'sı; verilmezse nakil sınırına önceki işyerinde çıkış 16 + sonrakinde giriş yazılır; tarih yoksa sınır prim + eksik günden tahmin edilir, reason'da not). Yanıt: ilk kayıt fişin sonucunu (created / updated / skipped + merged.records), diğerleri action: merged (+ merged_into, aynı slip_id) döner; data.merged = birleşen ek kayıt sayısı. Tekrar güvenli; sonradan TEK kayıt gönderilirse o ayın tamamı sayılır ve dilimler kaldırılır. Aynı işyeri iki kez ya da işyeri belirtilmeyen iki kayıt eskisi gibi işlenir (ikincisi atlanır / on_existing=update ile ezer); dilimler çakışıyorsa (aynı ayda iki işyerinde eşzamanlı çalışma) grubun tüm kayıtları failed. --update_fields declaration ile iki işyerli kayıt, birleştirilmiş pusulanın dilim beyan alanlarını işyerine göre düzeltir (tutarlar kilitli; fiş düzeyi gün/eksik gün dilimlerden yeniden kurulur).

Elinizde yapılandırılmış veri yoksa (ekran görüntüsü, düz metin liste) data-migration.employees.parse / leaves.parse metni ve görselleri AI ile kayıtlara çevirir (sorgu başına 2 AI kredisi); sonucu commit'e verirsiniz.

bash
# Sıra: çalışanlar → izinler → avanslar → masraflar → bordrolar → evrak (JSON ya da Excel'den CSV)
empuno migrate employees calisanlar.csv --validate
empuno migrate employees calisanlar.csv            # ayrılmışlar: status=terminated + termination_date, sgk_exit_code
empuno migrate employments donemler.csv --validate # giriş-çıkış geçmişi + SGK işyeri sicili: employee_effects'i kontrol edin
empuno migrate employments donemler.csv            # identity_number, hire_date, termination_date, sgk_exit_code, sgk_workplace
empuno migrate leaves izinler.csv                  # identity_number, leave_type, start_date, end_date, days
empuno migrate advances avanslar.csv               # amount, advance_date, deduction_period, deducted_amount (mahsup edilen)
empuno migrate expenses masraflar.csv              # expense_date, amount, category, merchant_name, status=paid
empuno migrate payroll bordrolar.csv --decimal ,   # period, identity_number, gross_total, income_tax_base, net_pay (+ SGK/GV/DV kalemleri)
empuno migrate payroll beyan.csv --on_existing update --update_fields declaration   # aktarılmış aylara yalnız SGK/MUHSGK beyan alanları
empuno migrate documents manifest.csv              # file (yol), identity_number, document_type, document_date, period
empuno attendance import puantaj.xlsx --validate   # aylık puantaj (ızgara ya da özet) — bkz. "Puantaj" bölümü

İşten çıkış ödemeleri ve bordro hesaplama tercihleri

Her işten çıkışta kullanılmayan yıllık izin ücreti, ihbar ve kıdem tazminatı hesaplanır ve çıkış ayının bordrosuna kalem olarak girer. Hak, SGK çıkış kodundan gelir (ör. 04 → kıdem + ihbar, 03 istifa → yalnız izin ücreti); "şartlara bağlı" kodlarda tazminatlar varsayılan kapalıdır.

  • Vergiler: izin ücreti SGK + GV + DV (çıkış ayının ücretine eklenir); ihbar GV + DV (SGK yok); kıdem yalnız DV (GV istisna, SGK yok), tavanla sınırlı.
  • Yakalama: çıkışı başka yoldan (aktarım) girilmiş çalışan bordro hesabında bulunur; firma tercihine göre onay bekler (flash.attention) ya da doğrudan eklenir. Onaydan sonra dönemi yeniden hesaplayın.
  • Tercihler (payroll-settings.options.update, yalnız gönderilen anahtarlar): kıst ayda asgari ücret istisnası (varsayılan tam ay — GV Genel Tebliği 319), yıl içinde işe girende AÜ GV istisnasının kümülatifi (mw_exemption_cumulative_start, varsayılan hire_month: asgari ücretin kümülatif matrahı bu işverendeki giriş ayından başlar — 319 Örnek 7/15, 331 Örnek 1; ör. 2025/Eylül girişlide istisna 3.315,70, yıl başından beri çalışanda 4.420,93 TL; january eski takvim tablosu, Tebliğe aykırı), ücretsiz iznin hafta sonu (takvim / yalnız iş günü), rapor günleri (maaş tamamlama / ücretsiz / ilk 2 gün işveren), çıkış ödemesi ekleme, izin ücreti ve tazminat ücret esası (çıplak / giydirilmiş), kıdemde kısmi yıl yöntemi, kıdem tavanı aşımı. Her seçeneğin mevzuat dayanağı empuno reference payroll_options çıktısındaki help alanında.
  • Gün hesabı (SGK 2020/20): eksik günlü tam ayda prim günü = ayın takvim günü − eksik gün (31 çeken ayda 1 eksik → 30, Şubat'ta → 27); ücret 30 esaslı. Yarım gün ücretsiz izin SGK gününü düşürmez, yalnız ücretten düşer.
  • Hak yoksa tutar 0: kıdem için en az 1 tam yıl + kıdem doğuran kod, ihbar için bildirim süresine uyulmayan fesih gerekir; hak yoksa önizlemede eligible=false, tutar 0 ve reason; istense bile eklenmez (gönüllü ödeme ek kazanç olarak girilir).
  • Müşavir bordrosu aktarılan ay: data-migration.payroll.commit earnings[].type = leave_pay | notice | severance (+ days) ile çıkış kalemleri empuno çıkış ödemesi olarak kaydedilir (durum imported); tipli kalem yoksa o ayın onay bekleyen ödemesi superseded olur. Bordro dışında ödenen için: employees.exit-settlement.update --dismiss true --notes "…".
  • Kıdem tavanı fesih tarihindeki dönemin tavanıdır (2026: 01.01–30.06 64.948,77 TL; 01.07–31.12 73.729,87 TL).
bash
# Önce gör (yan etkisiz): çıkarsa ne öderiz?
empuno employees.exit-settlement.show 45 --termination_date 2026-04-20 --sgk_exit_code 04
# Çıkar: ödemeler otomatik hesaplanıp onaylanır; izin gününü elle verebilirsiniz
empuno employees.terminate 45 --termination_date 2026-04-20 --sgk_exit_code 04 --exit_leave_days 12
# Ayrılmış çalışanda düzelt / onayla (aktarılan çalışanın izin bakiyesi eksikse)
empuno employees.exit-settlement.update 45 --leave_days 9 --include_notice false
# Firma tercihleri ve güncel değerler
empuno reference payroll_options
empuno payroll-settings.options.update --sick_leave_pay first_two_paid --mw_exemption_partial_month full_month

Çalışma dönemleri, SGK işyerleri, kıdem ve izin süresi

Bir çalışanın giriş-çıkış geçmişi çalışma dönemleri olarak tutulur: her dönem bir sigortalılık dönemidir (giriş, çıkış, SGK çıkış kodu, SGK işyeri, sigorta türü). Çalışan kartındaki hire_date / termination_date / sgk_exit_code / termination_reason bu dönemlerin aynasıdır: hire_date = güncel sözleşmenin başlangıcı (aynı işverende kesintisiz zincirin ilk dönemi). Dönemi hiç girilmemiş çalışan tek "örtük" dönemle (id=null) aynen eskisi gibi hesaplanır — okumak satır oluşturmaz.

  • Kurallar: dönemler çakışmaz; yalnız son dönem açık olabilir; aktif çalışanın son dönemi açık, ayrılmışınki kapalıdır. continues_previous = önceki dönemin çıkışının ertesi günü başlayan devam (nakil). İhlal rejected + flash.rule (kod) + flash.hint (sonraki komut) döner; kod listesi empuno reference agent_errors (returned_as: "flash.rule"). Çalışan kartındaki işe giriş tarihi (employees.update --hire_date, mobil, root admin) dönemlerle çakışırsa hiçbir alan yazılmaz: flash.rule: hire_date_conflicts_periods + hint (employees.employments.update).
  • Ne nereden yapılır: açık döneme çıkış → employees.terminate (hesap kapatma, bekleyen talepler, çıkış ödemesi); hatalı çıkışı geri alma → employees.reactivate; ayrılmış çalışanın yeni dönemi → employees.rehire (--update_payroll_profile true + payroll.manage: bordro profilinin sigorta grubu giriş tarihinden yeni sürümle dönemin sigorta türüne çekilir, çıkışta kapanmış profil yeniden açılır — yanıt created.payroll_profile {action: versioned | reopened | updated | unchanged | missing}; yetki yoksa rejected + flash.rule: payroll_permission_required; kutu işaretsizken profil kapanmışsa payroll_profile_closed uyarısı); işyeri düzeltme (tarihsiz) → employees.update --sgk_workplace_id ya da sgk-workplaces.assign --mode correct; tarihli nakil → employees.employments.transfer ya da sgk-workplaces.assign --mode transfer.
  • 16 çıkış kodu yalnız aynı işverenin (aynı vergi no) başka SGK işyerine nakildir: işten çıkışta reddedilir, grup şirketleri arasında kullanılamaz (grup şirketine geçiş yeni işverende yeni sözleşmedir). empuno reference sgk_exit_codes: usable_in_termination, retired (29), note.
  • Önceki hizmet (kind=prior_service): aynı işveren sayılan grup şirketi / işyeri devri (4857 md. 6). Kapalı olmalı, external_employer_name zorunlu.
  • Kıdem: güncel sözleşme zinciri hep sayılır. Önceki zincir: elle karar (counts_for_severance) > kıdemi ödenmiş (severance_paid ya da aynı tarihli onaylı/aktarılmış çıkış ödemesi; ödeme aynı kesintisiz iş ilişkisinde ondan önceki dönemleri — nakil 16 öncesi — de kapsar: reason_code: paid_chain, paid_by_employment_id) > zamanaşımı (2017-10-25 öncesi çıkış 10, sonrası 5 yıl) > çıkış koduna göre hak. "Şartlara bağlı"/boş kodlu dönem severance_prior_unknown_exit tercihine göre (vars. hariç + severance_decision_needed uyarısı). Ayrıntı employees.employments.index → timeline.severance.periods[] (her dönem için sayılır/sayılmaz + gerekçe) ve employees.exit-settlement.show → preview.service. Kıdem değerlendirmesi, ihbar, kıdem ödemeleri ve karar notları payroll.view ister — yoksa okumada yer almaz (timeline.severance_hidden: true); severance_paid* / counts_for_severance yazmak payroll.manage ister (flash.rule: payroll_permission_required).
  • Yıllık izin süresi: leave_prior_service = combine (vars.; önceki dönemler izin kıdemine eklenir, iş K. md. 54) | current_only. Sözleşme öncesi yıldönümlerinde yeniden hak doğmaz (o dönemin izni kullanıldı ya da çıkışta ödendi), sözleşme öncesi izin kullanımı düşülmez. Devreden bakiye (employees.leave-opening.update): as_of_date itibarıyla kalan gün; sonraki yıldönümleri eklenir, as_of_date sonrası kullanım düşülür. Açılış sözleşmeye bağlıdır: yeniden işe alımdan sonra önceki sözleşmenin açılışı yeni bakiyeye eklenmez (timeline.leave_opening_stale + leave_opening_stale uyarısı; md. 59 — önceki dönemin izni çıkışta ödenir). Ücretsiz izin ötelemesi yalnız izne sayılan dönemlerdeki ücretsiz izinden. Geçmiş bir çıkışın kullanılmayan izni (employees.exit-settlement.show) yeniden işe alımdan sonra da çıkış anındaki sözleşmeyle hesaplanır.
  • İhbar süresi: notice_service_basis = current_contract (vars.; güncel sözleşme) | combined (önceki sayılan dönemlerle).
  • Sicil numarası 26 hanedir (mahiyet, işkolu, ünite, sıra no, il, ilçe, kontrol, aracı); METİN olarak gönderin — sayı olarak Excel/JSON'da son haneler kaybolur. zone_type (technopark / rd_center) ve default_law_no yalnız ipucudur: Ar-Ge kapsamı bordro profilinden, kanun no beyan kurallarından gelir; teknopark işyerine nakilde rd_profile_hint uyarısı profili güncelleme komutunu verir.
  • Bordroda nakil ayı: çalışan başına TEK fiş kalır (ücret, GV kümülatifi ve asgari ücret istisnası işveren bazında tek hesaplanır); nakil kıst yapmaz. Fişe sgk_workplace_id (son dilimin işyeri, dönemsiz çalışanda firmanın varsayılanı) ve ≥ 2 dilimde sgk_segments[] yazılır: işyeri başına gün, eksik gün + neden, giriş/çıkış (nakilde 16), Ar-Ge günü (profil aralığı ∩ dilim) ve PEK/prim payı (gün payıyla, son dilim kuruş farkını alır). Her işyeri kendi takvim gününü bildirir: 31 çeken ayda toplam 31 olabilir (25 koduyla azaltılmaz); kesintisiz nakilde Şubat 30'a tamamlanır — fark transfer_february_completion tercihine göre sonraki (vars., TÜRMOB 06.03.2024/60-1) ya da önceki işyerine. slip.sgk_day_count aylık toplamdır (30). Ay içinde çıkış + yeniden giriş: iki sözleşmenin günleri toplanır (kıst), devamı olmayan dönem sonu çıkış ödemesi niyeti üretir. Yeniden giren çalışanın eski sözleşmesindeki ay da bordroya girer (geçmiş ay yeniden hesabı). Uyarılar (payroll.calculate → flash.warnings): workplace_missing, workplace_closed, insurance_group_mismatch (dönem ↔ profil; hesap profile göre), rd_zone_mismatch, transfer_31_day_ceiling (31 günlük nakil ayında PEK taban/tavana bağlı → işyeri başına kontrol). Denemek için: payroll.simulate --period 2026-02 --employee_id 45 --segments '[{"from":"2026-02-01","to":"2026-02-13","sgk_workplace_id":1},{"from":"2026-02-14","to":"2026-02-28","sgk_workplace_id":2}]' (yanıt workplace.sgk_segments).
  • Beyanda işyeri (payroll.declaration): öncelik fişin dilimleri > fişin işyeri > fişteki ham sicil (firmanın işyerleriyle okuma anında eşleşir; eşleşmezse ham numara aynen + workplace_registration_unmatched bilgisi) > çalışma dönemlerinin o aya düşen dilimleri (canlı — dönemleri sonradan girseniz de eski fiş işyeri bazlı beyan verir, fiş değişmez) > varsayılan işyeri > yok (workplace_missing). Nakil ayında kişi işyeri başına APHB satırı alır, vergi satırları da gün payıyla işyerine bölünür (MUHSGK her sicil için ayrı). --sgk_workplace_id <id> yalnız o işyerinin satırları — ay içinde nakledilen çalışanın bordro detayı ve summary.totals (brüt, net, kesinti, işveren maliyeti) o işyerinin payıyla (detail_rows[].workplace_share {days, total_days, ratio, full}, summary.totals.workplace_share_rows; işyeri görünümlerinin toplamı bordroya eşit); summary.by_workplace işyeri toplamları; Excel'de işyeri başına "APHB – <ad>" sayfaları.
  • Fişte işyeri dilimleri: payroll.employee-slip <dönem> <çalışan> → slip.sgk_workplace_id + slip.sgk_segments[] (gün, eksik gün + neden, giriş/çıkış kodu, PEK ve prim payları). Dönemi girilmemiş, tek işyerli çalışanda sgk_segments boştur.
  • Okumalarda ek alanlar: employees.show → employments (zaman çizelgesi; hesap hatasında null), employee.sgk_workplace, sgkWorkplaces (aktif işyerleri), employmentExitCodes (dönem kaydında geçerli tüm kodlar: 16 ve 29 dahil, retired + note); işten çıkış listesi sgkExitCodes 16 içermez. employees.index --sgk_workplace_id <id> süzer, satırda sgk_workplace. payroll-settings.index → sgkWorkplaces, sgkWorkplaceMeta (sicil parçaları, 81 il, bölge türleri, kanunlar).
  • Panelde aynı uçlar: Bordro Ayarları → SGK İşyerleri kartı (ekle / düzenle / varsayılan yap / kapat / sil / Çalışan ata: Düzeltme ya da tarihli Nakil, önce Doğrula) ve bölümlü Hesaplama Tercihleri (Çıkış, kıdem ve izin bölümünde dört yeni tercih); Firma Ayarları → Genel'de işyeri sayısı kartı; çalışan detayında Çalışma Dönemleri sekmesi (son sözleşme / izin kıdemi / kıdeme esas süre özeti, gerekçe rozetli zaman çizelgesi, Dönem ekle, İşyeri nakli, Devreden izin — her yazma önce dry_run etkilerini gösterir); İşe Geri Al iki seçenekli (Çıkışı geri al = employees.reactivate | Yeniden işe al = employees.rehire); Düzenle / Davet formlarında ve Çalışanlar listesinde SGK İşyeri; Mutabakat'ta işyeri filtresi + işyeri kartları; çıkış ödemesi kartında Hizmet dökümü; Veri Göçü → Dosyadan Aktar → "Çalışma dönemleri" (çalışan başına etki tablosu).
  • Çalışanın kendisi: GET /api/v1/profile (mobil) ve web profilinde service özeti — sözleşme başlangıcı, izin kıdemi başlangıcı ve süresi, yıllık izin hakkı (14/20/26), toplam hizmet, devreden izin {as_of, days, source_label}, dönemler (tarih, süre, işyeri adı, nakil). Kıdem tazminatı değerlendirmesi, yönetici notları ve çıkış gerekçesi çalışana gösterilmez. Web: Profil → "Hizmet Sürem"; mobil: Profil → Hizmet Sürem.
bash
# 1) SGK işyerlerini açın (sicil METİN; boşluk/tire serbest; ad boşsa sicilden)
empuno sgk-workplaces.store --registration_no "2 1041 02 02 4444444 006 05 88 000" --name "Merkez"
empuno sgk-workplaces.store --registration_no "2 1041 02 02 5555555 035 01 88 000" --name "İzmir Teknopark" --zone_type technopark
empuno reference sgk_workplaces
# 2) Geçmişi yükleyin — önce deneme, employee_effects'i kontrol edin
empuno migrate employments donemler.csv --validate
empuno migrate employments donemler.csv
# 3) Tek çalışan: oku / geçmiş dönem ekle / düzelt
empuno employees.employments.index 45
empuno employees.employments.store 45 --hire_date 2016-02-01 --termination_date 2019-12-31 --sgk_exit_code 04 --severance_paid true
empuno employees.employments.update 45 812 --iskur_exit_reason 2   # İŞKUR çıkış nedeni (SGK kodundan ayrı): empuno reference iskur_exit_reasons
empuno employees.employments.update 45 812 --counts_for_severance false --override_note "2019 çıkışında kıdem ödendi (dekont)"
# 4) Şirket içi nakil (aynı vergi no): 16 + ertesi gün giriş, iş ilişkisi sürer
empuno employees.employments.transfer 45 --date 2026-07-16 --sgk_workplace "İzmir Teknopark"
empuno sgk-workplaces.assign 2 --employee_ids 45,46,47 --mode transfer --date 2026-07-16 --validate
# 5) Ayrılmış çalışanı yeniden işe alma (yeni dönem; e-posta yok, lisans tüketir)
empuno employees.rehire 45 --hire_date 2026-11-02
# emekli olarak dönüş: dönem SGDP + bordro profili giriş tarihinden yeni sürüm (payroll.manage)
empuno employees.rehire 45 --hire_date 2026-11-02 --insurance_group sgdp --update_payroll_profile true --validate
# 6) Devreden yıllık izin (önceki sistemden kalan bakiye)
empuno employees.leave-opening.update 45 --as_of_date 2025-12-31 --annual_days 12.5

SGK sicil geçmişi: işkolu / ilçe değişince yeni numara

Aynı fiziksel işyeri işkolu (NACE), ilçe ya da ünite değişince SGK'dan yeni 26 haneli numara alır; sıra no ve il genelde aynı kalır, çalışanlar nakil olmaz. empuno'da işyerinin güncel numarası registration_no'dadır, eskileri geçerlilik aralığıyla sicil geçmişinde (former_registrations). Geçmiş dönemin APHB'si o tarihteki numarayla çözülür; aktarımda eski numara aynı işyerine eşleşir. Her numarayı ayrı işyeri açtıysanız birleştirin.

  • Düzeltme ≠ değişiklik: sgk-workplaces.update --registration_no yanlış girilmiş numarayı DÜZELTİR (geçmişe yazılmaz, geçmiş APHB'ler de yeni numarayla görünür). SGK yeni numara verdiyse sgk-workplaces.change-registration.
  • APHB'de numara: fişteki/dilimdeki ham numara işyerinin (güncel ya da eski) numarasıysa o; değilse işyerinin dönem sonunda geçerli numarası. Eski numara: valid_until'i dönem sonuna eşit ya da sonra olan ilk geçmiş satırı.
  • Birleştirme atomiktir: kaynakların çalışma dönemleri, fişleri ve fiş dilimleri hedefe taşınır; kaynağın numarası hedefin geçmişine, son günü valid_until ?? kaynağın fişlerindeki son ayın son günü ?? son çıkış. Hedefin numarası en son kullanılan olmalı (merge_target_not_latest). Numara değişikliği yüzünden açılmış "16 + ertesi gün devam" nakil çiftleri tek döneme iner (collapsed_transfers[]); sigorta türü değişen, grup nakli ya da kıdem ödemeli çiftler dokunulmaz (warnings[].transfer_kept). Kaynak varsayılansa varsayılan hedefe geçer, kaynaklar silinir, payroll_audit_logs'a geri alma için tam eşleme yazılır.
  • declaration_check: birleştirmede her fişin APHB sicili önce ve sonra çözülür — changed > 0 ise samples[]'a bakın (ör. işyerisiz eski fişler artık varsayılanın o dönemdeki numarasını alır).
  • Tekillik: bir numara firmada tek yerde durur (güncel ya da geçmiş). Başka işyerinin güncel numarasını geçmişe eklemek registration_taken + birleştirme ipucu; eski numarayla sgk-workplaces.store yeni işyeri açmaz (registration_is_former). migrate employments bilinmeyen numara açarken aynı sıra no/il'li işyeri varsa notta birleştirme ipucu verir.
  • Panelde: Bordro Ayarları → SGK İşyerleri: satırda sicil geçmişi, ⋯ menüsünde Sicil değişti / Eski sicil ekle, kart başında birleştirme önerisi (önizlemeli).
bash
# Ayrı açılmış eski siciller: öneri (aynı sıra no + il + aracı) → deneme → birleştir
empuno sgk-workplaces.merge-suggestions
empuno sgk-workplaces.merge 8 --source_ids 13,12,11 --validate   # declaration_check.changed ve collapsed_transfers'a bakın
empuno sgk-workplaces.merge 8 --source_ids 13,12,11
# Son gün fiş/dönemden bilinmiyorsa elle
empuno sgk-workplaces.merge 9 --json '{"source_ids":[10],"valid_until":{"10":"2025-01-31"}}' --validate
# SGK bugün yeni numara verdi (işkolu değişti): eski numara date − 1 son günüyle geçmişe
empuno sgk-workplaces.change-registration 8 --registration_no "2 5231 01 01 1677872 035 23 07 000" --date 2025-08-01 --validate
# Geçmişe eski numara ekle / kaldır
empuno sgk-workplaces.registrations.store 9 --registration_no "2 6201 01 01 1893700 035 22 10 000" --valid_until 2025-01-31
empuno sgk-workplaces.registrations.destroy 9 41

Puantaj aktarımı, saat bazlı kazançlar, kısmi süreli ve çağrı üzerine çalışma

Ayın puantajı (müşavirin ya da PDKS'in Excel'i, ajanınızın ürettiği kayıt) çalışan-ay başına tek kayıt olarak saklanır ve bordroda tek kaynak olur: prim günü, eksik gün + SGK nedeni, ücret günü ve fazla çalışma / hafta tatili / UBGT / gece saatleri buradan okunur. Puantajı olmayan çalışan-ay bugünkü gibi izin kayıtları ve PDKS'ten hesaplanır. Puantaj uçları bildirim / e-posta göndermez; okumalar yan etkisizdir. Okuma payroll.view, yazma payroll.manage ister.

  • Tek kaynak ve uyuşmazlık: puantajı olan çalışan-ayda (attendance_days_source=attendance, varsayılan) prim günü, eksik gün ve ücret günü puantajdan gelir; izin kayıtları ve devamsızlık kesintisi o ayın hesabına girmez. attendance_hours_source=attendance (varsayılan) iken PDKS saatleri de girmez. İzin kayıtları ve PDKS ile farklar uyuşmazlık olarak döner (conflicts, conflict_count; kodlar: leave_record_not_in_attendance, attendance_leave_without_record, leave_type_mismatch, pdks_presence_on_absence, unpaid_days_mismatch, sick_days_mismatch, overtime_hours_mismatch), bordroyu otomatik değiştirmez; incelendiğinde conflicts_reviewed=true. Kaynağı leave_records / pdks yaparsanız puantaj yalnız karşılaştırma olur. Kayıt yalnız taşıdığı bilginin kaynağıdır: gün alanı olmayan özet (prim günü, eksik gün / kırılım — missing_days: 0 ya da missing_breakdown: {} "eksik gün yok" demektir —, neden, çalışılan gün yok; ör. yalnız FM sütunu) günleri izin kayıtlarından bıraktırır (days_not_in_entry uyarısı); saat alanı olmayan kayıt (yalnız kodlu ızgara, yalnız gün sütunlu özet) saatleri PDKS'ten bıraktırır (hours_not_in_entry). Puantajdaki "0" esas olsun istiyorsanız saat sütununu 0 olarak gönderin. Hesapta aynı durum attendance_days_not_in_entry / attendance_hours_not_in_entry uyarısıdır; preview.days_in_entry / hours_in_entry hangisinin kullanıldığını söyler.
  • Kayıt biçimi: ızgara — days {"2026-04-01" ya da "1": "Ç" | "HT" | "Yİ" | "R" | "7,5" | "HT8" | "08:30-17:45" | {c, h, n}}; özet — alanlar (sgk_days, missing_breakdown {"01": 2, "21": 1}, missing_day_reason, missing_days + sick_days / unpaid_leave_days / absent_days, wage_deduction_days, worked_days, worked_hours, paid_rest_hours, overtime_50_hours, overtime_25_hours, weekly_rest_days/hours, holiday_days/hours, night_hours, notes). worked_hours normal iş günü saatidir — FM, HT ve UBGT HARİÇ; *_days ile *_hours birlikte verilebilir. Izgarada özet alanlar gün kodlarından çalışanın sözleşme saatiyle türetilir (derived[]): FM %50 / FS %25 haftalık 45 saat kuralıyla (yalnız tüm normal günlerde saat varsa), saat aralığında md. 68 ara dinlenmesi düşülür (≤4 sa 15 dk, ≤7,5 sa 30 dk, üstü 1 sa), 20:00–06:00 kesişimi gece saatidir. Açık verilen alan türetileni ezer (explicit_differs uyarısı).
  • Kodlar: empuno reference attendance_codes — her kanonik değerin takma adları, SGK eksik gün nedeni (rapor 01, ücretsiz izin 21, ücretsiz doğum izni 19, yol izni 20, devamsızlık 15, kısa çalışma 18, kısmi süreli çalışılmayan gün 06, disiplin 03 …), ücret etkisi ve saat alıp almadığı. Sayı = çalıştı + saat; "HT8" = hafta tatilinde 8 saat çalıştı. Rapor (R) gününün ücreti firmanın sick_leave_pay tercihine göre. "0", "İzin" gibi belirsiz hücre ve tanımadığımız kısaltma tanınmaz: parse unknown_codes[{raw, count, sample_rows}] döner, commit o satırı failed (unknown_codes + hint) yapar → code_map ({"X": "absent"} ya da "X=absent,Y=worked") ile yeniden okuyun.
  • Dosya okuma: başlık satırı ilk satırlarda aranır (Ad Soyad / TC Kimlik No / empuno Sicil No; gün sütunları 1..31, "1 Pzt", "01.04.2026"); ay sırasıyla istekteki period > tarih başlıkları > başlık üstündeki "Nisan 2026" > sayfa adı > dosya adı (period_source). "Toplam" satırı atlanır. Özet sütunu (ör. "Fazla Mesai %50") ızgaradan türetilenle çelişirse açık değer kazanır, warnings[]'te yazar. 26–25 puantaj düzeni desteklenmez (uyarı; takvim ayı beklenir). Yönetici aynı akışı Bordro → Puantaj → Puantaj Excel'ini yükle ya da Veri Göçü → Dosyadan Aktar → "Puantaj (aylık)" ile yapar.
  • Eksik gün ve prim günü (SGK 2020/20): prim günü = ayın takvim günü − eksik gün; 31 çeken ayda 3 eksik gün → 28 (ücret 30 − ücretsiz gün). Kırılım missing_breakdown; birden çok neden → 12, kırılımla karşılanmayan eksik gün → 13 (kısmi süreli 06, çalışma şekli girilmemiş saatlik 07). 02 kullanılmaz: gelen satır invalid_missing_day_reason ile düşer, ipucu 21 / 19 / 20. Izgarada kırılım gün kodlarından gelir; kırılım alanları (missing_breakdown, sick_days …) yok sayılır ve grid_field_ignored uyarısı döner (PATCH dahil) — günün kodunu değiştirin. Özette sgk_days verilirse kazanır (sgk_days_differs uyarısı). Fişte day_source (attendance | records) ve hour_source (attendance | pdks) hangi kaynağın kullanıldığını söyler.
  • Kilit, tekrar, yeniden hesap: ayın bordrosu onaylı / kesinleşmiş / ödenmiş / hesaplanıyor ya da aktarılmışsa satır failed (code: period_locked, hint payroll.reopen …); gelecek ay period_in_future, çalışanın istihdamda olmadığı ay outside_employment. Aynı içerik tekrar gelirse skipped (duplicate: true); on_existing=update yalnız gönderilen alanları yazar (days tümüyle değişir); silinmiş kayıt yeniden aktarılınca geri gelir (restored). Hesaplanmış dönem yazılır ama yeniden hesaplanmaz: periods[].recalculate_required → payroll.calculate. Yanıt: {created, updated, skipped, failed, results[{index, action, id, employee_id, period, warnings[], derived[], conflicts, reason?, code?, hint?}], periods[]}; dry_run'da id'ler null.
  • Fazla mesai fiyatı: saat ücreti = aylık brüt / bölen (hourly_rate_divisor: 225 varsayılan = 7,5 × 30 | 240 | contract = profildeki haftalık saat × 5); saatlik ücretlide profildeki saat ücreti. Yerleşik çarpanlar parametre setinden (FM 1,5, FS 1,25). Hafta tatili / UBGT çalışması rest_day_work_pay: statutory_additional (varsayılan, 9 Kas 2026'dan beri: 1,5 / 1,0 ilave — 4857 md. 46–47; aylık ücret tatil yevmiyesini zaten içerir) | parameter_set (2,0 / 2,5 ilave — TİS / işveren tercihi, eski varsayılan). Çarpanlar aylık ücrete ilavedir. Gece çalışmasına kanunda zam yoktur: yerleşik ödenmez, gece çarpanlı saat bazlı tür tanımlayın (yoksa night_hours_unpaid uyarısı). Yıllık 270 saat aşımı annual_overtime_limit uyarısı.
  • Saat bazlı kazanç türü ve tek ödeyici: calculation_type=hourly_multiplier + hours_source (overtime_50 | overtime_25 | weekly_rest | holiday | night | manual) + multiplier (0 < x ≤ 10). Tutar = saat × saat ücreti × çarpan (+ gün × günlük ücret × çarpan). Bir kovayı tür ödüyorsa yerleşik fazla mesai o kovayı ödemez; aynı kovaya ikinci tür 0 öder (bucket_multiple_payers uyarısı). manual kaynaklı türde saat çalışan kaleminden (hours; payroll-items.bulk records[].hours). Serbest zaman kullanan çalışanda FM ödenmez. hourly-presets kanuni şablonları ekler (kod hourly_<kova>, tekrar güvenli: var olan skipped); gece için --multipliers.night zorunlu. Ödeyici ve tutar: payroll.attendance.show → preview.priced_buckets[]. Kova listesi: empuno reference hour_sources.
  • Saatlik ücretli (profil salary_type=hourly): brüt = saat ücreti × taban saat (toplam saat − fazla mesai; HT/UBGT çalışma saati tabanda 1× + kova ilavesi). Ücretli hafta tatili / genel tatil saati paid_rest_hours (ızgarada HT/RT günü × haftalık saat / 6; saat PDKS'ten gelse de puantajdan eklenir). Puantajda normal saat yoksa (worked_hours boş, yalnız kodlu ızgara) ücret PDKS saatinden; PDKS de boşsa çalışılan gün × günlük saat (haftalık sözleşme saati / 6, vars. 7,5) + ücretli tatil saati — hourly_hours_from_days uyarısı (aktarımda hourly_hours_missing). Prim günü olup hiç saat yoksa fiş üretilmez (hesap hatası: saat yok). HT/UBGT çalışma saati tabanda 1× + kova ilavesi olduğundan varsayılan statutory_additional'da toplam kanuni 2,5× / 2,0×; rest_day_work_pay=parameter_set'te 3,0× / 3,5× olur → hourly_rest_day_stacking uyarısı. Çalışma şekli girilmemiş saatlikte prim günü = ⌈saat / 7,5⌉ ≤ 30, eksik gün nedeni 07 (bugünkü kural); şekil girilmişse günler takvimden.
  • Kısmi süreli / çağrı üzerine (profil work_schedule: full_time | part_time | on_call + weekly_hours; empuno reference work_schedules; boş = bugünkü hesap): prim günü = ⌈ay içi ücretli saat / 7,5⌉, en çok 30 ve takvim günü; eksik gün nedeni 06; saat önceliği puantaj → PDKS → sözleşme (haftalık saat × gün / 7); aylık ücretli kısmi sürelide PDKS sözleşme saatinin altındaysa (eksik okutma) prim günü sözleşmeden — part_time_hours_below_contract uyarısı (saatlikte ücret de PDKS'ten olduğundan yalnız uyarı); daha az çalıştıysa puantaj (worked_hours) yükleyin. Çağrı üzerine çalışmada sözleşmedeki haftalık saat (boşsa 20) çalışılmasa da ücretlendirilir (4857 md. 14; iz adımında on_call_floor_hours). Kısmi süreliye fazla çalışma yaptırılamaz → part_time_overtime uyarısı (FÇY md. 7); haftalık 30 saat ve üstü kısmi süreli sayılmaz (part_time_threshold). Asgari ücret GV/DV istisnası mw_exemption_partial_month tercihine göre (varsayılan tam ay — GVGT 319). 30 günden eksik bildirimde çalışanın GSS tamamlaması hesaplanmaz.
  • Doğrulama: payroll.simulate attendance.{sgk_days, missing_breakdown, missing_day_reason, worked_hours, paid_rest_hours}, profile.{work_schedule, weekly_hours} ve overtime.{overtime_50_hours, overtime_25_hours, weekly_rest_hours, weekly_rest_days, holiday_hours, holiday_days, night_hours} alır; payroll.employee-slip <dönem> <çalışan> --explain 1 iz adımları days.attendance, days.schedule, salary.hours, overtime.rate, overtime.bucket_*, overtime.rd_excluded; motor uyarıları iz bayrağı attendance.<kod> ve fiş detayında attendance.warnings[] (hesaplamanın attention[] satırlarında code). Simülasyon tercihleri (options.attendance_days_source, attendance_hours_source, hourly_rate_divisor, rest_day_work_pay) doğrulanır — geçersiz değer 422.
  • Panelde aynı uçlar: Bordro → Puantaj sekmesi (Bordro · Puantaj · Mutabakat; ay seçimi, kaynak rozetleri, uyuşmazlık filtresi, kayıt penceresi: gün gün takvim, özet, saatler ve ödeyici, İncelendi), dönem ekranında puantaj özeti ve fişte "P" rozeti, fiş detayında Puantaj ve saatler kartı, Bordro Ayarları → Kazanç türleri "Saat × saat ücreti × çarpan" + Yasal şablonları ekle, Hesaplama tercihleri → "Puantaj ve saatlik ücret", çalışan bordro profilinde Çalışma şekli + haftalık saat, çalışan kaleminde Saat. Çalışan web ve mobil Puantajım ekranında "Bordro puantajı" kartı (attendance_employee_visibility: dönem onayından sonra | hemen | gizli; not ve uyuşmazlık gösterilmez).
bash
# 1) Kodlar ve tercihler
empuno reference attendance_codes          # Ç, HT, HTÇ, RT/UBGT, Yİ, R, Üİ, D, KS … → kanonik değer + SGK eksik gün nedeni + ücret etkisi
empuno reference payroll_options           # attendance_days_source, attendance_hours_source, hourly_rate_divisor, rest_day_work_pay, attendance_employee_visibility
# 2) Excel'den: oku → (tanınmayan kodu eşle) → dene → aktar — CLI tek komutta
empuno attendance import puantaj.xlsx --validate
empuno attendance import puantaj.xlsx --period 2026-04 --map "G=worked,X=absent" [--on_existing update]
# aynı akış ham komutlarla
empuno payroll.attendance.parse --file file=puantaj.xlsx --period 2026-04 --code_map "X=absent"   # yazmaz; records[] + unknown_codes[]
empuno payroll.attendance.commit --json @kayitlar.json --validate   # {"period":"2026-04","on_existing":"update","code_map":{…},"records":[…]}
# 3) Oku / düzelt / sil
empuno attendance show 2026-04 --conflicts_only 1    # = payroll.attendance.index --period 2026-04
empuno payroll.attendance.show 812                   # gün gün + bordro motoru önizlemesi (yazmaz) + uyuşmazlıklar + denetim
empuno payroll.attendance.update 812 --overtime_50_hours 12 --conflicts_reviewed true
empuno payroll.attendance.destroy 812                # o çalışan-ay izin kayıtları + PDKS'e döner
empuno payroll.attendance.export --period 2026-04 --output puantaj.xlsx   # geri okunabilir şablon
# 4) Hesapla (önce önizle)
empuno payroll.calculate 2026-04 --dry_run 1 && empuno payroll.calculate 2026-04
# 5) Saat bazlı kazançlar, çalışma şekli, tercihler
empuno payroll-settings.earning-types.hourly-presets --presets overtime_50,overtime_25,weekly_rest,holiday
empuno payroll-settings.earning-types.store --name "Nöbet" --calculation_type hourly_multiplier --hours_source manual --multiplier 1.5 --applies_to assigned
empuno employees.payroll-items.store 45 --kind earning --type nobet --hours 16 --start_period 2026-11
empuno employees.payroll-profile.update 45 --work_schedule part_time --weekly_hours 24 --effective_from 2026-11-01
empuno payroll-settings.options.update --hourly_rate_divisor contract --rest_day_work_pay parameter_set

Bordro ek kazanç ve kesintileri (prim, ikramiye, yan hak, aidat)

Ek kazanç ve kesinti türleri firma bazında tanımlanır (vergi/prim bayrakları, hesap şekli, kapsam). Kapsam all olan tür her ay tüm çalışanlara varsayılan tutarla girer; assigned tür çalışana kalem atanınca. Kalem süreli (start_period..end_period) ya da tek seferlik olur. Tutarlar SGK, gelir vergisi, damga vergisi ve nete doğru yansır; GV matrahından düşen kesintiler (GVK 63) türün oran sınırıyla uygulanır. Profildeki yemek/yol yardımı tür tanımı gerekmeden ödenir (gün sayısı: allowance_day_basis tercihi).

Kalem eklendikten sonra hesaplanmış dönemi yeniden hesaplayın (payroll.calculate). Kullanılmış tür silinmez, pasife alınır. Saate bağlı kazançlar (fazla mesai, hafta tatili, UBGT, gece zammı, nöbet) için calculation_type=hourly_multiplier türü + kalemde hours — bkz. "Puantaj" bölümü.

BES kesintisini kesinti türüyle tanımlamayın: BES otomatik katılım planı (pension.*) kesintiyi PEK × oran olarak kendisi yapar; elle tanımlı pension kategorili tür varsa kesinti iki kez yapılır (pension.index bunu warnings[]'te bildirir).

bash
empuno payroll-settings.earning-types.store --name "Satış Primi" --category premium --calculation_type manual
empuno payroll-settings.deduction-types.store --name "Özel Sağlık Sigortası" --category insurance --reduces_tax_base true --applies_to all --default_amount 400
empuno reference earning_types
# Tek çalışana tek seferlik kalem
empuno employees.payroll-items.store 45 --kind earning --type satis_primi --amount 12500 --start_period 2026-11
# Toplu (bu ayın primleri) — JSON ya da Excel/CSV
empuno payroll-items.bulk --json @primler.json   # records[]: identity_number|employee_name, type, amount, period, end_period
empuno data-migration.files.parse --kind payroll_items --file file=primler.xlsx
bash
# Sendika aidatı (GVK 63: matrahtan düşer) — yalnız üyelere; aylık tutar = bir günlük ücret (brüt / 30), tutarı ajan hesaplar
empuno payroll-settings.deduction-types.store --name "Sendika Aidatı" --category union --reduces_tax_base true --applies_to assigned
empuno payroll-items.bulk --json @aidatlar.json   # records[]: identity_number, type: sendika_aidati, kind: deduction, amount, period, end_period
# TİS ikramiyesi: brütün yüzdesi; dönem kalemi amount=100 → 1 brüt maaş (50 → yarım)
empuno payroll-settings.earning-types.store --name "TİS İkramiyesi" --category bonus --calculation_type percentage_of_gross
empuno employees.payroll-items.store 45 --kind earning --type tis_ikramiyesi --amount 100 --start_period 2026-12
# TİS'li işyerinde asgari ücret desteği sınırı (günlük PEK 2.600 TL)
empuno payroll-settings.options.update --minimum_wage_support auto --minimum_wage_support_limit collective_agreement

İş avansı (195), fişli masraf ve cepten harcamanın iadesi

İş avansı çalışana şirket harcaması için önceden verilen paradır; maaştan kesilmez, masraflarla kapanır (maaş avansı 196 ayrıdır, bordrodan taksitle düşer). Çalışan kendi cebinden harcadıysa masraf funding=out_of_pocket olur ve onaydan sonra kendisine iade edilir (expenses.mark-paid ile iade yöntemi/ref). Bakiye: verilen − onaylı masraf − iade + şirketin ödediği fark ± düzeltme; 0 olunca avans kapanır.

  • Kim ödedi (funding): out_of_pocket (çalışan — iade edilir, muhasebede 335), work_advance (iş avansından — iade yok, 195 kapanır), company_card. Vermezseniz kart eşleştiyse kart, değilse cepten sayılır; work_advance_id vermeden work_advance seçilirse en eski açık avansa bağlanır.
  • Muhasebe Excel'i (masraf raporu paketi): Kim Ödedi, Karşı Hesap (195/335), Kapanış sütunları ve "Finansman Bazında" sayfası.
  • Çıkışta açık iş avansı çıkış ödemesi önizlemesinde not olarak görünür; kalan tahsil edilmeli ya da belgeyle kapatılmalı (vazgeçilen tutar ücret sayılabilir).
  • Maaş avansı taksit geçmişi: advance-payments.show → history[] (bordro kesintileri dönem dönem + bordro dışı ödemeler; counted=false = dönem henüz ödenmedi). Geçmiş taksitleri aktarırken data-migration.advances.commit satırında installments[] (period, amount, source).
bash
empuno work-advances.store --employee_id 45 --amount 5000 --purpose "Saha turu" --due_on 2026-11-30
# Yönetici çalışan adına fişli masraf: tür/tarih/tutar/KDV AI ile fişten çıkar (Ürün Kuralı #1)
empuno expenses.store --employee_id 45 --file receipt=fis.jpg --funding work_advance
# Mevcut masrafı avansa bağla / bağı kaldır
empuno expenses.work-advance 812 --work_advance_id 7
# Kalan iade edildi (refund) | harcama aştı, fark ödendi (payout) | düzeltme (adjustment, gerekçe zorunlu)
empuno work-advances.record-movement 7 --type refund --amount 350 --method bank --reference "EFT 1234"
empuno work-advances.show 7          # bakiye, bağlı masraflar, hareketler
empuno data-migration.work-advances.commit --json @acik_avanslar.json   # geçişte açık bakiyeler

YK üyesi huzur hakkı, Ar-Ge / teknokent teşviki, SGK meslek kodu

Bunlar çalışanın bordro profilinde (employees.payroll-profile.update) ayarlanır; motor her ay buna göre hesaplar. Profil komutu kısmidir: effective_from zorunlu, gönderilmeyen her alan güncel sürümden taşınır (daha sonraki tarih yeni sürüm açar, aynı/önceki tarih düzeltir; açık null/false temizler). Profili hiç olmayan çalışanda salary_type, ücret ve insurance_group da zorunludur. Geçmiş sürümler: employees.payroll-profile.edit → history[].

  • Ar-Ge hesabı: asgari ücret istisnasından sonra kalan GV × terkin oranı terkin edilir; fazla mesai hariç, brüt asgari ücretin 40 katını aşan kısım teşviksiz. DV aynı payda istisna. SGK: 5510 indiriminden sonra kalan işveren hissesinin (işsizlik hariç) yarısı Hazine desteği. Kapsam ay içinde başlar/biterse teşvikler gün oranında uygulanır ve SGK satırı 05746 + 05510 diye bölünür.
  • Ödeme türü (tax_payment_type): boşsa otomatik — asgari ücretliye 011, diğerlerine 012; huzur hakkı 014. Kıdem (013) ve ihbar (015) çıkış ödemelerinden otomatik ayrılır.
  • Destek personeli sınırı: rd_personnel_type=support olanlar dönem hesabında işe giriş sırasıyla Ar-Ge + tasarım personeli sayısının %10'u (yukarı yuvarlanır; tercih rd_support_personnel_ratio 20) kadar Ar-Ge teşviki alır; sınır dışındaki çalışanın fişinde uyarı vardır ve teşviksiz hesaplanır. Tür boşsa eski davranış (sınır yok).
  • Henüz desteklenmeyen: uzaktan çalışma oranı sınırı (CBK 10766) — kapsam tarihleriyle yönetin.
bash
# Sigortasız YK üyesi (huzur hakkı): SGK yok, GV kümülatif + DV; başka yerde asgari ücret istisnası kullanıyorsa kapatın
empuno employees.payroll-profile.update 45 --insurance_group none --tax_payment_type 014 --mw_exemption_applies false --gross_salary 40000 --effective_from 2026-11-01
# 5746 Ar-Ge merkezi (%80/90/95 GV terkini) — kapsam ay içinde başlıyorsa tarih verin
empuno employees.payroll-profile.update 46 --rd_incentive 5746 --rd_tax_exemption_rate 95 --rd_incentive_start 2026-11-16 --gross_salary 120000 --effective_from 2026-11-01
# 4691 teknokent (%100) 
empuno employees.payroll-profile.update 47 --rd_incentive 4691 --gross_salary 90000 --effective_from 2026-11-01
# Ar-Ge personel türü: destek personeli Ar-Ge + tasarım personelinin %10'u ile sınırlı (tercih rd_support_personnel_ratio 20)
empuno employees.payroll-profile.update 48 --rd_personnel_type support --effective_from 2026-11-01
# Ar-Ge GV terkini + DV istisnası işverende kalsın (net teşviksiz hesaplanır, fişte "işverene kalan" kesintisi)
empuno payroll-settings.options.update --rd_tax_benefit employer
# Yalnız GV terkini işverende (DV istisnası çalışanın netinde) — müşavirin "Ar-Ge GV istisnası, işverene kalır" satırı
empuno payroll-settings.options.update --rd_tax_benefit employer_income_tax
# APHB meslek kodu
empuno employees.update 45 --sgk_occupation_code 2512.01

SGK teşvikleri: ön uygunluk, atama, en avantajlı kanun, asgari ücret desteği

empuno teşvik kataloğu (empuno reference incentive_codes: 6111, 14857, 5746, 3294, 2828, 15921, 7103 … — durum, dayanak, yürürlük / işe alım / yararlanma son günü, belge türü, formül, süre kuralı, gereken bilgiler, kaynaklar) ve çalışanın verisiyle (yaş, cinsiyet, işe giriş, engellilik, önceki 6 ayın fişleri) her çalışan için kanun bazlı ön uygunluk çıkarır. Türetilemeyen bilgiler (işe girişten önceki 6 ay sigortasız mı, İŞKUR kaydı, mesleki belge, sosyal yardım, işsizlik ödeneği kalan gün) teşvik bilgisi olarak bir kez girilir. Dönem hesabında motor çalışanın aktif atamaları arasından TL olarak en avantajlı TEK kanunu uygular (5510 puanı birleşebilen kanunlarda dahil); seçilen kanun fişe ve APHB'ye yazılır, incentive_breakdown formülü, bileşenleri ve alternatifleri taşır.

  • Öneri ≠ uygulama: apply varsayılan olarak proposed yazar; motor yalnız active atamayı uygular. Teyit gerektiren kanunlar (02828, 26322, 55225/25225, 16322/25510) otomatik önerilmez, aktif atamada incentive_confirm_required uyarısı döner. Ön uygunlukta uygun olmayan satır force=true olmadan failed (incentive_ineligible / incentive_window_ended).
  • Ret kodları (422, flash.rule / satırda code): incentive_unknown_law (hint: empuno reference incentive_codes), incentive_expired (expired: benefit_until …), incentive_not_assignable (05510/00000 firma ayarı payroll-settings.update --auto_apply_incentive, 05746 bordro profili), incentive_dates_invalid, incentive_fact_invalid.
  • Süre: verilmezse katalogdan — 6111'de kadın ve 18–28 yaş erkek: MYK belgesi 48, mesleki-teknik eğitim / İŞKUR kursu 36, diğer 24 ay (+6 İŞKUR kayıtlı); 29+ erkek: belge 24 (+6), belgesiz İŞKUR 6 ay. Bilgi eksikse en kısa süre + uyarı. Atama başlangıç ayı dahil duration_months ay uygulanır, süresi dolan fişte incentive_duration_ended uyarısı.
  • Hesap: 6111 işveren hissesinin tamamı (PEK üzerinden), 14857 / 3294 asgari ücret tabanı üzerinden işveren hissesi + 5510 puanı, 5746 Ar-Ge kalan işveren hissesinin yarısı (motorun Ar-Ge hesabı), 2828 / 26322 tüm hisseler taban üzerinden, 15921 işsizlik ödeneği süresince. SGDP ve sigortasızda teşvik 0. payroll-settings.update --auto_apply_incentive false firmada 5510'u kapatır (kanun 00000). payroll-settings.update kısmidir: gönderilmeyen alan (5510 dahil) korunur; 5510 ya da sektör değişirse yanıtta effects + recalculate_required.
  • İlave istihdam (6111, 3294): şart her ay aranır — dönemde bildirilen sigortalı sayısı çalışanın işe girişinden önceki 6 ayın ortalamasını aşmıyorsa dönem hesabı incentive_additional_employment_not_met uyarısı verir (tutar değişmez; müşavirle teyit edin).
  • Bordro profilindeki eski alan active_incentive_code normalize edilir (6111 → 06111), katalogda yoksa 422; atanabilir kanun çalışanın atamalarına legacy_profile kaynağıyla yansır ve yansıma TEK KAYNAKTIR: satırı reddetmek / silmek / sonlandırmak teşviki durdurur (fişte legacy_incentive_closed uyarısı), kodu değiştirmeden profili kaydetmek satırı yeniden açmaz. Yeniden uygulamak: employees.incentives.update … --status active. Yeni kayıt için employees.incentives.store kullanın.
  • Asgari ücret desteği (reference minimum_wage_support): tercih minimum_wage_support off (vars.) | auto (önceki yılın aynı ayında düşük PEK'li gün sayısı kadar; 2026: 42,33 TL/gün, günlük PEK sınırı 1.300 — TİS 2.600, yeraltı 3.467: minimum_wage_support_limit) | all_days. Destek dönem sonunda SGK işyeri (sicil) bazında hesaplanır (her işyerinin tavanı kendi önceki yıl bildiriminden, kalan primle sınırlı; nakil ayında kişinin günü işyerlerine bölünür — beyanla aynı işyeri önceliği; işyeri tanımı yoksa tek grup), fişlere gün oranıyla dağıtılır ve izleyen ay primlerinden mahsup edilir; işveren maliyetinden düşer, net ve SGK primini değiştirmez. Aktarılmış fişler desteğe katılmaz ve değiştirilmez. Kırılım summary.employer_supports.minimum_wage_support.by_workplace (+ --sgk_workplace_id filtresinde o işyerinin payı).
  • Beyan ve özet: payroll.declaration → summary.employer_supports (kanun bazında kişi + tutar, Ar-Ge SGK desteği, asgari ücret desteği, işverene kalan Ar-Ge vergi teşviki, BES, işveren maliyeti); payroll.show → employer_supports; Excel Özet sayfası "İşveren desteği" satırları.
  • Simülasyon: payroll.simulate incentives[]{law_no, start_date, duration_months}, apply_5510, options.minimum_wage_support alır; ay satırında employer_supports (seçilen kanun, BES, asgari ücret desteği tahmini).
  • Geçiş: empuno migrate incentive-facts tesvik.csv (TC + bilgi sütunları + Kanun No + Başlangıç).
  • Panelde aynı uçlar: Bordro Ayarları → Teşvikler sekmesi (uygunluk tablosu, öneri, uygula), çalışan bordro profili → Teşvikler kartı ve teşvik bilgileri. Teşvik bilgileri KVKK hassas: yalnız bordro yetkisiyle görünür, çalışan ve mobil uçlarına girmez.
bash
empuno reference incentive_codes                   # katalog; atanabilenler assignable=true
empuno payroll-settings.incentives.index --status needs_confirmation --per_page 100
#   satır: options[{law_no, status applied|eligible|needs_confirmation|ineligible|expired, reasons[], missing_facts[],
#   window{start,end,months_total,months_left}, estimated_monthly, gain_monthly}], recommendation, data_gaps[]
empuno reference incentive_fact_keys               # bilgi anahtarları, türleri, hangi kanunlar kullanıyor
empuno employees.incentive-facts.update 45 --uninsured_6_months_before_hire true --iskur_registered_unemployed true
empuno payroll-settings.incentives.apply --json @oneriler.json --dry_run true   # rows[]{employee_id, law_no?, start_date?, status?}
empuno payroll-settings.incentives.apply --all_recommended true                 # önerisi olan herkes → proposed
empuno employees.incentives.update 45 812 --status active   # e-SGK tanımlamasından sonra uygula
empuno employees.incentives.store 46 --law_no 14857         # elle atama (vars. active, başlangıç işe giriş, süre katalogdan)
empuno payroll-settings.options.update --minimum_wage_support auto

BES otomatik katılım: plan, katılımcılar, cayma, kurum aktarımı

Firma emeklilik şirketi sözleşmesini plan olarak ekler (pension.plans.store: şirket, sözleşme no, başlangıç, varsayılan oran %3, isteğe bağlı işveren katkısı). Plan başlangıcından SONRA işe giren, 45 yaşını doldurmamış Türk vatandaşı çalışan (sigorta grubu normal / SGDP) dönem hesabında otomatik dahil edilir; öncekiler pension.sync ile (önce --validate). Kesinti her ay PEK × oran'dır: netten düşer, GV matrahından indirilmez; fişte BES satırı ve pension_employee_contribution. 45+ yalnız talebiyle (voluntary=true), doğum tarihi boş olan "teyit gerekli" (otomatik dahil edilmez; plan sonrası işe girdiyse dönem hesabı pension_enrollment_needs_birth_date uyarısı verir — doğum tarihini girip yeniden hesaplayın ya da employees.pension.store), yabancı uyruklu kapsam dışıdır.

  • Kurallar (4632 ek md. 2; Yönetmelik 22/E–22/I, reference pension_actions): cayma yalnız plana dahil olduğunun bildirildiği tarihten (yoksa dahil olma) itibaren 2 ay içinde — sonrası 422 pension_opt_out_deadline_passed (hint: leave_system ya da pause); başlangıç döneminde ayrılma/ara verme yerine cayma (pension_use_opt_out); oran %3'ün altına inemez (pension_rate_below_legal). Cayma iadesini emeklilik şirketi 10 iş günü içinde yapar — bordrodan iade yapılmaz. İşlemler hemen uygulanır, sonraki hesapta kesinti buna göre yapılır/durur; her işlem hareket olarak yazılır.
  • Çalışan talebi (web Bordrom → BES kartı, mobil /api/v1/pension): cayma, ayrılma, ara verme, devam, oran, katılım — yönetici onayı beklemez; payroll.manage yetkilileri uygulama içi bildirim alır, e-posta gitmez. Aynı talep tekrarlanırsa yazılmaz.
  • İşveren katkısı: tercih bes_employer_contribution wage (vars.; brüte kazanç olarak eklenir — SGK'da asgari ücretin %30'una kadar istisna, GV/DV'ye tabi — ve aynı tutarda karşı kesintiyle şirkete aktarılır, net değişmez) | expense_only (yalnız işveren maliyeti). Brüt yüzdesi (percent_of_gross) KAZANILAN ücret üzerinden — ay içinde giren / çıkan çalışanda kıst; sabit tutar aylıktır. Kesinti sırası: bes_deduction_order before_garnishment (vars.; icra matrahından önce) | after_garnishment.
  • Kurum aktarımı: son gün ücret ödeme gününü izleyen ilk iş günü (dönem paid_at); overdue bayrağı. Excel plan başına sayfa + "Kesinti Yok" (caydı / ara veriyor / ayrıldı). "Aktarıldı" işareti dönem + plan başına tektir.
  • Kaynak sözleşmesi (reference payroll_line_sources): çalışan kesintisi source_type=App\Models\EmployeePensionEnrollment, işveren katkısı kazancı bes_employer_contribution + karşı kesinti pension_employer_passthrough, işverene kalan Ar-Ge vergi teşviki rd_employer_benefit.
  • Panelde aynı uçlar: Bordro Ayarları → BES sekmesi (planlar, katılımcılar, toplu dahil et, hareketler), çalışan bordro profili → BES kartı, dönem ekranı → Çıktılar → BES Aktarım Listesi.
bash
empuno pension.plans.store --provider_name "Örnek Emeklilik" --contract_no GRP-123 --starts_on 2026-01-01 [--employer_contribution_type fixed --employer_contribution_value 250]
empuno pension.sync --validate                          # kimler dahil olur (45+, yabancı, doğum tarihi boş, plan öncesi giriş nedenleriyle)
empuno pension.sync --include_existing_hires true      # plan öncesi işe girenleri de dahil et
empuno pension.index --status active --per_page 100     # katılımcılar + istatistik + son 20 hareket
empuno employees.pension.show 45                        # kayıt, kapsam, yapılabilir işlemler (can{}), hareketler, kesinti geçmişi
empuno employees.pension.action 45 301 --action opt_out                  # cayma: bildirimden 2 ay içinde
empuno employees.pension.action 45 301 --action pause --until 2027-03-31
empuno employees.pension.action 45 301 --action rate_change --rate 5
empuno employees.pension.update 45 301 --certificate_no SRT-123 --notified_at 2026-10-15
empuno payroll.pension-transfer 2026-10                  # kurum aktarım listesi (TCKN maskeli), son gün, durum
empuno payroll.pension-transfer-export 2026-10 --plan_id 2 --output bes-2026-10.xlsx
empuno payroll.pension-transfer-mark 2026-10 --plan_id 2 --reference "DEKONT-55"   # tekrar güvenli
empuno migrate pension bes.csv --validate               # önceki sistemin katılımcı listesi

SGK (APHB) + MUHSGK mutabakatı

Hesaplanmış ya da aktarılmış her dönem için müşavirin beyannameyle satır satır karşılaştıracağı veri: SGK satırları (belge türü, kanun no, prim günü, hak edilen ücret + prim/ikramiye, eksik gün sayısı ve nedeni, giriş/çıkış + çıkış kodu, meslek kodu, işyeri sicil no, işçi/işveren payları, teşvik, Ar-Ge desteği), vergi satırları (ödeme türü başına GV matrahı, hesaplanan GV, asgari ücret istisnası, Ar-Ge terkini, GV/DV kesintisi), bordro detayı ve özet. Toplamlar fişlerle kuruşu kuruşuna tutar. Yan etkisizdir (GET).

  • Kaynak kuralı: fişteki açık değer (aktarım ya da elle düzeltme) > türetme > varsayılan. Aktarılmış fişte çalışanın BUGÜNKÜ bordro profili okunmaz (geçmiş ay bugünkü ayarla yeniden yorumlanmaz). Her SGK/vergi satırında sources{} alanın nereden geldiğini söyler: import (aktarım), manual (elle düzeltildi), derived (türetildi), profile (bordro profili), employee (çalışan kartı), auto (asgari ücretten), engine (empuno hesapladı), none; açıklaması notes{}.
  • Türetme: kanun no aktarılmış fişte employer_incentive_code'dan (5510 → 05510; listede olmayan 5 haneli kod "Kanun XXXXX" ile aynen girer), empuno fişinde teşvik tutarı > 0 → 05510. Belge türü işçi payı %7,5 ve işsizlik 0 ise 02 (SGDP), değilse 01. İşçi SGK = işçi prim toplamı − işsizlik payı. Ödeme türü: aktarılmış fişte sigortasız (insurance_group=none ya da PEK = 0 kuralı) → 014 (huzur hakkı); dönemin parametre seti varsa (2021–2026 hepsinde var; 2022 öncesi her zaman 012) ücret ≤ brüt asgari ücret → 011, değilse 012 — çıplak ücret aktarılmamışsa toplam brüt − ek kazanç − fazla mesai; fişteki vergi kesintisi bununla çelişirse (asgari ücretli ama GV/DV kesilmiş, ya da asgari ücretin üstünde ama GV = DV = 0) tür yine ücretten gelir, info satırı payment_type_tax_mismatch müşavirin beyanını kontrol etmenizi söyler; set yoksa GV ve DV 0 ise 011. Farklıysa tax_payment_type verin. Kanun no 05746 iken Ar-Ge günü boşsa tüm prim günü Ar-Ge sayılır; eski veride açık 0 varsa yine tüm gün sayılır ve rd_days_conflict uyarısı döner.
  • PEK = 0 kuralı: brüt ödemesi olup SGK matrahı ve primi 0 olan kişi sigortasız sayılır, APHB'ye girmez (bilgi treated_as_uninsured) ve MUHSGK ana satırı 014 (huzur hakkı) türetilir; insurance_group=none her durumda APHB dışıdır, yalnız vergi satırı alır. Brütü 0 olan ya da eksik gün nedeni verilmiş 0 PEK'li sigortalı APHB'de 0 günlük satır olarak kalır — missing_day_count + missing_day_reason ekleyin.
  • Kıdem / ihbar dağıtımı (MUHSGK): kalemin vergisi aktarımda verilmişse (earnings[].income_tax / stamp_tax) 013/015 satırı aynen alır. Verilmemişse kalem DV = kalem tutarı × binde 7,59, GV kalem matrahı oranında (artan oranlı tarifede yaklaşık — kesin değer için kalem vergisini gönderin). Asgari ücret ve Ar-Ge istisnaları önce ücrete, artarsa ihbara, sonra kıdeme; ücret satırı kalanı alır, toplamlar fişle tutar. Hesaplanan GV = kesilen + AÜ istisnası + Ar-Ge terkini.
  • Uyarılar: warnings[].level = warning (beyandan önce tamamlanmalı: eksik TC, Ar-Ge tutarı yok, kanun no 05746 ama Ar-Ge günü 0 (rd_days_conflict), eksik gün nedeni yok…) | info (türetme açıklaması: sigortasız sayıldı, SGDP türetildi, işsizlik payı yok, ödeme türü türetildi, ödeme türü vergi kesintisiyle çelişiyor — payment_type_tax_mismatch). Aktarılmış dönemde summary.source_coverage hangi beyan alanının kaynaktan geldiğini, hangisinin türetildiğini sayar.
  • Düzeltme: payroll.declaration.update <dönem> <çalışan> — aktarılmış fişte tüm beyan alanları (kırılım değişince yalnız türevler yeniden kurulur: hesaplanan GV/DV, işveren SGK − teşvik − Ar-Ge desteği); empuno'nun hesapladığı fişte yalnız tutarı etkilemeyenler (eksik gün nedeni, meslek kodu, işyeri sicil no, ödeme türü) — belge türü, kanun no ve sigorta türü 422 döner; prim günü temizlenemez (boş/null 422): bordro profili / çalışan kartı düzeltilip dönem yeniden hesaplanır (kesinleşmişse önce payroll.reopen). Elle düzeltme yeniden hesaplamada korunur. Yanıt updated {type: payroll_slip, id, fields}; değişiklik yoksa fields boş. Fiş detayı (payroll.employee-slip) aynı değerleri declaration altında okur.
  • Eksik gün nedeni empuno'nun hesapladığı fişe hesap anında yazılır: 01 istirahat, 21 diğer ücretsiz izin, 15 devamsızlık, 06 kısmi süreli çalışma, 07 puantaj (çalışma şekli girilmemiş saatlik), 13 diğer (kırılımla karşılanmayan eksik gün), 12 birden fazla, 25 kanun bölünmesi; puantajı olan çalışan-ayda neden puantajın missing_breakdown'ından (gün kodlarının SGK karşılığı: 19, 20, 18, 03 …) gelir — bkz. "Puantaj" bölümü. Bu özellikten önce hesaplanmış empuno fişinde neden boştur (uyarı döner) — dönemi yeniden hesaplayın. Aktarılmış dönem yeniden hesaplanmaz: nedeni payroll.declaration.update ya da --update_fields declaration ile gönderin; neden verilip sayı verilmezse eksik gün = 30 − prim günü sayılır.
  • SGK işyeri: her satırda sgk_workplace_id, workplace_name, workplace_registration_no(_formatted) ve workplace_source (segments | slip | registration_no | registration_no_unmatched | timeline | default | none). Nakil ayında kişi işyeri başına satır alır; --sgk_workplace_id filtresi ve summary.by_workplace için bkz. "Çalışma dönemleri" bölümü. Firmada SGK işyeri tanımı yoksa çıktı işyerisiz eski hâliyle aynıdır.
  • Excel'de kod sütunları metindir (05510, 01 baştaki sıfırla kalır); SGK sayfasında İşyeri Sicil No ve Kaynak (işyeri tanımlıysa İşyeri), Uyarılar sayfasında Düzey sütunu; birden çok işyeri varsa İşyerleri + "APHB – <ad>" sayfaları. GİB/SGK XML'i üretilmez (şema kamuya açık değil); dosya mutabakat ve beyan girişi içindir.
bash
empuno payroll.declaration 2026-04                              # JSON: sgk_rows[], tax_rows[], detail_rows[], summary, warnings[], attributes{}
empuno payroll.declaration-export 2026-04 --output mutabakat.xlsx  # Özet · SGK (APHB) · Vergi (MUHSGK) · Bordro Detayı · Uyarılar (+ işyeri sayfaları)
empuno payroll.declaration 2026-04 --sgk_workplace_id 2              # yalnız bir SGK işyeri (MUHSGK her sicil için ayrı)
# Tek fişi düzelt (yalnız gönderilen alanlar; null siler; denetim kaydı tutulur)
empuno payroll.declaration.update 2026-04 101 --insurance_group none --tax_payment_type 014 --reason "YK huzur hakkı"
empuno payroll.declaration.update 2026-04 107 --missing_day_count 1 --missing_day_reason 15
empuno payroll.declaration.update 2026-04 103 --rd_law 5746 --rd_rate 95 --rd_income_tax_exemption 12450.30 --rd_sgk_support 4120.55
# Toplu (aktarılmış aylar): yalnız beyan alanları
empuno migrate payroll beyan.csv --on_existing update --update_fields declaration --validate

Raporlar: bordro dökümü, icmal, GV listesi, personel listeleri, ücret hesap pusulası

Luca "Raporlar" menüsünün karşılıkları. Hepsi yan etkisiz GET; aynı komut --format json (vars.) | xlsx | pdf verir (dosyada --output). Kaynak kayıtlı fişler ve çalışma dönemleri; iptal edilmiş / silinmiş dönem hiçbir rapora girmez. Bordro raporları ve pusula payroll.view, personel raporları employees.view ister (ücret sütunu ayrıca payroll.view). Rapor adları: empuno reference payroll_reports / personnel_reports.

Aktarılmış (müşavir) fişlerde SGK işçi payı bileşenlere ayrılmadan geldiyse rapor SGK toplamı − işsizlik işçi payı gösterir; fişte işyeri yoksa dönem sonundaki çalışma dönemi işyeri (sigortasız dönemde boş) kullanılır. Çalışan kendi pusulasını panelde Bordrolarım → PDF ile indirir.

bash
empuno reports.payroll --report register --period 2026-10                 # bordro dökümü: kişi başına tüm kazanç/kesinti/matrah/vergi + TOPLAM
empuno reports.payroll --report icmal --period 2026-10 --format pdf --output icmal.pdf   # işyeri/bölüm kırılımlı icmal + kanun kırılımı
empuno reports.payroll --report yearly --year 2025                          # kişi başına yıl toplamı + yıl sonu kümülatif GV matrahı
empuno reports.payroll --report income_tax --year 2025 --format xlsx --output gv.xlsx   # kişi × ay GV matrahı ve GV
empuno reports.payroll --report salary_summary --period 2026-10             # net, kesinti, banka (IBAN maskeli)
empuno reports.payroll --report rd --period 2026-10                         # Ar-Ge / Ar-Ge dışı (istisnalar, SGK desteği)
empuno reports.payroll --report employee_info --period 2026-10 --sgk_workplace_id 8
empuno reports.personnel --report list --as_of 2026-11-11 --include_leavers 1 --show_salary 1 --show_bank 1
empuno reports.personnel --report registry --as_of 2023-06-30             # o tarihteki işyeri sicili (sicil geçmişinden)
empuno reports.personnel --report exits --from 2026-01-01 --to 2026-10-31  # SGK + İŞKUR çıkış nedeni, nakil işaretli
empuno reports.payslips --period 2026-10 --output pusulalar.pdf            # ücret hesap pusulası (4857 md. 37), dönemin tümü
empuno reports.payslips --period 2026-10 --employee_ids 45 --format json   # tek kişi, belge verisi
empuno payroll-settings.update --payslip_note "Ücretiniz her ayın 5'inde yatırılır."   # pusulanın altına basılır

Zorunlu personel evrakı ve eksik evrak listesi

Kurulum gerekmez: varsayılan liste işe girişte iş sözleşmesi, SGK işe giriş bildirgesi, KVKK aydınlatması, işe giriş sağlık raporu (İSG) ve kimlik belgesi (kimlik kartı / pasaport / diğer — biri yeterli); işten çıkışta SGK işten ayrılış bildirgesi ve istifa dilekçesi / fesih bildirimi / devir protokolünden biri. Firma kalemleri açar/kapatır (diploma, ikametgâh, nüfus kaydı, adli sicil, askerlik — yalnız erkek, NDA, ibraname, kıdem/ihbar hesabı). Kalemler: empuno reference document_requirements. Okuma documents.view, liste değişikliği documents.manage.

Kimlik belgesi (AI): employees.identity-documents.store <çalışan> --file file=./kimlik.pdf (PDF, ilk 3 sayfa) ya da --file images[]=./on.jpg --file images[]=./arka.jpg — yapay zekâ türü (kimlik / pasaport / ehliyet) ve alanları (ad, soyad, TC, doğum tarihi, cinsiyet, uyruk) okur, belge saklanır; apply=missing (vars.) çalışanın yalnız BOŞ alanlarını doldurur, dolu alanın üzerine yazmaz; apply=none yalnız field_diff döner. Yanıt data.document, extracted, field_diff[], applied{}, skipped{}, credits_consumed (sayfa başına 1 AI kredisi; yetersizse 402 insufficient_credits). Üzerine yazmak için employees.identity-documents.apply <çalışan> <belge> --json '{"fields":{"first_name":"Ayşe"}}'; liste employees.identity-documents.index <çalışan>. Yetki identity_documents.view|manage; belge çalışana gösterilmez (KVKK), bildirim yok, deneme (--validate) desteklenmez (AI + dosya).

Yanıt: summary (employees_checked, employees_with_missing, missing_total, by_requirement kalem başına eksik çalışan sayısı) ve sayfalı rows (çalışan + missing[]: key, stage, label, types). İşe giriş aşaması her çalışana, çıkış aşaması yalnız ayrılana uygulanır; kalemin türlerinden biri yüklüyse tamamdır. documents.requirements.update aşamanın listesinin tamamını alır, gönderilmeyen aşama aynen kalır; boş liste o aşamada hiçbir evrakı zorunlu tutmaz. Eksik evrakı employees.documents.store (kimlik için employees.identity-documents.store) ya da toplu migrate documents ile tamamlayın.

bash
empuno documents.missing                                   # aktif çalışanlarda eksik zorunlu evrak (yalnız eksiği olanlar)
empuno documents.missing --status terminated --requirement termination_basis   # ayrılanlarda istifa/fesih belgesi eksik olanlar
empuno documents.missing --employee_id 45                  # tek çalışan (eksiksizse missing_count 0)
empuno documents.requirements                              # firmanın listesi (source: default | company) + tüm kalemler
empuno documents.requirements.update --json '{"required":{"onboarding":["is_sozlesmesi","sgk_ise_giris","kvkk","isg","identity","diploma"]}}'

Luca Köprüsü: gelen zarflar ve Luca bordrosu ↔ kayıtlı fişler

Firma bir Luca şirketine eşliyse (eşleme empuno ekibinde; eşli değilse 404) Luca'dan gelen zarfları ve her zarf türünün empuno'da neye yansıdığını görürsünüz. Yetki luca_bridge.view; başarısız zarfı yeniden işletmek luca_bridge.manage; bordro karşılaştırması ayrıca payroll.view ister. Luca verisi canlı kayıtlara doğrudan yazılmaz: personel kartı ve bordro geçmişi yalnız önizleme + onaylı aktarımla güncellenir.

Luca'ya aktarım: luca-bridge.export.timesheet Luca'nın puantaj CSV'sini üretir (işyeri × ay; ISO-8859-9, ;, her alan tırnaklı; gün kodları N normal, H hafta tatili, T resmi tatil, S yıllık izin, R rapor, E eksik gün, İ diğer izin; eksik gün nedeni SGK kodu). Ay içinde giren/çıkan kişiye Luca toplu puantaj uygulamaz → dosyada değil manifest.manual[]'da (gün kodlarıyla); sigortasız ve Luca'da kartı olmayanlar excluded[]. luca-bridge.export.personnel Luca'nın boş "LUCA Personel Giriş Şablonu"nu doldurur (--mode new Luca'da kartı olmayanlar, update işyerinin tüm personeli; güncellemede empuno'da boş alan Luca kartındaki değerle). Varsayılan çıktı zip (dosya + manifest.json: sha256, satır, expected = empuno fişlerinden kişi sayısı, brüt, net, SGK işçi, işsizlik, GV, DV — Luca hesapladıktan sonra karşılaştırma için); --format file | manifest. Yan etkisiz; Luca eşlemesi şart değil. Yetki luca_export.view (mali müşavirlerde varsayılan luca_export.manage) + employees.view (personelde ve kontrol ekranında + payroll.view). Yüklemeyi mali müşavir yapar: önce luca-bridge.export.index (puantaj, elle girilecek / dosyada olmayan kişiler, kart eksikleri, empuno bordrosu; --format xlsx kontrol listesi) ile inceler. Yükleme izi: luca-bridge.export.packages.store --period 2026-10 --kind timesheet|personnel_update|personnel_new --status reviewed|uploaded --content_sha256 <manifest.trail.content_sha256> kim / ne zaman kaydı tutar; dosya indirildikten sonra veri değiştiyse rule=content_changed, aynı ay × işyeri × tür zaten yüklendiyse rule=already_uploaded (önce luca-bridge.export.packages.destroy <id> --reason … ya da --force true --notes …); aynı içerikle tekrar no-op. Liste luca-bridge.export.packages (changed_since: yüklendikten sonra veri değişti mi).

Luca'dan empuno'ya dosya (aynı biçimler, ters yön): mali müşavirin Luca'dan indirdiği dosyalar dönüştürülmeden okunur; yanıtta source_format hangi Luca düzeninin tanındığını söyler. Puantaj (payroll.attendance.parse, luca_csv | luca_xls | luca_xls_detailed): Luca gün kodları yalnız Luca dosyasında uygulanır (N/G/O çalıştı, H hafta tatili, T resmi tatil, S yıllık izin, R rapor, İ ücretli izin; E eksik gün nedenine göre — 21 ücretsiz izin, 15 devamsızlık …; Y/K/C yarım gün unknown_codes), dönem AY+YIL ya da başlıktan, detaylı XLS'te Fazla Mesai / Gece Mesaisi saatleri puantaja girer, NET tutar kolonları luca_extras[]'ta listelenir (yazılmaz); kayıtlar payroll.attendance.commit'e. Personel (data-migration.files.parse --kind employees, luca_personnel): Luca'nın 40 kolonlu şablonu / "Rapor" çıktısı, kredisiz; NET ücret kart maaşına yazılmaz (not), kanun no / SGK grubu / net-brüt luca{} ipucu; kayıtlar data-migration.employees.commit'e (--on_existing update kart alanlarını Luca'ya göre günceller; yalnız harf büyüklüğü farklı ad ezilmez). Bordro (data-migration.files.parse --kind payroll, luca_payroll): Luca "Bordro" Excel'i → data-migration.payroll.commit (kayıtlı fiş varsa varsayılan skip); Luca kuralları: kesilen GV = Gel.Ver. − 5746 GV İst., SSK Teşviki 5746 Ar-Ge SGK desteğini de içerir (ayrım dosyada yok, satıra not), Net Kazanç özel kesintiden sonraki ele geçendir. Forwardie'nin 67 aylık Luca Bordro dosyası kayıtlı 1.700 fişle 20.400 alanda farksız.

payroll-compare yan etkisizdir: summary.statuses (match, diff, no_slip, no_period, no_employee, not_in_luca), summary.fields (alan başına fark sayısı), months[] ve sayfalı rows (her satırda diffs.{alan}: {luca, empuno, delta}). Luca nakil ayında aynı kişi için birden çok bordro gönderirse kişi-ayda toplanır; kümülatif GV matrahı ayın son değeridir. not_in_luca: empuno'da fiş var, Luca'da o kişi-ay bordrosu yok.

bash
empuno luca-bridge.index                                   # özet: zarflar, yansımalar, son personel / bordro aktarımı
empuno luca-bridge.envelopes --status failed [--type export.bundle] [--year 2026]
empuno luca-bridge.envelopes.reprocess 01M71C…             # başarısızı sunucuda yeniden işlet
empuno luca-bridge.payroll-compare --status issues         # yalnız farklı / eksik kişi-aylar
empuno luca-bridge.payroll-compare --year 2023 --per_page 100
# Luca'ya geri aktarım (Luca yazma servisi yok, bordroyu kendisi hesaplar; yükleme Luca ekranından)
empuno luca-bridge.export.timesheet --period 2026-10 --sgk_workplace_id 8 --output puantaj.zip   # CSV + manifest.json
empuno luca-bridge.export.personnel --period 2026-10 --mode new --output personel.zip           # LUCA Personel Giriş Şablonu
empuno luca-bridge.export.timesheet --period 2026-10 --format manifest                          # yalnız manifest (JSON)
empuno luca-bridge.export.index --period 2026-10 --format xlsx --output kontrol.xlsx              # mali müşavir kontrol listesi
# Luca'dan empuno'ya: Luca'nın kendi dosyaları olduğu gibi okunur (önce parse, sonra ilgili commit)
empuno payroll.attendance.parse --file file=./puantaj_2026_11_ALSANCAK.csv          # Luca puantaj CSV / XLS / detaylı XLS
empuno data-migration.files.parse --kind employees --file file=./personel_rapor.xls # Luca personel Excel'i
empuno data-migration.files.parse --kind payroll --file file=./bordro_2026_11.xlsx   # Luca "Bordro" Excel'i

Bordro çıktıları: muhasebe fişi ve banka maaş dosyası

Hesaplanmış ya da aktarılmış her dönem için iki dosya: muhasebe fişi (yevmiye: ücret gideri, SGK işveren payı, 335 net ödeme, 360 GV + DV, 361 SGK, kesintiler ve destekler; borç = alacak kuruşu kuruşuna, fişlerle mutabakat) ve banka maaş ödeme dosyası (IBAN + tutar listesi; bankanın internet şubesine yüklenir). Önizlemeler yan etkisizdir (GET). Hiçbir dosya muhasebe programına ya da bankaya otomatik GÖNDERİLMEZ.

  • Varsayılan hesaplar (Tekdüzen): ücret ve SGK işveren payı gideri {root} (departman/şube gider kökü; vars. 770 Genel Yönetim), net ücret 335, GV ve DV 360, SGK (işçi + işveren + işsizlik) 361, avans mahsubu 196, icra/nafaka/sendika/BES/diğer kesinti 336, teşvik ve Ar-Ge desteği (tercihe göre giderden indirilir ya da 602), asgari ücret desteği alacağı 136, kuruş farkı 649/659, banka 102. Firmanın eşlemesi yoksa fiş yine dengelidir; mapping.defaults_used hangi kalemin varsayılanla yazıldığını söyler.
  • Bütünlük: fiş başına 1,00 ₺'yi aşan iç fark kuruş farkı değildir — askı satırına (399 / 199) yazılır ve yanıtın integrity bloğunda listelenir: ok, blockers[] (slip_inconsistency, employer_cost_gap), inconsistent_slips, inconsistent_total, slips[] (slip_id, employee_id, amount, findings[]: net_mismatch | deduction_rows_missing | earnings_exceed_gross | employer_side). ok=false iken can_post=false; payroll.accounting-postings.store 422 voucher_integrity döner, bilerek işaretlemek için --accept_integrity_issues true. Kaynağı düzeltin: aktarılan fişte her ek kesinti deductions[] satırıyla, işverende kalan Ar-Ge terkini type: rd_retained ile gönderilir.
  • Eşleme çözüm sırası: çalışan → departman → şube → firma geneli → varsayılan; bulunamazsa yedek zincir (ör. deduction:<kod> → deduction_category:<kategori> → deduction_other). Gider kalemlerinde {root} yer tutucusu departman/şube gider köküne (line_key=expense_root, scope_type department | branch) çözülür: wage → {root}.01 ile her masraf merkezi kendi 7xx hesabına yazar. account_code=null eşlemeyi siler (varsayılana döner); her satırda account_code anahtarı ZORUNLU, account_name/cost_center gönderilmezse korunur.
  • Aktarılan kesintiler: önceki sistemden tipli gelen kesinti (import:<tür>) türünden eşlenir; yalnız adıyla gelen eski kesinti adına göre sınıflanır (avans → 196, icra/haciz, nafaka, sendika, BES → 336, Ar-Ge) ve import_deduction_classified uyarısı döner — yanlışsa import_deduction:<anahtar> satırını (reference payroll_account_lines) doğru hesaba eşleyin.
  • Fiş türleri: tahakkuk (accrual), ödeme (payment: 335 / 102), düzeltme (correction = güncel tahakkuk − muhasebeleştirilmiş kayıtlar; yalnız fark satırları). Muhasebeleştirme işareti yalnız kesinleşmiş/ödenmiş dönemde; aynı özet tekrar gönderilirse yeni kayıt açılmaz. Tahakkuk sonrası dönem düzeltildiyse (payroll.reopen) payroll.show → outputs.changed_after_posting=true ve tahakkuk tekrarı 422 already_posted. outputs.change_kind: amounts (bordro tutarı değişti) | reclassification (tutarlar aynı; hesap/masraf merkezi eşlemesi ya da fiş tercihi değişti — düzeltme fişi yalnız hesaplar/masraf merkezleri arası aktarım satırı içerir).
  • Masraf merkezi: satırda cost_center görünen ad, cost_center_key kararlı kimliktir (department:<id> | branch:<id> | code:<eşlemedeki kod>); toplama, muhasebeleştirme özeti ve düzeltme kimliğe bakar — departmanı yeniden adlandırmak muhasebeleştirilmiş dönemi değiştirmez. Boyut kaynağı cost_dimensions {basis, snapshot, frozen, current}: fişin hesap anındaki departmanı/şubesi (snapshot) > muhasebeleştirmede dondurulan (frozen; aktarılan/eski fişler) > çalışanın bugünkü departmanı (current, cost_dimension_current uyarısı). Muhasebeleştirince current fişler dondurulur: sonradan başka departmana taşınan çalışan geçmiş ayın gider dağılımını kaydırmaz; işaret geri alınırsa dondurma kalkar. Satırda department / branch: satır tek departmana/şubeye aitse adı (kişi bazında her satırda) — fiş dosyasının Departman/Şube sütunları buradan dolar.
  • Biçimler: empuno_xlsx (Fiş · Hesap Özeti · Eşleme · Mutabakat · Uyarılar sayfaları), csv, luca (kısmen doğrulandı: fiş başına en çok 400 satır, dosya başına 50 fiş — kişi bazında fiş kişi sınırından dengeli parçalara bölünür, özet fiş bölünmez + voucher_too_long), merkezihesap (doğrulanmadı) ya da firma şablonu (template:<id>). Dosyada hesap kodları ve TCKN metin hücresidir (335.01, 05510 bozulmaz).
  • Banka dosyası: ödenecek tutar fişin net ödemesidir (avans, icra ve diğer kesintiler düşülmüş; kırılım deductions{}). Dışarıda kalanlar excluded[].reason: iban_missing, iban_invalid (mod-97), iban_foreign, iban_duplicate (aynı IBAN birden çok kişide → hepsi), non_positive_net. Banka önayarında same_bank_only açıksa başka bankadakiler other_bank[]'a ayrılır (--include_other_banks true ya da genel şablon). source=revision + revision_id: düzeltme turunun yalnız ek ödeme farkları.
  • Şablon önizlemesi (payroll-settings.export-templates.preview): kaydetmeden, son onaylı dönemin (fişte yoksa son hesaplanmış; --period ile seçilir) ilk satırlarını şablona göre biçimlenmiş döndürür — başlık, üst bilgi, rows[[…]], csv/txt için dosya metni text; IBAN, hesap no ve TCKN uzunluk korunarak * ile maskeli. --template taban, --definition / --params üstüne yazılır (editördeki taslak). Yan etkisiz; bilinmeyen alan unknown_field uyarısı.
  • Önayarların doğruluğu: halkbank_dto_iban resmî kılavuzla birebir (documented: A1–A8 üst bilgi, 11. satır başlık, 12. satırdan kayıt; müşteri no + borçlu IBAN zorunlu parametre); diğer banka önayarları genel liste biçimidir (unverified) — ilk dosyayı bankanın ekranında karşılaştırın ya da bankanızın örnek dosyasını export-templates.detect ile şablona çevirin.
  • Üretim kuralları: önizleme her hesaplanmış dönemde; dosya yalnız onaylanmış/kesinleşmiş/ödenmiş dönemde (422 not_approved). Önce payroll.bank-file ile totals.amount'ı okuyup --confirm_total gönderin (değiştiyse 422 total_changed). Aynı içerik 10 dakika içinde tekrar üretilirse aynı kayıt döner (X-Empuno-Duplicate: 1). Meta başlıklarda: X-Empuno-Rows, X-Empuno-Total, X-Empuno-Excluded, X-Empuno-Payment-File-Id. Üretim denetim kaydına yazılır; IBAN ve dosya içeriği SAKLANMAZ. Denemede (--validate) çalışmaz — önizleme zaten yan etkisiz.
  • IBAN isteme (payroll.bank-file.request-iban): IBAN'ı eksik ya da geçersiz olan ve aktif hesabı bulunan çalışana push + e-posta (IBAN/tutar yok); çalışan başına 24 saatte bir. Bildirime dokunan çalışan mobilde profil tamamlamanın Banka / IBAN adımına, web'de profil düzenlemeye gider; Bordrom ekranındaki "Maaş hesabı" kartı da durumu gösterir. IBAN her yerde mod-97 ile doğrulanır.
  • Panelde aynı uçlar: dönem ekranı → Çıktılar → Muhasebe Fişi / Banka Ödeme Dosyası; Bordro Ayarları → Hesap Planı Eşleme ve Dosya Şablonları.
bash
# Muhasebe fişi
empuno payroll.accounting-voucher 2026-10                         # JSON: lines[], totals.balanced, accounts[], reconciliation, warnings[], mapping.defaults_used
empuno payroll.accounting-voucher 2026-10 --format luca --output fis.xlsx       # Luca fiş aktarımı (400 satırda kişi sınırından bölünür)
empuno payroll.accounting-voucher 2026-10 --format csv --detail per_employee      # kişi bazında; ; ayraç, ondalık virgül, UTF-8 BOM
empuno payroll.accounting-voucher 2026-10 --kind payment --format empuno_xlsx     # ödeme fişi: 335 borç / 102 alacak
empuno payroll.accounting-postings.store 2026-10 --voucher_no 2026100001          # muhasebeleştirildi işareti (kesinleşmiş/ödenmiş dönem)
empuno payroll.accounting-voucher 2026-10 --kind correction                       # dönem sonradan değiştiyse fark fişi
empuno payroll.accounting-postings.store 2026-10 --kind correction
# Hesap planı eşlemesi (varsayılan Tekdüzen hesapları; firma planınıza göre bir kez)
empuno reference payroll_account_lines                           # kalemler, varsayılan hesap, yedek zinciri, firma eşlemesi
empuno payroll-settings.accounting.suggest --file file=./mizan.xlsx --apply true --validate   # hesap planından öneri (AI yok)
empuno payroll-settings.accounting.mappings.update --json '{"mappings":[{"line_key":"net_pay","account_code":"335.01"},{"line_key":"wage","account_code":"{root}.01"},{"line_key":"expense_root","scope_type":"department","scope_id":7,"account_code":"760"}]}'
empuno payroll-settings.accounting.options.update --voucher_detail per_employee --employer_support_treatment other_income
# Banka maaş ödeme dosyası
empuno reference bank_file_presets                               # önayarlar + doğrulama durumu (documented | partial | unverified)
empuno payroll.bank-file 2026-10 --template preset:halkbank_dto_iban --params.customer_no 01234567 --params.debit_iban TR…
empuno payroll.bank-file.generate 2026-10 --template preset:halkbank_dto_iban --payment_date 2026-11-05 --confirm_total 1234567.89 --output maas.xlsx
empuno payroll.bank-file.request-iban 2026-10 --validate          # IBAN'ı eksik/geçersiz olanlar (push + e-posta; 24 saatte bir)
# Bankanın / programın kendi şablonu
empuno payroll-settings.export-templates.detect --kind bank --file file=./garanti_ornek.xlsx --store true --name "Garanti maaş"
empuno payroll-settings.export-templates.store --kind bank --preset ziraat_maas_liste --params.customer_no 12345 --is_default true
empuno payroll-settings.export-templates.update 3 --params.debit_iban TR…   # yalnız gönderilen alanlar; params.<anahtar> null → siler
empuno payroll-settings.export-templates.preview --kind bank --template template:3 --period 2026-10   # son onaylı dönemden ilk 3 satır (maskeli; dosya üretmez)
empuno payroll-settings.export-templates.preview --kind voucher --template luca --json '{"definition":{"columns":[{"field":"account_code","title":"Hesap"},{"field":"department","title":"Departman"},{"field":"debit","title":"Borç"}]}}'

Bordro dönemleri: listeleme, ay ile adresleme, iptal ve silme

Bordro komutlarındaki <period> hem dönem id'si hem ay etiketi (YYYY-AA, ör. 2026-04) olabilir. Etiket, o ayın tek iptal edilmemiş dönemini seçer; yalnız iptal edilmiş dönemi olan ayda o seçilir. Aynı ayın birden çok iptal edilmemiş dönemi varsa 409 ambiguous_period + candidates[] döner (id, durum, aktarılmış mı, fiş sayısı, silinmiş mi) ve hint o komutun id'li hâlini söyler — id ile tekrar çağırın. Dönem yoksa 404 ve payroll.store ipucu. Silme ve geri almada (payroll.destroy, payroll.restore) etiket yalnız o ayın silinmişler dahil tek dönemi varsa çözülür; aksi 409 — böylece tekrar çağrı başka bir dönemi silmez (aynı dönemi bulur, yan etkisiz). Çalışan web/mobil bordro uçları id ile kalır.

Durumİptal (payroll.cancel)Silme (payroll.destroy)Çalışan görür
Taslak / HesaplandıEvetEvet (doğrudan)Hayır
OnaylandıEvetÖnce iptalEvet
Kesinleştirildi / ÖdendiHayır — düzeltme için payroll.reopenHayır (resmî bordro, VUK md. 253)Evet
İptal edildi— (tekrar çağrı yan etkisiz)EvetHayır
Aktarıldı (önceki sistemden)HayırHayırStatüsüne göre
Düzeltmeye açılmış (revision_count > 0)Hayır — yeniden hesaplayıp kesinleştirinHayırHayır
  • İptal edilmiş ve silinmiş dönem hiçbir hesaba girmez: kümülatif GV matrahı, yıllık 270 saat fazla mesai toplamı, avans/haciz bakiyesi ve geçmişi, icra kapasite tahmini, çıkış ödemesi, SGK/MUHSGK beyanı, mali müşavir kesinti raporu, çalışan web/mobil bordro, yıllık işveren maliyeti rozeti, belgesiz rapor onayındaki ay kilidi.
  • Silme = arşiv: dönem, fişleri ve alt kayıtları birlikte soft-delete edilir; kim/ne zaman/gerekçe dönemde ve bordro denetim günlüğünde kalır. reason zorunlu (3–500). Zaten silinmişse yan etkisiz başarı (flash.deleted.already: true).
  • Silinemeyen dönemde 422 rejected + errors.period; makine kodu payroll.show / payroll.index satırında deletion_blocker.code: imported | locked | revised.
  • Toplu silme satır bazlı results[] döner (deleted | skipped + engel metni | failed); dry_run: true hiçbir şey yazmaz. Her dönem ayrı işlenir.
  • Hesaplanmış bir dönemi iptal etmek, silmek ya da geri almak, sonraki ayların kümülatif GV matrahını bayatlatır: yanıtta warnings[{code: later_periods_affected, periods[{id, label, status, action, next_step}]}]. Yol duruma göre: recalculate (hesaplanmış → payroll.calculate), cancel_and_recreate (onaylanmış dönem yeniden hesaplanamaz → payroll.cancel, payroll.store, payroll.calculate), reopen (kesinleşmiş/ödenmiş → payroll.reopen, hesapla, onayla, kesinleştir; fark raporu). next_step komutu hazır verir.
  • payroll.index varsayılan olarak sayfa başına 100 dönem döner (pagination.total, --per_page ≤100, --page); hepsini okuyan betik sayfaları gezmeli.
  • İptal edilmiş dönemin mutabakatı (payroll.declaration <id>) satır üretmez; tek uyarı period_cancelled — beyana esas alınamaz.
  • Geri alma yalnız dönemle aynı anda silinen fişleri geri getirir. İptal edilmiş dönem her zaman geri alınır; taslak/hesaplanmış dönem, o ayın iptal edilmemiş başka dönemi varken alınamaz (month_taken).
  • Yalnız iptal edilmiş dönemi olan ayda payroll.store yeni dönem açar. Durum değerleri: empuno reference payroll_period_statuses.
bash
empuno payroll.index --year 2026                  # varsayılan: iptal edilmişler gizli (counts.cancelled kaç tane gizlendiğini söyler), sayfa başına 100 (pagination)
empuno payroll.index --year 2026 --status all     # iptal dahil hepsi; --status cancelled | paid,draft | …
empuno payroll.index --archived 1                 # silinmiş dönemler (kim, ne zaman, gerekçe)
empuno payroll.show 2026-04                       # ay ile; aynı ayın diğer dönemleri period.same_month[]
empuno payroll.declaration 2026-04
empuno payroll.cancel 7 --reason "Yanlış hesap"
empuno payroll.destroy 7 --reason "Test hesaplaması"
empuno payroll.bulk-destroy --json '{"all_cancelled":true,"year":2026,"dry_run":true}'                            # önce ne silineceğini görün
empuno payroll.bulk-destroy --json '{"all_cancelled":true,"year":2026,"reason":"Önceki sistemden aktarıldı — mükerrer"}'
empuno payroll.restore 7                          # geri al (ay etiketi yalnız o ayın tek dönemiyse: empuno payroll.restore 2026-04)

Kesinleşmiş / ödenmiş bordro döneminin düzeltilmesi

İki yol vardır. (A) Fark bordrosu: dönem kilitli kalır, fark cari aya bordro kalemi olarak girilir (payroll-items.bulk) — prim/ikramiye gibi ödendiği ayda vergilenen farklar için. (B) Dönemi düzeltmeye aç: hatalı hesaplanmış ayı yeniden hesaplamak için.

  • Açılışta fişler snapshot olarak saklanır (eski hâl silinmez). Dönem ödenmişse ödemede avans/hacze işlenen tahsilatlar geri alınır; yeniden payroll.pay ile güncel tutarlarla işlenir.
  • Kesinleştirmede kişi bazında net fark (net_difference > 0 çalışana ek ödeme, < 0 alacak), sgk_changed (APHB ek/iptal belge), tax_changed (MUHSGK düzeltme beyannamesi) ve kümülatif GV matrahı değiştiyse yeniden hesaplanması gereken sonraki dönemler döner.
  • Kümülatif GV matrahı her zaman önceki ayların fişlerinden türetilir; önceki ayı düzelttiyseniz sonraki ayları sırayla yeniden hesaplayın (kesinleşmişse onları da düzeltmeye açın).
  • Aktarılan (önceki sistemden) dönem yeniden açılamaz; düzeltmeyi içe aktarımı yeniden yaparak girin.
bash
empuno payroll.reopen 145 --reason "Fazla mesai eksik girilmiş"
# düzeltmeyi yapın (puantaj, profil, kalem…), sonra olağan akış:
empuno payroll.calculate 145 && empuno payroll.approve 145 && empuno payroll.finalize 145
empuno payroll.show 145      # revisions[]: snapshot + fark (diff.employees[], totals, actions, affected_later_periods)

Bordro doğrulama: simülasyon, kaydetmeden önizleme, hesap izi, yasal parametreler

Gerçek hesapla aynı motor (toplayıcı → hesaplayıcı) yazıcı çağrılmadan koşar: hiçbir kayıt oluşmaz, değişmez; bildirim, e-posta, AI kredisi yok (her çağrı geri alınan bir transaction içinde; yazma girişimi engellenir). Sonuçlar gerçek payroll.calculate ile kuruşu kuruşuna aynıdır. Yetki: payroll.view (önizleme payroll.calculate üzerinden olduğu için payroll.manage).

  • Simülasyon (payroll.simulate, POST): zorunlu yalnız period (YYYY-AA, 2021-01 … bugün+12 ay) + employee_id YA DA profile.gross_salary | net_salary | hourly_rate. İstekteki alanlar yalnız "değiştir"dir: profile.*, days.{sgk_days|missing_days, missing_reason, pay_days, allowance_days, rd_days}, overtime.{overtime_50_hours, overtime_25_hours, weekly_rest_hours, weekly_rest_days, holiday_hours, holiday_days, night_hours} (gerçek hesapla aynı fiyat: saat ücreti × çarpan, saat bazlı tür o kovayı ödüyorsa türün çarpanı; gece yalnız gece türüyle ödenir, yoksa night_hours_unpaid uyarısı), attendance.{sgk_days, missing_breakdown, missing_day_reason, worked_hours, paid_rest_hours} (puantaj özeti), profile.{work_schedule, weekly_hours} (kısmi süreli / çağrı üzerine), earnings[] / deductions[] (gerçek kalemlere EKLENİR; include_live_items: false gerçekleri çıkarır), cumulative_tax_base_before, exit.*, options.* (yalnız bu istekte; firmanın tercihi değişmez). Alanların tam listesi: empuno describe payroll.simulate.
  • Yanıt: slip (payroll_slips kolon adları), summary, earnings[], deductions[], trace{phases, steps[{phase, key, label, value, inputs, formula, basis, flags, note}], flags[]}, input + input_sources (hangi alan istekten), comparison{current, simulated, diff} (dönemde fişi varsa), would_write[] (gerçek hesapta yazılacaklar: profil açma, çıkış ödemesi kaydı, sistem kazanç türü — simülasyon yazmaz), warnings[], results[] (months > 1).
  • Önizleme (payroll.calculate --dry_run 1): dönem durumu, fişler, çıkış ödemeleri ve profiller değişmez; iptal hariç her durumda çalışır (onaylı/kesin dönemde "düzeltmeye açsam ne değişir"). basis=live: results[].action would_create | would_update | would_delete | error + diff + hints. basis=slips: hesap izi olan fiş birebir yeniden oynatılır; izi olmayan eski fiş ve aktarılmış fiş kolonlarından kurulur (source stored | reconstructed | imported). employee_ids[] alt küme, tolerance (TL, vars. 0,05). Not: CLI'nin genel --dry-run bayrağı isteği yerelde basar; sunucu alanı dry_run (alt çizgi) — --dry_run 1 ya da --validate kullanın.
  • Aktarılmış (müşavir) fişlerin geri testi: set fişin bağından değil dönem tarihinden seçilir. Fişte yazılı olgular girdi olur (ücret, prim günü, SGK/GV/DV matrahlarından istisnalı kısım, kümülatif matrah, sigorta türü SGK tutarlarından). AGİ yılında müşavirin uyguladığı AGİ, motor vergisi − fiş vergisi farkından aile durumuyla eşlenir (aynı tutarı veren durumlar listelenir; çalışan kartı seçer). Kırılımı yazılmamış AÜ istisnası / 5510 teşviki, nihai tutar aynıysa fark sayılmaz (inferred[] notu). Ar-Ge kanunu ve terkini yazılı ama oranı (rd_rate) olmayan fişte oran — gün de yoksa gün — fişteki terkinden yasal oranlara (%100/95/90/80) oturtularak türetilir (inferred[]: profile.rd_tax_exemption_rate, days.rd_days; aynı tutarı veren iki çözümde firmanın oran yazılı fişlerindeki en sık oran); oturmazsa ipucu. Firma tercihi rd_tax_benefit = employer iken fişteki "Ar-Ge … işverene kalır" kesinti satırı (deductions[].type=rd_retained ya da adı Ar-Ge geçen, tutarı terkine eşit) girdiden çıkarılır — motor bu kesintiyi kendisi üretir. Kalan farklar hints[] ile açıklanır: AÜ istisnası uygulanmamış (yalnız fişin GV'si motorunkinden yüksekse), Ar-Ge alanları eksik (kanun 05746, terkin yok), Ar-Ge terkini / SGK desteği farkı, işsizlik payı aktarılmamış olabilir, SGK tabanı/tavanı, işçi payı tutarsız, işveren maliyeti farkı yönüyle (müşavir yüksekse fişte uygulanmamış teşvik/destek, düşükse motorun uygulamadığı destek).
  • Hesap izi: empuno'nun hesapladığı her fişte hesap anında saklanır (girdi + adımlar + motor sürümü + parametre seti); --explain 1 bunu ve tutarlılık kontrolünü (consistency.matches) döner. Zorunlu adımlar: SGK matrahı (taban/tavan bayrağı, 5510 md. 82), kümülatif matrah ve kaynak aylar, dilim dağılımı + bracket_crossed, AÜ istisnası (asgari ücretlinin matrahı, ay vergisi, uygulanan), Ar-Ge, eksik gün + neden, parametre seti ve tarihli satırlar (kıdem tavanı, SGK yemek istisnası). Çalışan web/mobil bordroda explain_summary (≤4 sade cümle) görür.
  • Yasal parametreler (reference payroll_parameters, payroll.parameters aynı veri): asgari ücret, SGK oranları (normal + SGDP) / taban / tavan, GV dilimleri (alt sınırdaki vergi dahil), DV oranı + kâğıt başı azami tutar, AÜ istisnası (ay tablosu — yıl başından beri çalışan için; yıl içinde girende kümülatif giriş ayından başlar, mw_exemption_cumulative_start), AGİ (yalnız ≤2021), yemek/yol/SGK yemek istisnası, engellilik indirimleri, kıdem tavanı, fazla mesai çarpanları, kaynaklar, minimum_wage_support (yürürlükteki günlük tutar + PEK sınırları; firma tercihi minimum_wage_support ile dönem hesabında uygulanır) statutory.items[] (kanunla değişen oran/eşikler — Ar-Ge ücret sınırı katı, teknokent GV oranı, Ar-Ge SGK desteği, 5746 personel oranları, BES SGK istisna payı: key, label, unit, basis, tarihte geçerli value ve yıl içi değişen değerde schedule[] — ör. 2025'te 40 kat sınırı 01.08'den), labor_law (haftalık azami 45 / günlük 7,5 saat — fazla mesai ve kısmi gün çevirisi buna dayanır) ve not_modeled[] (bölgesel ilave puan, kısmi sigorta alt grupları); kanun bazlı teşvikler reference incentive_codes. Tüm bordro tutarları kuruş kesindir: her yasal kesinti (SGK işçi/işveren bileşenleri, GV, DV, istisna) ayrı ayrı kuruşa yarım-yukarı yuvarlanır ve bileşenler toplamı birebir tutar; net anlaşmada brüt, tam neti veren en küçük kuruş ücrettir. Set yoksa 404 parameters_missing (en erken 2021-01-01); simülasyon ve önizlemede aynı kod 422.
  • Panelde aynı uçlar: Bordro → Bordro Simülatörü (Simülasyon + Yasal Parametreler sekmeleri; "CLI komutunu kopyala" buradaki payroll.simulate komutunu verir), dönem sayfasında Önizle (kaydetmeden) / Motorla karşılaştır (payroll.calculate --dry_run 1), fiş detayında Hesap İzi kartı (--explain 1, aktarılmışta "empuno ile yeniden hesapla" = --recompute 1). Yönetici ekranda gördüğünü ajanınız aynı sonuçla çalıştırır.
  • AGİ yılları (2021 ve öncesi) için bordro dönemi açılmaz (payroll.store 422): geçmişi data-migration.payroll.commit ile aktarın, doğrulamayı payroll.simulate ve payroll.calculate --dry_run 1 --basis slips ile yapın. AGİ yılı simülasyonunda aile durumu istekte yoksa çalışan kartından alınır; kartta boş olan bileşen en düşük AGİ ile varsayılır (bekâr / eş çalışıyor / 0 çocuk) ve warnings[]'te agi_status_assumed döner — gerçeğini agi.* ile verin.
  • Ret nedenleri (422 {error: "rejected", reason}): salary_missing (çalışanın bordro profilinde/kartında ücret yok — gerçek hesap da bu çalışanı atlar; simülasyon için profile.gross_salary verin, kalıcı düzeltme employees.payroll-profile.update), simulation_salary_missing (serbest modda ücret alanı yok), calculation_failed (girdi hesaplanamadı, mesajda neden), period_cancelled, preview_too_large (tek önizleme en çok 300 çalışan/fiş — employee_ids ile parçalara bölün).
  • Elle düzeltilmiş beyan alanları (Mutabakat → Düzelt / payroll.declaration.update, ör. eksik gün nedeni) motor çıktısı değildir: tutarlılık kontrolü, --basis slips önizlemesi ve geri test bunları fark saymaz; --explain 1 yanıtında overrides[{field, label, value, engine_value}] olarak listelenir (iz motorun türettiğini gösterir, beyan ve yeniden hesap düzeltmeyi kullanır).
bash
# 1) Çalışan simülasyonu: verilmeyen her alan gerçek veriden (profil, izin/yoklama günleri, kalemler, haciz/avans, kümülatif matrah)
empuno payroll.simulate --json '{"period":"2026-04","employee_id":118,"options":{"sick_leave_pay":"unpaid"}}'
# 2) Serbest profil (çalışan yok): brüt/net/saat ücreti + istenen olgular
empuno payroll.simulate --json '{"period":"2023-07","profile":{"gross_salary":45000,"insurance_group":"none","mw_exemption_applies":false},"cumulative_tax_base_before":250000}'
# 3) AGİ yılı (2021): aile durumu
empuno payroll.simulate --json '{"period":"2021-03","profile":{"gross_salary":6291.05},"agi":{"marital_status":"married","spouse_works":false,"children":2}}'
# 4) 12 ay zincir (kümülatif matrah aydan aya, Ocak sıfırlanır; dilim geçişi results[].flags)
empuno payroll.simulate --json '{"period":"2026-01","months":12,"employee_id":118,"trace":"none"}'
# 5) Dönemi kaydetmeden önizle: bugünkü veriyle (live) ya da her fişin kendi girdisiyle (slips)
empuno payroll.calculate 2026-04 --dry_run 1
empuno payroll.calculate 2023-07 --dry_run 1 --basis slips      # aktarılmış dönem: müşavir değeri ↔ motor + ipuçları
# 6) Fişin hesap izi (neden bu rakam)
empuno payroll.employee-slip 2026-04 118 --explain 1
empuno payroll.employee-slip 2022-03 118 --explain 1 --recompute 1   # aktarılmış / eski fiş: motorla yeniden hesap + fark
# 7) Yürürlük tarihli yasal parametreler (2021–)
empuno reference payroll_parameters --date 2023-07-15
empuno reference payroll_parameters --year 2022                # yılın setleri + 12 aylık AÜ istisnası

Talepler: geliştirme isteği, hata, eleştiri, soru

Ajanınız bir işlemi yapamadığında, bir hata gördüğünde ya da sistemi geliştirmek için önerisi olduğunda empuno ekibine talep açar. Talep çok mesajlı bir yazışmadır: ekibimiz (insan ya da bizim ajanımız) yanıtlar, ek bilgi ister, kapatır; ajanınız yanıtı bir sonraki kontrolde okunmamış olarak görür.

Tür (kind)Ne zaman
featureYeni özellik / geliştirme isteği
bugBeklenmeyen davranış, yanlış sonuç, 500 hatası
criticismEleştiri, kullanılabilirlik, genel geri bildirim
questionNasıl yapılır / kural sorusu
missing_commandAjanın yapması gereken işlem katalogda yok (unknown_command yanıtındaki hint bunu önerir)
docsDokümantasyon eksik ya da yanlış

Mükerrer koruması: aynı başlıkta açık talep varsa (ya da aynı Idempotency-Key gönderilirse) yeni talep açılmaz, mevcut talep duplicate: true ile döner — ek bilgiyi reply ile ekleyin. CLI anahtarı içerikten kendisi üretir; betiğin yeniden denemesi güvenlidir.

Durumlar: open (ekipten yanıt bekliyor) → answered (ekip yanıtladı) → … → closed. Ajanınızın her mesajı talebi yeniden open yapar; kapalı talebe yazılamaz (409), yeni talep açıp eski numarayı belirtin. Her anahtar türü (salt-okuma dahil) talep açabilir; talepler firma düzeyinde görünür. Yazma sınırı anahtar başına dakikada 6, saatte 40. Taleplere kişisel veri (kimlik no, maaş, sağlık) yazmayın. HTTP uçları: /api/company/v1/tickets (ayrıntı: /api-docs).

bash
empuno tickets open "Toplu izin onayı" --kind feature --body "Bekleyen izinleri tek komutla onaylamak istiyoruz." --command leave-requests.approve
empuno tickets --unread              # yanıtı gelen talepler
empuno tickets show TK-7Q3M9X        # yazışmayı oku (okundu sayılır)
empuno tickets reply TK-7Q3M9X "Her ay sonu gerekiyor."
empuno tickets close TK-7Q3M9X --note "Çözüldü, teşekkürler"
empuno tickets kinds                 # tür listesi

Yanıt biçimi

DurumYanıt
Okuma (GET){"ok": true, "page": "Manager/LeaveRequests/Index", "data": {…}} — data, panel ekranının gösterdiği verinin tamamı
Yazma başarılı{"ok": true, "message": "İzin talebi onaylandı!", "data": {…}, "meta": {…}, "redirect": {"command": "leave-requests.index", "params": {}}} — message, flash ve redirect eskisi gibi durur; sonucu datadan okuyun
data (yazma){"action": "created", "type": "advance_payment", "id": 812, "ids": [812], "created": 1, "updated": null, "deleted": null, "skipped": null, "failed": null, "partial": false, "results": [{"index": 0, "action": "created", "type": "advance_payment", "id": 812}], "warnings": [], "changed_fields": []} — tüm yazma komutlarında aynı biçim. Kaynak sırası: komutun açık beyanı (flash.created / updated / deleted) → komutun JSON sayaçları → gözlenen kayıt (inferred: true). Belirlenemeyen sayaç 0 değil null; changed_fields yalnız alan ADLARI. Toplu komutlarda results[] satır bazlıdır (created / updated / skipped / failed + reason)
meta{"company_id": 12, "company_slug": "acme", "command": "advance-payments.store", "dry_run": false, "idempotent_replay": false} — her nesne yanıtında (okuma dahil); başlıkta da X-Empuno-Command, X-Empuno-Company-Id. Liste (dizi) dönen JSON'a dokunulmaz
Deneme (dry_run){"ok": true, "dry_run": true, "message": "Deneme (kaydedilmedi): …", "data": {"id": null, …}, "dry_run_report": {"rolled_back": true, "changes": {"inserts": {"departments": 1}, "updates": {}, "deletes": {}}, "side_effects": {"mail": [], "notifications": [], "jobs": [], "storage": []}, "blocked": []}} — oluşacak kayıtların kimliği null; başlık X-Empuno-Dry-Run: 1
Tekrar (Idempotency-Key)İlk yanıtın aynısı + "idempotent_replay": true ve Idempotent-Replayed: true başlığı; işlem ikinci kez YAPILMAZ
Doğrulama / iş kuralı422 {"ok": false, "message": "…", "errors": {"alan": ["…"]}}
Dosyaİkili içerik (PDF, Excel). CLI kaydeder: --output ./klasor
Bazı uçlarPanel bileşenlerinin kullandığı uçlar zaten JSON döner; olduğu gibi iletilir.

Yetki ve güvenlik modeli

  • Kimin adına: Ajan anahtarı, onu oluşturan kişi adına çalışır. Yapılan işlem panelde o kişi yapmış gibi kaydedilir (ör. izni onaylayan).
  • Etkin yetki = anahtarın kapsamı ∩ o kişinin güncel yetkisi. Kapsamı anahtarı oluştururken modül modül (Görüntüle / Yönet) seçersiniz; sizde olmayan yetkiyi veremezsiniz. Kişinin yetkisi azalırsa anahtar da daralır, kişi pasifleşirse anahtar çalışmaz.
  • Yönetici-özel işlemler (yetki devri, mali müşavir yönetimi) ayrı company_admin kapsamı ister; varsayılan kapalıdır.
  • Grup anahtarı: birden çok grup şirketinde çalışan anahtar her istekte hedef firmayı (X-Empuno-Company / --company) ister ve o firmada, kişinin oradaki hesabı adına çalışır; etkin yetki her firmada ayrı kesişir. Ayrıntı: [Grup anahtarı](#grup-anahtari).
  • Hiçbir kapsamla açılmayanlar: API anahtarı üretme/iptal, abonelik ve ödeme işlemleri, kişisel profil (ad, e-posta, şifre).
  • İşlem günlüğü: Her yazma isteği (komut, yol, durum kodu, süre) anahtarın günlüğüne düşer: Firma Ayarları → API. Denemeler (Deneme) ve tekrarlar (Tekrar) da ayrı rozetle görünür; panelde Hatalar / Denemeler / Tekrarlar diye süzülür. İstek/yanıt içeriği saklanmaz.
  • Tekrar anahtarı zorunluluğu: Anahtar ayarlarında "Her yazmada tekrar anahtarı (Idempotency-Key) zorunlu" açılırsa anahtarsız yazma 400 idempotency_key_required alır (deneme ve okumalar muaf). Kataloğun conventions.idempotency.required_for_this_key alanı bunu söyler.
  • Süre ve iptal: 7 / 30 / 90 / 180 / 365 gün veya süresiz; panelden anında iptal. Ham anahtar yalnız oluşturulurken bir kez gösterilir, sunucuda yalnız özeti (sha256) tutulur.
  • Hız sınırı: anahtar başına 240 istek/dakika, 6000 istek/saat (aşılırsa 429 + Retry-After).
  • Gerçek etki: İşlemler canlı veride çalışır ve panelle aynı yan etkileri doğurur (ör. aday/çalışana e-posta gider, AI kredisi harcanır). Komutun yan etkileri empuno describe özetinde yazar; kapatılabilenler parametreyle kapatılır. Örnek: personel evrakı varsayılan olarak yalnız yöneticilere görünür ve çalışana bildirim gitmez; --visible_to_employee true ile çalışanın Evraklarım bölümüne açılır (bildirim gider, toplu aktarımda --notify_employee false ile susturulur).
  • Geçmiş veri aktarımı: data-migration.* komutları davet, e-posta ya da bildirim GÖNDERMEZ ve lisans tüketmez. data-migration.employees.commit ayrılmış çalışanları çıkış bilgisiyle alır, TC ile eşler (--on_existing update) ve satır bazlı results döner; tekrar çalıştırmak güvenlidir.

Grup anahtarı ve firma seçimi (grup şirketleri)

Birden çok şirketi olan gruplar (holding, kardeş şirketler) firmalarını panelde Grup Şirketleri ekranından bağlar (group.* komutları). Aynı kişi grup firmalarında aynı e-posta ve şifreyle hesaba sahipse, anahtar oluştururken Firmalar bölümünden diğer grup firmalarını seçerek tek bir grup anahtarı oluşturur. Seçilebilen firma: aynı grupta, aktif ve kişinin orada API anahtarı yönetme yetkisi var.

  • Firma her istekte zorunlu (okuma dahil). Başlıksız panel komutu 400 company_required alır (yanıtta erişilebilir companies[]). Gerekçe: okumada sessizce ev firmasına düşmek, ajanın yanlış firmanın verisini görüp yanlış firmaya yazmasının ilk adımıdır. Başlıksız serbest uçlar: /api/company/v1/me, /catalog (ev firmasına göre allowed + requires_company: true), /companies, /tickets (talepler her zaman anahtarın ev firmasınındır) ve firmaya bağlı olmayan referanslar; firmaya bağlı referanslar (departments, branches, leave_types, sgk_workplaces, payroll_options, earning_types, pension_plans …) başlık ister.
  • Komut hedef firmada, kişinin oradaki hesabı adına koşar: yapılan işlem o firmada o kullanıcı yapmış gibi kaydedilir; günlük satırı (company_api_key_logs) hedef firma ve o kullanıcıyla yazılır; tekrar anahtarı (Idempotency-Key) kapsamı da hedef firmadır — aynı anahtar iki firmada iki ayrı işlemdir.
  • Etkin yetki = anahtar kapsamı ∩ o firmadaki hesabın güncel yetkisi. B'de yönetici değil de yalnız izin görüntüleme yetkiniz varsa, aynı anahtar B'de yalnız onu yapar. empuno companies her firmanın effective_scopes listesini verir.
  • Her yanıt firmasını söyler: meta.company_id, meta.company_slug ve X-Empuno-Company-Id / X-Empuno-Company-Slug başlıkları (dosya indirmede yalnız başlık). Yazmadan önce doğrulayın.
  • Tek firmalı anahtar: başlık gerekmez; verilirse anahtarın firmasıyla (id ya da slug) eşleşmelidir, yoksa 403 company_mismatch + key_company (profili karışan ajanı korur).
  • CLI sürümü: --company, EMPUNO_COMPANY, empuno login --company ve empuno companies CLI 1.6.0 ile gelir (npm i -g empuno@latest; empuno version). 1.5.0 --company değerini göndermez — grup anahtarıyla eski CLI her panel komutunda company_required alır.
  • İptal kuralları (her istekte denetlenir): anahtar iptal/süresi dolmuş → 401 (her firmada). Hedef firma askıda → 403 company_inactive (yalnız o firma; diğerleri çalışır). Listede olmayan ya da var olmayan firma → aynı gövdeyle 403 company_not_in_key. Erişim kalktıysa 403 company_access_revoked + reason: detached_by_member (o firmanın yöneticisi "Bu firmadan kaldır" dedi), left_group (firma gruptan ayrıldı/çıkarıldı), removed_by_owner, group_dissolved, account_unavailable (kişinin oradaki hesabı pasif, silinmiş ya da şifresi artık aynı değil).
  • Yönetim: firma listesini yalnız anahtarı oluşturan kişi değiştirir; anahtarın tamamını yalnız ev firması iptal eder; üye firmanın yöneticisi anahtarı Firma Ayarları → API & Ajan'da salt okuma görür, yalnız kendi firmasındaki işlemleri günlükte izler ve "Bu firmadan kaldır" ile o firmadaki erişimi kapatır. Firmaların birbirine bağlanması (grup) tek başına hiçbir veriyi açmaz; firmalar arası her işlem açık rıza (grup üyeliği) + aynı kişi kuralıyla yapılır.
  • Grup komutları: group.index (üyeler, davet kodları, etkinlik — group.view), group.store / group.update / group.companies.store --target_company <id|slug> (aynı yöneticinin firmasını ekle; --company çalışılan firmadır, eklenecek firma değil — eski alan adı company yalnız --json gövdesinde kabul edilir) / group.invites.store (tek kullanımlık kod, yalnız bir kez döner) / group.invites.destroy / group.join --code / group.leave — üyelik değişiklikleri company_admin kapsamı ister.
bash
empuno companies                                        # id, slug, durum, ev/üye, etkin kapsam
empuno --company forwardie-lojistik-as employees.index  # firma id ya da slug
export EMPUNO_COMPANY=3                                 # ya da profil varsayılanı: empuno login --company 3
empuno --company 3 payroll.show 2026-10                 # ay etiketi de o firmanın dönemine çözülür
empuno --company 3 group.index                          # grup üyeleri, davet kodları, etkinlik
empuno reference group_companies                        # aynı liste (referans olarak)

# HTTP
curl -H "Authorization: Bearer $EMPUNO_API_KEY" https://empuno.com/api/company/v1/companies
curl -H "Authorization: Bearer $EMPUNO_API_KEY" -H "X-Empuno-Company: 3" https://empuno.com/manager/employees

Grup işlemleri: ayar kopyalama ve grup özeti

Aynı gruptaki firmalar arasında yapılandırma tek seferde kopyalanır ve firmaların maliyet / avans / izin durumu tek raporda okunur. Her iki işlem de firmalar arası erişim kuralına tabidir: kaynak/okunan firma aynı grupta olmalı, kişinin orada aynı e-posta + şifreyle hesabı olmalı, ajan isteğinde firma anahtarın listesinde olmalı (tek firmalı anahtar → 403 company_not_in_key).

  • Ayar kopyalama (company-settings.clone, group.manage): hedef = isteğin firması (--company), kaynak = --from (id ya da slug). Bölümler: payroll_options (yalnız tanımlı ve geçerli tercihler), payroll_general (ödeme günü, para birimi, kilit günü, devamsızlık, 5510 otomatik), meal_transport, advance_settings, earning_types / deduction_types (kodla), leave_types (type_key ya da adla), leave_settings, departments, branches, shifts, expense_categories (adla; büyük/küçük harf ve boşluk farkı önemsiz), accounting_options, payroll_account_mappings (yalnız firma geneli, line_key ile), payroll_export_templates (tür + adla; parametreler kopyalanmaz). document_types platform geneli — her firmada aynı liste, kopyalamaya gerek yok.
  • Hiçbir kayıt silinmez. --on_existing skip (varsayılan): eşleşen kayıt ve özelleştirilmiş ayar korunur, yalnız eksikler eklenir; ayar bölümü bu firmada hiç değiştirilmemişse (varsayılan değerlerde) kaynağın değerleri yazılır. update: eşleşenler kaynakla eşitlenir; tercihlerde kaynakta tanımsız anahtar burada varsayılana döner. Tekrar çalıştırmak güvenlidir (aynısı → skipped).
  • Bölüm izni: kaynakta {modül}.view, burada {modül}.manage (bordro bölümleri payroll, izin bölümleri leaves, departman/şube company_settings, vardiya shifts, masraf expenses, avans advance_payments). Yoksa bölüm sections[].status = skipped, reason = permission, required_permission, required_in (source | target); diğer bölümler yine çalışır.
  • Kopyalanmayanlar: personel verisi, departman/şube yönetici adları, şube telefon/e-posta, PDKS bağlantısı (yeni şubeye yeni bağlantı üretilir), merkez şube bayrağı, sektör/NACE, şablon parametreleri (müşteri/firma kodları), kapsamlı hesap eşlemeleri, SGK işyerleri, BES planları.
  • Yan etkiler: grup etkinliğine settings_cloned (iki firmaya; yalnız değişiklik olduysa). E-posta / bildirim yok — vardiya saatleri değişirse ileri tarihli ataması olanlara bildirim gitmez, warnings[].code = shift_assignments_affected döner. Diğer uyarılar: recalculate_required (hesap tercihi değişti), apply_5510_enabled|disabled, applies_to_all (tüm çalışanlara uygulanan tür eklendi), template_params_not_copied.
  • Grup Özeti (group.summary, group.view): yalnız sizin group.view yetkinizin olduğu grup firmaları gelir; firma başına headcount (employees.view), cost (payroll.view: son onaylı / kesinleşmiş / ödenmiş dönem ya da --period ayı; aktarılmış dönemler dahil — brüt, SGK işçi, gelir + damga, net, SGK işveren, teşvik, toplam işveren maliyeti), advances (advance_payments.view: aktif maaş avansı kalanı, bekleyen talepler), work_advances (expenses.view: açık iş avansı bakiyesi), leave (leaves.view: kalan yıllık izin toplamı, ortalama, tahmini karşılık = gün × brüt/30, en yüksek 5 bakiye). Yetkisiz bölüm {available: false, required_permission}; totals yalnız erişilebilir bloklardan, complete=false ise kısmi. warnings: period_mismatch (son dönemler farklı ay → --period verin), cost_missing. GET yan etkisizdir (izin toplamı 10 dk önbelleklenir). --sections headcount,cost ile daraltılır; group.summary.export aynı veriyi Excel olarak verir (Özet, Maliyet, Avanslar, İzin).
bash
empuno reference clone_sections                         # bölümler, gereken yetkiler, eşleme anahtarı, kopyalanmayan alanlar
# Önce deneme: ne eklenecek / güncellenecek / atlanacak (satır bazlı results[])
empuno --company 5 company-settings.clone --from 3 --sections payroll_options,payroll_general,earning_types,deduction_types,leave_types,departments --dry-run
empuno --company 5 company-settings.clone --from 3 --sections payroll_options,earning_types   # uygula (on_existing=skip)
empuno --company 5 company-settings.clone --from 3 --sections departments --on_existing update

empuno --company 3 group.summary                        # her firmanın son kapanmış dönemi
empuno --company 3 group.summary --period 2026-10       # aynı ay
empuno --company 3 group.summary.export --period 2026-10 --output grup-ozeti.xlsx

Grup içi nakil: çalışanı kıdemi ve izniyle başka grup firmasına devretme

Aktif bir çalışanın iş sözleşmesi aynı gruptaki başka firmaya tek komutla devredilir (TBK 429: devralan bütün hak ve borçlarla taraf olur, hizmet süresi kesintisiz sayılır). İstek KAYNAK firmada yapılır (--company = çalışanın şu anki firması), hedef --to ile verilir. Önce önizleyin; ardından --dry-run ile deneyin.

  • Yetki: kaynakta ve hedefte employees.manage + group.manage (ajan anahtarında kapsam + hedef firma anahtarın listesinde). Bordro profili ve kalemleri yalnız kaynakta payroll.view + hedefte payroll.manage varsa kopyalanır (yoksa warnings[].code = payroll_copy_permission).
  • Kaynakta: çıkış transfer_date − 1, SGK kodu varsayılan 22 (16 yalnız iki firmanın vergi numarası aynıysa — grup şirketleri ayrı işverendir); bekleyen izin/avans/masraf talepleri iptal, hesap pasif ve mobil oturumlar kapanır; çıkış ödemesi YAPILMAZ (kayıt dismissed, bordro otomatik oluşturmaz) — kıdem, ihbar ve izin hakları devralanda sürer. Aktif avans, açık iş avansı, zimmet ve icra kaynakta kalır (uyarı döner; --advance_action settle_in_final_payroll kalan avansı çıkış bordrosunda mahsup eder).
  • Hedefte: yeni çalışan kaydı (sicil numarası hedefin önekiyle; aynı T.C.'li AYRILMIŞ kayıt varsa yeniden kullanılır, AKTİF varsa 422 target_identity_active), aynı e-posta + aynı şifreyle çalışan hesabı (yönetici rolü / yetki devirleri taşınmaz; KVKK aydınlatması ilk girişte yeniden), kaynaktaki çalışma dönemleri "önceki hizmet" + nakil tarihinde devam eden güncel dönem (kıdem ve izin kıdemi kaynaktaki başlangıçtan), devreden yıllık izin (kalan bakiye; nakil gününe denk gelen yıldönümü dahil), ileri tarihli ONAYLI izinler (hedefte aynı türle; yoksa iptal + uyarı), bordro profili (effective_from = transfer_date; teşvik ve Ar-Ge alanları sıfırlanır) ve süreli kalemler (tür KODUYLA; hedefte kod yoksa atlanır — önce company-settings.clone --sections earning_types,deduction_types). Kümülatif GV matrahı hedefte sıfırdan başlar (bilgi: cumulative_tax_base_at_transfer).
  • Kişisel veri (KVKK): hedefe yalnız izin listesindeki alanlar gider (kimlik, iletişim, adres, banka/IBAN, SGK, eğitim, aile, acil durum; özel nitelikli veriden yalnız engellilik derecesi). Evrak varsayılan none; employment = iş sözleşmesi, NDA, SGK işe giriş, hizmet dökümü, diploma, devir protokolü; tür listesi de verilebilir — sağlık (isg) ve adli sicil seçilse de kopyalanmaz. Önizlemede T.C. ve IBAN maskeli.
  • Rıza (TBK 429): işçinin yazılı rızası gerekir; sistem ön koşul yapmaz. group-transfers.protocol devir protokolünü üretir (T.C. tam yalnız employees.manage'de), imzalı nüsha group-transfers.consent ile yüklenir → iki firmanın özlük dosyasına devir_protokolu; kayıt consent_status = received.
  • Yan etkiler: iki firmanın grup etkinliğine employee_transferred / transfer_linked / consent_received; documents ≠ none ise evrak kopyası arka planda (documents.copied); notify_employee (varsayılan true) çalışana bilgilendirme e-postası (davet değil); taşınan ileri tarihli izin mali müşavire gönderilmiş bir dönem raporuna düşüyorsa (geriye tarihli nakil) o dönemin raporu iki firmada yeniden üretilip "Düzeltme: İzin Raporu" maili gider — kaynakta "Rapordan çıkarıldı", hedefte "Rapora eklendi (grup içi nakil)"; önizlemede leave.accountant_reports[], sonuçta accountant_corrections {planned, sent, failed}, --notify_accountants false kapatır. --dry-run hepsini geri alır: id'ler null, e-posta, iş ve düzeltme yok (plan yine döner).
  • Tekrar güvenli: aynı çalışanın tamamlanmış nakli varsa yeni nakil yapılmaz, duplicate: true ile mevcut kayıt döner. Geçmiş nakil bağlamada aynı çift skipped.
  • Geçmiş nakiller (group-transfers.candidates → link-bulk): aynı T.C.'li "bir firmada ayrılmış + diğerinde çıkıştan sonraki 31 gün içinde girmiş" çiftleri sistem bulur (iki yönde; her satırdaki record olduğu gibi gönderilir). Bağlama kayıt oluşturmaz: hedefe kaynak dönemleri (boşluksuzsa devam zinciri, boşluk varsa link_gap uyarısı) + devreden izin (kaynakta çıkışta izin ücreti ödenmişse 0, leave_paid_at_exit) yazar; hedefte elle girilmiş devreden izin varsa üzerine yazmaz. Satır bazlı results[] (created | skipped | failed + rule).
  • Geri alma (group-transfers.revert, --reason zorunlu, --dry-run destekli, tekrar güvenli): yanlış nakil için iki firmada tek işlemde geri dönüş — kaynakta çıkış geri alınır (çalışan + hesap aktif, son çalışma dönemi açık, çıkışta otomatik iptal edilen bekleyen talepler geri gelir, "ödenmedi" çıkış kaydı silinir), hedefte çalışan kaydı kaldırılır (nakilden önce de var olan ayrılmış kayıt ayrılmış hâline döner), hedef hesap nakil öncesi hâline döner (nakilde açılan hesap silinir; önceden var olan İK / mali müşavir / yönetici hesabı önceki aktiflik ve çalışan bağıyla kalır — summary.target_account: deleted | unlinked | deactivated), devralınan dönemler, devreden izin, kopyalanan bordro profili/kalemleri silinir; taşınan ileri tarihli izinler hedefte arşivlenir ve kaynakta yeniden onaylı olur — mali müşavire gönderilmiş bir döneme düşüyorsa iki firmada düzeltme raporu gider (summary.accountant_reports, --notify_accountants false kapatır). Hedef firmadan geri alınıp hedef kayıt silindiyse yanıtta redirect_to (Nakiller; çalışan kartı artık açılmaz). Bağlamada (mode=link) yalnız dönem bağı, devreden izin ve bağlamanın açtığı çıkış kaydı kaldırılır. Kayıt silinmez (status=reverted, revert_reason); iki firmaya transfer_reverted. Koşullar group-transfers.show → revert.blockers[]: revert_target_activity (hedefte nakilden sonra hareket — bordro fişi, izin talebi, PDKS / puantaj, masraf, maaş / iş avansı, zimmet, vardiya ataması, yüklenmiş evrak (kopyalanan evrak ve devir protokolü hariç), teşvik, haciz, BES, yeni bordro profili / kalemi; activity sayıları — önce hedefte geri alın: zimmeti iade alın, vardiya atamasını / evrakı silin), revert_source_payroll_closed (kaynakta çıkış ayı ve sonrası onaylı/kesinleşmiş/ödenmiş dönem; periods — önce payroll.reopen), revert_source_changed, revert_target_changed, revert_source_license_full, revert_manual_required. Koşul sağlanmıyorsa doğru yol hedefte employees.terminate + kaynakta employees.rehire. Devredilmiş çalışanı employees.reactivate ile geri almak reddedilir (transferred_out): kişi iki firmada aktif kalırdı.
  • Hata kodları (422 rejected, rule): employee_not_active (ayrılmış çalışan → link), self_transfer, last_admin, transfer_date_invalid (girişten sonra, en geç bugün), exit_code_invalid, exit_code_16_not_same_employer, target_identity_active, target_email_taken, target_email_deleted, target_license_full, active_equipment (--confirm_active_equipment true), target_department_foreign / target_branch_foreign, transfer_periods_conflict, link_*. Erişim (403): company_not_in_key, company_not_in_group, no_account_there, permission_there (+ required_permission).
bash
empuno reference group_transfer_options                 # varsayılanlar, çıkış kodları, evrak modları, kopyalanan / sıfırlanan alanlar
empuno --company 3 employees.group-transfer.create 812 --to 5 --transfer_date 2026-12-01      # önizleme (yan etkisiz)
empuno --company 3 employees.group-transfer.store 812 --to 5 --transfer_date 2026-12-01 --documents employment --dry-run
empuno --company 3 employees.group-transfer.store 812 --to 5 --transfer_date 2026-12-01 --documents employment

empuno --company 3 group-transfers.index --direction out              # giden / gelen nakiller, rıza durumu
empuno --company 3 group-transfers.protocol 41 --output devir-41.pdf  # imzalatılacak devir protokolü
empuno --company 3 group-transfers.consent 41 --document @imzali.pdf  # imzalı protokolü yükle (iki firmanın dosyasına)

# Geçmişte yapılmış geçişler: sistem bulur, siz onaylarsınız
empuno --company 3 group-transfers.candidates
empuno --company 3 group-transfers.link-bulk --records '[{"source_employee_id":812,"target_employee_id":95,"to":"b-lojistik"}]' --dry-run

# Yanlış nakil: önce koşullar, sonra deneme, sonra geri alma (iki firmada tek işlem)
empuno --company 3 group-transfers.show 41                            # revert.available + revert.blockers[]
empuno --company 3 group-transfers.revert 41 --reason "Yanlış firma seçildi" --dry-run
empuno --company 3 group-transfers.revert 41 --reason "Yanlış firma seçildi"

Hata kodları

Her hata gövdesi {"ok": false, "error": "<kod>", "message": "…", "hint": "…"} biçimindedir. Liste tek kaynaktan gelir; makine okunur hali: empuno reference agent_errors (GET /api/company/v1/reference/agent_errors).

HTTPerrorAnlamıNe yapmalı
401unauthenticatedAnahtar yok, geçersiz, süresi dolmuş ya da iptal edilmiş.Firma Ayarları → API & Ajan sekmesinden yeni anahtar oluşturun.
401key_owner_inactiveAnahtarı oluşturan kişi artık aktif değil.Aktif bir yöneticiyle yeni anahtar oluşturun.
403read_only_keySalt-okuma entegrasyon anahtarı panel komutlarını çalıştıramaz."Ajan" türünde anahtar oluşturun.
403company_inactiveAnahtarın bağlı olduğu firma ya da grup anahtarında hedef firma (X-Empuno-Company) pasif (askıda).Firma yöneticisine bildirin; grup anahtarı diğer firmalarda çalışmaya devam eder.
403scope_requiredKomut company_admin kapsamı istiyor (required_scope).Anahtar sahibi kapsamı panelden genişletir.
403forbiddenModül yetkisi yok; gereken izin required_permission alanında.Anahtar kapsamına ve sahibinin yetkisine ilgili izni ekletin.
403legal_consent_requiredAnahtar sahibi KVKK ve Kullanım Şartları (yöneticiyse ayrıca Veri İşleme Sözleşmesi) onayını vermemiş; ajan onun adına çalıştığı için panel komutları kapalı.Ajan bu onayı veremez: anahtar sahibine bildirin, panele giriş yapıp onay ekranını tamamlasın (redirect alanı). Sonra aynı komutu tekrar çalıştırın.
403email_verification_requiredAnahtar sahibinin e-posta adresi doğrulanmamış; panel komutları kapalı.Anahtar sahibine bildirin: panele giriş yapıp e-posta doğrulamasını tamamlasın. Tekrar denemek işe yaramaz.
404unknown_commandUç bir ajan komutu değil (ya da ajana kapalı).empuno commands ile doğru komutu bulun; yoksa talep açın.
404not_foundKayıt bulunamadı ya da bu firmaya ait değil.Kimliği liste komutuyla doğrulayın.
404no_receiptMasrafın fiş görseli yok (/api/company/v1 masraf fişi indirme).Masraf kaydı geçerli; görsel yüklenmemiş. Tekrar denemeyin.
405method_not_allowedKomut bu HTTP metoduyla çağrılamaz.Katalogdaki method alanını kullanın.
409conflictİşlem kaydın mevcut durumuyla çelişiyor.Kaydın güncel durumunu okuyup yeniden deneyin.
422validation_failedEksik/yanlış alan; ayrıntı errors alanında.errors alanındaki alanları düzeltip yeniden gönderin.
422rejectedİş kuralı reddi (message) ya da doğrulama hatası (errors).Mesajdaki kuralı giderin; deneme için --validate kullanın.
429rate_limitedHız sınırı aşıldı.Retry-After saniye bekleyin.
429insufficient_ai_creditsFirmanın AI kredisi bu işlem için yetmiyor (credits.remaining / credits.requested). Hız sınırı DEĞİLDİR; hiçbir şey yapılmadı.Beklemek ya da tekrar denemek işe yaramaz: yöneticiye AI kredisinin bittiğini bildirin; varsa AI kullanmayan komutu seçin (ör. dosyadan aktarım: empuno migrate …).
500server_errorSunucu hatası; işlem yapılmış, yarım kalmış ya da hiç yapılmamış olabilir.Önce durumu okuma komutuyla doğrulayın. Aynı Idempotency-Key ile tekrar göndermek komutu YENİDEN ÇALIŞTIRMAZ (409 idempotency_replay_unavailable döner); işlem yapılmadıysa YENİ anahtarla gönderin.
422dry_run_unsupportedKomut denemede (dry_run) çalıştırılamaz: dış servis/AI çağırır ya da taklit edilemeyen bir kanala gider (reason / blocked). Hiçbir şey kaydedilmedi.Katalogdaki dry_run alanına bakın; gerekiyorsa denemeden gerçek çalıştırın.
500dry_run_failedDeneme güvenle tamamlanamadı; hiçbir değişiklik kaydedilmedi.Talep açın (empuno tickets open … --kind bug); komutu denemesiz çalıştırmadan önce durumu okuyun.
400idempotency_key_requiredBu anahtar için her yazmada Idempotency-Key zorunlu (deneme hariç).Idempotency-Key başlığı ya da client_request_id alanı ekleyin (CLI: --idempotency-key).
400idempotency_key_invalidTekrar anahtarı boş, 120 karakterden uzun ya da başlık ile gövde değeri farklı.Tek bir geçerli anahtar gönderin.
409idempotency_in_progressAynı anahtarla gönderilen ilk istek hâlâ işleniyor (elapsed_seconds).Retry-After kadar bekleyip AYNI anahtarla tekrar deneyin (CLI: --retry); yeni anahtarla göndermeyin.
409idempotency_replay_unavailableBu anahtarla işlem yeniden YAPILMADI ve kayıtlı yanıt verilemiyor. reason: previous_attempt_failed (önceki deneme sunucu hatasıyla bitti, sonuç belirsiz), stale_lock (ilk istek kilit süresinde bitmedi), not_stored (başarılı dosya yanıtı saklanmaz), unreadable.İşlemin gerçekleşip gerçekleşmediğini okuma komutuyla doğrulayın; yapılmadıysa YENİ anahtarla gönderin. stale_lock'ta ilk istek sonradan biterse aynı anahtar kayıtlı yanıtı döndürür.
422idempotency_key_reusedAnahtar son 24 saatte farklı içerikli bir istekte kullanıldı.Yeni işlem için yeni anahtar kullanın; aynı işlemse gövde birebir aynı olmalı.
409ambiguous_periodYYYY-AA etiketi birden çok bordro dönemine uyuyor; adaylar candidates[] alanında (id, status, imported, slips_count, deleted, deletable). Silme ve geri almada (payroll.destroy / payroll.restore) etiket yalnız o ayın silinmişler DAHİL tek dönemi varsa çözülür — tekrar çağrı başka dönemi seçmesin diye.hint alanındaki komutu id ile çağırın (geri almada payroll.restore <id>; deleted=true aday payroll.show ile açılmaz); iptal edilmiş/test dönemini payroll.destroy <id> --reason "…" ile silin.
422parameters_missingTarih için yasal bordro parametre seti yok (empuno 2021-01-01 ve sonrasını destekler). payroll.simulate ve payroll.calculate --dry_run 422; reference payroll_parameters 404 döner (kod aynı; available=false, earliest).Daha yeni bir dönem seçin; 2021 sonrası bir yılda görülürse hint'teki payroll:parameters-sync komutunu yöneticiye iletin ya da talep açın.
422migration_pendingÖzellik için veritabanı güncellemesi henüz uygulanmamış; hiçbir şey yazılmadı (ör. payroll.bulk-destroy). Panel yönlendirmeli komutlarda (payroll.destroy / payroll.restore) aynı durum rejected + errors.period metniyle gelir.Bir süre sonra aynı komutla tekrar deneyin; sürerse talep açın (empuno tickets open … --kind bug).
400company_requiredGrup anahtarı her panel isteğinde (okuma dahil) hedef firmayı ister; başlıksız istek hiçbir firmada çalışmaz.X-Empuno-Company başlığı gönderin (firma id ya da slug); CLI: --company <id|slug> ya da EMPUNO_COMPANY. Firmalar: empuno companies (GET /api/company/v1/companies).
403company_mismatchTek firmalı anahtar başka bir firma için kullanıldı: X-Empuno-Company anahtarın firmasıyla uyuşmuyor (key_company).Başlığı kaldırın ya da o firmanın anahtarını kullanın (CLI: --profile). Birden çok grup firmasında çalışmak için grup anahtarı oluşturun (Firma Ayarları → API & Ajan → Firmalar).
403company_access_revokedGrup anahtarının bu firmadaki erişimi kalktı (reason: detached_by_member | left_group | removed_by_owner | group_dissolved | account_unavailable). Diğer firmalarda anahtar çalışmaya devam eder.Anahtar sahibine bildirin: erişim panelden yeniden eklenir (Firma Ayarları → API & Ajan). account_unavailable: sahibinin o firmadaki hesabı pasif, silinmiş ya da şifresi artık aynı değil.
403company_not_in_keyFirma bu anahtarın izin listesinde değil ya da böyle bir firma yok (tek firmalı anahtar yalnız kendi firmasında çalışır).empuno companies ile erişilebilir firmaları görün; başka firmada çalışmak için grup anahtarı kullanın (Firma Ayarları → API & Ajan → Firmalar).
403company_not_in_groupHedef firma bu firmanın grubunda değil.group.index ile grup üyelerini görün; firma gruba group.companies.store ya da davet koduyla (group.join) katılır.
403no_account_thereHedef firmada aynı e-posta ve aynı şifreyle aktif bir hesabınız yok.Hedef firmanın yöneticisinden sizi aynı e-postayla eklemesini isteyin.
403permission_thereHedef firmadaki hesabınızın bu işlem için yetkisi yok (required_permission).Hedef firmanın yöneticisinden yetkiyi isteyin.

İş kuralı reddinde üst düzey error rejected (422) olur; makine kodu flash.rule, sonraki komut flash.hint alanındadır (çalışma dönemi, SGK işyeri, devreden izin). Aynı listede returned_as: "flash.rule" ile işaretlidir:

flash.ruleAnlamıNe yapmalı
overlapDönemler çakışıyor (aynı günler iki dönemde).Tarihleri düzeltin; employees.employments.index ile mevcut dönemleri okuyun.
open_not_lastYalnız en son dönem açık (çıkışsız) olabilir.Önceki dönemin çıkış tarihini girin.
continuity_gap"Önceki dönemin devamı" işaretli dönem, önceki dönemin çıkışının ertesi günü başlamıyor.Giriş tarihini önceki çıkış + 1 gün yapın ya da continues_previous=false gönderin.
continuity_without_previousİlk dönem "önceki dönemin devamı" olamaz.continues_previous=false gönderin.
open_row_terminatedAyrılmış çalışanın son dönemi açık kalamaz.Son döneme çıkış tarihi girin ya da hatalı çıkışı employees.reactivate ile geri alın.
active_without_open_rowAktif çalışanın son dönemi açık olmalı.Ayrılmışsa employees.terminate; yeni dönem için employees.rehire.
no_employment_rowÇalışanın "bu firmada" (kind=employment) dönemi kalmıyor.En az bir employment dönemi bırakın.
use_terminateAçık (güncel) döneme çıkış bu uçla girilmez.employees.terminate kullanın (hesap kapatma, bekleyen talepler, çıkış ödemesi).
use_reactivateSon dönemin çıkışı bu uçla silinemez.Hatalı çıkış: employees.reactivate; yeni sözleşme: employees.rehire.
termination_requiredSon dönemden önceki dönem kapalı olmalı.termination_date gönderin.
contract_start_rowGüncel sözleşmenin başlangıç dönemi silinemez.Tarihini employees.employments.update ile düzeltin.
open_rowAçık (güncel) dönem silinemez.Çıkış: employees.terminate; tarih düzeltme: employees.employments.update.
hire_date_requiredDönemin giriş tarihi zorunlu.hire_date gönderin (YYYY-AA-GG).
hire_in_futureGiriş tarihi bugünden ileri olamaz.Bugün ya da geçmiş bir tarih gönderin.
exit_in_futureÇıkış tarihi bugünden ileri olamaz.Gelecekteki çıkış için tarihi gelince employees.terminate.
exit_before_hireÇıkış tarihi girişten önce.Tarihleri düzeltin.
invalid_exit_codeGeçersiz SGK çıkış kodu.empuno reference sgk_exit_codes.
invalid_kindGeçersiz dönem türü.kind: employment | prior_service (empuno reference employment_kinds).
invalid_insurance_groupGeçersiz sigorta türü.insurance_group: normal | sgdp | none.
prior_service_employer_requiredÖnceki hizmet (prior_service) için işveren adı zorunlu.external_employer_name gönderin.
prior_service_openÖnceki hizmet (prior_service) dönemi kapalı olmalı.termination_date gönderin.
hire_date_conflicts_periodsÇalışan kartındaki işe giriş tarihi (employees.update, mobil, root admin) çalışma dönemleriyle çakışıyor; hiçbir alan yazılmadı.hint'teki employees.employments.update komutuyla dönemi düzeltin ya da önce önceki dönemi düzenleyin.
not_activeAyrılmış çalışan nakledilemez / işlem aktif çalışan ister.Önce employees.rehire.
same_workplaceÇalışan zaten bu işyerinde.Başka işyeri seçin ya da tarihsiz düzeltme için employees.update --sgk_workplace_id.
not_terminatedYalnız ayrılmış çalışan yeniden işe alınır.Aktif çalışan için işlem gerekmez; hatalı çıkış employees.reactivate.
rehire_before_exitYeniden giriş tarihi son çıkıştan sonra olmalı.hire_date'i son çıkış + 1 gün ya da sonrası yapın.
license_fullLisans dolu; yeniden işe alım yapılamaz.Lisansı yükseltin ya da başka bir çalışanı pasifleştirin.
payroll_permission_requiredBordro alanı (bordro profili, kıdem ödemesi, kıdeme sayılma kararı) bordro yönetme yetkisi (payroll.manage) ister; hiçbir şey yazılmadı.Bu alanlar olmadan gönderin; bordro yetkilisi ayrıca girer.
workplace_foreignSGK işyeri bulunamadı ya da bu firmaya ait değil.empuno reference sgk_workplaces (id, 26 haneli sicil ya da ad).
workplace_closedSGK işyeri kapatılmış; dönem/nakil kapalı işyerine yazılamaz.Açık bir işyeri seçin ya da sgk-workplaces.update --closed_at null.
workplace_in_useİşyerine bağlı dönem ya da bordro fişi var; silinemez.sgk-workplaces.update --closed_at <tarih> ile kapatın.
registration_takenBu sicil numarası firmada başka bir işyerinde kayıtlı.Mevcut işyerini kullanın (empuno reference sgk_workplaces).
invalid_registration_noSGK işyeri sicil numarası 26 hane değil ya da sayı olarak gönderildi.Sicili METİN olarak 26 hane gönderin (boşluk/tire serbest).
registration_missingİşyerinin sicil numarası yok; geçmişe yazılacak ya da birleştirilecek numara yok.Önce güncel numarayı girin: sgk-workplaces.update <id> --registration_no "…".
same_registrationYeni numara güncel numarayla aynı.Farklı bir numara gönderin.
date_too_farSicil değişikliği tarihi bir yıldan ileri.Yeni numaranın ilk gününü verin (en çok bir yıl ileri).
registration_date_orderDeğişiklik tarihi son eski numaranın bitişinden önce.sgk-workplaces.index ile sicil geçmişini okuyun; tarihi sonraya alın.
registration_is_currentNumara işyerinin güncel numarası; geçmişe eklenemez.Numara değiştiyse sgk-workplaces.change-registration kullanın.
registration_range_invalidEski numaranın başlangıcı bitişinden sonra.valid_from ≤ valid_until gönderin.
registration_ranges_overlapSicil geçmişi aralıkları çakışıyor (bir işyerinin aynı anda tek numarası olur).Tarihleri düzeltin; sgk-workplaces.index ile geçmişi okuyun.
merge_selfHedef işyeri kaynak listesinde.Kaynakları (source_ids) hedeften ayrı verin.
merge_range_unknownBirleştirilen numaranın son geçerli günü bilinmiyor (fiş ve çalışma dönemi yok ya da dönem açık).valid_until {kaynak_id: YYYY-AA-GG} gönderin.
merge_target_not_latestHedef işyerinin numarası en son kullanılan değil.sgk-workplaces.merge-suggestions önerisindeki hedefi kullanın ya da valid_until ile son günleri verin.
name_requiredİşyeri adı ya da sicil numarası gerekli.name ya da registration_no gönderin.
invalid_law_noKanun numarası 4–5 haneli rakam olmalı.empuno reference incentive_codes.
invalid_zone_typeGeçersiz bölge türü.zone_type: standard | technopark | rd_center.
branch_foreignŞube bulunamadı (bu firmaya ait değil).empuno reference branches.
as_of_in_futureDevreden izin tarihi bugünden ileri olamaz.Bugün ya da geçmiş bir tarih gönderin.
as_of_before_contractDevreden izin tarihi güncel sözleşme başlangıcından önce.Önceki dönemin izni yeni bakiyeye taşınmaz; aynı iş ilişkisi sürüyorsa önceki dönemi employees.employments.store ile ekleyin.
as_of_after_exitDevreden izin tarihi çıkış tarihinden sonra (ayrılmış çalışanın izni çıkışta donar).as_of_date'i çıkış tarihi ya da öncesi yapın.
incentive_unknown_lawKanun numarası teşvik kataloğunda yok.empuno reference incentive_codes ile geçerli kanun numarasını seçin (5 hane; 6111 → 06111 kabul edilir).
incentive_not_assignableBu kanun çalışana atanamaz: 05510 ve 00000 firma ayarıyla (5510 uygulansın mı), 05746 bordro profilindeki Ar-Ge alanıyla yönetilir; yalnız referans olan ya da motorun hesaplamadığı kanunlar atanmaz.Ar-Ge için employees.payroll-profile.update --rd_incentive 5746; 5510 için payroll-settings.update --auto_apply_incentive; atanabilenler reference incentive_codes → assignable=true.
incentive_expiredKanunun yararlanma süresi bu tarihte dolmuş (expired: benefit_until …).reference incentive_codes → benefit_until; geçmiş dönem için start_date ve end_date'i yararlanma süresi içinde verin.
incentive_dates_invalidTarih geçersiz (bitiş başlangıçtan önce ya da başlangıç işe girişten çok önce).start_date ≤ end_date olmalı; varsayılan başlangıç işe giriş tarihidir.
incentive_employee_terminatedAyrılmış çalışana çıkış tarihinden sonra başlayan teşvik atanamaz.start_date'i çıkış tarihinden önce verin ya da atamayı yapmayın.
incentive_fact_invalidTeşvik bilgisi anahtarı ya da değeri geçersiz.empuno reference incentive_fact_keys (anahtar, tür, seçenekler).
pension_no_active_planFirmada aktif BES planı yok.pension.plans.store ile emeklilik şirketi sözleşmesini (şirket + sözleşme no) ekleyin.
pension_plan_foreignBES planı bulunamadı ya da bu firmaya ait değil.empuno reference pension_plans.
pension_already_enrolledÇalışanın güncel bir BES kaydı var.employees.pension.update ya da employees.pension.action kullanın.
pension_terminatedAyrılmış çalışan BES planına dahil edilemez.Yeniden işe alımda (employees.rehire) yeni kayıt açılır.
pension_age_45_requires_request45 yaşını doldurmuş çalışan yalnız kendi talebiyle dahil edilir (4632 ek md. 2).Çalışanın talebi varsa voluntary=true gönderin; çalışan web/mobilden de talep edebilir.
pension_foreign_citizenYabancı uyruklu çalışan otomatik katılım kapsamında değil (Türk vatandaşı ya da 5901 md. 28).5901 md. 28 kapsamındaysa çalışan kartında vatandaşlığı güncelleyin.
pension_insurance_groupSigorta grubu otomatik katılım kapsamında değil (sigortasız).Bordro profilinde sigorta grubunu kontrol edin.
pension_opt_out_deadline_passedCayma süresi (plana dahil olduğunun bildirildiği tarihten 2 ay) geçti.action=leave_system (sistemden ayrılma) ya da action=pause (katkıya ara verme) kullanın.
pension_use_opt_outBaşlangıç döneminde (cayma süresi içinde) sistemden ayrılma / ara verme yerine cayma kullanılır.action=opt_out gönderin (iade emeklilik şirketince 10 iş günü içinde).
pension_invalid_actionBu işlem kaydın bugünkü durumunda yapılamaz.employees.pension.show ile durumu okuyun (reference pension_actions).
pension_rate_below_legalKatkı oranı yasal oranın (%3) altına inemez.rate en az 3 olmalı.
pension_rate_above_maxKatkı oranı izin verilen üst sınırı aşıyor.Daha düşük bir oran gönderin.
pension_date_invalidTarih geçersiz (dahil olmadan önce ya da ara verme bitişi başlangıçtan önce).effective_date / until değerlerini düzeltin.
period_not_calculatedDönem hesaplanmamış (taslak) ya da iptal edilmiş; fiş ve ödeme dosyası çıkmaz.Önce payroll.calculate; iptal edilmiş dönemde çıktı yok.
period_not_finalizedMuhasebeleştirme için dönem kesinleşmiş ya da ödenmiş olmalı.payroll.finalize; taslak fişi payroll.accounting-voucher ile yine indirebilirsiniz.
already_postedDönemin tahakkuk fişi zaten muhasebeleştirildi ve dönem o tarihten sonra değişti.Farkı düzeltme fişiyle işleyin: payroll.accounting-voucher --kind correction, ardından payroll.accounting-postings.store --kind correction.
correction_without_postingDüzeltme fişi için önce tahakkuk fişi muhasebeleştirilmiş olmalı.payroll.accounting-postings.store --kind accrual.
nothing_to_correctMuhasebeleştirilmiş tutarlarla güncel bordro arasında fark yok.Düzeltme fişi gerekmiyor.
empty_voucherFişte satır yok (dönemde fiş ya da ödenecek net yok).payroll.show ile dönemin fişlerini kontrol edin.
voucher_unbalancedFiş dengesiz (borç ≠ alacak); muhasebeleştirilemez.payroll.accounting-voucher uyarılarını inceleyin.
voucher_integrityFişte kuruş farkı olmayan tutarsızlık var: kendi içinde tutmayan bordro fişi (fark askı hesabında) ya da açıklanamayan işveren maliyeti farkı.payroll.accounting-voucher → integrity.slips[] (fiş, çalışan, tutar, findings[]) ve integrity.employer_cost_gap; kaynak fişleri düzeltin (data-migration.payroll.commit --on_existing update) ya da bilerek muhasebeleştirmek için accept_integrity_issues=true gönderin.
template_not_foundDosya şablonu ya da önayar bulunamadı.Önayarlar: empuno reference bank_file_presets / payroll_voucher_formats ("preset:<anahtar>"); firma şablonları payroll-settings.export-templates.index ("template:<id>").
template_name_takenBu adla aynı türde bir şablon zaten var.payroll-settings.export-templates.update ile güncelleyin ya da başka bir ad verin.
unknown_fieldŞablonda alan kataloğunda olmayan bir alan adı var.empuno reference export_template_fields; sabit değer için const:<değer>, parametre için param:<anahtar>, boş sütun için empty.
invalid_bank_codeBanka kodu 5 haneli EFT/ÖHS kodu olmalı.empuno reference tr_bank_codes.
invalid_param_ibanŞablon parametresindeki IBAN (ör. borçlu firma hesabı) geçersiz (mod-97).params.debit_iban değerini bankanızdaki IBAN ile düzeltin (TR + 24 hane).
detect_failedÖrnek dosyada başlık satırı bulunamadı (ilk 30 satırda en az 2 tanınan sütun).Başlıkları IBAN, Tutar, TC Kimlik No, Ad Soyad (fişte Hesap Kodu, Borç, Alacak) gibi tanınır adlarla yazın ya da şablonu elle oluşturun.
file_unreadableDosya okunamadı.xlsx, xls, csv ya da txt yükleyin (en çok 5 MB).
not_approvedBanka ödeme dosyası yalnız onaylanmış, kesinleşmiş ya da ödenmiş dönemde üretilir.Önce payroll.approve; önizleme (payroll.bank-file) her hesaplanmış dönemde açık.
total_changedToplam tutar önizlemede görülenle aynı değil (bordro ya da IBAN'lar değişmiş olabilir).payroll.bank-file ile yeniden önizleyin ve confirm_total'ı yeni toplamla gönderin.
no_payable_rowsDosyaya girecek çalışan yok.Önizlemedeki excluded[] / other_bank[] nedenlerine bakın; eksik IBAN için payroll.bank-file.request-iban, diğer bankalar için include_other_banks=true ya da genel şablon.
missing_paramsŞablonun zorunlu parametresi eksik (ör. firma müşteri no, borçlu IBAN).İsteğe params.<anahtar> ekleyin ya da şablonu payroll-settings.export-templates.update --params ile kalıcı tamamlayın.
revision_not_foundKapanmış düzeltme turu bulunamadı.source=revision yalnız düzeltmeye açılıp yeniden kesinleşmiş dönemde; revision_id payroll.show revisions[]'dan.
invalid_payment_dateÖdeme tarihi geçersiz.payment_date YYYY-AA-GG biçiminde gönderin.
already_in_groupFirma zaten bir grubun üyesi (bir firma en fazla bir gruba üye olabilir).Önce group.leave ile mevcut gruptan ayrılın; gruplar birleştirilmez.
not_in_groupFirma bir gruba üye değil.group.index ile grubu ve üyeleri görün; grup yoksa group.store ile oluşturun.
not_manager_thereEklenmek istenen firmada aynı e-posta ve şifreyle YÖNETİCİ hesabınız yok.O firmanın yöneticisinden davet kodu isteyin: karşı tarafta group.invites.store, burada değil o firmada group.join --code.
invalid_inviteDavet kodu geçersiz, süresi dolmuş, iptal edilmiş ya da kullanılmış.Grubun bir üyesinden yeni kod isteyin (group.invites.store; kodlar 7 gün geçerli, tek kullanımlık).
invite_foreignDavet kodu bu firmanın grubuna ait değil.group.index invites[] listesindeki kimliği kullanın.
group_name_requiredGrup adı gerekli.name gönderin (en çok 120 karakter).
same_companyKaynak ve hedef firma aynı.Başka bir grup firması seçin.
company_not_foundFirma bulunamadı (id ya da slug).group.index members[] ya da empuno companies ile firma kimliğini doğrulayın.
employee_not_activeYalnız aktif çalışan naklen devredilir; bu çalışan ayrılmış.Geçmişte yapılmış bir geçişi bağlamak için group-transfers.candidates ve group-transfers.link-bulk kullanın.
self_transferKendi çalışan kaydınızı nakledemezsiniz.Naklinizi başka bir yönetici yapsın.
last_adminFirmanın son yöneticisi nakledilemez (en az bir yönetici kalmalı).Önce başka bir kullanıcıyı yönetici yapın.
transfer_date_invalidNakil tarihi geçersiz: işe girişten (ve son çalışma döneminin başlangıcından) sonra ve en geç bugün olmalı.transfer_date = hedef firmadaki ilk iş günü (YYYY-AA-GG); kaynakta çıkış bir gün öncesine yazılır. İleri tarihli planlı nakil yok: tarihinde yapın.
exit_code_invalidGeçersiz SGK çıkış kodu.Boş bırakın (22 — Diğer nedenler) ya da empuno reference group_transfer_options (exit_codes).
exit_code_16_not_same_employerKod 16 yalnız aynı işverenin (aynı vergi numarası) işyerleri arasında kullanılır; bu iki firmanın vergi numarası farklı.Kodu boş bırakın (22 — Diğer nedenler). Grup şirketleri ayrı işverendir (SGK duyurusu).
target_identity_activeHedef firmada aynı T.C. kimlik numaralı AKTİF bir çalışan var (çift kayıt açılmaz).Kişi hedefte zaten çalışıyorsa geçmiş nakli group-transfers.link-bulk ile bağlayın (önce kaynakta çıkış: employees.terminate).
target_email_takenHedef firmada bu e-posta başka bir aktif çalışana bağlı.Aynı kişiyse geçmiş nakli group-transfers.link-bulk ile bağlayın; değilse kaynak çalışanın e-postasını düzeltin.
target_email_deletedHedef firmada bu e-postayla silinmiş bir çalışan kaydı var (e-posta firmada tekildir).Hedef firmada silinmiş kaydın e-postasını değiştirin ya da destek ekibine yazın (empuno tickets).
target_license_fullHedef firmanın lisansı dolu.Hedef firmada lisansı artırın ya da bir aktif çalışanı pasifleştirin.
active_equipmentÇalışanın zimmetli ekipmanı var.Önce iade alın ya da confirm_active_equipment=true ile devam edin (zimmet kaynak firmada kalır).
target_department_foreignDepartman hedef firmaya ait değil.Boş bırakın (kaynaktaki departman adıyla eşlenir, yoksa varsayılan) ya da hedef firmanın departman kimliğini verin (empuno --company <hedef> departments.index).
target_branch_foreignŞube hedef firmaya ait değil.Boş bırakın (kaynaktaki şube adıyla eşlenir, yoksa merkez şube) ya da hedef firmanın şube kimliğini verin.
transfer_periods_conflictDevralınan çalışma dönemleri hedefteki mevcut dönemlerle çakışıyor.Hedef çalışanın dönemlerini düzeltin (employees.employments.*) ya da destek ekibine yazın.
link_source_activeBağlama yalnız kaynakta AYRILMIŞ çalışan için yapılır; aktif çalışan naklen devredilir.employees.group-transfer.store ile nakledin.
link_identity_mismatchİki kaydın T.C. kimlik numarası aynı değil ya da biri boş.Doğru çifti group-transfers.candidates ile bulun.
link_dates_invalidHedefteki işe giriş, kaynaktaki çıkıştan sonra olmalı.Tarihleri kontrol edin (employees.termination.update / employees.employments.update).
link_target_not_activeBağlanacak hedef çalışan aktif değil.Hedefte çalışan ayrıldıysa bağlama anlamsız; tarihleri kontrol edin.
transfer_not_completedNakil kaydı tamamlanmış durumda değil (geri alınmış).group-transfers.index ile güncel kayıtları görün.
revert_source_changedKaynak çalışan nakilden sonra değişmiş (artık ayrılmış değil, çıkış tarihi farklı, silinmiş ya da yeniden işe alınmış): otomatik geri alma güvenli değil.Çalışan kartını kontrol edin; gerekiyorsa hedefte işten çıkış (employees.terminate) + kaynakta yeniden işe alım (employees.rehire) ile elle düzeltin.
revert_target_changedHedef çalışan artık aktif değil ya da silinmiş (ayrılmış ya da yeniden nakledilmiş): otomatik geri alma güvenli değil.Önce sonraki nakli / çıkışı geri alın; değilse kaynakta yeniden işe alım (employees.rehire) ile elle düzeltin.
revert_target_activityHedef firmada nakilden sonra bu çalışan için hareket var (bordro fişi, izin talebi, PDKS / puantaj, masraf, avans, zimmet, vardiya ataması, yüklenmiş evrak, teşvik, haciz, BES ya da yeni bordro profili / kalemi): geri alma bu kayıtları sahipsiz bırakırdı.activity alanı sayıları verir. Hareketleri hedefte geri alın (zimmeti iade alın, vardiya atamasını / evrakı / kaydı silin) ya da nakli geri almak yerine hedefte işten çıkış (employees.terminate) + kaynakta yeniden işe alım (employees.rehire) yapın.
revert_source_payroll_closedKaynak firmada çıkış ayı ya da sonrası için onaylanmış / kesinleşmiş / ödenmiş bordro var (çıkış bildirgeye girmiş olabilir).periods alanındaki dönemleri önce düzeltmeye açın (payroll.reopen) ya da iptal edin (payroll.cancel), sonra yeniden deneyin.
revert_source_license_fullKaynak firmanın lisansı dolu: çalışan kaynakta yeniden aktif edilemez.Kaynak firmada lisansı artırın ya da bir aktif çalışanı pasifleştirin.
revert_manual_requiredHedefte yeniden kullanılmış çalışan kaydının nakilden önceki dönemi bulunamadı ya da dönem zinciri geri alınamıyor: kart otomatik olarak eski hâline getirilemez.Hedefte işten çıkış (employees.terminate) + kaynakta yeniden işe alım (employees.rehire) ile elle düzeltin ya da destek ekibine yazın (empuno tickets).

Salt-okuma entegrasyon API'si

Yalnızca izin ve masraf verisini kendi ERP/muhasebe sisteminize çekecekseniz sabit şemalı, salt-okuma Company API daha uygundur: https://empuno.com/api-docs. Ajan anahtarı o uçları da (empuno api leaves) ilgili modülün görüntüleme yetkisiyle çağırabilir.

Komut kataloğu

Liste panelin rota tablosundan otomatik üretilir; panele yeni bir özellik eklendiğinde burada da görünür. Alanlar, sunucunun doğrulama kurallarından çıkarılır (alan listesi olmayan komutta eksik alanlar 422 yanıtındaki errors nesnesinde döner). Anahtarınıza özel liste: empuno commands.

Avans Yönetimi advance_payments 11 komut
POST advance-payments.approve /manager/advance-payments/{advancePayment}/approve advance_payments.manage

Avans talepleri — Onayla

deduction_period
GET advance-payments.create /manager/advance-payments/create advance_payments.manage

Avans talepleri — Oluşturma formu verisi

POST advance-payments.generate-contract /manager/advance-payments/{advancePayment}/generate-contract advance_payments.manage

Avans talepleri — generate contract

employee_tc employee_position company_address amount_text additional_terms
GET advance-payments.index /manager/advance-payments advance_payments.view

Avans talepleri — Listele

POST advance-payments.record-repayment /manager/advance-payments/{advancePayment}/repayments advance_payments.manage

Avansa bordro dışı tahsilat kaydeder (banka, nakit, çıkış ödemesinden mahsup, vazgeçme).

amount paid_on source reference notes period
POST advance-payments.reject /manager/advance-payments/{advancePayment}/reject advance_payments.manage

Avans talepleri — Reddet

rejection_reason
GET advance-payments.settings /manager/advance-payments/settings advance_payments.manage

Avans talepleri — Ayarlar

PUT advance-payments.settings.update /manager/advance-payments/settings advance_payments.manage

Avans ayarları — Güncelle

advance_enabled advance_max_active_count advance_limit_type advance_limit_percentage advance_limit_amount advance_max_installments
GET advance-payments.show /manager/advance-payments/{advancePayment} advance_payments.view

Avans talepleri — Detay

POST advance-payments.store /manager/advance-payments advance_payments.manage

Yönetici avans kaydı: onay akışına GİRMEZ (doğrudan aktif) ve avans modülü

employee_id amount installment_count deduction_period notes reason advance_date deducted_amount installment_amount
PATCH advance-payments.update /manager/advance-payments/{advancePayment} advance_payments.manage

Avans kaydını düzeltir; yalnız gönderilen alanlar değişir.

notes reason deduction_period installment_amount installment_count
AI Araçları (CV analizi, belge/e-posta taslağı) ai_assistants 11 komut
POST ai.chat /manager/ai/chat ai_assistants.view

AI Chat

message context
POST ai.cv.analyze /manager/ai/cv-analysis ai_assistants.view

Analyze CV

cv_file requirements
POST ai.document.generate /manager/ai/generate-document ai_assistants.view

Generate document

template data
POST ai.email.generate /manager/ai/generate-email ai_assistants.view

Generate email draft

type data
POST ai.generate-description /manager/ai/generate-description ai_assistants.view

Generate company description with AI

company_name user_input industry address employee_count founding_year website
POST ai.generate-job-posting /manager/ai/generate-job-posting ai_assistants.view

Generate job posting with AI

details
POST ai.image.analyze /manager/ai/analyze-image ai_assistants.view

Analyze image

image purpose
GET ai.index /manager/ai ai_assistants.view

AI Dashboard

id type prompt response model cost created_at user
POST ai.leave.suggest /manager/ai/leave-suggestion/{leaveRequest} ai_assistants.view

Suggest leave approval

GET ai.models /manager/ai/models ai_assistants.view

Get available AI models

POST ai.performance.insights /manager/ai/performance-insights/{employee} ai_assistants.view

Generate performance insights

Yönetici-özel (yetki devri, mali müşavirler) company_admin 16 komut
DELETE accountants.destroy /manager/accountants/{user} company_admin

Mali Müşavirler — Sil

GET accountants.detail /manager/accountants/{user}/detail company_admin

Bir mali müşavir için ayrıntılı rapor geçmişi (JSON, detail dialog için).

GET accountants.index /manager/accountants company_admin

Mali Müşavirler — Listele

id name email is_active first_login_completed has_password has_other_role other_role_label created_at reports_sent_count last_report_sent_at last_send_error
DELETE accountants.invite.cancel /manager/accountants/invitations/{invitation} company_admin

Mali müşavir daveti — İptal et

POST accountants.invite.resend /manager/accountants/invitations/{invitation}/resend company_admin

Mali müşavir daveti — Yeniden gönder

POST accountants.store /manager/accountants company_admin

Mali Müşavirler — Oluştur

email first_name last_name
POST accountants.toggle-active /manager/accountants/{user}/toggle-active company_admin

Mali Müşavirler — Aktif/pasif yap

GET employees.permissions.edit /manager/employees/{employee}/permissions company_admin

Yetki devri — Düzenleme formu verisi

PUT employees.permissions.update /manager/employees/{employee}/permissions company_admin

Yetki devri — Güncelle

POST group.companies.store /manager/group/companies company_admin

Yöneticisi olduğunuz başka bir firmayı gruba doğrudan ekler (davet kodu gerekmez).

target_company
DELETE group.invites.destroy /manager/group/invites/{invite} company_admin

Kullanılmamış bir davet kodunu iptal eder.

POST group.invites.store /manager/group/invites company_admin

Gruba katılım için tek kullanımlık davet kodu üretir (ham kod YALNIZ bu yanıtta döner).

expires_in_days
POST group.join /manager/group/join company_admin

Davet koduyla bu firmayı bir gruba katar.

code
POST group.leave /manager/group/leave company_admin

Bu firmayı gruptan çıkarır (her zaman serbest).

reason
POST group.store /manager/group company_admin

Yeni grup şirketleri grubu oluşturur; bu firma ilk üye olur.

name
PATCH group.update /manager/group company_admin

Grubun adını değiştirir.

name
Şirket Kartları company_cards 5 komut
DELETE company-cards.destroy /manager/company-cards/{card} company_cards.manage

Şirket kartları — Sil

GET company-cards.index /manager/company-cards company_cards.view

Şirket kartları — Listele

id cardholder_user_id cardholder_name cardholder_email last_four card_type bank_name label is_active display_name created_at
POST company-cards.store /manager/company-cards company_cards.manage

Şirket kartları — Oluştur

cardholder_user_id last_four card_type bank_name label is_active
POST company-cards.toggle /manager/company-cards/{card}/toggle company_cards.manage

Şirket kartları — Aç/kapat

PUT company-cards.update /manager/company-cards/{card} company_cards.manage

Şirket kartları — Güncelle

cardholder_user_id last_four card_type bank_name label is_active
Firma Ayarları company_profile 6 komut
GET settings.cities /manager/settings/cities/{country} company_profile.view

Firma ayarları — cities

DELETE settings.delete-logo /manager/settings/logo company_profile.manage

Firma ayarları — delete logo

GET settings.districts /manager/settings/districts/{city} company_profile.view

Firma ayarları — districts

POST settings.generate-with-ai /manager/settings/generate-with-ai company_profile.manage

Firma ayarları — generate with ai

description
GET settings.index /manager/settings company_profile.view

Firma ayarları — Listele

PUT settings.update /manager/settings company_profile.manage

Firma ayarları — Güncelle

name email phone address country_id city_id district_id neighborhood street building_no postal_code description slogan value_descriptions value_descriptions.* website linkedin_url facebook_url twitter_url instagram_url employee_count founding_year industry company_values company_values.* tax_number legal_name tax_office billing_address timezone logo cover_image
Departman & Şube company_settings 16 komut
GET branches.active /manager/api/branches/active company_settings.view

Get branches for AJAX (for employee forms)

id name city
GET branches.create /manager/branches/create company_settings.manage

Show the form for creating a new resource.

DELETE branches.destroy /manager/branches/{branch} company_settings.manage

Remove the specified resource from storage.

GET branches.edit /manager/branches/{branch}/edit company_settings.manage

Show the form for editing the specified resource.

GET branches.index /manager/branches company_settings.view

Display a listing of the resource.

GET branches.show /manager/branches/{branch} company_settings.view

Display the specified resource.

POST branches.store /manager/branches company_settings.manage

Store a newly created resource in storage.

name code address city phone email manager_name is_active
POST branches.toggle-status /manager/branches/{branch}/toggle-status company_settings.manage

Toggle branch active status

PUT branches.update /manager/branches/{branch} company_settings.manage

Update the specified resource in storage.

name code address city phone email manager_name is_active
GET departments.create /manager/departments/create company_settings.manage

Departmanlar — Oluşturma formu verisi

DELETE departments.destroy /manager/departments/{department} company_settings.manage

Departmanlar — Sil

GET departments.edit /manager/departments/{department}/edit company_settings.manage

Departmanlar — Düzenleme formu verisi

GET departments.index /manager/departments company_settings.view

Departmanlar — Listele

GET departments.show /manager/departments/{department} company_settings.view

Departmanlar — Detay

POST departments.store /manager/departments company_settings.manage

Departmanlar — Oluştur

name description manager_name
PUT departments.update /manager/departments/{department} company_settings.manage

Departmanlar — Güncelle

name description manager_name
Kurumsal Evrak Deposu corporate_documents 6 komut
DELETE corporate-documents.destroy /manager/corporate-documents/{corporateDocument} corporate_documents.manage

Kurumsal evraklar — Sil

GET corporate-documents.index /manager/corporate-documents corporate_documents.view

Kurumsal evraklar — Listele

GET corporate-documents.show /manager/corporate-documents/{corporateDocument} corporate_documents.view

Kurumsal evraklar — Detay

GET corporate-documents.status /manager/corporate-documents/status corporate_documents.view

Analizi devam eden kayıtların güncel durumu (liste ekranı yokluyor).

POST corporate-documents.store /manager/corporate-documents corporate_documents.manage

Yükleme — SADECE dosya.

file
PUT corporate-documents.update /manager/corporate-documents/{corporateDocument} corporate_documents.manage

Yapay zekanın çıkardığı künyeyi yönetici düzeltebilir.

document_type title notes issued_date expires_at
Yönetim özeti dashboard 1 komut
GET dashboard /manager/dashboard

Yönetim özeti (dashboard)

Veri Göçü (Eski Sistem) data_migration 17 komut
POST data-migration.advances.commit /manager/data-migration/advances/commit data_migration.manage

Geçmiş maaş avansları ve devreden bakiyeler. records[]: çalışan anahtarı, amount,

records dry_run records.*.amount records.*.advance_date records.*.deduction_period records.*.installment_count records.*.installment_amount records.*.deducted_amount records.*.notes records.*.reason records.*.payment_reference records.*.installments records.*.installments.*.period records.*.installments.*.amount records.*.installments.*.source records.*.installments.*.reference records.*.employee_id records.*.employee_number records.*.identity_number records.*.employee_name
POST data-migration.documents.commit /manager/data-migration/documents/commit data_migration.manage

Toplu personel evrakı (istek başına ≤10 dosya; büyük arşiv için CLI `empuno migrate

manifest files files.* dry_run manifest.*.file manifest.*.document_type manifest.*.title manifest.*.document_date manifest.*.period manifest.*.visible_to_employee manifest.*.notes
GET data-migration.employees /manager/data-migration/employees data_migration.manage

Çalışan aktarım ekranı verisi (AI kredi bakiyesi). Ajan doğrudan data-migration.employees.parse / commit kullanır.

POST data-migration.employees.commit /manager/data-migration/employees/commit data_migration.manage

Çalışanları kaydet (parse sonucu ya da ajanın kendi JSON'u). Davet e-postası GÖNDERMEZ,

records on_existing dry_run records.*.first_name records.*.last_name records.*.email records.*.phone records.*.position records.*.hire_date records.*.birth_date records.*.identity_number records.*.salary records.*.status records.*.department_id records.*.branch_id records.*.department records.*.branch records.*.gender records.*.iban records.*.sgk_registration_no records.*.sgk_start_date records.*.sgk_occupation_code records.*.marital_status records.*.highest_education_level records.*.disability_degree records.*.address records.*.city records.*.termination_date records.*.termination_reason records.*.sgk_exit_code records.*.sgk_workplace_id records.*.sgk_workplace records.*.employments create_workplaces
POST data-migration.employees.parse /manager/data-migration/employees/parse data_migration.manage

Eski sistemden çalışan listesini AI ile ayrıştır (KAYDETMEZ; sonucu commit'e verin).

POST data-migration.employments.commit /manager/data-migration/employments/commit data_migration.manage

Çalışma dönemleri + SGK işyeri aktarımı (giriş-çıkış geçmişi) — çalışan başına satır bazlı; davet/e-posta/push YOK.

records on_existing create_workplaces dry_run records.*.kind records.*.hire_date records.*.termination_date records.*.sgk_exit_code records.*.iskur_exit_reason records.*.termination_reason records.*.sgk_workplace_id records.*.sgk_workplace records.*.insurance_group records.*.continues_previous records.*.severance_paid records.*.severance_paid_amount records.*.severance_paid_at records.*.counts_for_severance records.*.counts_for_leave records.*.override_note records.*.external_employer_name records.*.external_employer_tax_number records.*.notes records.*.sgk_workplace_registration_no records.*.insurance_type records.*.employee_id records.*.employee_number records.*.identity_number records.*.employee_name
POST data-migration.expenses.commit /manager/data-migration/expenses/commit data_migration.manage

Geçmiş (onaylanmış / ödenmiş) masraflar. records[]: çalışan anahtarı, expense_date

records dry_run records.*.expense_date records.*.amount records.*.currency records.*.title records.*.category_id records.*.category records.*.description records.*.merchant_name records.*.tax_amount records.*.payment_method records.*.status records.*.paid_at records.*.payment_reference records.*.accounting_processed records.*.employee_id records.*.employee_number records.*.identity_number records.*.employee_name
GET data-migration.files /manager/data-migration/files data_migration.manage

Dosyadan aktarım ekranı (yönetici): eski sistemin Excel/CSV dışa aktarımı → önizleme →

POST data-migration.files.parse /manager/data-migration/files/parse data_migration.manage

Excel/CSV dosyasını aktarım kayıtlarına çevirir (yazmaz): kind = employees | leaves | advances |

kind file period code_map code_map.* format
POST data-migration.incentive-facts.commit /manager/data-migration/incentive-facts/commit data_migration.manage payroll.manage

Teşvik bilgileri (+ önceki sistemde uygulanan kanun; TK-0UXIAY §4): records[]: çalışan anahtarı, teşvik bilgisi

records on_existing dry_run records.*.law_no records.*.start_date records.*.end_date records.*.status records.*.certificate_no records.*.notes records.*.disability_rate records.*.uninsured_6_months_before_hire records.*.iskur_registered_unemployed records.*.vocational_certificate records.*.social_assistance_household records.*.law_2828_beneficiary records.*.unemployment_benefit_remaining_days records.*.abroad_assignment records.*.investment_certificate records.*.culture_certificate records.*.sgk_definition_done records.*.additional_employment_override records.*.employee_id records.*.employee_number records.*.identity_number records.*.employee_name
GET data-migration.index /manager/data-migration data_migration.manage

Veri göçü ana ekranı: AI kredi bakiyesi (aktarım türleri ve komutları: rehber #gecis, `empuno migrate <tür>`).

GET data-migration.leaves /manager/data-migration/leaves data_migration.manage

İzin geçmişi aktarım ekranı verisi (AI kredi bakiyesi). Ajan doğrudan data-migration.leaves.parse / commit kullanır.

POST data-migration.leaves.commit /manager/data-migration/leaves/commit data_migration.manage

Geçmiş izinleri kaydet (onaylı, geçmiş tarihli; bakiye hesabına girer). Tek çalışan

employee_id dry_run records records.*.leave_type_id records.*.leave_type records.*.start_date records.*.end_date records.*.days records.*.reason records.*.employee_id records.*.employee_number records.*.identity_number records.*.employee_name
POST data-migration.leaves.parse /manager/data-migration/leaves/parse data_migration.manage

Bir çalışanın eski izin geçmişini AI ile ayrıştır (KAYDETMEZ; sonucu leaves.commit'e verin).

POST data-migration.payroll.commit /manager/data-migration/payroll/commit data_migration.manage payroll.manage

Geçmiş bordroları müşavirin hesapladığı tutarlarla aktarır; update_fields=declaration ile yalnız beyan alanlarını (SGK/MUHSGK) günceller.

records dry_run on_existing update_fields records.*.period records.*.gross_total records.*.income_tax_base records.*.net_pay records.*.sgk_days records.*.paid_at records.*.employer_incentive_code records.*.notes records.*.earnings records.*.earnings.*.name records.*.earnings.*.amount records.*.earnings.*.taxable records.*.earnings.*.sgk records.*.earnings.*.type records.*.earnings.*.days records.*.earnings.*.income_tax records.*.earnings.*.stamp_tax records.*.deductions records.*.deductions.*.name records.*.deductions.*.amount records.*.deductions.*.type records.*.worked_days records.*.unpaid_leave_days records.*.paid_leave_days records.*.gross_salary records.*.overtime_hours records.*.overtime_pay records.*.sgk_base records.*.sgk_employee records.*.sgk_employee_pension records.*.sgk_employee_health records.*.unemployment_employee records.*.sgk_employee_total records.*.sgk_employer records.*.sgk_employer_pension records.*.sgk_employer_health records.*.sgk_employer_short_term records.*.unemployment_employer records.*.sgk_employer_total records.*.employer_incentive_amount records.*.minimum_wage_support records.*.cumulative_tax_base records.*.income_tax records.*.mw_income_tax_exemption records.*.income_tax_final records.*.stamp_tax_base records.*.stamp_tax records.*.mw_stamp_exemption records.*.stamp_tax_final records.*.disability_deduction records.*.other_deductions records.*.employer_cost records.*.sgk_workplace_id records.*.sgk_workplace records.*.sgk_entry_date records.*.sgk_exit_date records.*.sgk_exit_code records.*.missing_day_count records.*.missing_day_reason records.*.sgk_document_type records.*.insurance_group records.*.sgk_occupation_code records.*.sgk_workplace_registration_no records.*.tax_payment_type records.*.rd_law records.*.rd_rate records.*.rd_days records.*.rd_income_tax_exemption records.*.rd_stamp_exemption records.*.rd_sgk_support records.*.employee_id records.*.employee_number records.*.identity_number records.*.employee_name
POST data-migration.pension-enrollments.commit /manager/data-migration/pension-enrollments/commit data_migration.manage payroll.manage

BES katılım kayıtları (önceki sistemden; TK-0UXIAY §5): records[]: çalışan anahtarı, plan_id | contract_no (vars.

records on_existing dry_run records.*.plan_id records.*.contract_no records.*.status records.*.enrolled_on records.*.rate records.*.notified_at records.*.opted_out_at records.*.paused_from records.*.paused_until records.*.left_at records.*.certificate_no records.*.voluntary records.*.notes records.*.employee_id records.*.employee_number records.*.identity_number records.*.employee_name
POST data-migration.work-advances.commit /manager/data-migration/work-advances/commit data_migration.manage

Geçmiş iş avansları (195): records[]: çalışan anahtarı, amount, given_on (≤ bugün), purpose,

records dry_run records.*.amount records.*.given_on records.*.purpose records.*.payment_reference records.*.spent_amount records.*.refunded_amount records.*.due_on records.*.notes records.*.currency records.*.employee_id records.*.employee_number records.*.identity_number records.*.employee_name
Kesinti Raporları deduction_reports 7 komut
PUT deduction-report-settings.update /manager/deduction-report-settings deduction_reports.manage

Kesinti raporu ayarlarını upsert eder (aylık anchor günü + aktiflik).

monthly_day is_active
GET deduction-reports.download /manager/deduction-reports/{report}/download deduction_reports.view

PDF'i force-download ile indirir.

GET deduction-reports.download-excel /manager/deduction-reports/{report}/download-excel deduction_reports.view

Excel'i force-download ile indirir.

POST deduction-reports.generate-now /manager/deduction-reports/generate-now deduction_reports.manage

Manuel rapor üretimi. Önceki tam ayı (anchor güne göre) hesaplar ve

GET deduction-reports.index /manager/deduction-reports deduction_reports.view

Geçmiş kesinti raporları + ayar kartı. Tek truth source olarak

GET deduction-reports.preview /manager/deduction-reports/{report} deduction_reports.view

PDF'i tarayıcıda inline olarak gösterir (önizleme için).

POST deduction-reports.resend /manager/deduction-reports/{report}/resend deduction_reports.manage

Mevcut raporu mali müşavirlere yeniden gönderir.

Personel Evrakları documents 7 komut
GET documents.missing /manager/documents/missing documents.view

Eksik zorunlu evrak listesi: çalışan başına eksik kalemler (status active vars. | terminated | all; employee_id; requirement; per_page ≤100).

status employee_id requirement page
GET documents.requirements /manager/documents/requirements documents.view

Zorunlu evrak politikası: aşama başına zorunlu kalemler (required), kaynak (default | company) ve tüm kalemler (catalog).

PUT documents.requirements.update /manager/documents/requirements documents.manage

Zorunlu evrak politikasını değiştirir: required.onboarding / required.exit = kalem anahtarları listesi (aşamanın tamamı; gönderilmeyen aşama aynen kalır).

required required.onboarding required.onboarding.* required.exit required.exit.*
DELETE employees.documents.destroy /manager/employees/{employee}/documents/{document} documents.manage

Çalışan evrağını sil. documents.manage gerektirir.

GET employees.documents.show /manager/employees/{employee}/documents/{document} documents.view

Çalışan evrağını tarayıcıda göster. documents.view yeterli.

POST employees.documents.store /manager/employees/{employee}/documents documents.manage

Çalışana evrak yükle (file: tek PDF ≤20 MB ya da images[]: taranmış sayfalar).

document_type title notify_employee file images images.* notes visible_to_employee document_date period
PATCH employees.documents.update /manager/employees/{employee}/documents/{document} documents.manage

Evrak bilgisini düzelt (dosyaya dokunmaz): tür, başlık, görünürlük, belge tarihi, dönem.

document_type title notify_employee visible_to_employee document_date period
Çalışan Yönetimi employees 30 komut
GET employees.available /manager/employees/available employees.manage

Get available employees for equipment assignment

id full_name department branch equipment_count
GET employees.create /manager/employees/create employees.manage

Çalışanlar — Oluşturma formu verisi

GET employees.edit /manager/employees/{employee}/edit employees.manage

Düzenleme formu verisi (yalnız aktif/pasif çalışan; ayrılmışta profile yönlendirir).

DELETE employees.employments.destroy /manager/employees/{employee}/employments/{employment} employees.manage

Çalışma dönemini siler (geri alınabilir kayıt silme) — dry_run destekler.

reason dry_run
GET employees.employments.index /manager/employees/{employee}/employments employees.view

Çalışanın çalışma dönemleri, SGK işyeri ve kıdem/izin/ihbar süresi özeti — yan etkisiz.

POST employees.employments.store /manager/employees/{employee}/employments employees.manage

Geçmiş çalışma dönemi ya da önceki hizmet (kind=prior_service) ekler — dry_run destekler; e-posta yok.

kind hire_date termination_date sgk_exit_code iskur_exit_reason termination_reason sgk_workplace_id sgk_workplace insurance_group continues_previous severance_paid severance_paid_amount severance_paid_at counts_for_severance counts_for_leave override_note external_employer_name external_employer_tax_number notes external_company_id external_employment_id transfer_uuid dry_run
POST employees.employments.transfer /manager/employees/{employee}/employments/transfer employees.manage

Şirket içi SGK işyeri nakli — açık dönem date−1'de 16 koduyla kapanır, date'te yeni işyerinde devam eder.

date sgk_workplace_id sgk_workplace notes dry_run
PATCH employees.employments.update /manager/employees/{employee}/employments/{employment} employees.manage

Çalışma dönemini düzeltir — yalnız gönderilen alanlar; dry_run destekler.

kind hire_date termination_date sgk_exit_code iskur_exit_reason termination_reason sgk_workplace_id sgk_workplace insurance_group continues_previous severance_paid severance_paid_amount severance_paid_at counts_for_severance counts_for_leave override_note external_employer_name external_employer_tax_number notes external_company_id external_employment_id transfer_uuid dry_run
GET employees.group-transfer.create /manager/employees/{employee}/group-transfer employees.manage group.manage

Grup şirketine nakil önizlemesi (yan etkisiz): engeller, uyarılar, hedefte departman/şube eşlemesi, kalan izin,

POST employees.group-transfer.store /manager/employees/{employee}/group-transfer employees.manage group.manage

Çalışanı grup şirketine naklen devreder (TBK 429; kıdem ve izin kesintisiz).

GET employees.index /manager/employees employees.view

Çalışanları listeler — filtreler: search (ad/e-posta/sicil no), department, status (vars. active,inactive; terminated | all), sgk_workplace_id, per_page.

GET employees.leave-balance-detail /manager/employees/{employee}/leave-balance-detail employees.view

Get detailed leave balance for an employee (JSON endpoint for modal)

GET employees.leave-balance-export /manager/employees/{employee}/leave-balance-export employees.view

Export employee leave balance report to Excel

GET employees.profile /manager/employees/{employee}/profile employees.view

Çalışan detayı — kişisel/iş bilgileri, izin bakiyeleri, zimmet, belgeler; çalışma dönemleri ve SGK işyeri dahil (yan etkisiz).

POST employees.reactivate /manager/employees/{employee}/reactivate employees.manage

Çalışanlar — Yeniden aktifleştir

POST employees.rehire /manager/employees/{employee}/rehire employees.manage

Ayrılmış çalışanı yeniden işe alır — yeni çalışma dönemi açar, eski dönem ve hesapları korunur.

hire_date sgk_workplace_id sgk_workplace insurance_group update_payroll_profile notes dry_run
POST employees.resend-invite /manager/employees/{employee}/resend-invite employees.manage

Kabul edilmemiş çalışan davetini yeniden gönderir (token + süre yenilenir).

GET employees.show /manager/employees/{employee} employees.view

Çalışan detayı — kişisel/iş bilgileri, izin bakiyeleri, zimmet, belgeler; çalışma dönemleri ve SGK işyeri dahil (yan etkisiz).

POST employees.store /manager/employees employees.manage

Çalışan davet et: yalnız e-posta alır, çalışana DAVET E-POSTASI gönderir ve lisans tüketir.

email sgk_workplace_id
POST employees.terminate /manager/employees/{employee}/terminate employees.manage

İşten çıkış: durum "terminated", kullanıcı hesabı pasif, BEKLEYEN izin/avans/masraf talepleri iptal.

termination_date termination_reason sgk_exit_code confirm_active_equipment advance_action exit_settlement exit_leave_days exit_include_leave_pay exit_include_notice exit_notice_served exit_include_severance
PUT employees.termination.update /manager/employees/{employee}/termination employees.manage

Ayrılmış çalışanın çıkış bilgisini düzelt (tarih, gerekçe, SGK çıkış kodu).

termination_date termination_reason sgk_exit_code
PUT employees.update /manager/employees/{employee} employees.manage

Çalışan sicilini güncelle — yalnız gönderilen alanlar değişir, gönderilmeyen alan olduğu gibi kalır.

first_name last_name email phone department_id branch_id position salary hire_date birth_date status role sgk_registration_no sgk_start_date sgk_occupation_code sgk_workplace_id nationality gender disability_degree citizenship identity_number education_status highest_education_level last_education_institution marital_status number_of_children address address_continued city country postal_code address_phone bank_name account_type account_number iban personal_email personal_phone emergency_contact_name emergency_contact_phone emergency_contact_relationship
GET group-transfers.candidates /manager/group-transfers/candidates employees.view

Olası geçmiş nakiller (sistem bulur): erişilebilir grup firmaları arasında aynı T.C.'li "bir firmada ayrılmış +

POST group-transfers.consent /manager/group-transfers/{transfer}/consent employees.manage group.manage

İmzalı devir protokolünü yükler (PDF / JPG / PNG, en çok 20 MB): bu firmadaki çalışan kaydının özlük dosyasına

document
GET group-transfers.index /manager/group-transfers employees.view

Grup içi nakiller (bu firmadan giden ve bu firmaya gelen): yön (direction in | out), durum (completed |

direction status mode consent
POST group-transfers.link-bulk /manager/group-transfers/link-bulk employees.manage group.manage

Geçmiş nakilleri toplu bağlar (kayıt oluşturmadan): kaynakta ayrılmış + hedefte aynı T.C.'li aktif çalışan.

records records.*.source_employee_id records.*.target_employee_id records.*.to records.*.from records.*.transfer_date dry_run
GET group-transfers.protocol /manager/group-transfers/{transfer}/protocol employees.view

Devir protokolü PDF'i (TBK 429; devreden, devralan ve işçi imzası için). T.C. kimlik no employees.manage

POST group-transfers.revert /manager/group-transfers/{transfer}/revert employees.manage group.manage

Grup içi nakli ya da geçmiş nakil bağlamasını geri alır (yanlış nakil düzeltmesi; koşullu, iki firmada tek işlem).

reason notify_accountants dry_run
GET group-transfers.show /manager/group-transfers/{transfer} employees.view

Nakil kaydının ayrıntısı (yalnız bu firmanın kaynak ya da hedef olduğu kayıt; yan etkisiz). `revert` alanı

GET reports.personnel /manager/reports/personnel employees.view

Personel raporu (report=list|registry|personal|hires|exits; as_of=YYYY-AA-GG, from/to hareket raporlarında).

report as_of from to include_leavers show_salary show_bank sgk_workplace_id department_id format
Ekipman Yönetimi equipment 37 komut
DELETE equipment-assignments.documents.destroy /manager/equipment-assignments/{equipmentAssignment}/documents/{document} equipment.manage

İmzalı zimmet/iade formunu sil. equipment.manage gerektirir.

GET equipment-assignments.documents.show /manager/equipment-assignments/{equipmentAssignment}/documents/{document} equipment.view

İmzalı zimmet/iade formunu tarayıcıda göster. equipment.view yeterli.

POST equipment-assignments.documents.store /manager/equipment-assignments/{equipmentAssignment}/documents equipment.manage

İmzalı zimmet/iade formu yükle (PDF veya görsel(ler)). equipment.manage gerektirir.

document_type file images images.* notes
GET equipment-assignments.index /manager/equipment-assignments equipment.view

Zimmetler — Listele

GET equipment-assignments.pdf /manager/equipment-assignments/{equipmentAssignment}/pdf equipment.view

Zimmetler — PDF indir

GET equipment-assignments.return-pdf /manager/equipment-assignments/{assignment}/return-pdf equipment.view

Generate return receipt PDF for a returned equipment assignment

POST equipment.analyze-photos /manager/equipment/analyze-photos equipment.manage

Foto'lari S3'e yukle + AI analiz et + sonuclari don.

photos photos.*
POST equipment.assign /manager/equipment/{equipment}/assign equipment.manage

Ekipmanlar — Ata

employee_id assigned_date assignment_notes delivery_photo
GET equipment.create /manager/equipment/create equipment.manage

Ekipmanlar — Oluşturma formu verisi

DELETE equipment.destroy /manager/equipment/{equipment} equipment.manage

Ekipmanlar — Sil

GET equipment.edit /manager/equipment/{equipment}/edit equipment.manage

Ekipmanlar — Düzenleme formu verisi

GET equipment.index /manager/equipment equipment.view

Ekipmanlar — Listele

DELETE equipment.invoice.destroy /manager/equipment/{equipment}/invoice equipment.manage

Fatura dosyasını sil. Fatura no + KDV alanları temizlenir; alış fiyatı ve

GET equipment.invoice.show /manager/equipment/{equipment}/invoice equipment.view

Fatura PDF/görselini görüntüle (S3 geçici URL'ine yönlendirir).

POST equipment.invoice.store /manager/equipment/{equipment}/invoice equipment.manage

Fatura yükle + AI ile fatura bilgilerini (fatura no, tarih, tutar, KDV)

invoice
GET equipment.label /manager/equipment/{equipment}/label equipment.manage

Tek ekipman için etiket sayfası — labels route'una redirect.

GET equipment.labels /manager/equipment/labels equipment.manage

Birden çok ekipman için A4 yazdırılabilir etiket sayfası.

DELETE equipment.maintenance.destroy /manager/equipment/{equipment}/maintenance/{maintenance} equipment.manage

Bakım kaydını sil (varsa fatura dosyasını S3'ten temizle, kaydı soft-delete et).

GET equipment.maintenance.invoice.show /manager/equipment/{equipment}/maintenance/{maintenance}/invoice equipment.view

Bakım faturasını görüntüle (S3 geçici URL'ine yönlendirir).

POST equipment.maintenance.store /manager/equipment/{equipment}/maintenance equipment.manage

Bakım kaydını elle ekle (fatura/AI olmadan).

maintenance_type vendor_name description maintenance_date amount currency vat_rate vat_amount invoice_number
PATCH equipment.maintenance.update /manager/equipment/{equipment}/maintenance/{maintenance} equipment.manage

Bakım kaydının alanlarını güncelle (fatura dosyası değişmez).

maintenance_type vendor_name description maintenance_date amount currency vat_rate vat_amount invoice_number
POST equipment.maintenance.upload /manager/equipment/{equipment}/maintenance/upload equipment.manage

Bakım faturası yükle + AI ile firma adı, tutar, KDV, tarih ve bakım tipini

invoice
DELETE equipment.notes.destroy /manager/equipment/{equipment}/notes/{note} equipment.manage

Ekipman notları — Sil

POST equipment.notes.store /manager/equipment/{equipment}/notes equipment.manage

Menajer notu ekle. is_visible_to_employee=true ise ekipmanı zimmetinde

note is_visible_to_employee
PATCH equipment.notes.update /manager/equipment/{equipment}/notes/{note} equipment.manage

Ekipman notları — Güncelle

note is_visible_to_employee
DELETE equipment.photos.destroy /manager/equipment/{equipment}/photos/{photo} equipment.manage

Ekipman fotoğrafları — Sil

PATCH equipment.photos.primary /manager/equipment/{equipment}/photos/{photo}/primary equipment.manage

Ekipman fotoğrafları — primary

PATCH equipment.photos.reorder /manager/equipment/{equipment}/photos/reorder equipment.manage

Ekipman fotoğrafları — reorder

ids ids.*
POST equipment.photos.store /manager/equipment/{equipment}/photos equipment.manage

Var olan ekipmana foto ekle. analyze=true ise her foto 1 AI kredisi harcar ve

photos photos.* analyze
DELETE equipment.sales-invoice.destroy /manager/equipment/{equipment}/sales-invoice equipment.manage

Satış faturası dosyasını sil. Fatura no + KDV temizlenir; sold_at ve

GET equipment.sales-invoice.show /manager/equipment/{equipment}/sales-invoice equipment.view

Satış faturası PDF/görselini görüntüle (S3 geçici URL'ine yönlendirir).

POST equipment.sales-invoice.store /manager/equipment/{equipment}/sales-invoice equipment.manage

Satış faturası yükle + AI ile (SATIS_FATURA_ANALIZ_ASISTANI) fatura no,

invoice
GET equipment.show /manager/equipment/{equipment} equipment.view

Ekipmanlar — Detay

POST equipment.store /manager/equipment equipment.manage

Ekipmanlar — Oluştur

name description serial_number brand model category ai_category purchase_price currency purchase_date condition is_active notes photo_paths photo_paths.*
POST equipment.unassign /manager/equipment/{equipment}/unassign equipment.manage

Ekipmanlar — unassign

returned_date return_notes
PUT equipment.update /manager/equipment/{equipment} equipment.manage

Ekipmanlar — Güncelle

name description serial_number brand model category purchase_price currency purchase_date condition status notes
PATCH equipment.update-status /manager/equipment/{equipment}/update-status equipment.manage

Ekipmanlar — update status

status
Masraf Raporları expense_reports 7 komut
GET expense-reports.download /manager/expense-reports/{report}/download expense_reports.view

PDF'i force-download ile indirir.

GET expense-reports.download-excel /manager/expense-reports/{report}/download-excel expense_reports.view

Paketin TEK Excel dosyasını indirir. excel_path paketteki üç satıra da aynı

GET expense-reports.index /manager/expense-reports expense_reports.view

Geçmiş raporlar sayfası. Tek truth source: hem manager hem mali müşavir

GET expense-reports.preview /manager/expense-reports/{report} expense_reports.view

PDF'i tarayıcıda inline olarak gösterir (önizleme için).

GET expense-reports.preview-range /manager/expense-reports/preview-range expense_reports.view

"harcama tarihi" aralığındaki TÜM fişlerden (tek tek seçmeye gerek yok)

date_from date_to status employee_id category_id report_status accounting_status search
GET expense-reports.preview-range.count /manager/expense-reports/preview-range/count expense_reports.view

"Fişleri Yazdır" modalında seçili tarih aralığı + filtrelerle KAÇ fişin

date_from date_to status employee_id category_id report_status accounting_status search
GET expense-reports.preview-selected /manager/expense-reports/preview-selected expense_reports.view

Seçili fişlerden ephemeral PDF üretir, tarayıcıda inline gösterir.

Masraf Yönetimi expenses 26 komut
DELETE expense-categories.destroy /manager/expense-categories/{category} expenses.manage

Masraf kategorileri — Sil

GET expense-categories.index /manager/expense-categories expenses.manage

Masraf kategorileri — Listele

POST expense-categories.seed-defaults /manager/expense-categories/seed-defaults expenses.manage

Masraf kategorileri — seed defaults

POST expense-categories.store /manager/expense-categories expenses.manage

Masraf kategorileri — Oluştur

name description max_amount requires_receipt
PUT expense-categories.update /manager/expense-categories/{category} expenses.manage

Masraf kategorileri — Güncelle

name description max_amount requires_receipt is_active
PUT expense-report-settings.update /manager/expense-report-settings expenses.manage

Masraf raporu ayarlarını upsert eder.

period_type weekly_day monthly_day is_active
POST expense-reports.generate-now /manager/expense-reports/generate-now expenses.manage

Manuel rapor üretimi. Body:

period_type period start_date end_date exclude_already_sent
POST expense-reports.resend /manager/expense-reports/{report}/resend expenses.manage

Mevcut raporu mali müşavirlere yeniden gönderir.

POST expenses.approve /manager/expenses/{expense}/approve expenses.manage

Masraflar — Onayla

POST expenses.bulk-mark-processed /manager/expenses/bulk-mark-processed expenses.manage

Seçili masrafları toplu olarak muhasebeye işlendi işaretler.

ids ids.*
DELETE expenses.destroy /manager/expenses/{expense} expenses.manage

Masraflar — Sil

GET expenses.index /manager/expenses expenses.view

Masraflar — Listele

POST expenses.mark-paid /manager/expenses/{expense}/mark-paid expenses.manage

Onaylı masrafı çalışana ödendi (iade edildi) olarak işaretler. İsteğe bağlı: reimbursement_method

reimbursement_method reimbursement_reference paid_at
POST expenses.mark-processed /manager/expenses/{expense}/mark-processed expenses.process

Masrafı "Muhasebeye İşlendi" olarak işaretler (tekil).

POST expenses.reject /manager/expenses/{expense}/reject expenses.manage

Masraflar — Reddet

rejected_reason
GET expenses.show /manager/expenses/{expense} expenses.view

Masraflar — Detay

POST expenses.store /manager/expenses expenses.manage

Yönetici/ajan çalışan adına masraf kaydeder — fişi verin, alanları yapay zekâ çıkarır (TK-EKSOR6).

receipt receipt_path title amount expense_date expense_category_id category merchant_name tax_amount currency payment_method description status notify funding work_advance_id
POST expenses.unmark-processed /manager/expenses/{expense}/unmark-processed expenses.manage

"Muhasebeye İşlendi" işaretini geri alır.

PUT expenses.update /manager/expenses/{expense} expenses.manage

Masraf alanlarını düzelt.

title amount currency expense_date expense_category_id employee_id merchant_name tax_amount payment_method company_card_id description expense_date.before_or_equal
PUT expenses.work-advance /manager/expenses/{expense}/work-advance expenses.manage

Masrafı iş avansına bağlar (work_advance_id) ya da bağı kaldırır (null). Bağlı ve onaylı masraf

work_advance_id
POST work-advances.cancel /manager/work-advances/{workAdvance}/cancel expenses.manage

İş avansını iptal eder (yanlış açıldıysa; bağlı masraf yoksa).

GET work-advances.index /manager/work-advances expenses.view

İş avansı listesi + bakiyeler. Filtre: status (open | closed | cancelled), employee_id, per_page.

POST work-advances.record-movement /manager/work-advances/{workAdvance}/movements expenses.manage

Hareket kaydeder: type = refund (çalışan kalanı iade etti) | payout (harcama avansı aştı, şirket

type amount occurred_on method reference notes
GET work-advances.show /manager/work-advances/{workAdvance} expenses.view

İş avansı detayı: bakiye, bağlı masraflar, iade/fark ödemesi hareketleri.

POST work-advances.store /manager/work-advances expenses.manage

Çalışana iş avansı verir: employee_id, amount, given_on (≤ bugün, vars. bugün), purpose,

employee_id amount currency given_on purpose payment_method payment_reference due_on notes notify
PATCH work-advances.update /manager/work-advances/{workAdvance} expenses.manage

İş avansını düzeltir (yalnız gönderilen alanlar): purpose, due_on, notes, payment_method, payment_reference, amount.

amount given_on purpose payment_method payment_reference due_on notes
Personel Kesintileri / İcra garnishments 12 komut
POST garnishments.analyze-document /manager/garnishments/analyze-document garnishments.manage

İcra/haciz/nafaka belgesini AI ile analiz et ve form alanlarını döndür

document employee_id
POST garnishments.cancel /manager/garnishments/{garnishment}/cancel garnishments.manage

→ İptal.

GET garnishments.create /manager/garnishments/create garnishments.manage

Yeni haciz/nafaka oluşturma formu.

DELETE garnishments.destroy /manager/garnishments/{garnishment} garnishments.manage

Soft delete.

GET garnishments.edit /manager/garnishments/{garnishment}/edit garnishments.manage

Haciz/nafaka düzenleme formu.

GET garnishments.employee-capacity /manager/garnishments/employee-capacity garnishments.manage

Seçilen çalışanın aylık net ücreti + kesinti tipine göre yasal aylık üst

employee_id
GET garnishments.index /manager/garnishments garnishments.view

Haciz/icra/nafaka kayıtlarını listele (firma bazlı).

POST garnishments.resume /manager/garnishments/{garnishment}/resume garnishments.manage

Durduruldu → Aktif.

GET garnishments.show /manager/garnishments/{garnishment} garnishments.view

Haciz/nafaka detayı + geçmiş bordro kesintileri.

POST garnishments.store /manager/garnishments garnishments.manage

Yeni haciz/nafaka kaydet (onaysız → doğrudan aktif).

employee_id garnishment_type case_number court_name priority_order deduction_type deduction_rate deduction_amount total_debt_amount start_date end_date notes document
POST garnishments.suspend /manager/garnishments/{garnishment}/suspend garnishments.manage

Aktif → Durduruldu.

PUT garnishments.update /manager/garnishments/{garnishment} garnishments.manage

Haciz/nafaka güncelle.

employee_id garnishment_type case_number court_name priority_order deduction_type deduction_rate deduction_amount total_debt_amount start_date end_date notes document
Grup Şirketleri group 4 komut
POST company-settings.clone /manager/company-settings/clone group.manage

Başka bir grup firmasının ayarlarını bu firmaya kopyalar (yalnız yapılandırma; personel verisi yok).

from sections sections.* on_existing dry_run
GET group.index /manager/group group.view

Grubu, üye firmaları, davet kodlarını ve bu firmanın grup olaylarını gösterir.

company_id name slug logo_url is_active is_current joined_at joined_via joined_via_label my_role can_switch
GET group.summary /manager/group/summary group.view

Grup firmalarının personel maliyeti, açık avansları ve yıllık izin bakiyelerini firma başına ve toplam olarak gösterir.

GET group.summary.export /manager/group/summary/export group.view

Grup Özeti Excel'i (sayfalar: Özet, Maliyet, Avanslar, İzin) — group.summary ile aynı süzgeç ve yetkiler.

Kimlik Belgeleri identity_documents 5 komut
POST employees.identity-documents.apply /manager/employees/{employee}/identity-documents/{document}/apply identity_documents.manage

Kimlik belgesinden çıkarılan alanları çalışana yazar: fields {first_name, last_name, identity_number, birth_date, gender, nationality} — gönderilen değer yazılı

fields
DELETE employees.identity-documents.destroy /manager/employees/{employee}/identity-documents/{document} identity_documents.manage

Kimlik belgesini sil. identity_documents.manage gerektirir.

GET employees.identity-documents.index /manager/employees/{employee}/identity-documents identity_documents.view

Çalışanın kimlik belgeleri: tür, sayfa, yükleyen, AI'nın çıkardığı alanlar (extracted_data). Yan etkisiz.

GET employees.identity-documents.show /manager/employees/{employee}/identity-documents/{document} identity_documents.view

Kimlik belgesi PDF'ini tarayıcıda göster. identity_documents.view yeterli.

POST employees.identity-documents.store /manager/employees/{employee}/identity-documents identity_documents.manage

Kimlik / pasaport / ehliyet yükle: AI türü ve alanları çıkarır, belge saklanır; apply=missing (vars.) çalışanın yalnız boş alanlarını doldurur.

file images images.* apply notes
İş İlanları job_postings 19 komut
GET job-postings.analytics /manager/job-postings/{jobPosting}/analitik job_postings.manage

İlan analitiği sekmesi.

GET job-postings.application.detail /manager/job-postings/{jobPosting}/applications/{application} job_postings.manage

İş başvurusu — detail

GET job-postings.application.resume /manager/job-postings/{jobPosting}/applications/{application}/cv job_postings.manage

Aday CV'sini indirir.

PUT job-postings.application.update-status /manager/job-postings/{jobPosting}/applications/{application}/status job_postings.manage

İş başvurusu — update status

status notes
GET job-postings.applications /manager/job-postings/{jobPosting}/applications job_postings.manage

İlan başvuru listesi — filtre + sıralama + kolon seçimi.

id job_posting_id first_name last_name full_name email phone status notes reviewed_at created_at reviewer ai_match_score ai_analyzed_at is_test sent_mails answers
POST job-postings.applications.bulk-mail /manager/job-postings/{jobPosting}/applications/bulk-mail job_postings.manage

Seçilen başvurulara toplu durum değişikliği + bilgilendirme e-postası.

all application_ids application_ids.* action
GET job-postings.applications.export /manager/job-postings/{jobPosting}/applications/export job_postings.manage

Başvuruların Excel/PDF dışa aktarımı — ekrandaki filtre ve sıralamayı

GET job-postings.applications.export-count /manager/job-postings/{jobPosting}/applications/export-count job_postings.manage

"Bu filtrede kaç başvuru var" canlı sayacı — indirme düğmesinin yanında

POST job-postings.applications.remind-abandoned /manager/job-postings/{jobPosting}/applications/remind-abandoned job_postings.manage

E-postasını doğrulayıp başvurusunu tamamlamayanlara hatırlatma gönderir.

emails emails.*
GET job-postings.cities /manager/job-postings/cities/{country} job_postings.manage

İş ilanları — cities

id name plate_code
GET job-postings.create /manager/job-postings/create job_postings.manage

İş ilanları — Oluşturma formu verisi

id name code
DELETE job-postings.destroy /manager/job-postings/{job_posting} job_postings.manage

İş ilanları — Sil

GET job-postings.edit /manager/job-postings/{job_posting}/edit job_postings.manage

İş ilanları — Düzenleme formu verisi

id name code
POST job-postings.generate-with-ai /manager/job-postings/generate-with-ai job_postings.manage

İş ilanları — generate with ai

details
GET job-postings.index /manager/job-postings job_postings.manage

İş ilanları — Listele

GET job-postings.show /manager/job-postings/{job_posting} job_postings.manage

İş ilanları — Detay

POST job-postings.store /manager/job-postings job_postings.manage

İş ilanları — Oluştur

GET job-postings.test-application /manager/job-postings/{jobPosting}/test-basvuru job_postings.manage

Ilan sahibinin kendi basvuru formunu aday gibi test etmesini saglar.

PUT job-postings.update /manager/job-postings/{job_posting} job_postings.manage

İş ilanları — Güncelle

İzin Raporları leave_reports 4 komut
GET leave-reports.download /manager/leave-reports/{report}/download leave_reports.view

PDF'i indirir.

GET leave-reports.download-excel /manager/leave-reports/{report}/download-excel leave_reports.view

Excel'i indirir. Paket satırlarında excel_path üçüne de aynı yazılır →

GET leave-reports.index /manager/leave-reports leave_reports.view

Gönderilmiş izin raporları arşivi (liste ekranı).

GET leave-reports.preview /manager/leave-reports/{report} leave_reports.view

PDF'i tarayıcıda inline gösterir.

İzin Yönetimi leaves 28 komut
DELETE employees.leave-opening.destroy /manager/employees/{employee}/leave-opening leaves.manage

Devreden yıllık izin kaydını kaldırır — izin bakiyesi yeniden tüm yıldönümlerinden hesaplanır; dry_run destekler.

dry_run
PUT employees.leave-opening.update /manager/employees/{employee}/leave-opening leaves.manage

Çalışanın devreden yıllık izin bakiyesini yazar (yoksa oluşturur) — dry_run destekler; e-posta yok.

as_of_date annual_days unpaid_days note dry_run
POST leave-reports.generate-now /manager/leave-reports/generate-now leaves.manage

Manuel rapor üretimi. Varsayılan: geçen ay (kapanmış son takvim ayı).

period start_date end_date
POST leave-reports.resend /manager/leave-reports/{report}/resend leaves.manage

Arşivdeki raporu alıcılara (mali müşavir + yönetici) yeniden gönderir.

POST leave-requests.approve /manager/leave-requests/{leaveRequest}/approve leaves.manage

İzin talepleri — Onayla

DELETE leave-requests.archive /manager/leave-requests/{leaveRequest} leaves.manage

İzni siler (arşive taşır) — onaylı olsa bile. Satır soft-delete ile korunur

reason notify_accountants
GET leave-requests.archive-impact /manager/leave-requests/{leaveRequest}/archive-impact leaves.manage

Silme diyaloğu için etki önizlemesi: izin, mali müşavire GÖNDERİLMİŞ hangi

GET leave-requests.documents.show /manager/leave-requests/{leaveRequest}/documents/{document} leaves.view

İzin talebi belgesini tarayıcıda göster. leaves.view yeterli.

POST leave-requests.documents.store /manager/leave-requests/{leaveRequest}/documents leaves.manage

İzin talebine belge yükle (doğrudan PDF veya görsel(ler)). leaves.manage gerektirir.

file images images.* notes
GET leave-requests.export /manager/leave-requests/export leaves.view

İzin talepleri sayfasındaki "İzinleri İndir" modalından dışa aktarım.

format date_start date_end all_dates statuses statuses.*
GET leave-requests.export.preview /manager/leave-requests/export/preview leaves.view

"İzinleri İndir" modalında seçili filtrelerle KAÇ kaydın ineceğini gösteren

date_start date_end all_dates statuses statuses.*
GET leave-requests.index /manager/leave-requests leaves.view

İzin talepleri — Listele

id name color
POST leave-requests.override-document /manager/leave-requests/{leaveRequest}/override-document leaves.manage

Yöneticinin "yine de kabul et" override'ı: AI tarafından reddedilen/şüpheli

POST leave-requests.reject /manager/leave-requests/{leaveRequest}/reject leaves.manage

İzin talepleri — Reddet

rejection_reason
POST leave-requests.restore /manager/leave-requests/{leaveRequest}/restore leaves.manage

Arşivdeki izni geri alır.

GET leave-requests.show /manager/leave-requests/{leaveRequest} leaves.view

Show leave request details for admin

PUT leave-settings.update /manager/leave-settings leaves.manage

Firma izin ayarlarını (mod, günlük saat, Cumartesi/Cuma kuralları) güncelle.

leave_mode leave_daily_hours saturday_is_rest_day auto_include_saturday_on_friday_leave
GET leave-types.active /manager/api/leave-types/active leaves.view

Aktif izin türlerini getir (API - dropdown için)

GET leave-types.create /manager/leave-types/create leaves.manage

Yeni özel izin türü oluşturma formu

DELETE leave-types.destroy /manager/leave-types/{leave_type} leaves.manage

İzin türleri — Sil

GET leave-types.edit /manager/leave-types/{leave_type}/edit leaves.manage

İzin türleri — Düzenleme formu verisi

GET leave-types.index /manager/leave-types leaves.manage

Firma izin türlerini listele

id name type_key description max_days_per_year max_days_per_request requires_approval allow_negative_balance affects_annual_balance requires_document document_type_key is_active is_system_type is_custom_type can_reset color leave_requests_count created_at
POST leave-types.reset-to-default /manager/leave-types/{leaveType}/reset-to-default leaves.manage

Sistem izin türünü config varsayılan değerlerine sıfırla

PATCH leave-types.rule-flags /manager/leave-types/{leaveType}/rule-flags leaves.manage

Kural bayraklarını (yıllık bakiyeyi etkiler / belge zorunlu) güncelle.

affects_annual_balance requires_document document_type_key
GET leave-types.show /manager/leave-types/{leave_type} leaves.manage

İzin türleri — Detay

POST leave-types.store /manager/leave-types leaves.manage

Yeni özel izin türü oluştur

name description max_days_per_year max_days_per_request requires_approval allow_negative_balance affects_annual_balance requires_document document_type_key is_active
POST leave-types.toggle-status /manager/leave-types/{leaveType}/toggle-status leaves.manage

İzin türleri — Aktif/pasif yap

PUT leave-types.update /manager/leave-types/{leave_type} leaves.manage

İzin türleri — Güncelle

name description max_days_per_year max_days_per_request requires_approval is_active allow_negative_balance affects_annual_balance requires_document document_type_key
Luca Köprüsü luca_bridge 5 komut
GET luca-bridge.envelopes /manager/luca-bridge/envelopes luca_bridge.view

Zarf listesi (status=processed|failed, type, report, year; per_page ≤100): durum, hata, neye yansıdığı.

status type report year
POST luca-bridge.envelopes.reprocess /manager/luca-bridge/envelopes/{envelope}/reprocess luca_bridge.manage

Başarısız zarfı sunucuda yeniden işletir (gönderici yeniden göndermeden; aynı işleyici). İşlenmiş zarfa dokunmaz

GET luca-bridge.envelopes.show /manager/luca-bridge/envelopes/{envelope} luca_bridge.view

Tek zarf: durum, hata, işleyici sonucu, artifact listesi (içerik değil).

GET luca-bridge.index /manager/luca-bridge luca_bridge.view

Luca Köprüsü özeti: zarf sayıları/durumları, her türün neye yansıdığı, personel aktarımı, parite, ekran kapsamı.

GET luca-bridge.payroll-compare /manager/luca-bridge/payroll-compare luca_bridge.view payroll.view

Kayıtlı bordro fişleri ↔ Luca bordrosu (kişi × ay, alan alan; year, status=match|diff|no_slip|no_period|no_employee|not_in_luca|issues, per_page ≤100).

year status page
Luca'ya Aktarım luca_export 6 komut
GET luca-bridge.export.index /manager/luca-bridge/export luca_export.view employees.view payroll.view

Luca'ya aktarım kontrol ekranı (mali müşavir): ay × işyeri için puantaj (gün gün), personel kartı (zorunlu alan eksikleri), empuno bordrosu (kişi başına) ve not

period sgk_workplace_id format
DELETE luca-bridge.export.packages.destroy /manager/luca-bridge/export/packages/{package} luca_export.manage

Yükleme izi kaydını geri al (reason zorunlu): kayıt silinmez, "geri alındı" olur; aynı dosya yeniden işaretlenebilir. Luca'daki veriye dokunmaz.

reason
GET luca-bridge.export.packages.index /manager/luca-bridge/export/packages luca_export.view

Yükleme izi listesi (mali müşavirin "kontrol edildi" / "Luca'ya yüklendi" kayıtları; period, sgk_workplace_id, kind, status=reviewed|uploaded|voided, per_page ≤

period sgk_workplace_id kind status
POST luca-bridge.export.packages.store /manager/luca-bridge/export/packages luca_export.manage employees.view

Yükleme izi işareti: dosya "kontrol edildi" (status=reviewed) ya da "Luca'ya yüklendi" (status=uploaded); kind=timesheet|personnel_update|personnel_new, period,

period sgk_workplace_id kind status content_sha256 notes force
GET luca-bridge.export.personnel /manager/luca-bridge/export/personnel luca_export.view employees.view payroll.view

Luca personel Excel'i (LUCA Personel Giriş Şablonu): mode=new (Luca'da kartı olmayanlar) | update (işyerinin o ayki tüm personeli); format zip (vars.: .xls + ma

period sgk_workplace_id department_id employee_ids employee_ids.* format
GET luca-bridge.export.timesheet /manager/luca-bridge/export/timesheet luca_export.view employees.view

Luca puantaj CSV'si (işyeri × ay; ISO-8859-9, `;`): gün kodları N/H/T/S/R/E/İ, eksik gün nedeni; ay içinde giren/çıkan manifest manual[]'da. format zip (vars.)

period sgk_workplace_id department_id employee_ids employee_ids.* format
Bordro payroll 97 komut
GET employees.exit-settlement.show /manager/employees/{employee}/exit-settlement payroll.view

Çıkış ödemesi önizlemesi + kayıtlı hesap (yan etkisiz). Ayrılmış çalışanda çıkış tarihi ve kodu

termination_date sgk_exit_code leave_days include_leave_pay include_notice notice_served include_severance monthly_gross monthly_dressed notes dismiss confirm
PUT employees.exit-settlement.update /manager/employees/{employee}/exit-settlement payroll.manage

Ayrılmış çalışanın çıkış ödemesini kaydeder / düzeltir ve onaylar (confirm=false: onay bekler).

termination_date sgk_exit_code leave_days include_leave_pay include_notice notice_served include_severance monthly_gross monthly_dressed notes dismiss confirm
PATCH employees.incentive-facts.update /manager/employees/{employee}/incentive-facts payroll.manage

Çalışanın teşvik bilgilerini günceller — yalnız gönderilen anahtarlar birleşir (null siler); dry_run destekler.

facts dry_run
DELETE employees.incentives.destroy /manager/employees/{employee}/incentives/{incentive} payroll.manage

Teşvik atamasını siler (yumuşak) — kesinleşmiş fişlerin kanun kodu korunur; dry_run destekler.

dry_run
GET employees.incentives.index /manager/employees/{employee}/incentives payroll.view

Çalışanın teşvik atamaları, ön uygunluğu ve teşvik bilgileri (yan etkisiz).

POST employees.incentives.store /manager/employees/{employee}/incentives payroll.manage

Çalışana teşvik atar — dry_run destekler; e-posta yok. Yalnız status=active atama dönem hesabına girer.

law_no status start_date end_date duration_months certificate_no notes dry_run
PATCH employees.incentives.update /manager/employees/{employee}/incentives/{incentive} payroll.manage

Teşvik atamasını günceller — yalnız gönderilen alanlar (status, start_date, end_date, duration_months, certificate_no, notes).

DELETE employees.payroll-items.destroy /manager/employees/{employee}/payroll-items/{item} payroll.manage

Çalışan kalemini siler (geçmiş bordrolardaki satırlar korunur).

GET employees.payroll-items.index /manager/employees/{employee}/payroll-items payroll.view

Çalışanın ek kazanç/kesinti kalemleri (yan etkisiz) + seçilebilir türler.

POST employees.payroll-items.store /manager/employees/{employee}/payroll-items payroll.manage

Çalışana kalem ekler: kind (earning | deduction), type (tür id, kodu ya da adı), amount,

kind type amount hours start_period end_period description
PATCH employees.payroll-items.update /manager/employees/{employee}/payroll-items/{item} payroll.manage

Çalışan kalemini günceller (yalnız gönderilen alanlar: amount, hours, start_period, end_period, description). Saat bazlı kalemde amount yerine hours.

amount hours start_period end_period description
GET employees.payroll-profile.edit /manager/employees/{employee}/payroll-profile payroll.manage

Çalışanın güncel bordro profili + sürüm geçmişi (history[]: effective_from/to, maaş). Yan etkisiz.

PUT employees.payroll-profile.update /manager/employees/{employee}/payroll-profile payroll.manage

Çalışanın bordro profilini kaydeder; effective_from mevcut sürümden SONRAysa yeni sürüm açar.

salary_type gross_salary is_net_salary net_salary insurance_group mw_exemption_applies tax_payment_type rd_incentive rd_tax_exemption_rate rd_incentive_start rd_incentive_end disability_degree_payroll has_meal_allowance meal_allowance_daily has_transport_allowance transport_allowance_daily active_incentive_code incentive_start_date incentive_end_date rd_personnel_type effective_from effective_to work_schedule weekly_hours
POST employees.pension.action /manager/employees/{employee}/pension/{enrollment}/action payroll.manage

BES kaydında işlem: opt_out | leave_system | pause | resume | rate_change | rejoin | certificate — hemen uygulanır; dry_run destekler.

action effective_date until rate certificate_no source note dry_run
GET employees.pension.show /manager/employees/{employee}/pension payroll.view

Çalışanın BES kaydı, kapsam durumu, hareketleri ve kesinti geçmişi (yan etkisiz).

POST employees.pension.store /manager/employees/{employee}/pension payroll.manage

Çalışanı BES planına elle dahil eder — dry_run destekler; e-posta yok.

plan_id enrolled_on rate notified_at certificate_no voluntary notes dry_run
PATCH employees.pension.update /manager/employees/{employee}/pension/{enrollment} payroll.manage

BES kaydının alanlarını günceller — yalnız gönderilenler: rate (≥ %3), certificate_no, notified_at (cayma süresi yeniden hesaplanır), notes.

POST payroll-items.bulk /manager/payroll-items/bulk payroll.manage

Toplu kalem ekleme (ör. bu ayın primleri, ikramiye, sendika aidatı): records[]: çalışan anahtarı

records dry_run records.*.kind records.*.type records.*.amount records.*.hours records.*.period records.*.end_period records.*.description records.*.employee_id records.*.employee_number records.*.identity_number records.*.employee_name
POST payroll-profiles.bulk-update /manager/payroll-profiles/bulk-update payroll.manage

Toplu bordro profili güncelleme. Paylaşılan tek geçerlilik tarihiyle tüm

effective_from rows rows.*.employee_id rows.*.salary_type rows.*.is_net_salary rows.*.gross_salary rows.*.net_salary rows.*.insurance_group rows.*.disability_degree_payroll rows.*.meal_allowance_daily rows.*.transport_allowance_daily rows.*.active_incentive_code rows.*.incentive_start_date rows.*.incentive_end_date rows.*.work_schedule rows.*.weekly_hours rows.*.rd_personnel_type
GET payroll-profiles.index /manager/payroll-profiles payroll.manage

Toplu bordro profili giriş sayfası — tüm aktif çalışanların maaş/yan hak

employee_id full_name employee_number department salary_type is_net_salary gross_salary net_salary insurance_group disability_degree_payroll meal_allowance_daily transport_allowance_daily active_incentive_code incentive_start_date incentive_end_date effective_from work_schedule weekly_hours has_profile
GET payroll-settings.accounting.index /manager/payroll-settings/accounting payroll.manage

Muhasebe hesap planı eşlemesi: kalemler + varsayılan Tekdüzen hesabı + firma eşlemesi, departman/şube gider kökleri ve önerileri, fiş tercihleri.

PATCH payroll-settings.accounting.mappings.update /manager/payroll-settings/accounting/mappings payroll.manage

Hesap eşlemelerini toplu yazar; yalnız gönderilen satırlar, account_code=null varsayılana döndürür; satır bazlı results[].

mappings mappings.* mappings.*.line_key mappings.*.scope_id mappings.*.account_code mappings.*.account_name mappings.*.cost_center dry_run
PATCH payroll-settings.accounting.options.update /manager/payroll-settings/accounting/options payroll.manage

Muhasebe fişi tercihlerini günceller (yalnız gönderilen anahtarlar).

POST payroll-settings.accounting.suggest /manager/payroll-settings/accounting/suggest payroll.manage

Hesap planı/mizan dosyasından (xlsx/xls/csv, ≤5 MB) eşleme önerir; apply=true ise yüksek güvenli önerileri yazar.

file accounts accounts.*.code accounts.*.name apply overwrite min_confidence dry_run
DELETE payroll-settings.deduction-types.destroy /manager/payroll-settings/deduction-types/{deductionType} payroll.manage

Kesinti türünü kaldırır; kullanıldıysa pasife alınır.

POST payroll-settings.deduction-types.store /manager/payroll-settings/deduction-types payroll.manage

Kesinti türü ekler. reduces_tax_base: GV matrahından indirilir (GVK 63 — sendika aidatı, şahıs

name code category reduces_tax_base max_tax_deduction_rate default_amount is_recurring applies_to is_active
PATCH payroll-settings.deduction-types.update /manager/payroll-settings/deduction-types/{deductionType} payroll.manage

Kesinti türünü günceller (yalnız gönderilen alanlar).

name code category reduces_tax_base max_tax_deduction_rate default_amount is_recurring applies_to is_active
DELETE payroll-settings.earning-types.destroy /manager/payroll-settings/earning-types/{earningType} payroll.manage

Ek kazanç türünü kaldırır; bordroda ya da çalışan kaleminde kullanıldıysa pasife alınır.

POST payroll-settings.earning-types.hourly-presets /manager/payroll-settings/earning-types/hourly-presets payroll.manage

Saat bazlı yasal kazanç türlerini şablondan açar: presets[] (overtime_50 | overtime_25 | weekly_rest | holiday | night;

presets presets.* multipliers multipliers.* multiplier applies_to is_sgk_applicable
POST payroll-settings.earning-types.store /manager/payroll-settings/earning-types payroll.manage

Ek kazanç türü ekler. Vergi/prim bayrakları (is_taxable, is_sgk_applicable, is_stamp_tax_applicable),

name code category is_taxable is_sgk_applicable is_stamp_tax_applicable exemption_type calculation_type hours_source multiplier default_amount is_recurring applies_to is_active
PATCH payroll-settings.earning-types.update /manager/payroll-settings/earning-types/{earningType} payroll.manage

Ek kazanç türünü günceller (yalnız gönderilen alanlar). Sistem türlerinde (yemek/yol, çıkış) yalnız ad ve tutar. Saat bazlı türde hours_source ve multiplier.

name code category is_taxable is_sgk_applicable is_stamp_tax_applicable exemption_type calculation_type hours_source multiplier default_amount is_recurring applies_to is_active
DELETE payroll-settings.export-templates.destroy /manager/payroll-settings/export-templates/{template} payroll.manage

Dosya şablonunu siler (geçmiş üretim kayıtları korunur; şablon adı kayıtta saklıdır).

POST payroll-settings.export-templates.detect /manager/payroll-settings/export-templates/detect payroll.manage

Bankanın/muhasebe programının örnek dosyasından şablon çıkarır; store=true ve name verilirse kaydeder.

file kind store name is_default dry_run
GET payroll-settings.export-templates.index /manager/payroll-settings/export-templates payroll.manage

Bordro dosya şablonları: önayarlar (banka + muhasebe fişi, doğrulama durumu ve kaynağıyla) ve firmanın şablonları (yan etkisiz).

kind q page
POST payroll-settings.export-templates.preview /manager/payroll-settings/export-templates/preview payroll.manage

Dosya şablonunun canlı önizlemesi: son onaylı dönemin ilk satırları şablona göre biçimlenmiş; IBAN/TCKN maskeli (yan etkisiz, dosya üretmez).

GET payroll-settings.export-templates.show /manager/payroll-settings/export-templates/{template} payroll.manage

Tek dosya şablonu: tam tanım, parametreler (IBAN maskeli), kopyalandığı önayar ve kullanım (yan etkisiz).

POST payroll-settings.export-templates.store /manager/payroll-settings/export-templates payroll.manage

Banka/fiş dosya şablonu oluşturur; preset verilirse kopyalar.

kind name preset bank_code params params.* is_default definition definition.format definition.encoding definition.delimiter definition.quote definition.line_ending definition.header_row definition.decimal_separator definition.thousands_separator definition.amount_decimals definition.implied_decimals definition.ascii_only definition.uppercase definition.same_bank_only definition.sheet_name definition.preamble definition.preamble.*.row definition.preamble.*.label definition.preamble.*.field definition.preamble.*.format definition.detail_start_row definition.header_record definition.header_record.*.field definition.footer_record definition.footer_record.*.field definition.columns definition.columns.*.field definition.columns.*.title definition.columns.*.width definition.columns.*.align definition.columns.*.pad definition.columns.*.format definition.columns.*.value definition.max_lines_per_voucher definition.max_vouchers_per_file
PATCH payroll-settings.export-templates.update /manager/payroll-settings/export-templates/{template} payroll.manage

Dosya şablonunu günceller (yalnız gönderilen alanlar).

POST payroll-settings.incentives.apply /manager/payroll-settings/incentives/apply payroll.manage

Önerilen ya da seçilen teşvikleri çalışanlara uygular — satır bazlı sonuç, dry_run, tekrar güvenli; e-posta yok.

rows rows.*.employee_id rows.*.law_no rows.*.start_date rows.*.end_date rows.*.duration_months rows.*.status rows.*.certificate_no rows.*.notes rows.*.facts all_recommended status on_existing force dry_run
GET payroll-settings.incentives.index /manager/payroll-settings/incentives payroll.view

Firmadaki çalışanların teşvik ön uygunluğu, en avantajlı öneri ve aylık tahmini kazanç (yan etkisiz).

status law_no q as_of page
GET payroll-settings.index /manager/payroll-settings payroll.manage

Bordro ayarları sayfasını göster.

PATCH payroll-settings.options.update /manager/payroll-settings/options payroll.manage

Firma bordro hesaplama tercihlerini günceller (yalnız gönderilen anahtarlar). Seçenekler ve

PUT payroll-settings.update /manager/payroll-settings payroll.manage

Bordro ayarlarını güncelle (kısmi: yalnız gönderilen alanlar yazılır; gönderilmeyen evet/hayır alanları korunur).

sector_type nace_code pay_day currency include_meal_allowance default_meal_allowance_daily include_transport_allowance default_transport_allowance_daily auto_apply_incentive payroll_lock_day payslip_note
DELETE payroll.accounting-postings.destroy /manager/payroll/{period}/accounting-postings/{posting} payroll.manage

Muhasebeleştirme işaretini geri alır (muhasebe programındaki fişe dokunmaz).

POST payroll.accounting-postings.store /manager/payroll/{period}/accounting-postings payroll.manage

Dönemi muhasebeleştirildi olarak işaretler; fişin hesap özeti saklanır, sonraki düzeltme fişi buna göre çıkar.

kind voucher_no voucher_date notes accept_integrity_issues
GET payroll.accounting-voucher /manager/payroll/{period}/accounting-voucher payroll.view

Bordro döneminin muhasebe fişi: yevmiye satırları, borç = alacak denetimi, mutabakat, uyarılar; format verilirse dosya indirir (yan etkisiz).

kind detail format voucher_no voucher_date merge_same_account options
POST payroll.approve /manager/payroll/{period}/approve payroll.manage

Bordro dönemini onayla.

POST payroll.attendance.commit /manager/payroll/attendance/commit payroll.manage

Puantaj kayıtlarını yazar (toplu, satır bazlı sonuç): ızgara (days) ya da özet; çalışan-ay başına tek kayıt, tekrar güvenli.

records period on_existing dry_run source code_map code_map.* records.*.period records.*.format records.*.days records.*.sgk_days records.*.missing_breakdown records.*.missing_day_reason records.*.missing_days records.*.sick_days records.*.unpaid_leave_days records.*.absent_days records.*.wage_deduction_days records.*.worked_days records.*.worked_hours records.*.paid_rest_hours records.*.overtime_50_hours records.*.overtime_25_hours records.*.weekly_rest_days records.*.weekly_rest_hours records.*.holiday_days records.*.holiday_hours records.*.night_hours records.*.notes records.*.derived records.*.employee_id records.*.employee_number records.*.identity_number records.*.employee_name
DELETE payroll.attendance.destroy /manager/payroll/attendance/{entry} payroll.manage

Puantaj kaydını siler (yumuşak; aynı ay yeniden aktarılınca geri gelir) — o çalışan-ay yeniden izin kayıtları ve PDKS'ten hesaplanır.

GET payroll.attendance.export /manager/payroll/attendance/export payroll.view

Puantaj Excel'i (Puantaj ızgarası · Özet · Kodlar) — geri okunabilir; puantajı olmayan çalışan PDKS / izin / tatil takviminden ön doldurulur.

period department_id prefill
GET payroll.attendance.index /manager/payroll/attendance payroll.view

Ayın puantaj listesi: kayıtlar (önizleme + uyuşmazlık sayısı), puantajı olmayan uygun çalışanlar, kaynak tercihleri, dönem kilidi.

period department_id q format conflicts_only
POST payroll.attendance.parse /manager/payroll/attendance/parse payroll.manage

Puantaj dosyasını (Excel / CSV) okur, yazmaz: ızgara ya da özet, dönem, gün kodları; dönen records[] payroll.attendance.commit'e verilir.

file period code_map code_map.* format
GET payroll.attendance.show /manager/payroll/attendance/{entry} payroll.view

Tek puantaj kaydı: alanlar ve gün gün ızgara, bordro motoru önizlemesi (prim günü, ücret, kovaların ödeyicisi ve tutarı), uyuşmazlıklar, izin / PDKS kayıtları,

PATCH payroll.attendance.update /manager/payroll/attendance/{entry} payroll.manage

Tek puantaj kaydını düzeltir — yalnız gönderilen alanlar; conflicts_reviewed=true uyuşmazlıkları "incelendi" işaretler.

conflicts_reviewed code_map code_map.* period format days sgk_days missing_breakdown missing_day_reason notes wage_deduction_days worked_days weekly_rest_days holiday_days sick_days unpaid_leave_days absent_days missing_days worked_hours paid_rest_hours overtime_50_hours overtime_25_hours weekly_rest_hours holiday_hours night_hours
GET payroll.bank-file /manager/payroll/{period}/bank-file payroll.manage

Banka maaş ödeme dosyası önizlemesi: ödenecekler (IBAN maskeli), dışarıda kalanlar ve nedenleri, toplamlar, geçmiş dosyalar. Yan etkisiz.

POST payroll.bank-file.generate /manager/payroll/{period}/bank-file payroll.manage

Banka maaş ödeme dosyasını üretip indirir; üretim denetim kaydına yazılır (IBAN saklanmaz). Dönem onaylanmış olmalı; confirm_total verilirse toplam eşleşmeli.

confirm_total
POST payroll.bank-file.request-iban /manager/payroll/{period}/bank-file/request-iban payroll.manage

IBAN'ı eksik/geçersiz çalışanlara IBAN girmeleri için push + e-posta gönderir (yan etki; çalışan başına 24 saatte bir).

employee_ids employee_ids.* channels channels.* dry_run
POST payroll.bulk-destroy /manager/payroll/bulk-destroy payroll.manage

Bordro dönemlerini toplu siler: ids[] (≤100) YA DA all_cancelled=true (+ year) — iptal edilmiş tüm dönemler.

ids ids.* all_cancelled year reason dry_run
POST payroll.calculate /manager/payroll/{period}/calculate payroll.manage

Bordro dönemini hesaplar (taslak ya da hesaplanmış dönem; yeniden hesaplama fişleri yeniler).

dry_run basis employee_ids employee_ids.* tolerance
POST payroll.cancel /manager/payroll/{period}/cancel payroll.manage

Bordro dönemini iptal eder (isteğe bağlı reason ≤500, denetime yazılır).

reason
GET payroll.create /manager/payroll/create payroll.manage

Yeni bordro dönemi oluşturma formu.

GET payroll.declaration /manager/payroll/{period}/declaration payroll.manage

Dönemin SGK (APHB) + vergi (MUHSGK) mutabakatı: sgk_rows (belge türü, kanun no, prim günü, PEK, eksik gün nedeni, giriş/çıkış, meslek kodu, işyeri sicil no), ta

sgk_workplace_id
GET payroll.declaration-export /manager/payroll/{period}/declaration/export payroll.manage

SGK/MUHSGK mutabakat Excel'i (sayfalar: Özet, SGK (APHB), Vergi (MUHSGK), Bordro Detayı, Uyarılar). Firmada birden

sgk_workplace_id
PATCH payroll.declaration.update /manager/payroll/{period}/employee/{employee}/declaration payroll.manage

Fişin SGK (APHB) / MUHSGK beyan alanlarını düzeltir — yalnız gönderilen alanlar; tutar, net, kümülatif ve dönem kilidi değişmez.

sgk_days missing_day_count missing_day_reason sgk_document_type insurance_group employer_incentive_code employer_incentive_amount sgk_occupation_code sgk_workplace_registration_no tax_payment_type rd_law rd_rate rd_days rd_income_tax_exemption rd_stamp_exemption rd_sgk_support mw_income_tax_exemption mw_stamp_exemption reason
DELETE payroll.destroy /manager/payroll/{period} payroll.manage

İptal edilmiş ya da hiç onaylanmamış (taslak/hesaplanmış) bordro dönemini fişleriyle birlikte siler (soft delete + denetim kaydı).

reason
GET payroll.employee-slip /manager/payroll/{period}/employee/{employee} payroll.manage

Çalışanın dönem bordro fişi: kazanç/kesinti kalemleri, SGK ve vergi kırılımı, işveren maliyeti ve SGK/MUHSGK beyan bilgileri.

POST payroll.finalize /manager/payroll/{period}/finalize payroll.manage

Bordro dönemini kesinleştir.

GET payroll.index /manager/payroll payroll.view

Bordro dönemlerini listeler (varsayılan: iptal edilmişler gizli).

status year archived per_page page
GET payroll.parameters /manager/payroll/parameters payroll.view

Yürürlük tarihli yasal bordro parametreleri (date=YYYY-MM-DD ya da year=YYYY): asgari ücret, SGK oran/taban/tavan, GV dilimleri, istisnalar, AGİ/AÜ istisnası. Y

date year
POST payroll.pay /manager/payroll/{period}/pay payroll.manage

Bordro dönemini ödenmiş olarak işaretle.

GET payroll.pension-transfer /manager/payroll/{period}/pension-transfer payroll.manage

Dönemin BES kurum aktarım listesi — plan bazında çalışan/işveren katkıları, son gün, aktarım durumu (yan etkisiz).

plan_id
GET payroll.pension-transfer-export /manager/payroll/{period}/pension-transfer/export payroll.manage

BES kurum aktarım listesini Excel olarak indirir (plan başına sayfa, TCKN tam; ?plan_id ile tek plan) — yan etkisiz.

plan_id
POST payroll.pension-transfer-mark /manager/payroll/{period}/pension-transfer/mark payroll.manage

BES aktarımını "aktarıldı" olarak işaretler (dönem + plan; tekrar güvenli — ikinci çağrı tarihi/referansı günceller); dry_run destekler.

plan_id transferred_at reference dry_run
POST payroll.reopen /manager/payroll/{period}/reopen payroll.manage

Kesinleşmiş / ödenmiş dönemi düzeltmeye açar: reason (zorunlu, ör. "Ahmet'in fazla mesaisi eksik girilmiş").

reason
POST payroll.restore /manager/payroll/{period}/restore payroll.manage

Silinmiş bordro dönemini fişleriyle geri alır.

GET payroll.show /manager/payroll/{period} payroll.manage

Bordro dönemi detayı: fişler, özet, düzeltme turları. {period} id ya da YYYY-AA (ör. 2026-04; aynı ayın

id employee_id employee gross_salary gross_total sgk_employee_total income_tax_final stamp_tax_final total_deductions net_pay total_employer_cost sgk_employer_total status worked_days sgk_day_count day_source hour_source
POST payroll.simulate /manager/payroll/simulate payroll.view

Yan etkisiz bordro simülasyonu: çalışan ya da serbest profil için fiş + adım adım hesap izi; DB'ye hiçbir şey yazmaz, bildirim/AI kredisi yok.

period months employee_id profile profile.salary_type profile.gross_salary profile.net_salary profile.hourly_rate profile.hours profile.insurance_group profile.mw_exemption_applies profile.rd_incentive profile.rd_tax_exemption_rate profile.disability_degree profile.hire_date profile.is_manufacturing profile.work_schedule profile.weekly_hours attendance attendance.sgk_days attendance.missing_breakdown attendance.missing_breakdown.* attendance.missing_day_reason attendance.worked_hours attendance.paid_rest_hours days days.sgk_days days.missing_days days.missing_reason days.pay_days days.allowance_days days.rd_days overtime overtime.overtime_50_hours overtime.overtime_25_hours overtime.weekly_rest_hours overtime.weekly_rest_days overtime.holiday_hours overtime.holiday_days overtime.night_hours earnings earnings.*.type_id earnings.*.code earnings.*.name earnings.*.amount earnings.*.daily earnings.*.days earnings.*.gv_taxable earnings.*.sgk_applicable earnings.*.dv_applicable earnings.*.net deductions deductions.*.type_id deductions.*.name deductions.*.amount deductions.*.reduces_tax_base cumulative_tax_base_before exit exit.leave_pay exit.notice_pay exit.severance exit.severance_excess options incentives incentives.*.law_no incentives.*.start_date incentives.*.duration_months apply_5510 pension pension.enabled pension.employer_contribution_type pension.employer_contribution_value segments segments.*.from segments.*.to segments.*.sgk_workplace_id segments.*.sick_days segments.*.unpaid_days agi agi.marital_status agi.spouse_works agi.children include_live_items compare_with_slip trace
GET payroll.simulator /manager/payroll/simulator payroll.view

Bordro simülatörü form verisi: çalışanlar (profil özeti), ek kazanç/kesinti türleri, hesaplama tercihleri, parametre setleri. Yan etkisiz.

POST payroll.store /manager/payroll payroll.manage

Yeni bordro dönemi açar (year, month). Aynı ayın iptal edilmemiş dönemi varsa reddedilir; yalnız iptal

year month
GET pension.index /manager/pension payroll.view

BES planları, katılımcılar ve son hareketler (yan etkisiz).

status plan_id q page
DELETE pension.plans.destroy /manager/pension/plans/{plan} payroll.manage

BES planını siler — katılımcısı varsa silinmez, pasife alınır (yeni katılım durur, mevcut kesintiler sürer); dry_run destekler.

dry_run
POST pension.plans.store /manager/pension/plans payroll.manage

BES planı ekler (emeklilik şirketi sözleşmesi) — dry_run destekler; e-posta yok.

PATCH pension.plans.update /manager/pension/plans/{plan} payroll.manage

BES planını günceller — yalnız gönderilen alanlar; is_active=false ile pasife alma, is_default ile varsayılan seçimi.

POST pension.sync /manager/pension/sync payroll.manage

Uygun ve kaydı olmayan çalışanları BES planına dahil eder — dry_run ile önizleme, satır bazlı sonuç; e-posta yok.

plan_id as_of include_existing_hires dry_run
GET reports.index /manager/reports payroll.view

Rapor merkezi: tüm raporlar, süzgeçleri ve son dönemler (panel ekranı).

GET reports.payroll /manager/reports/payroll payroll.view

Bordro raporu (report=register|icmal|yearly|income_tax|salary_summary|rd|employee_info; period=YYYY-AA ya da year=YYYY).

report period year sgk_workplace_id department_id employee_id format
GET reports.payslips /manager/reports/payslips payroll.view

Ücret hesap pusulası (period=YYYY-AA; employee_ids[] boşsa dönemin tümü). format=pdf (vars.) | json.

period employee_ids employee_ids.* employer format
POST sgk-workplaces.assign /manager/sgk-workplaces/{sgkWorkplace}/assign payroll.manage

Çalışanları SGK işyerine bağlar — mode=correct (güncel dönemin işyerini düzelt) | transfer (tarihli nakil); satır bazlı results[].

employee_ids employee_ids.* mode date dry_run
POST sgk-workplaces.change-registration /manager/sgk-workplaces/{sgkWorkplace}/change-registration payroll.manage

SGK yeni sicil numarası verdi (işkolu / ilçe / ünite değişikliği) — dry_run destekler; e-posta yok.

registration_no date note dry_run
DELETE sgk-workplaces.destroy /manager/sgk-workplaces/{sgkWorkplace} payroll.manage

SGK işyerini siler — çalışma dönemi ya da bordro fişi bağlıysa reddedilir (closed_at ile kapatın); dry_run destekler.

dry_run
GET sgk-workplaces.index /manager/sgk-workplaces payroll.view

Firmanın SGK işyerlerini listeler — yan etkisiz; kapatılanlar include_closed=true ile.

POST sgk-workplaces.merge /manager/sgk-workplaces/{sgkWorkplace}/merge payroll.manage

Ayrı işyeri olarak açılmış eski sicilleri bu işyerine birleştirir (sicil geçmişine katar) — atomik, dry_run destekler.

source_ids source_ids.* valid_until valid_until.* dry_run
GET sgk-workplaces.merge-suggestions /manager/sgk-workplaces/merge-suggestions payroll.view

Birleştirme önerileri — yan etkisiz: aynı sıra no + il + aracı numaralı işyerleri (işkolu / ilçe / ünite değişince

DELETE sgk-workplaces.registrations.destroy /manager/sgk-workplaces/{sgkWorkplace}/registrations/{registration} payroll.manage

Sicil geçmişinden bir eski numarayı kaldırır (yanlış girilmiş) — dry_run destekler.

dry_run
POST sgk-workplaces.registrations.store /manager/sgk-workplaces/{sgkWorkplace}/registrations payroll.manage

İşyerinin sicil geçmişine eski bir numara ekler (aktarılmış geçmiş dönemler için) — dry_run destekler.

registration_no valid_until valid_from note dry_run
POST sgk-workplaces.store /manager/sgk-workplaces payroll.manage

SGK işyeri açar — dry_run destekler; e-posta yok.

name registration_no province district branch_id zone_type default_law_no is_default closed_at notes dry_run
PATCH sgk-workplaces.update /manager/sgk-workplaces/{sgkWorkplace} payroll.manage

SGK işyerini günceller — yalnız gönderilen alanlar; closed_at ile kapatma, is_default ile varsayılan seçimi.

name registration_no province district branch_id zone_type default_law_no is_default closed_at notes dry_run
PDKS Yönetimi pdks 16 komut
POST pdks.auto-checkout /manager/pdks/auto-checkout pdks.manage

PDKS (giriş-çıkış) — auto checkout

GET pdks.calendar /manager/pdks/calendar pdks.view

PDKS (giriş-çıkış) — calendar

id full_name employee_id
GET pdks.calendar.data /manager/pdks/calendar/data pdks.view

PDKS takvimi — data

id title start allDay color extendedProps
GET pdks.configure /manager/pdks/branches/{branch}/configure pdks.manage

PDKS (giriş-çıkış) — configure

POST pdks.disable /manager/pdks/branches/{branch}/disable pdks.manage

PDKS (giriş-çıkış) — Devre dışı bırak

POST pdks.enable /manager/pdks/branches/{branch}/enable pdks.manage

PDKS (giriş-çıkış) — Etkinleştir

GET pdks.export /manager/pdks/export pdks.view

PDKS (giriş-çıkış) — Dışa aktar

POST pdks.generate-token /manager/pdks/branches/{branch}/generate-token pdks.manage

PDKS (giriş-çıkış) — generate token

GET pdks.index /manager/pdks pdks.view

PDKS (giriş-çıkış) — Listele

GET pdks.live-attendance /manager/pdks/live-attendance pdks.view

PDKS (giriş-çıkış) — live attendance

GET pdks.live-attendance.data /manager/pdks/live-attendance/data pdks.view

Canlı yoklama — data

id employee_name status next_action next_action_label check_in_time check_out_time working_hours updated_at
GET pdks.public-link /manager/pdks/branches/{branch}/public-link pdks.view

PDKS (giriş-çıkış) — public link

GET pdks.reports /manager/pdks/branches/{branch}/reports pdks.view

PDKS (giriş-çıkış) — reports

PUT pdks.settings.update /manager/pdks/branches/{branch}/settings pdks.manage

PDKS ayarları — Güncelle

work_start_time work_end_time lunch_break_enabled lunch_start_time lunch_end_time overtime_limit location_check_enabled latitude longitude location_radius qr_validity_seconds pdks_max_distance_m
GET pdks.station-code /manager/pdks/branches/{branch}/station-code pdks.view

PDKS İstasyon Kodu sayfası — yöneticinin tablete gireceği 8 haneli dönen kod.

GET pdks.station-code.refresh /manager/pdks/branches/{branch}/station-code/refresh pdks.view

İstasyon kodunu JSON olarak döndürür (sayfa client-side auto-refresh için).

Web PDKS Entegrasyonu pdks_web 8 komut
GET pdks-web.branch /manager/pdks/branches/{branch}/web pdks_web.view

Tek şubenin web embed yönetim sayfası.

POST pdks-web.disable /manager/pdks/branches/{branch}/web/disable pdks_web.manage

Şube için Web PDKS'i kapat.

POST pdks-web.enable /manager/pdks/branches/{branch}/web/enable pdks_web.manage

Şube için Web PDKS aktif et — yoksa pinli token oluştur, varsa yeniden etkinleştir.

GET pdks-web.index /manager/pdks-web

Web PDKS — Listele

GET pdks-web.logs /manager/pdks-web/logs pdks_web.view

Web PDKS — logs

GET pdks-web.logs.export /manager/pdks-web/logs/export pdks_web.view

Web PDKS kayıtları — Dışa aktar

POST pdks-web.rotate /manager/pdks/branches/{branch}/web/rotate pdks_web.manage

Token'ı yenile — eski iframe/script kodu çalışmayı durdurur.

PUT pdks-web.update /manager/pdks/branches/{branch}/web pdks_web.manage

İzinli origin + konum zorunluluğu güncelle.

allowed_origins allowed_origins.* location_required
Vardiya Yönetimi shifts 14 komut
POST shift-scheduling.approve /manager/shift-scheduling/approve shifts.manage

Approve and apply the generated schedule

GET shift-scheduling.create /manager/shift-scheduling/create shifts.manage

Otomatik vardiya planı — Oluşturma formu verisi

id name start_time end_time working_days is_active
POST shift-scheduling.generate /manager/shift-scheduling/generate shifts.manage

Otomatik vardiya planı — Üret

start_date end_date branch_id employee_ids employee_ids.* business_type max_daily_hours max_weekly_hours shift_duration fair_distribution business_open_time business_close_time min_staff peak_min_staff
GET shift-scheduling.index /manager/shift-scheduling shifts.manage

Otomatik vardiya planı — Listele

id name start_time end_time working_days is_active
POST shifts.assign /manager/shifts/assign shifts.manage

Vardiyalar — Ata

employee_id shift_id assigned_date recurring
GET shifts.assignments /manager/shifts/assignments shifts.view

Vardiyalar — assignments

GET shifts.calendar /manager/shifts/calendar shifts.view

Vardiyalar — calendar

id name address
GET shifts.calendar-events /manager/shifts/calendar-events shifts.view

Vardiyalar — calendar events

GET shifts.create /manager/shifts/create shifts.manage

Vardiyalar — Oluşturma formu verisi

DELETE shifts.destroy /manager/shifts/{shift} shifts.manage

Vardiyalar — Sil

GET shifts.edit /manager/shifts/{shift}/edit shifts.manage

Vardiyalar — Düzenleme formu verisi

GET shifts.index /manager/shifts shifts.view

Vardiyalar — Listele

id name start_time end_time working_days break_duration_minutes is_active employees_count created_at
POST shifts.store /manager/shifts shifts.manage

Vardiyalar — Oluştur

name start_time end_time working_days working_days.* break_duration_minutes description
PUT shifts.update /manager/shifts/{shift} shifts.manage

Vardiyalar — Güncelle

name start_time end_time working_days working_days.* break_duration_minutes is_active
Vize Talepleri visa_requests 5 komut
POST visa-requests.cancel /manager/visa-requests/{visaRequest}/cancel visa_requests.manage

Vize talepleri — İptal et

GET visa-requests.download /manager/visa-requests/{visaRequest}/download visa_requests.view

Vize talepleri — İndir

POST visa-requests.generate /manager/visa-requests/{visaRequest}/generate visa_requests.manage

Vize talepleri — Üret

include_salary
GET visa-requests.index /manager/visa-requests visa_requests.view

Vize talepleri — Listele

POST visa-requests.share /manager/visa-requests/{visaRequest}/share visa_requests.manage

Vize talepleri — Paylaş

İK süreçlerinizi ajanınıza devredin

Hesap açın, Firma Ayarları → API sekmesinden bir Ajan anahtarı üretin ve ilk komutunuzu bir dakikada çalıştırın.

Ücretsiz Dene →

Ajan anahtarı canlı verinizde, anahtarı oluşturan kişinin adına çalışır ve panelle aynı yan etkileri doğurur (bildirim e-postaları, AI kredisi). Anahtarı yalnızca güvendiğiniz sistemlere verin, kapsamını gereken modüllerle sınırlayın ve kullanılmayan anahtarı panelden iptal edin.