API dokümantasyonu

Shifton Görevler, platformdaki işleri otomatikleştirmenize ve açık API üzerinden platformu harici hizmetlere bağlamanıza olanak tanır. API üzerinden tüm temel varlıklara erişilebilir — görevler, müşteriler, çalışanlar, kontrol listeleri, envanter, hizmet alanları, finansal belgeler ve raporlar — bu nedenle Shifton’u HR, bordro hesaplama ve analitik sistemlerinizle, ayrıca şirketin dâhilî hizmetleriyle bağlayabilirsiniz.

Dokümantasyon iki sürüm hâlinde yayımlanmıştır:

🚀 Yeni dokümantasyon — güncellenmiş yapıya ve en son yöntemlere sahip güncel başvuru sürümü: 👉 https://api2.shifton.com/openapi/
📄 Eski belgeler — önceki sürüm (mevcut entegrasyonlar için hâlâ desteklenmektedir): 👉 https://api2.shifton.com/docs/

Her iki sürümü doğrudan uygulamadan açabilirsiniz — Developer bölümünde, Genel Bakış sekmesinde, “Yeni dokümantasyon” ve “Eski belgeler” düğmeleriyle.

Dokümantasyon iki dilde mevcuttur. Yeni dokümantasyon sayfasının sağ üst köşesinde bir EN / RU anahtarı vardır — seçilen dil hatırlanır.

API anahtarı nasıl alınır

API anahtarı uygulamanın kendisinde oluşturulur:

Developer bölümünü açın.
API anahtarları (“API anahtarları”) sekmesine geçin.
“API anahtarı oluştur” düğmesine basın.

Anahtar oluştururken neler doldurulur

Şu alanları içeren API anahtarı oluştur yan paneli açılır:

Başlık — anahtarın adı, zorunlu alan. Sonradan neyi kapatacağınızın anlaşılması için amacına göre adlandırın: “1C’ye dışa aktarma”, “Analitik için raporlar”.
Şu saatte sona erer — anahtarın bu tarihten sonra geçerliliğini yitireceği tarih. Alanı boş bırakırsanız geçerlilik süresi sınırsız olur.
Erişim — anahtarın yetki kapsamı:
Full access (act as me) — anahtar sizin adınıza ve sizin yetkilerinizle çalışır.
Kısıtlı izinler — kendinizin seçtiği sınırlı bir izin seti.

Anahtarı oluşturmak için Ekle, paneli kapatmak için İptal Et düğmesine basın.

📷 *Anahtar oluşturma panelinin ekran görüntüsü — prodda alınacak*

Anahtar belirli bir şirket için oluşturulur ve yalnızca o şirketin verileriyle çalışır. Anahtar dilediğiniz zaman iptal edilebilir — iptal hemen geçerli olur ve bu anahtarla yapılan sonraki tüm istekler 401 hatası döndürür.

Önemli: oluşturulan anahtar yalnızca bir kez gösterilir. Hemen kopyalayın ve güvenli bir yerde saklayın — tekrar elde edilemez. Anahtar kaybolursa yenisini oluşturun, eskisini iptal edin.

Yetkilendirme

API’ye yapılan tüm istekler başlıkta anahtarla imzalanır:

Authorization: Bearer {your_API_key}

API’nin temel adresi:

https://api2.shifton.com/work/1.0.0

Geçerli bir anahtar olmadan yapılan istek 401 ve {"message":"Unauthenticated."} gövdesini döndürür.

İlk istek

Örneğin, şirketin çalışan listesini almak için ({companyId} yerine kendi şirket ID’nizi yazın):

GET https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees
Authorization: Bearer {your_API_key}
Accept: application/json

Aynı işlem curl ile:

curl -H "Authorization: Bearer {your_API_key}" \
     -H "Accept: application/json" \
     https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees

Şirket ID’si uygulamanın adres satırında görünür: app.shifton.com/c/8397/... — /c/ sonrasındaki sayı.

API üzerinden neler kullanılabilir

Başvuru kaynağı 360’tan fazla yöntemi kapsar. Saha hizmeti için temel bölümler:

Görevler — /companies/{companyId}/tasks: oluşturma, değiştirme, durumlar, görev dosyaları.
Yapılacaklar listesi (To Do) — /companies/{companyId}/todo.
Müşteriler — /companies/{companyId}/clients, ayrıca müşterilerin adresleri ve özel alanları.
Kontrol listeleri — /companies/{companyId}/checklists.
Hizmet alanları — /companies/{companyId}/tasks/service-areas.
Beceriler — /companies/{companyId}/skills.
Çalışanlar — /companies/{companyId}/employees: ekleme, düzenleme, işten çıkarma ve geri yükleme.
Envanter — öğeler, kategoriler, setler ve depolardaki bakiyeler.
Finansal belgeler — teklifler, iş emirleri, faturalar, makbuzlar, belge sayaçları ve logo.
Raporlar — çalışma ve devam verilerinin dışa aktarılması.

Bunun dışında çalışma programları ve vardiyalar, izinler ve izin talepleri, devam takibi, faturalandırma ve SMS faturalandırması, bildirimler ve modüller de mevcuttur.

Web kancaları

