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.
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.
# 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:
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>.
# 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/rejectGü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.
| Kanal | Denemede 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şi | Gö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. |
| Önbellek | Bu 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": trueveIdempotent-Replayed: truebaş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_unavailabledö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_requiredalı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--validateyoktur (CLI kullanım hatası verir). - CLI 1.5.0:
--idempotency-key autoanahtarı 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 Nağ hatası, 502/503/504 ya da409 idempotency_in_progressdurumundaRetry-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 migratebirden ç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.
# Ö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/departmentsBaş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_idya daemployee_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ütunmissing_required'da. Dönenrecords'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ınreason'ında yazar. - Ada göre eşleme: izin türü (
leave_type: ad ya daannualgibi 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,
skippeddöner. Çalışanlarda--on_existing updateyalnız gönderilen alanları günceller. - Satır bazlı sonuç: yanıtta
results[]her satır içincreated | updated | skipped | failed, oluşan kaydın kimliği ve hata nedeni. - Doğrulamada kimlik yok:
dry_runyanıtındacreatedsatırınınid'sinull'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,50tutarları için CLI'ye--decimal ,verin; TC, tarih ve sicil no dokunulmaz.
| Veri | Komut | Not |
|---|---|---|
| Ç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.commit | Her 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 izin | employees.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şi | data-migration.leaves.commit | Onaylı geçmiş izin; bakiye hesabına girer |
| Avanslar + devreden bakiye | data-migration.advances.commit | Bordro, deduction_period'dan itibaren kalan bakiyeden düşer |
| Masraflar | data-migration.expenses.commit | Ödenmiş/onaylı; muhasebeye işlenmiş sayılır |
| Geçmiş bordrolar | data-migration.payroll.commit | Ayrıca payroll.manage ister. Değerler aynen saklanır (yeniden hesaplanmaz); dönem kilitli "ödendi" açılır |
| Bordro beyan bilgileri | data-migration.payroll.commit + update_fields=declaration | Aktarı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 kanun | data-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.
# 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ılanhire_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;januaryeski 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ındakihelpalanı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 vereason; istense bile eklenmez (gönüllü ödeme ek kazanç olarak girilir). - Müşavir bordrosu aktarılan ay:
data-migration.payroll.commitearnings[].type = leave_pay | notice | severance (+ days) ile çıkış kalemleri empuno çıkış ödemesi olarak kaydedilir (durumimported); tipli kalem yoksa o ayın onay bekleyen ödemesisupersededolur. 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).
# Ö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). İhlalrejected+flash.rule(kod) +flash.hint(sonraki komut) döner; kod listesiempuno 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ıtcreated.payroll_profile {action: versioned | reopened | updated | unchanged | missing}; yetki yoksarejected+flash.rule: payroll_permission_required; kutu işaretsizken profil kapanmışsapayroll_profile_closeduyarısı); işyeri düzeltme (tarihsiz) →employees.update --sgk_workplace_idya dasgk-workplaces.assign --mode correct; tarihli nakil →employees.employments.transferya dasgk-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_namezorunlu. - Kıdem: güncel sözleşme zinciri hep sayılır. Önceki zincir: elle karar (
counts_for_severance) > kıdemi ödenmiş (severance_paidya 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önemseverance_prior_unknown_exittercihine göre (vars. hariç +severance_decision_neededuyarısı). Ayrıntıemployees.employments.index→timeline.severance.periods[](her dönem için sayılır/sayılmaz + gerekçe) veemployees.exit-settlement.show→preview.service. Kıdem değerlendirmesi, ihbar, kıdem ödemeleri ve karar notlarıpayroll.viewister — yoksa okumada yer almaz (timeline.severance_hidden: true);severance_paid*/counts_for_severanceyazmakpayroll.manageister (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_dateitibarıyla kalan gün; sonraki yıldönümleri eklenir,as_of_datesonrası 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_staleuyarı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) vedefault_law_noyalnız ipucudur: Ar-Ge kapsamı bordro profilinden, kanun no beyan kurallarından gelir; teknopark işyerine nakilderd_profile_hintuyarı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 dilimdesgk_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 — farktransfer_february_completiontercihine göre sonraki (vars., TÜRMOB 06.03.2024/60-1) ya da önceki işyerine.slip.sgk_day_countaylı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ıtworkplace.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_unmatchedbilgisi) > ç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ı vesummary.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_workplaceiş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ışandasgk_segmentsboş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ış listesisgkExitCodes16 içermez.employees.index --sgk_workplace_id <id>süzer, satırdasgk_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_runetkilerini 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 profilindeserviceö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.
# 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_noyanlış girilmiş numarayı DÜZELTİR (geçmişe yazılmaz, geçmiş APHB'ler de yeni numarayla görünür). SGK yeni numara verdiysesgk-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 isesamples[]'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 numaraylasgk-workplaces.storeyeni işyeri açmaz (registration_is_former).migrate employmentsbilinmeyen 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).
# 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 41Puantaj 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ğindeconflicts_reviewed=true. Kaynağıleave_records/pdksyaparsanı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: 0ya damissing_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_entryuyarı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ı durumattendance_days_not_in_entry/attendance_hours_not_in_entryuyarısıdır;preview.days_in_entry/hours_in_entryhangisinin 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_hoursnormal iş günü saatidir — FM, HT ve UBGT HARİÇ;*_daysile*_hoursbirlikte 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_differsuyarı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ınsick_leave_paytercihine göre. "0", "İzin" gibi belirsiz hücre ve tanımadığımız kısaltma tanınmaz: parseunknown_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ırinvalid_missing_day_reasonile 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 vegrid_field_ignoreduyarısı döner (PATCH dahil) — günün kodunu değiştirin. Özettesgk_daysverilirse kazanır (sgk_days_differsuyarısı). Fişteday_source(attendance | records) vehour_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, hintpayroll.reopen …); gelecek ayperiod_in_future, çalışanın istihdamda olmadığı ayoutside_employment. Aynı içerik tekrar gelirseskipped(duplicate: true);on_existing=updateyalnız gönderilen alanları yazar (daystü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 (yoksanight_hours_unpaiduyarısı). Yıllık 270 saat aşımıannual_overtime_limituyarı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_payersuyarısı).manualkaynaklı türde saat çalışan kaleminden (hours;payroll-items.bulkrecords[].hours). Serbest zaman kullanan çalışanda FM ödenmez.hourly-presetskanuni şablonları ekler (kodhourly_<kova>, tekrar güvenli: var olanskipped); gece için--multipliers.nightzorunlu. Ö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 saatipaid_rest_hours(ızgarada HT/RT günü × haftalık saat / 6; saat PDKS'ten gelse de puantajdan eklenir). Puantajda normal saat yoksa (worked_hoursboş, 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_daysuyarısı (aktarımdahourly_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ılanstatutory_additional'da toplam kanuni 2,5× / 2,0×;rest_day_work_pay=parameter_set'te 3,0× / 3,5× olur →hourly_rest_day_stackinguyarı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_contractuyarı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ındaon_call_floor_hours). Kısmi süreliye fazla çalışma yaptırılamaz →part_time_overtimeuyarı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_monthtercihine göre (varsayılan tam ay — GVGT 319). 30 günden eksik bildirimde çalışanın GSS tamamlaması hesaplanmaz. - Doğrulama:
payroll.simulateattendance.{sgk_days, missing_breakdown, missing_day_reason, worked_hours, paid_rest_hours},profile.{work_schedule, weekly_hours}veovertime.{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 1iz 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ındaattendance.warnings[](hesaplamanınattention[]satırlarındacode). 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).
# 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_setBordro 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).
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
# 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_idvermedenwork_advanceseç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ırkendata-migration.advances.commitsatırındainstallments[](period,amount,source).
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=supportolanlar dönem hesabında işe giriş sırasıyla Ar-Ge + tasarım personeli sayısının %10'u (yukarı yuvarlanır; tercihrd_support_personnel_ratio20) 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.
# 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:
applyvarsayılan olarakproposedyazar; motor yalnızactiveatamayı uygular. Teyit gerektiren kanunlar (02828, 26322, 55225/25225, 16322/25510) otomatik önerilmez, aktif atamadaincentive_confirm_requireduyarısı döner. Ön uygunlukta uygun olmayan satırforce=trueolmadanfailed(incentive_ineligible/incentive_window_ended). - Ret kodları (422,
flash.rule/ satırdacode):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_monthsay uygulanır, süresi dolan fişteincentive_duration_endeduyarı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 falsefirmada 5510'u kapatır (kanun 00000).payroll-settings.updatekısmidir: gönderilmeyen alan (5510 dahil) korunur; 5510 ya da sektör değişirse yanıttaeffects+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_metuyarısı verir (tutar değişmez; müşavirle teyit edin). - Bordro profilindeki eski alan
active_incentive_codenormalize edilir (6111 → 06111), katalogda yoksa 422; atanabilir kanun çalışanın atamalarınalegacy_profilekaynağıyla yansır ve yansıma TEK KAYNAKTIR: satırı reddetmek / silmek / sonlandırmak teşviki durdurur (fiştelegacy_incentive_closeduyarısı), kodu değiştirmeden profili kaydetmek satırı yeniden açmaz. Yeniden uygulamak:employees.incentives.update … --status active. Yeni kayıt içinemployees.incentives.storekullanın. - Asgari ücret desteği (
reference minimum_wage_support): tercihminimum_wage_supportoff (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ımsummary.employer_supports.minimum_wage_support.by_workplace(+--sgk_workplace_idfiltresinde 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.simulateincentives[]{law_no, start_date, duration_months},apply_5510,options.minimum_wage_supportalır; ay satırındaemployer_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.
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 autoBES 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ı 422pension_opt_out_deadline_passed(hint:leave_systemya dapause); 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.manageyetkilileri uygulama içi bildirim alır, e-posta gitmez. Aynı talep tekrarlanırsa yazılmaz. - İşveren katkısı: tercih
bes_employer_contributionwage (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_orderbefore_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);overduebayrağı. 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 kesintisisource_type=App\Models\EmployeePensionEnrollment, işveren katkısı kazancıbes_employer_contribution+ karşı kesintipension_employer_passthrough, işverene kalan Ar-Ge vergi teşvikird_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.
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ı listesiSGK (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=noneya 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,infosatırıpayment_type_tax_mismatchmüşavirin beyanını kontrol etmenizi söyler; set yoksa GV ve DV 0 ise 011. Farklıysatax_payment_typeverin. 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 verd_days_conflictuyarı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=noneher 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_reasonekleyin. - 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önemdesummary.source_coveragehangi 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 öncepayroll.reopen). Elle düzeltme yeniden hesaplamada korunur. Yanıtupdated {type: payroll_slip, id, fields}; değişiklik yoksafieldsboş. Fiş detayı (payroll.employee-slip) aynı değerlerideclarationaltı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: nedenipayroll.declaration.updateya da--update_fields declarationile 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)veworkplace_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_idfiltresi vesummary.by_workplaceiç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.
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 --validateRaporlar: 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.
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.
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.
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_usedhangi 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
integritybloğ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=falseikencan_post=false;payroll.accounting-postings.store422voucher_integritydöner, bilerek işaretlemek için--accept_integrity_issues true. Kaynağı düzeltin: aktarılan fişte her ek kesintideductions[]satırıyla, işverende kalan Ar-Ge terkinitype: rd_retainedile 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}.01ile 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) veimport_deduction_classifieduyarısı döner — yanlışsaimport_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=trueve tahakkuk tekrarı 422already_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_centergörünen ad,cost_center_keykararlı 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_currentuyarı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ırdadepartment/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 kalanlarexcluded[].reason: iban_missing, iban_invalid (mod-97), iban_foreign, iban_duplicate (aynı IBAN birden çok kişide → hepsi), non_positive_net. Banka önayarındasame_bank_onlyaçıksa başka bankadakilerother_bank[]'a ayrılır (--include_other_banks trueya 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ış;--periodile 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 metnitext; IBAN, hesap no ve TCKN uzunluk korunarak*ile maskeli.--templatetaban,--definition/--paramsüstüne yazılır (editördeki taslak). Yan etkisiz; bilinmeyen alanunknown_fielduyarısı. - Önayarların doğruluğu:
halkbank_dto_ibanresmî 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.detectile şablona çevirin. - Üretim kuralları: önizleme her hesaplanmış dönemde; dosya yalnız onaylanmış/kesinleşmiş/ödenmiş dönemde (422
not_approved). Öncepayroll.bank-fileiletotals.amount'ı okuyup--confirm_totalgönderin (değiştiyse 422total_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ı.
# 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ı | Evet | Evet (doğrudan) | Hayır |
| Onaylandı | Evet | Önce iptal | Evet |
| Kesinleştirildi / Ödendi | Hayır — düzeltme için payroll.reopen | Hayır (resmî bordro, VUK md. 253) | Evet |
| İptal edildi | — (tekrar çağrı yan etkisiz) | Evet | Hayır |
| Aktarıldı (önceki sistemden) | Hayır | Hayır | Statüsüne göre |
| Düzeltmeye açılmış (revision_count > 0) | Hayır — yeniden hesaplayıp kesinleştirin | Hayır | Hayı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.
reasonzorunlu (3–500). Zaten silinmişse yan etkisiz başarı (flash.deleted.already: true). - Silinemeyen dönemde 422
rejected+errors.period; makine kodupayroll.show/payroll.indexsatırındadeletion_blocker.code:imported|locked|revised. - Toplu silme satır bazlı
results[]döner (deleted|skipped+ engel metni |failed);dry_run: truehiç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_stepkomutu hazır verir. payroll.indexvarsayı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.storeyeni dönem açar. Durum değerleri:empuno reference payroll_period_statuses.
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.payile 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.
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ızperiod(YYYY-AA, 2021-01 … bugün+12 ay) +employee_idYA DAprofile.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, yoksanight_hours_unpaiduyarı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: falsegerç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[].actionwould_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 (sourcestored | reconstructed | imported).employee_ids[]alt küme,tolerance(TL, vars. 0,05). Not: CLI'nin genel--dry-runbayrağı isteği yerelde basar; sunucu alanıdry_run(alt çizgi) —--dry_run 1ya da--validatekullanı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 tercihird_tax_benefit = employeriken fişteki "Ar-Ge … işverene kalır" kesinti satırı (deductions[].type=rd_retainedya da adı Ar-Ge geçen, tutarı terkine eşit) girdiden çıkarılır — motor bu kesintiyi kendisi üretir. Kalan farklarhints[]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 1bunu 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 bordrodaexplain_summary(≤4 sade cümle) görür. - Yasal parametreler (
reference payroll_parameters,payroll.parametersaynı 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 tercihiminimum_wage_supportile 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çerlivalueve yıl içi değişen değerdeschedule[]— ö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) venot_modeled[](bölgesel ilave puan, kısmi sigorta alt grupları); kanun bazlı teşviklerreference 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 404parameters_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.simulatekomutunu 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.store422): geçmişidata-migration.payroll.commitile aktarın, doğrulamayıpayroll.simulatevepayroll.calculate --dry_run 1 --basis slipsile 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) vewarnings[]'teagi_status_assumeddöner — gerçeğiniagi.*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çinprofile.gross_salaryverin, kalıcı düzeltmeemployees.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_idsile 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 1yanıtındaoverrides[{field, label, value, engine_value}]olarak listelenir (iz motorun türettiğini gösterir, beyan ve yeniden hesap düzeltmeyi kullanır).
# 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 |
|---|---|
feature | Yeni özellik / geliştirme isteği |
bug | Beklenmeyen davranış, yanlış sonuç, 500 hatası |
criticism | Eleştiri, kullanılabilirlik, genel geri bildirim |
question | Nasıl yapılır / kural sorusu |
missing_command | Ajanın yapması gereken işlem katalogda yok (unknown_command yanıtındaki hint bunu önerir) |
docs | Dokü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).
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
| Durum | Yanı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çlar | Panel 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_adminkapsamı 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_requiredalır (deneme ve okumalar muaf). Kataloğunconventions.idempotency.required_for_this_keyalanı 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 trueile çalışanın Evraklarım bölümüne açılır (bildirim gider, toplu aktarımda--notify_employee falseile susturulur). - Geçmiş veri aktarımı:
data-migration.*komutları davet, e-posta ya da bildirim GÖNDERMEZ ve lisans tüketmez.data-migration.employees.commitayrılmış çalışanları çıkış bilgisiyle alır, TC ile eşler (--on_existing update) ve satır bazlıresultsdö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_requiredalır (yanıtta erişilebilircompanies[]). 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öreallowed+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 companiesher firmanıneffective_scopeslistesini verir. - Her yanıt firmasını söyler:
meta.company_id,meta.company_slugveX-Empuno-Company-Id/X-Empuno-Company-Slugbaş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 --companyveempuno companiesCLI 1.6.0 ile gelir (npm i -g empuno@latest;empuno version). 1.5.0--companydeğerini göndermez — grup anahtarıyla eski CLI her panel komutundacompany_requiredalı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övdeyle403 company_not_in_key. Erişim kalktıysa403 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ıcompanyyalnız--jsongö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şikliklericompany_adminkapsamı ister.
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_typesplatform 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ümsections[].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_affecteddö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 sizingroup.viewyetkinizin olduğu grup firmaları gelir; firma başınaheadcount(employees.view),cost(payroll.view: son onaylı / kesinleşmiş / ödenmiş dönem ya da--periodayı; 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};totalsyalnız erişilebilir bloklardan,complete=falseise kısmi.warnings:period_mismatch(son dönemler farklı ay →--periodverin),cost_missing. GET yan etkisizdir (izin toplamı 10 dk önbelleklenir).--sections headcount,costile daraltılır;group.summary.exportaynı veriyi Excel olarak verir (Özet, Maliyet, Avanslar, İzin).
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 kaynaktapayroll.view+ hedeftepayroll.managevarsa kopyalanır (yoksawarnings[].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ıtdismissed, 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_payrollkalan 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 — öncecompany-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.protocoldevir protokolünü üretir (T.C. tam yalnız employees.manage'de), imzalı nüshagroup-transfers.consentile yüklenir → iki firmanın özlük dosyasınadevir_protokolu; kayıtconsent_status = received. - Yan etkiler: iki firmanın grup etkinliğine
employee_transferred/transfer_linked/consent_received;documents ≠ noneise 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)"; önizlemedeleave.accountant_reports[], sonuçtaaccountant_corrections {planned, sent, failed},--notify_accountants falsekapatır.--dry-runhepsini geri alır: id'lernull, 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: trueile mevcut kayıt döner. Geçmiş nakil bağlamada aynı çiftskipped. - 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ırdakirecordolduğu gibi gönderilir). Bağlama kayıt oluşturmaz: hedefe kaynak dönemleri (boşluksuzsa devam zinciri, boşluk varsalink_gapuyarı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,--reasonzorunlu,--dry-rundestekli, 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 falsekapatır). Hedef firmadan geri alınıp hedef kayıt silindiyse yanıttaredirect_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 firmayatransfer_reverted. Koşullargroup-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;activitysayı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— öncepayroll.reopen),revert_source_changed,revert_target_changed,revert_source_license_full,revert_manual_required. Koşul sağlanmıyorsa doğru yol hedefteemployees.terminate+ kaynaktaemployees.rehire. Devredilmiş çalışanıemployees.reactivateile 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).
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).
| HTTP | error | Anlamı | Ne yapmalı |
|---|---|---|---|
| 401 | unauthenticated | Anahtar yok, geçersiz, süresi dolmuş ya da iptal edilmiş. | Firma Ayarları → API & Ajan sekmesinden yeni anahtar oluşturun. |
| 401 | key_owner_inactive | Anahtarı oluşturan kişi artık aktif değil. | Aktif bir yöneticiyle yeni anahtar oluşturun. |
| 403 | read_only_key | Salt-okuma entegrasyon anahtarı panel komutlarını çalıştıramaz. | "Ajan" türünde anahtar oluşturun. |
| 403 | company_inactive | Anahtarı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. |
| 403 | scope_required | Komut company_admin kapsamı istiyor (required_scope). | Anahtar sahibi kapsamı panelden genişletir. |
| 403 | forbidden | Modül yetkisi yok; gereken izin required_permission alanında. | Anahtar kapsamına ve sahibinin yetkisine ilgili izni ekletin. |
| 403 | legal_consent_required | Anahtar 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. |
| 403 | email_verification_required | Anahtar 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. |
| 404 | unknown_command | Uç bir ajan komutu değil (ya da ajana kapalı). | empuno commands ile doğru komutu bulun; yoksa talep açın. |
| 404 | not_found | Kayıt bulunamadı ya da bu firmaya ait değil. | Kimliği liste komutuyla doğrulayın. |
| 404 | no_receipt | Masrafın fiş görseli yok (/api/company/v1 masraf fişi indirme). | Masraf kaydı geçerli; görsel yüklenmemiş. Tekrar denemeyin. |
| 405 | method_not_allowed | Komut bu HTTP metoduyla çağrılamaz. | Katalogdaki method alanını kullanın. |
| 409 | conflict | İşlem kaydın mevcut durumuyla çelişiyor. | Kaydın güncel durumunu okuyup yeniden deneyin. |
| 422 | validation_failed | Eksik/yanlış alan; ayrıntı errors alanında. | errors alanındaki alanları düzeltip yeniden gönderin. |
| 422 | rejected | İş kuralı reddi (message) ya da doğrulama hatası (errors). | Mesajdaki kuralı giderin; deneme için --validate kullanın. |
| 429 | rate_limited | Hız sınırı aşıldı. | Retry-After saniye bekleyin. |
| 429 | insufficient_ai_credits | Firmanı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 …). |
| 500 | server_error | Sunucu 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. |
| 422 | dry_run_unsupported | Komut 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. |
| 500 | dry_run_failed | Deneme 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. |
| 400 | idempotency_key_required | Bu anahtar için her yazmada Idempotency-Key zorunlu (deneme hariç). | Idempotency-Key başlığı ya da client_request_id alanı ekleyin (CLI: --idempotency-key). |
| 400 | idempotency_key_invalid | Tekrar anahtarı boş, 120 karakterden uzun ya da başlık ile gövde değeri farklı. | Tek bir geçerli anahtar gönderin. |
| 409 | idempotency_in_progress | Aynı 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. |
| 409 | idempotency_replay_unavailable | Bu 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. |
| 422 | idempotency_key_reused | Anahtar 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ı. |
| 409 | ambiguous_period | YYYY-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. |
| 422 | parameters_missing | Tarih 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. |
| 422 | migration_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). |
| 400 | company_required | Grup 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). |
| 403 | company_mismatch | Tek 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). |
| 403 | company_access_revoked | Grup 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. |
| 403 | company_not_in_key | Firma 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). |
| 403 | company_not_in_group | Hedef 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. |
| 403 | no_account_there | Hedef firmada aynı e-posta ve aynı şifreyle aktif bir hesabınız yok. | Hedef firmanın yöneticisinden sizi aynı e-postayla eklemesini isteyin. |
| 403 | permission_there | Hedef 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.rule | Anlamı | Ne yapmalı |
|---|---|---|
overlap | Dönemler çakışıyor (aynı günler iki dönemde). | Tarihleri düzeltin; employees.employments.index ile mevcut dönemleri okuyun. |
open_not_last | Yalnı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_terminated | Ayrı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_row | Aktif ç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_terminate | Açık (güncel) döneme çıkış bu uçla girilmez. | employees.terminate kullanın (hesap kapatma, bekleyen talepler, çıkış ödemesi). |
use_reactivate | Son dönemin çıkışı bu uçla silinemez. | Hatalı çıkış: employees.reactivate; yeni sözleşme: employees.rehire. |
termination_required | Son dönemden önceki dönem kapalı olmalı. | termination_date gönderin. |
contract_start_row | Güncel sözleşmenin başlangıç dönemi silinemez. | Tarihini employees.employments.update ile düzeltin. |
open_row | Açık (güncel) dönem silinemez. | Çıkış: employees.terminate; tarih düzeltme: employees.employments.update. |
hire_date_required | Dönemin giriş tarihi zorunlu. | hire_date gönderin (YYYY-AA-GG). |
hire_in_future | Giriş 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_code | Geçersiz SGK çıkış kodu. | empuno reference sgk_exit_codes. |
invalid_kind | Geçersiz dönem türü. | kind: employment | prior_service (empuno reference employment_kinds). |
invalid_insurance_group | Geç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_active | Ayrı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_terminated | Yalnı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_exit | Yeniden giriş tarihi son çıkıştan sonra olmalı. | hire_date'i son çıkış + 1 gün ya da sonrası yapın. |
license_full | Lisans dolu; yeniden işe alım yapılamaz. | Lisansı yükseltin ya da başka bir çalışanı pasifleştirin. |
payroll_permission_required | Bordro 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_foreign | SGK işyeri bulunamadı ya da bu firmaya ait değil. | empuno reference sgk_workplaces (id, 26 haneli sicil ya da ad). |
workplace_closed | SGK 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_taken | Bu sicil numarası firmada başka bir işyerinde kayıtlı. | Mevcut işyerini kullanın (empuno reference sgk_workplaces). |
invalid_registration_no | SGK 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_registration | Yeni numara güncel numarayla aynı. | Farklı bir numara gönderin. |
date_too_far | Sicil 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_order | Değ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_current | Numara işyerinin güncel numarası; geçmişe eklenemez. | Numara değiştiyse sgk-workplaces.change-registration kullanın. |
registration_range_invalid | Eski numaranın başlangıcı bitişinden sonra. | valid_from ≤ valid_until gönderin. |
registration_ranges_overlap | Sicil 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_self | Hedef işyeri kaynak listesinde. | Kaynakları (source_ids) hedeften ayrı verin. |
merge_range_unknown | Birleş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_latest | Hedef 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_no | Kanun numarası 4–5 haneli rakam olmalı. | empuno reference incentive_codes. |
invalid_zone_type | Geç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_future | Devreden izin tarihi bugünden ileri olamaz. | Bugün ya da geçmiş bir tarih gönderin. |
as_of_before_contract | Devreden 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_exit | Devreden 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_law | Kanun 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_assignable | Bu 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_expired | Kanunun 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_invalid | Tarih 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_terminated | Ayrı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_invalid | Teşvik bilgisi anahtarı ya da değeri geçersiz. | empuno reference incentive_fact_keys (anahtar, tür, seçenekler). |
pension_no_active_plan | Firmada aktif BES planı yok. | pension.plans.store ile emeklilik şirketi sözleşmesini (şirket + sözleşme no) ekleyin. |
pension_plan_foreign | BES 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_terminated | Ayrı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_request | 45 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_citizen | Yabancı 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_group | Sigorta grubu otomatik katılım kapsamında değil (sigortasız). | Bordro profilinde sigorta grubunu kontrol edin. |
pension_opt_out_deadline_passed | Cayma 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_out | Baş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_action | Bu işlem kaydın bugünkü durumunda yapılamaz. | employees.pension.show ile durumu okuyun (reference pension_actions). |
pension_rate_below_legal | Katkı oranı yasal oranın (%3) altına inemez. | rate en az 3 olmalı. |
pension_rate_above_max | Katkı oranı izin verilen üst sınırı aşıyor. | Daha düşük bir oran gönderin. |
pension_date_invalid | Tarih geçersiz (dahil olmadan önce ya da ara verme bitişi başlangıçtan önce). | effective_date / until değerlerini düzeltin. |
period_not_calculated | Dönem hesaplanmamış (taslak) ya da iptal edilmiş; fiş ve ödeme dosyası çıkmaz. | Önce payroll.calculate; iptal edilmiş dönemde çıktı yok. |
period_not_finalized | Muhasebeleştirme için dönem kesinleşmiş ya da ödenmiş olmalı. | payroll.finalize; taslak fişi payroll.accounting-voucher ile yine indirebilirsiniz. |
already_posted | Dö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_posting | Düzeltme fişi için önce tahakkuk fişi muhasebeleştirilmiş olmalı. | payroll.accounting-postings.store --kind accrual. |
nothing_to_correct | Muhasebeleştirilmiş tutarlarla güncel bordro arasında fark yok. | Düzeltme fişi gerekmiyor. |
empty_voucher | Fişte satır yok (dönemde fiş ya da ödenecek net yok). | payroll.show ile dönemin fişlerini kontrol edin. |
voucher_unbalanced | Fiş dengesiz (borç ≠ alacak); muhasebeleştirilemez. | payroll.accounting-voucher uyarılarını inceleyin. |
voucher_integrity | Fiş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_found | Dosya ş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_taken | Bu 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_code | Banka 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_unreadable | Dosya okunamadı. | xlsx, xls, csv ya da txt yükleyin (en çok 5 MB). |
not_approved | Banka ö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_changed | Toplam 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_rows | Dosyaya 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_found | Kapanmış 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_group | Firma 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_group | Firma bir gruba üye değil. | group.index ile grubu ve üyeleri görün; grup yoksa group.store ile oluşturun. |
not_manager_there | Eklenmek 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_invite | Davet 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_foreign | Davet kodu bu firmanın grubuna ait değil. | group.index invites[] listesindeki kimliği kullanın. |
group_name_required | Grup adı gerekli. | name gönderin (en çok 120 karakter). |
same_company | Kaynak ve hedef firma aynı. | Başka bir grup firması seçin. |
company_not_found | Firma bulunamadı (id ya da slug). | group.index members[] ya da empuno companies ile firma kimliğini doğrulayın. |
employee_not_active | Yalnı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_transfer | Kendi çalışan kaydınızı nakledemezsiniz. | Naklinizi başka bir yönetici yapsın. |
last_admin | Firmanın son yöneticisi nakledilemez (en az bir yönetici kalmalı). | Önce başka bir kullanıcıyı yönetici yapın. |
transfer_date_invalid | Nakil 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_invalid | Geç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_employer | Kod 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_active | Hedef 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_taken | Hedef 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_deleted | Hedef 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_full | Hedef 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_foreign | Departman 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_conflict | Devralı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_active | Bağ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_invalid | Hedefteki işe giriş, kaynaktaki çıkıştan sonra olmalı. | Tarihleri kontrol edin (employees.termination.update / employees.employments.update). |
link_target_not_active | Bağlanacak hedef çalışan aktif değil. | Hedefte çalışan ayrıldıysa bağlama anlamsız; tarihleri kontrol edin. |
transfer_not_completed | Nakil kaydı tamamlanmış durumda değil (geri alınmış). | group-transfers.index ile güncel kayıtları görün. |
revert_source_changed | Kaynak ç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_changed | Hedef ç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_activity | Hedef 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_closed | Kaynak 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_full | Kaynak 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_required | Hedefte 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
Avans talepleri — Onayla
deduction_period
Avans talepleri — Oluşturma formu verisi
Avans talepleri — generate contract
employee_tc
employee_position
company_address
amount_text
additional_terms
Avans talepleri — Listele
Avansa bordro dışı tahsilat kaydeder (banka, nakit, çıkış ödemesinden mahsup, vazgeçme).
amount
paid_on
source
reference
notes
period
Avans talepleri — Reddet
rejection_reason
Avans talepleri — Ayarlar
Avans ayarları — Güncelle
advance_enabled
advance_max_active_count
advance_limit_type
advance_limit_percentage
advance_limit_amount
advance_max_installments
Avans talepleri — Detay
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
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
AI Chat
message
context
Analyze CV
cv_file
requirements
Generate document
template
data
Generate email draft
type
data
Generate company description with AI
company_name
user_input
industry
address
employee_count
founding_year
website
Generate job posting with AI
details
Analyze image
image
purpose
AI Dashboard
id
type
prompt
response
model
cost
created_at
user
Suggest leave approval
Get available AI models
Generate performance insights
Yönetici-özel (yetki devri, mali müşavirler) company_admin
16 komut
Mali Müşavirler — Sil
Bir mali müşavir için ayrıntılı rapor geçmişi (JSON, detail dialog için).
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
Mali müşavir daveti — İptal et
Mali müşavir daveti — Yeniden gönder
Mali Müşavirler — Oluştur
email
first_name
last_name
Mali Müşavirler — Aktif/pasif yap
Yetki devri — Düzenleme formu verisi
Yetki devri — Güncelle
Yöneticisi olduğunuz başka bir firmayı gruba doğrudan ekler (davet kodu gerekmez).
target_company
Kullanılmamış bir davet kodunu iptal eder.
Gruba katılım için tek kullanımlık davet kodu üretir (ham kod YALNIZ bu yanıtta döner).
expires_in_days
Davet koduyla bu firmayı bir gruba katar.
code
Bu firmayı gruptan çıkarır (her zaman serbest).
reason
Yeni grup şirketleri grubu oluşturur; bu firma ilk üye olur.
name
Grubun adını değiştirir.
name
Şirket Kartları company_cards
5 komut
Şirket kartları — Sil
Şirket kartları — Listele
id
cardholder_user_id
cardholder_name
cardholder_email
last_four
card_type
bank_name
label
is_active
display_name
created_at
Şirket kartları — Oluştur
cardholder_user_id
last_four
card_type
bank_name
label
is_active
Şirket kartları — Aç/kapat
Şirket kartları — Güncelle
cardholder_user_id
last_four
card_type
bank_name
label
is_active
Firma Ayarları company_profile
6 komut
Firma ayarları — cities
Firma ayarları — delete logo
Firma ayarları — districts
Firma ayarları — generate with ai
description
Firma ayarları — Listele
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 for AJAX (for employee forms)
id
name
city
Show the form for creating a new resource.
Remove the specified resource from storage.
Show the form for editing the specified resource.
Display a listing of the resource.
Display the specified resource.
Store a newly created resource in storage.
name
code
address
city
phone
email
manager_name
is_active
Toggle branch active status
Update the specified resource in storage.
name
code
address
city
phone
email
manager_name
is_active
Departmanlar — Oluşturma formu verisi
Departmanlar — Sil
Departmanlar — Düzenleme formu verisi
Departmanlar — Listele
Departmanlar — Detay
Departmanlar — Oluştur
name
description
manager_name
Departmanlar — Güncelle
name
description
manager_name
Kurumsal Evrak Deposu corporate_documents
6 komut
Kurumsal evraklar — Sil
Kurumsal evraklar — Listele
Kurumsal evraklar — Detay
Analizi devam eden kayıtların güncel durumu (liste ekranı yokluyor).
Yükleme — SADECE dosya.
file
Yapay zekanın çıkardığı künyeyi yönetici düzeltebilir.
document_type
title
notes
issued_date
expires_at
Yönetim özeti dashboard
1 komut
Yönetim özeti (dashboard)
Veri Göçü (Eski Sistem) data_migration
17 komut
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
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
Çalışan aktarım ekranı verisi (AI kredi bakiyesi). Ajan doğrudan data-migration.employees.parse / commit kullanır.
Ç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
Eski sistemden çalışan listesini AI ile ayrıştır (KAYDETMEZ; sonucu commit'e verin).
Ç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
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
Dosyadan aktarım ekranı (yönetici): eski sistemin Excel/CSV dışa aktarımı → önizleme →
Excel/CSV dosyasını aktarım kayıtlarına çevirir (yazmaz): kind = employees | leaves | advances |
kind
file
period
code_map
code_map.*
format
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
Veri göçü ana ekranı: AI kredi bakiyesi (aktarım türleri ve komutları: rehber #gecis, `empuno migrate <tür>`).
İzin geçmişi aktarım ekranı verisi (AI kredi bakiyesi). Ajan doğrudan data-migration.leaves.parse / commit kullanır.
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
Bir çalışanın eski izin geçmişini AI ile ayrıştır (KAYDETMEZ; sonucu leaves.commit'e verin).
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
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
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
Kesinti raporu ayarlarını upsert eder (aylık anchor günü + aktiflik).
monthly_day
is_active
PDF'i force-download ile indirir.
Excel'i force-download ile indirir.
Manuel rapor üretimi. Önceki tam ayı (anchor güne göre) hesaplar ve
Geçmiş kesinti raporları + ayar kartı. Tek truth source olarak
PDF'i tarayıcıda inline olarak gösterir (önizleme için).
Mevcut raporu mali müşavirlere yeniden gönderir.
Personel Evrakları documents
7 komut
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
Zorunlu evrak politikası: aşama başına zorunlu kalemler (required), kaynak (default | company) ve tüm kalemler (catalog).
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.*
Çalışan evrağını sil. documents.manage gerektirir.
Çalışan evrağını tarayıcıda göster. documents.view yeterli.
Ç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
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 available employees for equipment assignment
id
full_name
department
branch
equipment_count
Çalışanlar — Oluşturma formu verisi
Düzenleme formu verisi (yalnız aktif/pasif çalışan; ayrılmışta profile yönlendirir).
Çalışma dönemini siler (geri alınabilir kayıt silme) — dry_run destekler.
reason
dry_run
Çalışanın çalışma dönemleri, SGK işyeri ve kıdem/izin/ihbar süresi özeti — yan etkisiz.
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
Ş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
Ç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
Grup şirketine nakil önizlemesi (yan etkisiz): engeller, uyarılar, hedefte departman/şube eşlemesi, kalan izin,
Çalışanı grup şirketine naklen devreder (TBK 429; kıdem ve izin kesintisiz).
Çalışanları listeler — filtreler: search (ad/e-posta/sicil no), department, status (vars. active,inactive; terminated | all), sgk_workplace_id, per_page.
Get detailed leave balance for an employee (JSON endpoint for modal)
Export employee leave balance report to Excel
Çalışan detayı — kişisel/iş bilgileri, izin bakiyeleri, zimmet, belgeler; çalışma dönemleri ve SGK işyeri dahil (yan etkisiz).
Çalışanlar — Yeniden aktifleştir
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
Kabul edilmemiş çalışan davetini yeniden gönderir (token + süre yenilenir).
Çalışan detayı — kişisel/iş bilgileri, izin bakiyeleri, zimmet, belgeler; çalışma dönemleri ve SGK işyeri dahil (yan etkisiz).
Ç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
İş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
Ayrılmış çalışanın çıkış bilgisini düzelt (tarih, gerekçe, SGK çıkış kodu).
termination_date
termination_reason
sgk_exit_code
Ç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
Olası geçmiş nakiller (sistem bulur): erişilebilir grup firmaları arasında aynı T.C.'li "bir firmada ayrılmış +
İ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
Grup içi nakiller (bu firmadan giden ve bu firmaya gelen): yön (direction in | out), durum (completed |
direction
status
mode
consent
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
Devir protokolü PDF'i (TBK 429; devreden, devralan ve işçi imzası için). T.C. kimlik no employees.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
Nakil kaydının ayrıntısı (yalnız bu firmanın kaynak ya da hedef olduğu kayıt; yan etkisiz). `revert` alanı
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
İmzalı zimmet/iade formunu sil. equipment.manage gerektirir.
İmzalı zimmet/iade formunu tarayıcıda göster. equipment.view yeterli.
İmzalı zimmet/iade formu yükle (PDF veya görsel(ler)). equipment.manage gerektirir.
document_type
file
images
images.*
notes
Zimmetler — Listele
Zimmetler — PDF indir
Generate return receipt PDF for a returned equipment assignment
Foto'lari S3'e yukle + AI analiz et + sonuclari don.
photos
photos.*
Ekipmanlar — Ata
employee_id
assigned_date
assignment_notes
delivery_photo
Ekipmanlar — Oluşturma formu verisi
Ekipmanlar — Sil
Ekipmanlar — Düzenleme formu verisi
Ekipmanlar — Listele
Fatura dosyasını sil. Fatura no + KDV alanları temizlenir; alış fiyatı ve
Fatura PDF/görselini görüntüle (S3 geçici URL'ine yönlendirir).
Fatura yükle + AI ile fatura bilgilerini (fatura no, tarih, tutar, KDV)
invoice
Tek ekipman için etiket sayfası — labels route'una redirect.
Birden çok ekipman için A4 yazdırılabilir etiket sayfası.
Bakım kaydını sil (varsa fatura dosyasını S3'ten temizle, kaydı soft-delete et).
Bakım faturasını görüntüle (S3 geçici URL'ine yönlendirir).
Bakım kaydını elle ekle (fatura/AI olmadan).
maintenance_type
vendor_name
description
maintenance_date
amount
currency
vat_rate
vat_amount
invoice_number
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
Bakım faturası yükle + AI ile firma adı, tutar, KDV, tarih ve bakım tipini
invoice
Ekipman notları — Sil
Menajer notu ekle. is_visible_to_employee=true ise ekipmanı zimmetinde
note
is_visible_to_employee
Ekipman notları — Güncelle
note
is_visible_to_employee
Ekipman fotoğrafları — Sil
Ekipman fotoğrafları — primary
Ekipman fotoğrafları — reorder
ids
ids.*
Var olan ekipmana foto ekle. analyze=true ise her foto 1 AI kredisi harcar ve
photos
photos.*
analyze
Satış faturası dosyasını sil. Fatura no + KDV temizlenir; sold_at ve
Satış faturası PDF/görselini görüntüle (S3 geçici URL'ine yönlendirir).
Satış faturası yükle + AI ile (SATIS_FATURA_ANALIZ_ASISTANI) fatura no,
invoice
Ekipmanlar — Detay
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.*
Ekipmanlar — unassign
returned_date
return_notes
Ekipmanlar — Güncelle
name
description
serial_number
brand
model
category
purchase_price
currency
purchase_date
condition
status
notes
Ekipmanlar — update status
status
Masraf Raporları expense_reports
7 komut
PDF'i force-download ile indirir.
Paketin TEK Excel dosyasını indirir. excel_path paketteki üç satıra da aynı
Geçmiş raporlar sayfası. Tek truth source: hem manager hem mali müşavir
PDF'i tarayıcıda inline olarak gösterir (önizleme için).
"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
"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
Seçili fişlerden ephemeral PDF üretir, tarayıcıda inline gösterir.
Masraf Yönetimi expenses
26 komut
Masraf kategorileri — Sil
Masraf kategorileri — Listele
Masraf kategorileri — seed defaults
Masraf kategorileri — Oluştur
name
description
max_amount
requires_receipt
Masraf kategorileri — Güncelle
name
description
max_amount
requires_receipt
is_active
Masraf raporu ayarlarını upsert eder.
period_type
weekly_day
monthly_day
is_active
Manuel rapor üretimi. Body:
period_type
period
start_date
end_date
exclude_already_sent
Mevcut raporu mali müşavirlere yeniden gönderir.
Masraflar — Onayla
Seçili masrafları toplu olarak muhasebeye işlendi işaretler.
ids
ids.*
Masraflar — Sil
Masraflar — Listele
Onaylı masrafı çalışana ödendi (iade edildi) olarak işaretler. İsteğe bağlı: reimbursement_method
reimbursement_method
reimbursement_reference
paid_at
Masrafı "Muhasebeye İşlendi" olarak işaretler (tekil).
Masraflar — Reddet
rejected_reason
Masraflar — Detay
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
"Muhasebeye İşlendi" işaretini geri alır.
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
Masrafı iş avansına bağlar (work_advance_id) ya da bağı kaldırır (null). Bağlı ve onaylı masraf
work_advance_id
İş avansını iptal eder (yanlış açıldıysa; bağlı masraf yoksa).
İş avansı listesi + bakiyeler. Filtre: status (open | closed | cancelled), employee_id, per_page.
Hareket kaydeder: type = refund (çalışan kalanı iade etti) | payout (harcama avansı aştı, şirket
type
amount
occurred_on
method
reference
notes
İş avansı detayı: bakiye, bağlı masraflar, iade/fark ödemesi hareketleri.
Ç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
İş 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
İcra/haciz/nafaka belgesini AI ile analiz et ve form alanlarını döndür
document
employee_id
→ İptal.
Yeni haciz/nafaka oluşturma formu.
Soft delete.
Haciz/nafaka düzenleme formu.
Seçilen çalışanın aylık net ücreti + kesinti tipine göre yasal aylık üst
employee_id
Haciz/icra/nafaka kayıtlarını listele (firma bazlı).
Durduruldu → Aktif.
Haciz/nafaka detayı + geçmiş bordro kesintileri.
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
Aktif → Durduruldu.
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
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
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
Grup firmalarının personel maliyeti, açık avansları ve yıllık izin bakiyelerini firma başına ve toplam olarak gösterir.
Grup Özeti Excel'i (sayfalar: Özet, Maliyet, Avanslar, İzin) — group.summary ile aynı süzgeç ve yetkiler.
Kimlik Belgeleri identity_documents
5 komut
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
Kimlik belgesini sil. identity_documents.manage gerektirir.
Çalışanın kimlik belgeleri: tür, sayfa, yükleyen, AI'nın çıkardığı alanlar (extracted_data). Yan etkisiz.
Kimlik belgesi PDF'ini tarayıcıda göster. identity_documents.view yeterli.
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
İlan analitiği sekmesi.
İş başvurusu — detail
Aday CV'sini indirir.
İş başvurusu — update status
status
notes
İ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
Seçilen başvurulara toplu durum değişikliği + bilgilendirme e-postası.
all
application_ids
application_ids.*
action
Başvuruların Excel/PDF dışa aktarımı — ekrandaki filtre ve sıralamayı
"Bu filtrede kaç başvuru var" canlı sayacı — indirme düğmesinin yanında
E-postasını doğrulayıp başvurusunu tamamlamayanlara hatırlatma gönderir.
emails
emails.*
İş ilanları — cities
id
name
plate_code
İş ilanları — Oluşturma formu verisi
id
name
code
İş ilanları — Sil
İş ilanları — Düzenleme formu verisi
id
name
code
İş ilanları — generate with ai
details
İş ilanları — Listele
İş ilanları — Detay
İş ilanları — Oluştur
Ilan sahibinin kendi basvuru formunu aday gibi test etmesini saglar.
İş ilanları — Güncelle
İzin Raporları leave_reports
4 komut
PDF'i indirir.
Excel'i indirir. Paket satırlarında excel_path üçüne de aynı yazılır →
Gönderilmiş izin raporları arşivi (liste ekranı).
PDF'i tarayıcıda inline gösterir.
İzin Yönetimi leaves
28 komut
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
Ç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
Manuel rapor üretimi. Varsayılan: geçen ay (kapanmış son takvim ayı).
period
start_date
end_date
Arşivdeki raporu alıcılara (mali müşavir + yönetici) yeniden gönderir.
İzin talepleri — Onayla
İzni siler (arşive taşır) — onaylı olsa bile. Satır soft-delete ile korunur
reason
notify_accountants
Silme diyaloğu için etki önizlemesi: izin, mali müşavire GÖNDERİLMİŞ hangi
İzin talebi belgesini tarayıcıda göster. leaves.view yeterli.
İzin talebine belge yükle (doğrudan PDF veya görsel(ler)). leaves.manage gerektirir.
file
images
images.*
notes
İzin talepleri sayfasındaki "İzinleri İndir" modalından dışa aktarım.
format
date_start
date_end
all_dates
statuses
statuses.*
"İzinleri İndir" modalında seçili filtrelerle KAÇ kaydın ineceğini gösteren
date_start
date_end
all_dates
statuses
statuses.*
İzin talepleri — Listele
id
name
color
Yöneticinin "yine de kabul et" override'ı: AI tarafından reddedilen/şüpheli
İzin talepleri — Reddet
rejection_reason
Arşivdeki izni geri alır.
Show leave request details for admin
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
Aktif izin türlerini getir (API - dropdown için)
Yeni özel izin türü oluşturma formu
İzin türleri — Sil
İzin türleri — Düzenleme formu verisi
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
Sistem izin türünü config varsayılan değerlerine sıfırla
Kural bayraklarını (yıllık bakiyeyi etkiler / belge zorunlu) güncelle.
affects_annual_balance
requires_document
document_type_key
İzin türleri — Detay
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
İzin türleri — Aktif/pasif yap
İ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
Zarf listesi (status=processed|failed, type, report, year; per_page ≤100): durum, hata, neye yansıdığı.
status
type
report
year
Başarısız zarfı sunucuda yeniden işletir (gönderici yeniden göndermeden; aynı işleyici). İşlenmiş zarfa dokunmaz
Tek zarf: durum, hata, işleyici sonucu, artifact listesi (içerik değil).
Luca Köprüsü özeti: zarf sayıları/durumları, her türün neye yansıdığı, personel aktarımı, parite, ekran kapsamı.
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
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
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
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
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
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
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
Çı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
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
Çalışanın teşvik bilgilerini günceller — yalnız gönderilen anahtarlar birleşir (null siler); dry_run destekler.
facts
dry_run
Teşvik atamasını siler (yumuşak) — kesinleşmiş fişlerin kanun kodu korunur; dry_run destekler.
dry_run
Çalışanın teşvik atamaları, ön uygunluğu ve teşvik bilgileri (yan etkisiz).
Ç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
Teşvik atamasını günceller — yalnız gönderilen alanlar (status, start_date, end_date, duration_months, certificate_no, notes).
Çalışan kalemini siler (geçmiş bordrolardaki satırlar korunur).
Çalışanın ek kazanç/kesinti kalemleri (yan etkisiz) + seçilebilir türler.
Ç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
Ç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
Çalışanın güncel bordro profili + sürüm geçmişi (history[]: effective_from/to, maaş). Yan etkisiz.
Ç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
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
Çalışanın BES kaydı, kapsam durumu, hareketleri ve kesinti geçmişi (yan etkisiz).
Ç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
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.
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
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
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
Muhasebe hesap planı eşlemesi: kalemler + varsayılan Tekdüzen hesabı + firma eşlemesi, departman/şube gider kökleri ve önerileri, fiş tercihleri.
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
Muhasebe fişi tercihlerini günceller (yalnız gönderilen anahtarlar).
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
Kesinti türünü kaldırır; kullanıldıysa pasife alınır.
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
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
Ek kazanç türünü kaldırır; bordroda ya da çalışan kaleminde kullanıldıysa pasife alınır.
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
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
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
Dosya şablonunu siler (geçmiş üretim kayıtları korunur; şablon adı kayıtta saklıdır).
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
Bordro dosya şablonları: önayarlar (banka + muhasebe fişi, doğrulama durumu ve kaynağıyla) ve firmanın şablonları (yan etkisiz).
kind
q
page
Dosya şablonunun canlı önizlemesi: son onaylı dönemin ilk satırları şablona göre biçimlenmiş; IBAN/TCKN maskeli (yan etkisiz, dosya üretmez).
Tek dosya şablonu: tam tanım, parametreler (IBAN maskeli), kopyalandığı önayar ve kullanım (yan etkisiz).
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
Dosya şablonunu günceller (yalnız gönderilen alanlar).
Ö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
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
Bordro ayarları sayfasını göster.
Firma bordro hesaplama tercihlerini günceller (yalnız gönderilen anahtarlar). Seçenekler ve
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
Muhasebeleştirme işaretini geri alır (muhasebe programındaki fişe dokunmaz).
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
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
Bordro dönemini onayla.
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
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.
Puantaj Excel'i (Puantaj ızgarası · Özet · Kodlar) — geri okunabilir; puantajı olmayan çalışan PDKS / izin / tatil takviminden ön doldurulur.
period
department_id
prefill
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
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
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ı,
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
Banka maaş ödeme dosyası önizlemesi: ödenecekler (IBAN maskeli), dışarıda kalanlar ve nedenleri, toplamlar, geçmiş dosyalar. Yan etkisiz.
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
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
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
Bordro dönemini hesaplar (taslak ya da hesaplanmış dönem; yeniden hesaplama fişleri yeniler).
dry_run
basis
employee_ids
employee_ids.*
tolerance
Bordro dönemini iptal eder (isteğe bağlı reason ≤500, denetime yazılır).
reason
Yeni bordro dönemi oluşturma formu.
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
SGK/MUHSGK mutabakat Excel'i (sayfalar: Özet, SGK (APHB), Vergi (MUHSGK), Bordro Detayı, Uyarılar). Firmada birden
sgk_workplace_id
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
İptal edilmiş ya da hiç onaylanmamış (taslak/hesaplanmış) bordro dönemini fişleriyle birlikte siler (soft delete + denetim kaydı).
reason
Ç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.
Bordro dönemini kesinleştir.
Bordro dönemlerini listeler (varsayılan: iptal edilmişler gizli).
status
year
archived
per_page
page
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
Bordro dönemini ödenmiş olarak işaretle.
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
BES kurum aktarım listesini Excel olarak indirir (plan başına sayfa, TCKN tam; ?plan_id ile tek plan) — yan etkisiz.
plan_id
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
Kesinleşmiş / ödenmiş dönemi düzeltmeye açar: reason (zorunlu, ör. "Ahmet'in fazla mesaisi eksik girilmiş").
reason
Silinmiş bordro dönemini fişleriyle geri alır.
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
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
Bordro simülatörü form verisi: çalışanlar (profil özeti), ek kazanç/kesinti türleri, hesaplama tercihleri, parametre setleri. Yan etkisiz.
Yeni bordro dönemi açar (year, month). Aynı ayın iptal edilmemiş dönemi varsa reddedilir; yalnız iptal
year
month
BES planları, katılımcılar ve son hareketler (yan etkisiz).
status
plan_id
q
page
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
BES planı ekler (emeklilik şirketi sözleşmesi) — dry_run destekler; e-posta yok.
BES planını günceller — yalnız gönderilen alanlar; is_active=false ile pasife alma, is_default ile varsayılan seçimi.
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
Rapor merkezi: tüm raporlar, süzgeçleri ve son dönemler (panel ekranı).
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
Ü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
Ç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
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
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
Firmanın SGK işyerlerini listeler — yan etkisiz; kapatılanlar include_closed=true ile.
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
Birleştirme önerileri — yan etkisiz: aynı sıra no + il + aracı numaralı işyerleri (işkolu / ilçe / ünite değişince
Sicil geçmişinden bir eski numarayı kaldırır (yanlış girilmiş) — dry_run destekler.
dry_run
İş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
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
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
PDKS (giriş-çıkış) — auto checkout
PDKS (giriş-çıkış) — calendar
id
full_name
employee_id
PDKS takvimi — data
id
title
start
allDay
color
extendedProps
PDKS (giriş-çıkış) — configure
PDKS (giriş-çıkış) — Devre dışı bırak
PDKS (giriş-çıkış) — Etkinleştir
PDKS (giriş-çıkış) — Dışa aktar
PDKS (giriş-çıkış) — generate token
PDKS (giriş-çıkış) — Listele
PDKS (giriş-çıkış) — live attendance
Canlı yoklama — data
id
employee_name
status
next_action
next_action_label
check_in_time
check_out_time
working_hours
updated_at
PDKS (giriş-çıkış) — public link
PDKS (giriş-çıkış) — reports
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
PDKS İstasyon Kodu sayfası — yöneticinin tablete gireceği 8 haneli dönen kod.
İstasyon kodunu JSON olarak döndürür (sayfa client-side auto-refresh için).
Web PDKS Entegrasyonu pdks_web
8 komut
Tek şubenin web embed yönetim sayfası.
Şube için Web PDKS'i kapat.
Şube için Web PDKS aktif et — yoksa pinli token oluştur, varsa yeniden etkinleştir.
Web PDKS — Listele
Web PDKS — logs
Web PDKS kayıtları — Dışa aktar
Token'ı yenile — eski iframe/script kodu çalışmayı durdurur.
İzinli origin + konum zorunluluğu güncelle.
allowed_origins
allowed_origins.*
location_required
Vardiya Yönetimi shifts
14 komut
Approve and apply the generated schedule
Otomatik vardiya planı — Oluşturma formu verisi
id
name
start_time
end_time
working_days
is_active
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
Otomatik vardiya planı — Listele
id
name
start_time
end_time
working_days
is_active
Vardiyalar — Ata
employee_id
shift_id
assigned_date
recurring
Vardiyalar — assignments
Vardiyalar — calendar
id
name
address
Vardiyalar — calendar events
Vardiyalar — Oluşturma formu verisi
Vardiyalar — Sil
Vardiyalar — Düzenleme formu verisi
Vardiyalar — Listele
id
name
start_time
end_time
working_days
break_duration_minutes
is_active
employees_count
created_at
Vardiyalar — Oluştur
name
start_time
end_time
working_days
working_days.*
break_duration_minutes
description
Vardiyalar — Güncelle
name
start_time
end_time
working_days
working_days.*
break_duration_minutes
is_active
Vize Talepleri visa_requests
5 komut
Vize talepleri — İptal et
Vize talepleri — İndir
Vize talepleri — Üret
include_salary
Vize talepleri — Listele
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.