Koza Entegrasyon Zekâsı Entegrasyon Gereksinimleri Dokümanı

1) Amaç

Koza Entegrasyon Zekâsı, Koza AI çözümlerinin farklı ERP ve operasyonel sistemlerde hızlı kurulumu için standart bir
bağlantı ve veri eşleme (mapping) katmanı sağlar. Amaç; veri akışlarını güvenli, izlenebilir ve sürdürülebilir hale getirerek
“hazır olduğunuz gün” Koza zekâlarının kısa sürede devreye alınabilmesini sağlamaktır.

2) Kapsam

Veri erişim yöntemlerinin standardizasyonu
Koza Canonical Data Model (ortak şema) ile alan eşleme (mapping)
Değişiklik yakalama (CDC) / event-driven altyapı (varsa)
Kimlik doğrulama, yetkilendirme ve ağ güvenliği
Loglama, izleme ve entegrasyon sağlığı

3) Bağlanabilir Sistemler

Koza Entegrasyon Zekâsı aşağıdaki sistemlerle entegre olabilir:

Sistem	Örnek Veriler	Not
ERP	Sipariş, stok, üretim, finans, cari	Birincil kaynak
MES	Operasyon, duruş, OEE, iş emri gerçekleşen	Üretim zekâları için çok değerli
WMS	Lokasyon bazlı stok, toplama, sevkiyat	Stok/lojistik için önerilir
TMS	Rota, taşıma maliyeti, teslimat olayları	Lojistik zekâsını güçlendirir
CRM	Fırsatlar, pipeline, müşteri etkileşimi	Satış zekâsına derinlik
IoT/SCADA	Sensör, enerji, sıcaklık, titreşim	Bakım/kalite kestirim
e-Fatura/e-Arşiv	Fatura, e-belge durumları	Finans zekâsına hız
DWH/BI	Özet KPI, raporlar	Yönetim zekâsında hızlandırır

4) Entegrasyon Yöntemleri

4.1) API Entegrasyonu (REST / SOAP)

Tercih edilen: REST (JSON)
Desteklenen: SOAP (XML)
Pagination, filtreleme, tarih aralığı sorguları önerilir
Rate limit & retry politikası tanımlanır

4.2) Database View (Read-Only)

Koza için read-only kullanıcı
Tercih edilen: View/Stored Procedure
Zaman damgası alanı (UpdatedAt) önerilir

4.3) Message Queue / Stream (Event Driven)

Örnek: RabbitMQ, Kafka, Azure Service Bus vb.
Olay bazlı akışla gecikme azalır
Event şeması ve idempotency anahtarı zorunludur

4.4) Scheduled Export (JSON/CSV)

Belirli aralıklarla otomatik export
Dosya konumu: SFTP / Object Storage / Paylaşımlı klasör
Artımlı (incremental) export önerilir

5) Veri Sözleşmesi (Data Contract)

Koza, farklı sistemlerden gelen verileri ortak bir şemaya (Canonical Data Model) map ederek işler.
Bu sayede her “zekâ” için özel entegrasyon maliyeti düşer.

Alan	Açıklama	Zorunlu
entityType	Örn: customer, item, salesOrder, workOrder	Evet
entityId	Kayıt benzersiz kimliği	Evet
sourceSystem	ERP/MES/WMS vb.	Evet
occurredAt	Olay/oluş zamanı (ISO 8601)	Evet
updatedAt	Son güncelleme zamanı	Hayır
payload	Alanların gövdesi (JSON object)	Evet
hash	İçerik hash’i (idempotency)	Hayır

{
  "entityType": "salesOrder",
  "entityId": "SO-2026-001245",
  "sourceSystem": "ERP",
  "occurredAt": "2026-01-09T12:45:00+03:00",
  "updatedAt": "2026-01-09T12:46:10+03:00",
  "payload": { "customerCode": "C-0012", "lines": [ { "itemCode": "P-1001", "qty": 10 } ] },
  "hash": "sha256:...."
}

6) Olay Modeli (Event Model)

Event-driven altyapı varsa Koza, aşağıdaki tip olayları dinleyebilir:

created (kayıt oluşturuldu)
updated (kayıt güncellendi)
deleted (kayıt silindi – opsiyonel)
statusChanged (durum değişti: open → closed vb.)

Öneri: Her event, entityType + entityId + occurredAt ile izlenebilir olmalıdır.

7) Kimlik Doğrulama & Yetkilendirme

OAuth2 (önerilen)
API Key (IP whitelist ile birlikte)
mTLS (yüksek güvenlik ihtiyacı olan tesislerde)
RBAC: Koza erişimi sadece gerekli endpoint/view ile sınırlandırılmalıdır

8) Güvenlik & Ağ Gereksinimleri

SSL/TLS zorunlu
Koza sunucuları için IP whitelist önerilir
VPN / Site-to-Site (opsiyonel)
İç ağdan dış ağa çıkış kapalı ise “on-prem Koza Connector” kurulumu önerilir

On-Prem Connector: Koza Connector, iç ağdan veri toplayıp güvenli şekilde Koza AI’ye ileten hafif bir servis olarak konumlanır.

9) İzleme & Loglama

Entegrasyon sağlığı: başarısız istek sayısı, gecikme (latency), kuyruk birikimi
Veri bütünlüğü: eksik alan, referans kırılması, duplikasyon
Audit log: kim erişti, ne okudu, ne zaman

10) Hazırlık Kontrol Listesi

Kaynak sistemler (ERP/MES/WMS/CRM vb.) netleştirildi
Read-only erişim kullanıcıları açıldı
API/DB/View erişim yöntemleri belirlendi
Zaman damgaları (createdAt/updatedAt) sağlanabiliyor
Yetkilendirme (OAuth/API Key) hazır
Ağ erişimi (VPN/IP whitelist) planlandı
Loglama ve izleme gereksinimleri belirlendi

11) Örnek Endpoint & Kanal Seti

# API
/api/items
/api/customers
/api/sales-orders
/api/stock-levels
/api/work-orders
/api/invoices
/api/payments

# Event / MQ Topics
topic.erp.salesOrder.updated
topic.erp.stockLevel.updated
topic.mes.workOrder.statusChanged
topic.wms.shipment.created
topic.tms.trackingEvent.updated

# Webhook (opsiyonel)
/webhook/koza/notify

Yetkilendirme önerisi: OAuth2 / API Key / IP Whitelist + SSL/TLS (+ opsiyonel mTLS)