Geliştirici Dokümantasyonu

NotusFlow, dağıtık ve ölçeklenebilir mikroservis mimarisine sahiptir. Tüm servisler **.NET 10** platformunda geliştirilmiş olup **.NET Aspire** orkestrasyon motoru ile yönetilmektedir.

API istekleri oturum açınca verilen JWT ya da NotusFlow › API Token'ları sayfasından oluşturulan kişisel bir token (nf_…) ile doğrulanır. Token, sahibinin şirketi, rolleri ve izinleriyle bütün servislerde geçerlidir. Kiracı (Tenant) yalıtımı otomatik olarak DbContext seviyesinde uygulanır.

Süreç tetikleme, aktif kullanıcı görevlerini listeleme ve görev tamamlama işlemleri için YARP arkasındaki WorkflowExecution ve UserTasks uç noktalarını kullanın.

# 1. Yeni bir İş Akışı Örneği (Instance) Başlatmacurl -X POST https://gateway.notusflow.com/api/workflow-execution/start \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "definitionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "inputs": { "MusteriAdi": "Notussoft Yazılım", "SiparisTutari": 75000 } }'# 2. Bekleyen Kullanıcı Görevini Tamamlamacurl -X POST https://gateway.notusflow.com/api/user-tasks/task-9982/complete \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "OnayDurumu": "Approved", "Aciklama": "Bütçe onaylandı." }'

NotusFlow süreci tamamlandığında veya görev atandığında alıcı URL adresinize HMAC-SHA256 imzalı POST istekleri gönderilir.

bool VerifyWebhookSignature(string rawJsonBody, string receivedSignature, string secret) {using var hmac = new System.Security.Cryptography.HMACSHA256(Encoding.UTF8.GetBytes(secret));var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(rawJsonBody));var computedSignature = Convert.ToHexString(hash).ToLower();return string.Equals(computedSignature, receivedSignature, StringComparison.OrdinalIgnoreCase); }

NotusFlow ScriptingService altyapısı, form alanları ve iş akışı adımları üzerinde dinamik Roslyn C# betikleri yürütür. Kodlar ConcurrentDictionary ile temsilci (delegate) seviyesinde önbelleğe alınarak milisaniyelik hızla derlenir.

// Model verilerine erişim ve UI elemanı kontrolleridecimal siparisTutari = Convert.ToDecimal(Model.SiparisTutari ?? 0);string musteriTipi = Model.MusteriTipi?.ToString() ?? "Standart";decimal indirim = 0m;if (musteriTipi == "Premium" && siparisTutari > 50000m) { indirim = siparisTutari * 0.15m; UI.IndirimAlani.Visible = "true"; UI.OnayDugmesi.Disabled = "false"; }else{ UI.IndirimAlani.Visible = "false"; } Model.IndirimTutari = indirim; Model.NetToplam = siparisTutari - indirim;

NotusFlow AI mikroservisi, doğal dil komutları ile iş akışları oluşturmanıza ve kod tabanınızı indeksleyerek otomatik süreç önerileri sunmanıza imkan tanır.

NotusFlow bir MCP (Model Context Protocol) sunucusudur. Claude, ChatGPT, VS Code Copilot gibi bir yapay zekâ istemcisi süreçlerinizi okur, yeni bir süreç ya da mevcut sürecin yeni sürümünü hazırlar, doğrular, örnek veriyle dener ve onayınıza sunar. İstemci sizin yetkilerinizle ve yalnızca kendi şirketinizin verisiyle çalışır. Claude ve ChatGPT'de yalnızca adresi girersiniz; NotusFlow giriş ve onay ekranı açılır (OAuth). Claude Code, VS Code ve betikler kişisel API token'ıyla bağlanır.

