API ve Geliştirici

Workinno'nun API'si

Workinno, verinize dışarıdan erişmeniz için genel bir REST API sunar. Kendi yazılımınızı, Zapier veya Make gibi araçları ya da başka bir uygulamayı bu API üzerinden Workinno'ya bağlayabilirsiniz. Otomasyon bölümünün API ve Geliştirici sekmesi, ihtiyacınız olan tüm teknik bilgiyi tek sayfada toplar.

Bu sayfa geliştiriciler içindir; API'yi kendi yazılımına bağlayacak kişiye rehberlik eder.

Adres ve kimlik

Tüm istekler şu adrese gider: https://api.workinno.com/api/v1

Her istek bir API anahtarıyla doğrulanır. Anahtarı Authorization başlığında gönderirsiniz:

Authorization: Bearer wklive...

Anahtarı henüz oluşturmadıysanız API Anahtarları sayfasından oluşturun. Sayfadaki API anahtarı oluştur düğmesi de sizi oraya götürür. → API Anahtarları

Hız sınırı

Her anahtarın dakikada yapabileceği istek sayısı sınırlıdır. Hak paketinize göre değişir ve okuma ile yazma ayrı sayılır: ücretsiz pakette dakikada 20 okuma ve 5 yazma, ücretli paketlerde dilim yükseldikçe artar.

Sayıyı ezberlemenize gerek yok: her yanıt o anahtarın hakkını X-RateLimit-Limit, kalanını X-RateLimit-Remaining başlığında bildirir. Sınırı aşarsanız istek 429 hatasıyla döner ve Retry-After başlığı ne kadar bekleyeceğinizi söyler.

Çift-istek koruması

Bir yazma isteğinde ağ koparsa isteği tekrar göndermeniz gerekebilir. Aynı işlemin iki kez kaydedilmesini önlemek için isteğe bir Idempotency-Key başlığı eklersiniz. Aynı anahtarla gönderilen tekrar, ilk isteğin yanıtını döndürür ve ikinci bir kayıt oluşturmaz. Bu koruma 24 saat geçerlidir.

Hata biçimi

Hatalar tutarlı bir gövdeyle döner. code alanı makine tarafından okunur, message alanı İngilizce bir açıklamadır:

{ "success": false, "error": { "code": "errors.apiKey.scope_denied", "message": "This API key is not authorized for this action", "path": "/api/v1/tasks" } }

Sayfalama ve arama

Listeleme uç noktaları page, limit ve q (arama) parametrelerini kabul eder. Tek istekte en fazla 100 kayıt döner:

GET /api/v1/tasks?page=1&limit=20&q=demo

Sıralama ve "neyin değiştiğini" sorma

Listeleme uç noktaları sort parametresini de kabul eder. Değer alan ya da alan:asc / alan:desc biçimindedir:

GET /api/v1/tasks?sort=updatedAt:desc&limit=20

Bu parametre özellikle dışarıdan düzenli kontrol eden araçlar için vardır. Bir otomasyon aracı (örneğin Zapier ya da Make) "Workinno'da yeni bir şey oldu mu?" diye aralıklarla sorar; en son değişeni başa alabilmesi için sıralama gerekir.

Hangi alanla sıralayabileceğiniz kaynağa göre değişir; kabul edilen alanların tam listesi OpenAPI şemasında yazılıdır. Tanınmayan bir alan sessizce yok sayılmaz, sebebini söyleyen bir hatayla geri döner — böylece sıraladığınızı sanıp kayıt kaçırmazsınız.

Görevlerde ayrıca belli bir andan sonra değişenleri isteyebilirsiniz:

GET /api/v1/tasks?updatedFrom=2026-09-01T00:00:00Z&sort=updatedAt:desc

Tarih saat dilimiyle birlikte yazılır. Bu iki parametre yalnız görevlerde vardır.

Olaylara abone olma (anında haber)

Yukarıdaki sıralama, dışarıdan düzenli sorup yenileri almak içindir. Bir olay gerçekleştiği anda haber almak isterseniz abone olabilirsiniz: adresinizi kaydedersiniz, olay olunca oraya bir istek gönderilir.

POST /api/v1/hooks { "event": "task.completed", "targetUrl": "https://ornek.com/geldi" }