API’ye düzenli istek göndermek yerine olayları gerçekleştikleri anda almanız gerekiyorsa web kancalarını kullanın — Developer bölümündeki Webhooks sekmesi. Gereken olay gerçekleştiğinde Shifton isteği kendisi sizin adresinize gönderir; desteklenen olayların listesini ayrı bir yöntem döndürür.

Hata kodları

Shifton API’si standart HTTP durum kodlarını kullanır:

200 — istek başarıyla tamamlandı.
201 — nesne başarıyla oluşturuldu.
400 — hatalı istek parametreleri.
401 — yetkilendirme hatası: anahtar gönderilmedi, geçersiz veya iptal edilmiş.
403 — erişim reddedildi.
404 — kaynak bulunamadı (çoğunlukla yöntem adresinde yazım hatası).
500 — sunucu hatası.

Kullanım ipuçları

Yeni entegrasyonlar için yeni dokümantasyonu kullanın — eski sürüm, hâlihazırda çalışan entegrasyonlar için bırakılmıştır.
İstekleri denemek için Postman veya curl kullanışlıdır — tek satır kod yazmadan yanıtı görmenizi sağlar.
Anahtarı kodda açık biçimde saklamayın ve üçüncü kişilere vermeyin: anahtar, şirket verilerine erişim sağlar.
İstek sıklığı sınırlarına (rate limits) uyun — bunların aşılması API erişiminin geçici olarak engellenmesine yol açabilir.

Sıkça sorulan sorular

Soru: API anahtarı nereden alınır? Cevap: Uygulamada: Developer bölümü → API anahtarları sekmesi → “API anahtarı oluştur” düğmesi. Anahtar, mevcut şirket için verilir.

Soru: Pencereyi kapattım ve anahtarı kopyalamadım. Nereden görebilirim? Cevap: Hiçbir yerden — anahtar yalnızca bir kez gösterilir ve tekrar verilmez. Yeni bir anahtar oluşturun, eskisini iptal edin.

Soru: Anahtar yanlış kişilerin eline geçtiyse nasıl iptal edilir? Cevap: API anahtarları sekmesinden silin. İptal hemen geçerli olur: bu anahtarla yapılan tüm istekler anında 401 döndürmeye başlar.

Soru: “Full access” ile “Restricted permissions” arasındaki fark nedir? Cevap: Full access (act as me), anahtara sizin sahip olduğunuz yetkilerin aynısını verir. Kısıtlı izinler ise anahtara yalnızca seçilen izin setini vermenizi sağlar — verilerin yalnızca bir kısmına erişmesi gereken bir entegrasyon için bu daha güvenlidir.

Soru: Anahtarın geçerlilik süresi sınırlandırılabilir mi? Cevap: Evet, oluşturma sırasındaki Şu saatte sona erer alanı. Doldurulmazsa anahtar süresiz olur.

Soru: Tek bir anahtar birden fazla şirket için çalışır mı? Cevap: Hayır. Anahtar, oluşturulduğu şirkete bağlıdır ve yalnızca o şirketin verileriyle çalışır. Diğer şirket için ayrı bir anahtar oluşturun.

Soru: API’nin temel adresi nedir? Cevap: https://api2.shifton.com/work/1.0.0. Sonrasında yöntemin yolu gelir, örneğin /companies/{companyId}/tasks.

Soru: İstekler için şirket ID’si nereden alınır? Cevap: Uygulamanın adres satırında, hemen /c/ sonrasında bulunur — örneğin, app.shifton.com/c/8397/tasks adresinde şirket tanımlayıcısı 8397’dir.

Soru: Dokümantasyonun hangi sürümü kullanılmalı? Cevap: Yeni entegrasyonlar için yeni sürüm (api2.shifton.com/openapi). Eski sürüm (api2.shifton.com/docs) mevcut entegrasyonlar için desteklenir.

Soru: Rusça dokümantasyon var mı? Cevap: Evet. Yeni dokümantasyon sayfasının sağ üst köşesinde EN / RU anahtarı bulunur.

Soru: API isteklerini neyle test etmeli? Cevap: En kullanışlısı Postman veya curl’dur — kod yazmadan istek göndermenize ve yanıtları görmenize olanak tanır.

Soru: Anahtarı kopyalamış olmama rağmen neden 401 geliyor? Cevap: Anahtarın Authorization başlığında, önünde Bearer sözcüğüyle gönderildiğini, anahtarın iptal edilmediğini ve geçerlilik süresinin dolmadığını kontrol edin.

Soru: Neden 404 geliyor? Cevap: Çoğunlukla adres karıştırılmıştır: temel kısım https://api2.shifton.com/work/1.0.0 olmalı, yöntemin yolunda ise doğru {companyId} bulunmalıdır.

Soru: API üzerinden neler otomatikleştirilebilir? Cevap: Görevlerin oluşturulması ve değiştirilmesi, müşteriler ve adresleriyle çalışma, kontrol listeleri, hizmet alanları, beceriler, çalışanlar, envanter, finansal belgeler ve raporların dışa aktarılması, ayrıca çalışma programları, vardiyalar ve izinler.

Soru: API’yi sorgulamak yerine Shifton’dan olay alınabilir mi? Cevap: Evet, bunun için web kancaları vardır — Developer bölümündeki Webhooks sekmesi.

Soru: Şifre değişikliği entegrasyonun çalışmasını etkiler mi? Cevap: Hayır. Entegrasyonlar hesap şifresiyle değil, API anahtarıyla çalışır.