Çalışanlar
Çalışanlar uçları: parametreler, alanlar ve örnek yanıtlar.
Geliştirici belgesi
Çalışanları listeler
GET /api/v1/employees
Kapsam: employees:read
Anahtarın kapsamındaki çalışanlar. Liste öğesi T.C. kimlik, IBAN, ücret ve kişisel bilgi taşımaz; bunlar yalnız tek kayıt okumasındadır. Sıra kimliğe göredir ve kararlıdır; toplam sayı dönmez. Örnek kayıtlar listeye girmez.
Parametreler
| Alan | Tür | Açıklama |
|---|---|---|
company_ (sorgu) | string (uuid) | Yalnız bu şirketin çalışanları. |
status (sorgu) | string | Yalnız bu durumdaki çalışanlar. Değerler: active, pre_start, inactive, terminated |
updated_ (sorgu) | string (date-time) | Yalnız updated_at değeri bu andan büyük ya da eşit olan kayıtlar (saat dilimi taşıyan ISO 8601). Kapsayıcıdır: son gördüğünüz updated_at değerini gönderin ve kimlikle tekilleştirin. |
cursor (sorgu) | string | Önceki yanıtın next_cursor değeri. Opaktır; aynı anahtarla ve aynı süzgeçle gönderilir. |
limit (sorgu) | integer | Sayfa boyutu; azamiyi aşan değer azamiye iner. |
Yanıtlar
200 Başarılı
Liste yanıtı { data, next_cursor } zarfındadır.
| Alan | Tür | Açıklama |
|---|---|---|
id | string (uuid)zorunlu | Çalışan kaydının kimliği. |
company_ | string (uuid)zorunlu | Çalışanın şirketi. |
org_ | string (uuid)zorunlunull olabilir | Çalışanın birimi; birimsizse null. |
job_ | string (uuid)zorunlunull olabilir | Unvan; yoksa null. |
position_ | string (uuid)zorunlunull olabilir | Pozisyon; yoksa null. |
manager_ | string (uuid)zorunlunull olabilir | Yöneticinin çalışan kimliği. Yönetici anahtarın göremediği bir kayıtsa null gelir. |
first_ | stringzorunlu | |
last_ | stringzorunlu | |
work_ | stringzorunlunull olabilir | İş e-postası; yoksa null. |
status | stringzorunlu | active: çalışıyor; pre_start: işe alındı, ilk iş günü gelmedi; inactive: pasif; terminated: işten ayrıldı. Değerler: active, pre_start, inactive, terminated |
employment_ | stringzorunlunull olabilir | Değerler: full_time, part_time, temporary, intern |
hire_ | string (date)zorunlunull olabilir | İşe giriş günü. |
service_ | string (date)zorunlunull olabilir | |
sgk_ | string (date)zorunlunull olabilir | |
probation_ | string (date)zorunlunull olabilir | |
is_ | booleanzorunlu | Örnek veriyle gelen kayıt. Liste uçları örnek kayıtları döndürmez; tek kayıt okuması döndürür ve bu alan true olur. |
created_ | string (date-time)zorunlu | |
updated_ | string (date-time)zorunlu | Çalışan kaydının kendi alanlarının son değiştiği an (UTC). T.C. kimlik, IBAN, ücret ve kişisel bilgilerin değişmesi bu değeri değiştirmez. |
Örnek yanıt
{
"data": [
{
"id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"org_unit_id": "c4a1e2b3-7d6f-4e5a-9b8c-1f2e3d4c5b6a",
"job_title_id": "9e7d6c5b-4a39-4821-8f70-6e5d4c3b2a19",
"position_id": null,
"manager_id": null,
"first_name": "Deniz",
"last_name": "Kaya",
"work_email": "deniz.kaya@example.com",
"status": "active",
"employment_type": "full_time",
"hire_date": "2026-03-02",
"service_start_date": null,
"sgk_entry_date": null,
"probation_end": "2026-05-02",
"is_demo": false,
"created_at": "2026-02-24T09:30:00.000Z",
"updated_at": "2026-03-02T07:00:00.000Z"
}
],
"next_cursor": null
}Hata kodları
400:bad_request,validation_failed,key_in_query,cookie_with_key,idempotency_key_required,idempotency_key_invalid,cursor_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found429:rate_limited500:internal_error503:timeout
Çalışan oluşturur
POST /api/v1/employees
Kapsam: employees:write
Üründeki "Çalışan ekle" ile aynı kurallardan geçer. Gövde yalnız aşağıdaki alanları kabul eder; tanınmayan alan 400'dür. T.C. kimlik, IBAN ve ücret bu uçtan yazılamaz. Yanıt kaynağın güncel hâlidir, bu yüzden anahtar employees:read kapsamını da taşımalıdır. Kapsam dışındaki ya da var olmayan şirket, birim, unvan, pozisyon ve yönetici aynı 404 yanıtını alır.
Parametreler
| Alan | Tür | Açıklama |
|---|---|---|
Idempotency-Key (başlık) | stringzorunlu | İsteğin tekil anahtarı (UUID önerilir). Aynı anahtar ve gövdeyle yinelenen istek kaynağın güncel hâlini ve Idempotent-Replayed: true döner; pencere 24 saattir. |
İstek gövdesi
| Alan | Tür | Açıklama |
|---|---|---|
company_ | string (uuid)zorunlu | Çalışanın şirketi. Anahtarın oluşturma kapsamında olmalıdır. |
first_ | stringzorunlu | Ad (1-100 karakter). |
last_ | stringzorunlu | Soyad (1-100 karakter). |
work_ | string (email)null olabilir | İş e-postası; etkin çalışanlar arasında tekildir (çakışma 409). |
org_ | string (uuid)null olabilir | Birim; şirketin bir birimi olmalıdır. |
job_ | string (uuid)null olabilir | Unvan. |
manager_ | string (uuid)null olabilir | Yöneticinin çalışan kimliği; anahtarın kapsamında olmalıdır. Sonradan yalnız üründeki onay akışıyla değişir. |
status | string | active (varsayılan) ya da pre_start. pre_start için hire_date zorunludur ve bugünden sonra olmalıdır. Değerler: active, pre_start |
position_ | string (uuid)null olabilir | Pozisyon; şirketin bir pozisyonu olmalıdır. |
hire_ | string (date)null olabilir | İşe giriş günü (YYYY-MM-DD). |
service_ | string (date)null olabilir | |
sgk_ | string (date)null olabilir | |
employment_ | stringnull olabilir | Çalışma biçimi. Değerler: full_time, part_time, temporary, intern |
probation_ | string (date)null olabilir |
Yanıtlar
201 Oluşturuldu
| Alan | Tür | Açıklama |
|---|---|---|
id | string (uuid)zorunlu | Çalışan kaydının kimliği. |
company_ | string (uuid)zorunlu | Çalışanın şirketi. |
org_ | string (uuid)zorunlunull olabilir | Çalışanın birimi; birimsizse null. |
job_ | string (uuid)zorunlunull olabilir | Unvan; yoksa null. |
position_ | string (uuid)zorunlunull olabilir | Pozisyon; yoksa null. |
manager_ | string (uuid)zorunlunull olabilir | Yöneticinin çalışan kimliği. Yönetici anahtarın göremediği bir kayıtsa null gelir. |
first_ | stringzorunlu | |
last_ | stringzorunlu | |
work_ | stringzorunlunull olabilir | İş e-postası; yoksa null. |
status | stringzorunlu | active: çalışıyor; pre_start: işe alındı, ilk iş günü gelmedi; inactive: pasif; terminated: işten ayrıldı. Değerler: active, pre_start, inactive, terminated |
employment_ | stringzorunlunull olabilir | Değerler: full_time, part_time, temporary, intern |
hire_ | string (date)zorunlunull olabilir | İşe giriş günü. |
service_ | string (date)zorunlunull olabilir | |
sgk_ | string (date)zorunlunull olabilir | |
probation_ | string (date)zorunlunull olabilir | |
is_ | booleanzorunlu | Örnek veriyle gelen kayıt. Liste uçları örnek kayıtları döndürmez; tek kayıt okuması döndürür ve bu alan true olur. |
created_ | string (date-time)zorunlu | |
updated_ | string (date-time)zorunlu | Çalışan kaydının kendi alanlarının son değiştiği an (UTC). T.C. kimlik, IBAN, ücret ve kişisel bilgilerin değişmesi bu değeri değiştirmez. |
national_ | stringnull olabilir | T.C. kimlik numarası. Yalnız anahtarın field:national_id kapsamı ve rolünün aynı alan sınıfı varsa yanıtta bulunur; değer dönerse erişim kaydı yazılır. |
iban | stringnull olabilir | Maaş hesabının IBAN'ı. Yalnız field:iban kapsamı ve rolün aynı alan sınıfı varsa yanıtta bulunur; değer dönerse erişim kaydı yazılır. |
salary | objectnull olabilir | Bugün geçerli ücret kaydı (tutar ondalık metin, para birimi, geçerlilik günü); ileri tarihli ücret dönmez. Yalnız field:salary kapsamı ve rolün aynı alan sınıfı varsa yanıtta bulunur; değer dönerse erişim kaydı yazılır. |
personal | object | Kişisel bilgiler (doğum günü, cinsiyet, telefon, kişisel e-posta, adres, şehir). Yalnız field:pii kapsamı ve rolün aynı alan sınıfı varsa yanıtta bulunur; değer dönerse erişim kaydı yazılır. |
Örnek yanıt
{
"id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"org_unit_id": "c4a1e2b3-7d6f-4e5a-9b8c-1f2e3d4c5b6a",
"job_title_id": "9e7d6c5b-4a39-4821-8f70-6e5d4c3b2a19",
"position_id": null,
"manager_id": null,
"first_name": "Deniz",
"last_name": "Kaya",
"work_email": "deniz.kaya@example.com",
"status": "active",
"employment_type": "full_time",
"hire_date": "2026-03-02",
"service_start_date": null,
"sgk_entry_date": null,
"probation_end": "2026-05-02",
"is_demo": false,
"created_at": "2026-02-24T09:30:00.000Z",
"updated_at": "2026-03-02T07:00:00.000Z"
}Hata kodları
400:bad_request,validation_failed,key_in_query,cookie_with_key,idempotency_key_required,idempotency_key_invalid,cursor_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found409:idempotency_in_progress,conflict413:payload_too_large415:unsupported_media_type422:idempotency_key_reused429:rate_limited500:internal_error503:timeout
Tek çalışanı döndürür
GET /api/v1/employees/{id}
Kapsam: employees:read
T.C. kimlik, IBAN, ücret ve kişisel bilgiler yalnız ilgili field: kapsamı ve rolün aynı alan sınıfı birlikteyken yanıtta bulunur; yoksa alanın adı da yanıtta yoktur. Anahtarın görmediği kayıt ile var olmayan kayıt aynı 404 yanıtını alır.
Parametreler
| Alan | Tür | Açıklama |
|---|---|---|
id (yol) | string (uuid)zorunlu | Çalışan kaydının kimliği. |
Yanıtlar
200 Başarılı
| Alan | Tür | Açıklama |
|---|---|---|
id | string (uuid)zorunlu | Çalışan kaydının kimliği. |
company_ | string (uuid)zorunlu | Çalışanın şirketi. |
org_ | string (uuid)zorunlunull olabilir | Çalışanın birimi; birimsizse null. |
job_ | string (uuid)zorunlunull olabilir | Unvan; yoksa null. |
position_ | string (uuid)zorunlunull olabilir | Pozisyon; yoksa null. |
manager_ | string (uuid)zorunlunull olabilir | Yöneticinin çalışan kimliği. Yönetici anahtarın göremediği bir kayıtsa null gelir. |
first_ | stringzorunlu | |
last_ | stringzorunlu | |
work_ | stringzorunlunull olabilir | İş e-postası; yoksa null. |
status | stringzorunlu | active: çalışıyor; pre_start: işe alındı, ilk iş günü gelmedi; inactive: pasif; terminated: işten ayrıldı. Değerler: active, pre_start, inactive, terminated |
employment_ | stringzorunlunull olabilir | Değerler: full_time, part_time, temporary, intern |
hire_ | string (date)zorunlunull olabilir | İşe giriş günü. |
service_ | string (date)zorunlunull olabilir | |
sgk_ | string (date)zorunlunull olabilir | |
probation_ | string (date)zorunlunull olabilir | |
is_ | booleanzorunlu | Örnek veriyle gelen kayıt. Liste uçları örnek kayıtları döndürmez; tek kayıt okuması döndürür ve bu alan true olur. |
created_ | string (date-time)zorunlu | |
updated_ | string (date-time)zorunlu | Çalışan kaydının kendi alanlarının son değiştiği an (UTC). T.C. kimlik, IBAN, ücret ve kişisel bilgilerin değişmesi bu değeri değiştirmez. |
national_ | stringnull olabilir | T.C. kimlik numarası. Yalnız anahtarın field:national_id kapsamı ve rolünün aynı alan sınıfı varsa yanıtta bulunur; değer dönerse erişim kaydı yazılır. |
iban | stringnull olabilir | Maaş hesabının IBAN'ı. Yalnız field:iban kapsamı ve rolün aynı alan sınıfı varsa yanıtta bulunur; değer dönerse erişim kaydı yazılır. |
salary | objectnull olabilir | Bugün geçerli ücret kaydı (tutar ondalık metin, para birimi, geçerlilik günü); ileri tarihli ücret dönmez. Yalnız field:salary kapsamı ve rolün aynı alan sınıfı varsa yanıtta bulunur; değer dönerse erişim kaydı yazılır. |
personal | object | Kişisel bilgiler (doğum günü, cinsiyet, telefon, kişisel e-posta, adres, şehir). Yalnız field:pii kapsamı ve rolün aynı alan sınıfı varsa yanıtta bulunur; değer dönerse erişim kaydı yazılır. |
Örnek yanıt
{
"id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"org_unit_id": "c4a1e2b3-7d6f-4e5a-9b8c-1f2e3d4c5b6a",
"job_title_id": "9e7d6c5b-4a39-4821-8f70-6e5d4c3b2a19",
"position_id": null,
"manager_id": null,
"first_name": "Deniz",
"last_name": "Kaya",
"work_email": "deniz.kaya@example.com",
"status": "active",
"employment_type": "full_time",
"hire_date": "2026-03-02",
"service_start_date": null,
"sgk_entry_date": null,
"probation_end": "2026-05-02",
"is_demo": false,
"created_at": "2026-02-24T09:30:00.000Z",
"updated_at": "2026-03-02T07:00:00.000Z"
}Hata kodları
400:bad_request,validation_failed,key_in_query,cookie_with_key,idempotency_key_required,idempotency_key_invalid,cursor_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found429:rate_limited500:internal_error503:timeout
Çalışanın izinli alanlarını günceller
PATCH /api/v1/employees/{id}
Kapsam: employees:write
Kısmi güncelleme: gönderilmeyen alan değişmez, gövde en az bir alan taşır, tanınmayan alan 400'dür. Yönetici, durum, şirket, T.C. kimlik, IBAN ve ücret bu uçtan değişmez. Değerler mutlaktır: aynı istek yinelendiğinde kayıt aynı hâlde kalır, Idempotency-Key gerekmez. Yanıt kaynağın güncel hâlidir, bu yüzden anahtar employees:read kapsamını da taşımalıdır. Anahtarın görmediği kayıt ile var olmayan kayıt aynı 404 yanıtını alır. Ön koşul yoktur: son yazan kazanır (eşzamanlı iki güncellemede sonuncusu geçerlidir). Ad ve soyad kişinin alanıdır: kişinin başka bir şirketteki istihdam kaydı varsa orada da değişir.
Parametreler
| Alan | Tür | Açıklama |
|---|---|---|
id (yol) | string (uuid)zorunlu | Çalışan kaydının kimliği. |
İstek gövdesi
| Alan | Tür | Açıklama |
|---|---|---|
first_ | string | Ad (1-100 karakter). |
last_ | string | Soyad (1-100 karakter). |
work_ | string (email)null olabilir | İş e-postası; etkin çalışanlar arasında tekildir (çakışma 409). |
org_ | string (uuid)null olabilir | Birim; şirketin bir birimi olmalıdır. |
job_ | string (uuid)null olabilir | Unvan. |
position_ | string (uuid)null olabilir | Pozisyon; şirketin bir pozisyonu olmalıdır. |
hire_ | string (date)null olabilir | İşe giriş günü (YYYY-MM-DD). |
service_ | string (date)null olabilir | |
sgk_ | string (date)null olabilir | |
employment_ | stringnull olabilir | Çalışma biçimi. Değerler: full_time, part_time, temporary, intern |
probation_ | string (date)null olabilir | |
effective_ | string (date) | Birim, pozisyon ya da unvan değişikliğinin geçerli olduğu gün; verilmezse bugün. |
Yanıtlar
200 Başarılı
| Alan | Tür | Açıklama |
|---|---|---|
id | string (uuid)zorunlu | Çalışan kaydının kimliği. |
company_ | string (uuid)zorunlu | Çalışanın şirketi. |
org_ | string (uuid)zorunlunull olabilir | Çalışanın birimi; birimsizse null. |
job_ | string (uuid)zorunlunull olabilir | Unvan; yoksa null. |
position_ | string (uuid)zorunlunull olabilir | Pozisyon; yoksa null. |
manager_ | string (uuid)zorunlunull olabilir | Yöneticinin çalışan kimliği. Yönetici anahtarın göremediği bir kayıtsa null gelir. |
first_ | stringzorunlu | |
last_ | stringzorunlu | |
work_ | stringzorunlunull olabilir | İş e-postası; yoksa null. |
status | stringzorunlu | active: çalışıyor; pre_start: işe alındı, ilk iş günü gelmedi; inactive: pasif; terminated: işten ayrıldı. Değerler: active, pre_start, inactive, terminated |
employment_ | stringzorunlunull olabilir | Değerler: full_time, part_time, temporary, intern |
hire_ | string (date)zorunlunull olabilir | İşe giriş günü. |
service_ | string (date)zorunlunull olabilir | |
sgk_ | string (date)zorunlunull olabilir | |
probation_ | string (date)zorunlunull olabilir | |
is_ | booleanzorunlu | Örnek veriyle gelen kayıt. Liste uçları örnek kayıtları döndürmez; tek kayıt okuması döndürür ve bu alan true olur. |
created_ | string (date-time)zorunlu | |
updated_ | string (date-time)zorunlu | Çalışan kaydının kendi alanlarının son değiştiği an (UTC). T.C. kimlik, IBAN, ücret ve kişisel bilgilerin değişmesi bu değeri değiştirmez. |
national_ | stringnull olabilir | T.C. kimlik numarası. Yalnız anahtarın field:national_id kapsamı ve rolünün aynı alan sınıfı varsa yanıtta bulunur; değer dönerse erişim kaydı yazılır. |
iban | stringnull olabilir | Maaş hesabının IBAN'ı. Yalnız field:iban kapsamı ve rolün aynı alan sınıfı varsa yanıtta bulunur; değer dönerse erişim kaydı yazılır. |
salary | objectnull olabilir | Bugün geçerli ücret kaydı (tutar ondalık metin, para birimi, geçerlilik günü); ileri tarihli ücret dönmez. Yalnız field:salary kapsamı ve rolün aynı alan sınıfı varsa yanıtta bulunur; değer dönerse erişim kaydı yazılır. |
personal | object | Kişisel bilgiler (doğum günü, cinsiyet, telefon, kişisel e-posta, adres, şehir). Yalnız field:pii kapsamı ve rolün aynı alan sınıfı varsa yanıtta bulunur; değer dönerse erişim kaydı yazılır. |
Örnek yanıt
{
"id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"org_unit_id": "c4a1e2b3-7d6f-4e5a-9b8c-1f2e3d4c5b6a",
"job_title_id": "9e7d6c5b-4a39-4821-8f70-6e5d4c3b2a19",
"position_id": null,
"manager_id": null,
"first_name": "Deniz",
"last_name": "Kaya",
"work_email": "deniz.kaya@example.com",
"status": "active",
"employment_type": "full_time",
"hire_date": "2026-03-02",
"service_start_date": null,
"sgk_entry_date": null,
"probation_end": "2026-05-02",
"is_demo": false,
"created_at": "2026-02-24T09:30:00.000Z",
"updated_at": "2026-03-02T07:00:00.000Z"
}Hata kodları
400:bad_request,validation_failed,key_in_query,cookie_with_key,idempotency_key_required,idempotency_key_invalid,cursor_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found409:idempotency_in_progress,conflict413:payload_too_large415:unsupported_media_type429:rate_limited500:internal_error503:timeout