Abone olunabilecek sekiz olay var: görev tamamlandı, görev atandı, görev aşama değiştirdi, vade geçti, teklif kabul edildi, aday yakalandı, web sitesi formu gönderildi ve site erişilemiyor. Tam liste OpenAPI şemasında yazılıdır.

Aboneliklerinizi GET /api/v1/hooks ile görür, DELETE /api/v1/hooks/{id} ile bırakırsınız. Listede yalnız kendi anahtarınızın açtığı abonelikler görünür.

Bilmeniz gerekenler:

• Adres https:// olmalıdır; gönderilen veri iş verisi taşır. Adresin dışarıdan

erişilebilir olması da gerekir — kendi ağınıza dönük bir adres (örneğin 127.0.0.1) kaydedilmez, sebebini söyleyen bir hatayla geri döner.

• Anahtarınızın, abone olduğunuz olayın verisini okuma yetkisi olmalıdır. Örneğin görev

olaylarına abone olmak için görev görüntüleme yetkisi gerekir; yoksa istek reddedilir.

• Aynı olay ve aynı adres için ikinci kez abone olursanız yeni kayıt açılmaz, var olan

kayıt geri döner. Böylece bir akışı kapatıp açtığınızda aynı olay iki kez gelmez.

• Gönderilen istek imzalanır. İmza X-Workinno-Signature başlığında, giden webhook ile

aynı biçimde gelir.

• Adresiniz arka arkaya on kez yanıt vermezse abonelik askıya alınır. Yeniden abone

olduğunuzda kayıt tekrar açılır.

• Gönderilen veri kaydın kendisini değil, hangi kayıtta ne olduğunu söyler: olayın adı,

zamanı ve kaydın kimliği. Güncel hâli için o kimlikle ilgili uç noktadan kaydı çekersiniz.

Erişilebilen kaynaklar

API şu an dört kaynak için tam erişim sunar: Görevler, Müşteriler (kişi), Firmalar ve Projeler. Her kaynak için beş işlem vardır: listeleme, oluşturma, tek kayıt okuma, güncelleme ve silme.

İki kaynak da yalnız okunur: Web siteleri ve Form gönderimleri. Bunları listeleyebilirsiniz ama bu uçlardan yeni kayıt oluşturamazsınız. Dışarıdan site kurmak ya da form gönderimi eklemek için tasarlanmadılar; olaylara abone olduğunuzda gelen kaydın güncel hâlini çekebilmeniz için varlar.

GET /api/v1/websites?limit=20 GET /api/v1/form-submissions?formId=<kimlik>&sort=createdAt:desc

Görev yazarken durumu, önceliği ve tarihleri de gönderebilirsiniz. Bir görevin başlangıç veya bitiş tarihi verildiğinde önceliği kendiliğinden "Planlı" olur; önceliği "Planlı" dışında bir değere çevirdiğinizde ise tarihi kaldırılır (görev takvimden çıkar, tarih saklanır ve geri dönerseniz geri gelir). Bu iki kural birbirini iptal ettiği için tarih ile "Planlı" dışında bir önceliği aynı istekte gönderemezsiniz — böyle bir istek, sebebini söyleyen bir hatayla geri döner. İkisini ayrı isteklerde gönderin. Her işlem, o işlemi yapabilmek için anahtarın taşıması gereken yetkiyi de belirtir. Örneğin görev listelemek için anahtarın görev görüntüleme yetkisi olmalıdır.

Kaynakların ve uç noktaların tam listesini API ve Geliştirici sayfasında, her satırın gerektirdiği yetkiyle birlikte görürsünüz. Makine okunur tam şemayı ise OpenAPI şeması düğmesinden alırsınız; bu dosyayı kod üreten araçlara verebilirsiniz.

Yetkiler

API ve Geliştirici sekmesi yalnız çalışma alanı ayarlarını değiştirme yetkisi olanlara görünür; aynı yetki API Anahtarları sekmesi için de gerekir. Yetkiniz yoksa bu iki sekme şeritte hiç çıkmaz. API'yi gerçekten kullanmak için bir API anahtarı gerekir; anahtarın yapabilecekleri, ona verdiğiniz yetkilerle sınırlıdır. → API Anahtarları

İlgili: API Anahtarları, Otomasyonlar, Webhook Teslimatları