API anahtarları ve genel API

Workify360 Focus genel API’si kendi betiklerinizin ve araçlarınızın raporları ve zaman verilerini okumasını ve zaman kaydı ya da üye eklemek gibi değişiklikler yapmasını panelle aynı kurallarla sağlar. Genel API, API anahtarları ve webhook’lar Premium paketine dahildir.

API anahtarı kişiseldir: onu oluşturan kişiye aittir ve o kişi olarak çalışır. Sahibinin güncel rolünün izin verdiğinden fazlasını hiçbir zaman yapamaz ve sahibi organizasyondan ayrılınca çalışmayı bırakır.

Kim API anahtarı oluşturabilir

API anahtarları şirket ayarı kimin oluşturabileceğine karar verir: yalnız hesap sahipleri ve şirket yöneticileri (varsayılan) ya da herkes. Yalnız hesap sahipleri ve şirket yöneticileri oluşturabiliyorsa diğer kişiler reddedilir (api_keys_admins_only).

• Anahtar oluşturabilen herkes kendi anahtarlarını profilinin Entegrasyonlar sekmesinde bulur.
• Hesap sahipleri ve şirket yöneticileri ayrıca organizasyonun bütün anahtarlarını sahibi, kapsamları ve son kullanımıyla Ayarlar → Geliştirici sayfasında görür ve herhangi birini iptal edebilir.

Anahtar oluşturma

1. API anahtarı oluştur’u seçin.
2. Ne için olduğunu söyleyen bir ad verin, kapsamlarını ve kaç gün geçerli olacağını seçin: 1 ile 365 gün arası, varsayılan 90 (api_key_expiry_invalid).
3. Focus isterse girişinizi onaylayın; son girişiniz 10 dakikadan eskiyse ister.
4. Anahtar “Anahtarı şimdi kopyalayın. Bir daha gösterilmeyecek.” mesajıyla bir kez gösterilir. Kopyalayın ve parola yöneticisi gibi güvenli bir yerde saklayın.

Focus anahtarın kendisini değil yalnız parmak izini saklar; bu yüzden ne organizasyonunuzda ne de Workify360’ta kimse onu size yeniden gösteremez. Kaybolan anahtar iptal edilir ve yenisi oluşturulur. Her kişinin en fazla 10 etkin anahtarı olabilir (api_key_limit_reached).

Kapsamlar ve rolünüz

Bir anahtarın kapsamları API’nin hangi kısımlarını kullanabileceğini söyler:

Kapsam	Neye izin verir
me	Kendi profiliniz ve zamanlayıcınız
reports:read	Raporları, zaman kayıtlarını, devamsızlıkları, vardiyaları, takımları, projeleri, görevleri ve dışa aktarmaları okuma
time:write	Zaman kayıtları, devamsızlıklar, vardiyalar, görevler ve görevlere atanan süre eklemek ve değiştirmek, talepleri karara bağlamak
org:admin	Üyeleri, takımları, davetleri ve projeleri yönetmek
webhooks:manage	Webhook uçlarını yönetmek (webhook’lar)

Kapsam kendi başına yetki vermez. Her istek, panelde aynı şeyi yapıyormuşsunuz gibi, o andaki rolünüze, takımlarınıza ve organizasyonunuzun paketine göre denetlenir:

• Yalnız güncel rolünüzün kullanabildiği kapsamları seçebilirsiniz; örneğin bir çalışan org:admin ya da webhooks:manage seçemez (scope_exceeds_role). Var olmayan ya da anahtarlara verilemeyen bir kapsam reddedilir (scope_unknown).
• Rolünüz daha az yetkili bir role değişince anahtarlarınız da onunla daralır: yeni rolünüzün izin vermediği istekler forbidden ile reddedilir ve anahtar listesi anahtarın etkin kapsamlarının oluşturulduğu kapsamlardan küçük olduğunu gösterir. Rolünüz yeniden yükselince anahtar oluşturulduğu kapsamlara yine izin verir, fazlasına asla.
• Üyeliğiniz askıya alındığında ya da bittiğinde, SCIM ile de olsa, bütün anahtarlarınız hemen iptal edilir. Yeniden etkinleştirilmek onları geri getirmez.
• Organizasyonunuz API’si olmayan bir pakete geçerse anahtarlar yeniden Premium’a dönene kadar çalışmaz (feature_not_in_plan).

Anahtarlar başka anahtar oluşturamaz, entegrasyon bağlayamaz ya da SCIM’i yönetemez; bunlar panelde kalır.

API’yi çağırma

Anahtarı Authorization başlığında gönderin:

curl https://api.focus.workify360.com/v1/me \
  -H "Authorization: Bearer w360_pat_…"

Genel API’nin işlemleri kapsamları ve veri biçimleriyle birlikte API referansında listelenir ve https://api.focus.workify360.com/v1/openapi/public.json adresindeki OpenAPI belgesinde anlatılır. Bu işlemler geriye uyumlu tutulur. Anahtarı eksik, yanlış, süresi dolmuş ya da iptal edilmiş istek 401 alır.

Bir anahtarla yapılan değişiklikler denetim kaydında anahtar sahibinin adıyla ve anahtarla yapıldığı işaretiyle yer alır; anahtar oluşturma ve iptal etme de orada kaydedilir (denetim kaydı).

İstek sınırları

Sınır	Dakikada istek
Anahtar başına	600
Organizasyon başına, bütün anahtarlar birlikte	1.800

Bir şeyi değiştiren istek (GET ve HEAD dışındaki her şey) iki birim, diğer her istek bir birim sayılır. Bir anahtar ayrıca bir seferde en çok 60 birim gönderebilir; bu hak saniyede 10 birim dolar: art arda 60’tan fazla okuma (ya da 30’dan fazla değişiklik) gönderen bir betik dakikada 600’ün altında kalsa da 429 alır. İstekleri zamana yayın.

Sayılan her yanıt anahtarın kalan birimlerini gösteren bir RateLimit başlığı ve sınırları gösteren bir RateLimit-Policy başlığı taşır. Bir sınırın üstünde API rate_limited koduyla 429 ve beklenecek saniyeyi gösteren bir Retry-After başlığıyla yanıt verir.

Anahtarı iptal etme

Bir anahtarı profilinizin Entegrasyonlar sekmesinde ya da hesap sahibi veya şirket yöneticisi olarak Ayarlar → Geliştirici sayfasında iptal edin. Bir sonraki istekte çalışmayı bırakır. Süresi dolan anahtarlar kendiliğinden çalışmayı bırakır; liste, süresi dolmadan bir hafta önce sizi uyarır.

Hata mesajları

Kod	Ne yapmalı
api_keys_admins_only	Organizasyonunuzda API anahtarını yalnız hesap sahipleri ve şirket yöneticileri oluşturabilir
scope_exceeds_role	Güncel rolünüz bu kapsamı kullanamıyor; daha az kapsam seçin
scope_unknown	Kapsamları listeden seçin
api_key_expiry_invalid	1 ile 365 gün arasında bir geçerlilik seçin
api_key_limit_reached	10 etkin anahtarınız var; artık kullanmadığınız birini iptal edin
api_key_not_found	Anahtar iptal edilmiş ya da başkasına ait; listeyi yenileyin
rate_limited	Retry-After’daki saniye kadar bekleyin, sonra daha az istek gönderin
feature_not_in_plan	Genel API Premium paketine dahildir