İçeriğe geç

Ç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

employees.list: Parametreler
AlanTürAçıklama
company_id (sorgu)string (uuid)Yalnız bu şirketin çalışanları.
status (sorgu)stringYalnız bu durumdaki çalışanlar. Değerler: active, pre_start, inactive, terminated
updated_since (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)integerSayfa boyutu; azamiyi aşan değer azamiye iner.

Yanıtlar

200 Başarılı

Liste yanıtı { data, next_cursor } zarfındadır.

employees.list: Listedeki her öğe (data[])
AlanTürAçıklama
idstring (uuid)zorunluÇalışan kaydının kimliği.
company_idstring (uuid)zorunluÇalışanın şirketi.
org_unit_idstring (uuid)zorunlunull olabilirÇalışanın birimi; birimsizse null.
job_title_idstring (uuid)zorunlunull olabilirUnvan; yoksa null.
position_idstring (uuid)zorunlunull olabilirPozisyon; yoksa null.
manager_idstring (uuid)zorunlunull olabilirYöneticinin çalışan kimliği. Yönetici anahtarın göremediği bir kayıtsa null gelir.
first_namestringzorunlu
last_namestringzorunlu
work_emailstringzorunlunull olabilirİş e-postası; yoksa null.
statusstringzorunluactive: ç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_typestringzorunlunull olabilir Değerler: full_time, part_time, temporary, intern
hire_datestring (date)zorunlunull olabilirİşe giriş günü.
service_start_datestring (date)zorunlunull olabilir
sgk_entry_datestring (date)zorunlunull olabilir
probation_endstring (date)zorunlunull olabilir
is_demobooleanzorunluÖ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_atstring (date-time)zorunlu
updated_atstring (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_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 429: rate_limited
  • 500: internal_error
  • 503: 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

employees.create: Parametreler
AlanTürAçı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

employees.create: İstek gövdesi
AlanTürAçıklama
company_idstring (uuid)zorunluÇalışanın şirketi. Anahtarın oluşturma kapsamında olmalıdır.
first_namestringzorunluAd (1-100 karakter).
last_namestringzorunluSoyad (1-100 karakter).
work_emailstring (email)null olabilirİş e-postası; etkin çalışanlar arasında tekildir (çakışma 409).
org_unit_idstring (uuid)null olabilirBirim; şirketin bir birimi olmalıdır.
job_title_idstring (uuid)null olabilirUnvan.
manager_idstring (uuid)null olabilirYöneticinin çalışan kimliği; anahtarın kapsamında olmalıdır. Sonradan yalnız üründeki onay akışıyla değişir.
statusstringactive (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_idstring (uuid)null olabilirPozisyon; şirketin bir pozisyonu olmalıdır.
hire_datestring (date)null olabilirİşe giriş günü (YYYY-MM-DD).
service_start_datestring (date)null olabilir
sgk_entry_datestring (date)null olabilir
employment_typestringnull olabilirÇalışma biçimi. Değerler: full_time, part_time, temporary, intern
probation_endstring (date)null olabilir

Yanıtlar

201 Oluşturuldu

employees.create: Yanıtlar
AlanTürAçıklama
idstring (uuid)zorunluÇalışan kaydının kimliği.
company_idstring (uuid)zorunluÇalışanın şirketi.
org_unit_idstring (uuid)zorunlunull olabilirÇalışanın birimi; birimsizse null.
job_title_idstring (uuid)zorunlunull olabilirUnvan; yoksa null.
position_idstring (uuid)zorunlunull olabilirPozisyon; yoksa null.
manager_idstring (uuid)zorunlunull olabilirYöneticinin çalışan kimliği. Yönetici anahtarın göremediği bir kayıtsa null gelir.
first_namestringzorunlu
last_namestringzorunlu
work_emailstringzorunlunull olabilirİş e-postası; yoksa null.
statusstringzorunluactive: ç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_typestringzorunlunull olabilir Değerler: full_time, part_time, temporary, intern
hire_datestring (date)zorunlunull olabilirİşe giriş günü.
service_start_datestring (date)zorunlunull olabilir
sgk_entry_datestring (date)zorunlunull olabilir
probation_endstring (date)zorunlunull olabilir
is_demobooleanzorunluÖ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_atstring (date-time)zorunlu
updated_atstring (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_idstringnull olabilirT.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.
ibanstringnull olabilirMaaş 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.
salaryobjectnull olabilirBugü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.
personalobjectKiş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_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 409: idempotency_in_progress, conflict
  • 413: payload_too_large
  • 415: unsupported_media_type
  • 422: idempotency_key_reused
  • 429: rate_limited
  • 500: internal_error
  • 503: 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

employees.get: Parametreler
AlanTürAçıklama
id (yol)string (uuid)zorunluÇalışan kaydının kimliği.

Yanıtlar

200 Başarılı

employees.get: Yanıtlar
AlanTürAçıklama
idstring (uuid)zorunluÇalışan kaydının kimliği.
company_idstring (uuid)zorunluÇalışanın şirketi.
org_unit_idstring (uuid)zorunlunull olabilirÇalışanın birimi; birimsizse null.
job_title_idstring (uuid)zorunlunull olabilirUnvan; yoksa null.
position_idstring (uuid)zorunlunull olabilirPozisyon; yoksa null.
manager_idstring (uuid)zorunlunull olabilirYöneticinin çalışan kimliği. Yönetici anahtarın göremediği bir kayıtsa null gelir.
first_namestringzorunlu
last_namestringzorunlu
work_emailstringzorunlunull olabilirİş e-postası; yoksa null.
statusstringzorunluactive: ç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_typestringzorunlunull olabilir Değerler: full_time, part_time, temporary, intern
hire_datestring (date)zorunlunull olabilirİşe giriş günü.
service_start_datestring (date)zorunlunull olabilir
sgk_entry_datestring (date)zorunlunull olabilir
probation_endstring (date)zorunlunull olabilir
is_demobooleanzorunluÖ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_atstring (date-time)zorunlu
updated_atstring (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_idstringnull olabilirT.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.
ibanstringnull olabilirMaaş 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.
salaryobjectnull olabilirBugü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.
personalobjectKiş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_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 429: rate_limited
  • 500: internal_error
  • 503: 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

employees.update: Parametreler
AlanTürAçıklama
id (yol)string (uuid)zorunluÇalışan kaydının kimliği.

İstek gövdesi

employees.update: İstek gövdesi
AlanTürAçıklama
first_namestringAd (1-100 karakter).
last_namestringSoyad (1-100 karakter).
work_emailstring (email)null olabilirİş e-postası; etkin çalışanlar arasında tekildir (çakışma 409).
org_unit_idstring (uuid)null olabilirBirim; şirketin bir birimi olmalıdır.
job_title_idstring (uuid)null olabilirUnvan.
position_idstring (uuid)null olabilirPozisyon; şirketin bir pozisyonu olmalıdır.
hire_datestring (date)null olabilirİşe giriş günü (YYYY-MM-DD).
service_start_datestring (date)null olabilir
sgk_entry_datestring (date)null olabilir
employment_typestringnull olabilirÇalışma biçimi. Değerler: full_time, part_time, temporary, intern
probation_endstring (date)null olabilir
effective_datestring (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ı

employees.update: Yanıtlar
AlanTürAçıklama
idstring (uuid)zorunluÇalışan kaydının kimliği.
company_idstring (uuid)zorunluÇalışanın şirketi.
org_unit_idstring (uuid)zorunlunull olabilirÇalışanın birimi; birimsizse null.
job_title_idstring (uuid)zorunlunull olabilirUnvan; yoksa null.
position_idstring (uuid)zorunlunull olabilirPozisyon; yoksa null.
manager_idstring (uuid)zorunlunull olabilirYöneticinin çalışan kimliği. Yönetici anahtarın göremediği bir kayıtsa null gelir.
first_namestringzorunlu
last_namestringzorunlu
work_emailstringzorunlunull olabilirİş e-postası; yoksa null.
statusstringzorunluactive: ç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_typestringzorunlunull olabilir Değerler: full_time, part_time, temporary, intern
hire_datestring (date)zorunlunull olabilirİşe giriş günü.
service_start_datestring (date)zorunlunull olabilir
sgk_entry_datestring (date)zorunlunull olabilir
probation_endstring (date)zorunlunull olabilir
is_demobooleanzorunluÖ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_atstring (date-time)zorunlu
updated_atstring (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_idstringnull olabilirT.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.
ibanstringnull olabilirMaaş 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.
salaryobjectnull olabilirBugü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.
personalobjectKiş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_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 409: idempotency_in_progress, conflict
  • 413: payload_too_large
  • 415: unsupported_media_type
  • 429: rate_limited
  • 500: internal_error
  • 503: timeout