1. Claude (web ve masaüstü): Settings › Connectors › Add custom connector. Ad olarak NotusFlow, adres olarak https://api.notusflow.com/mcp yazın ve Connect'e basın. NotusFlow'a giriş yapıp "İzin ver" dediğinizde bağlantı kurulur; token gerekmez, OAuth Client ID/Secret alanlarını boş bırakın.
2. ChatGPT: Ayarlar › Bağlayıcılar (geliştirici modu) › Oluştur. Adres olarak https://api.notusflow.com/mcp, kimlik doğrulama olarak OAuth seçin; aynı NotusFlow onay ekranı açılır.
3. Erişimi yönetin: Bağladığınız uygulamalar NotusFlow'da API Token'ları › Bağlı uygulamalar bölümünde görünür; "Erişimi iptal et" bir dakika içinde etkili olur.
4. Token ile bağlanacaksanız: NotusFlow'da API Token'ları sayfasından bir token oluşturun. Token yalnızca bir kez gösterilir; sizin yerinize işlem yapar, paylaşmayın ve gerekmeyince iptal edin.
5. Claude Code:

   claude mcp add --transport http notusflow https://api.notusflow.com/mcp \
     --header "Authorization: Bearer nf_..."

6. VS Code (Copilot): .vscode/mcp.json

   {
     "servers": {
       "notusflow": {
         "type": "http",
         "url": "https://api.notusflow.com/mcp",
         "headers": { "Authorization": "Bearer ${input:notusflow-token}" }
       }
     },
     "inputs": [
       { "type": "promptString", "id": "notusflow-token", "description": "NotusFlow API token", "password": true }
     ]
   }

7. Claude Desktop: claude_desktop_config.json (Node.js gerekir)

   {
     "mcpServers": {
       "notusflow": {
         "command": "npx",
         "args": ["mcp-remote", "https://api.notusflow.com/mcp",
                  "--header", "Authorization:Bearer ${NOTUSFLOW_TOKEN}"],
         "env": { "NOTUSFLOW_TOKEN": "nf_..." }
       }
     }
   }

8. Deneyin: "NotusFlow'da hangi süreçler var?" diye sorun. İstemci önce whoami ile kim olarak bağlandığını, sonra süreç listesini gösterir.

NotusFlow.Reporting mikroservisi, tamamlanan süreçlerin tamamlama sürelerini, darboğaz oluşturan görev adımlarını ve kullanıcı bazlı performans analizlerini REST API üzerinden sağlar.

Süreçler üzerindeki tüm veri değişiklikleri ve adım geçişleri değişmez (immutable) denetim günlüklerine kaydedilir.

NotusFlow API katmanı tüm yanıtlarında standart ApiResponse<T> sarmalayıcısını kullanır.

{ "success": true, "data": { "instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "Running" }, "error": null, "timestamp": "2026-07-22T12:00:00Z" }

Zamanlanmış bir tetikleyici, cron ifadesiyle ya da basit zaman seçiciyle çalışır ve bir veri kaynağındaki her yeni satır için bir süreç başlatır. İşlenen satırlar kayıt altına alındığı için aynı satır iki kez süreç açmaz. Veritabanı bağlantıları süreç tanımında değil, şifreli veri kaynağı kayıtlarında tutulur.

Yeni bir sağlayıcı eklemek için kod yazılmaz. Sağlayıcıyı bildirimsel bir tanımla anlatırsınız; tanım Integration:Providers ayarında saklanır ve tasarımcıdaki entegrasyon düğümünde operasyonlarıyla listelenir. Elle yazılmış bir konnektör aynı anahtarı kullanırsa tanımın yerine geçer.

{ "Key": "kargo-takip", "BaseUrl": "https://api.kargofirmasi.com", "AuthMode": "OAuth2ClientCredentials", "TokenPath": "/oauth/token", "IdempotencyHeader": "X-Idempotency-Key", "Operations": [ { "Key": "gonderi-olustur", "Method": "POST", "Path": "/v1/shipments", "IsWrite": true, "Inputs": ["alici", "adres", "agirlik"], "OutputMappings": { "takipNo": "trackingNumber" } } ] }

Süreç madenciliği ucu, bir tanımın geçmiş koşularından düğüm ve kenar istatistiklerini döndürür: her adımın medyan ve p95 süresi, hata sayısı ve her bağlantının kaç kez geçildiği. Tasarım tuvalindeki ısı haritası bu veriyi çizer.

Süreç testleri, bir akışı gerçek veri yazmadan senaryolara karşı koşturur. Senaryo, grafikten türetilir: hangi düğümde hangi kararın verileceğini ve hangi değerin döneceğini senaryo söyler, onay ve zamanlayıcı adımları koşucu tarafından sürülür.