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.

Üç kaynak da yalnız okunur: Web siteleri, Form gönderimleri ve Teklifler. Bunları listeleyebilirsiniz ama bu uçlardan yeni kayıt oluşturamazsınız. Dışarıdan site kurmak, form gönderimi eklemek ya da teklif açmak 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 GET /api/v1/quotes?status=accepted&sort=updatedAt:desc

Teklif listesi yalnız teklifleri döner; satışlar bu uçta görünmez. Tekliflerin görünürlüğü ürün görüntüleme yetkinizin kapsamını izler: yalnız kendi ürünlerinizi görebiliyorsanız yalnız onların teklifleri gelir.

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.

Bir de anahtarın kendini tanıttığı uç vardır. GET /api/v1/me hiçbir yetki aramaz, geçerli bir anahtar yeter; hangi çalışma alanına bağlı olduğunuzu, anahtarın canlı mı test mi olduğunu ve hangi yetkileri taşıdığını döner. Bağlantınızı sınamak ya da bir uca dokunmadan önce yetkiniz var mı bakmak için kullanışlıdır: yetki listesini önden okursanız 403 yemeden karar verirsiniz.

GET /api/v1/me

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ı