Netsis REST API Kullanım Rehberi: Kurulum ve İlk İstek

Kısa cevap: Netsis REST API, sunucunuza kurulan REST servisi üzerinden token tabanlı kimlik doğrulama ile çalışır. Etkinleştirme süreci lisans kontrolü, servis kurulumu, API kullanıcısı tanımı ve port/HTTPS yapılandırmasından oluşur. İlk istek akışı her zaman aynıdır: önce token alınır, sonra bu token ile veri çağrısı yapılır. Endpoint adları ve parametreler sürüme göre değiştiği için kendi sürümünüzün dokümantasyonunu esas alın.

Netsis’i dış sistemlere bağlamak isteyen geliştiricilerin ilk sorusu genellikle aynı: “REST API’yi nasıl açarım, ilk isteği nasıl atarım?” Bu rehber tam olarak bu sorunun cevabı. Entegrasyon senaryolarını (e-ticaret, kargo, banka) ayrı bir yazıda ele almıştık; burada ise işin teknik başlangıç tarafına odaklanıyoruz: kurulum, yetkilendirme, ilk istek ve sahada en sık gördüğümüz hatalar.

Netsis’te REST API Hangi Sürümlerde Var?

Netsis ailesinde programatik erişim iki ana kanaldan sağlanır:

REST API: Modern, JSON tabanlı erişim. Özellikle Wings ailesinde ana entegrasyon kanalıdır; Netsis 3 tarafında da uygun sürüm ve lisansla REST servisi kullanılabilir.
SOAP / Web Service (NetOpenX): Netsis 3’ün klasik entegrasyon yöntemi. XML tabanlıdır ve uzun yıllardır sahada çalışan çok sayıda entegrasyon bu kanalı kullanır.

Hangi kanalın sizin kurulumunuzda aktif olduğu; sürümünüze, lisans paketinize ve sunucu kurulumunuza bağlıdır. Yeni bir projeye başlamadan önce mutlaka mevcut sürümünüzün API desteğini doğrulayın — emin değilseniz lisans ekranından kontrol edebilir veya bayinize sorabilirsiniz.

REST API’yi Etkinleştirme: Genel Adımlar

Kurulum ayrıntıları sürümden sürüme değişse de süreç her zaman şu iskeleti izler:

Lisans kontrolü: REST/web servis erişimi ayrı bir entegrasyon lisansı gerektirebilir. Mevcut paketinizde bu hakkın olup olmadığını önce doğrulayın.
Servis kurulumu: REST servisi, Netsis’in çalıştığı sunucuya kurulur ve bir Windows servisi ya da web uygulaması olarak ayağa kaldırılır. Servisin SQL Server’a ve Netsis veritabanlarına erişebildiğinden emin olun.
API kullanıcısı tanımlama: Entegrasyonun kullanacağı kullanıcıyı Netsis tarafında tanımlayın ve hangi şirket/şube/dönem üzerinde çalışacağını netleştirin.
Port ve güvenlik duvarı: Servisin dinlediği portu belirleyin; yalnızca ihtiyaç duyan sistemlerin erişebileceği şekilde güvenlik duvarı kuralı yazın.
HTTPS yapılandırması: Servis dışarıya açılacaksa mutlaka geçerli bir SSL sertifikası bağlayın.
Duman testi: Tarayıcı veya bir API istemcisi (Postman vb.) ile servisin ayakta olduğunu doğrulayın.

Bu adımlardan herhangi birinde sürüme özgü bir ekran veya parametre arıyorsanız, tahmin etmek yerine sürüm dokümantasyonunuza bakın; oradaki adlandırmalar sürümler arasında farklılık gösterebilir.

Kimlik Doğrulama ve Token Mantığı

Netsis REST API, yaygın API’lerdeki token tabanlı modeli izler:

İstemci, kimlik bilgilerini (API kullanıcısı, şifre ve şirket/şube/dönem bağlamı) token uç noktasına gönderir.
Servis, sınırlı süreli bir erişim token’ı döner.
Sonraki tüm istekler bu token’ı Authorization: Bearer <token> başlığında taşır.
Token süresi dolduğunda istemci yeni token alır.

Burada geliştiricilerin en sık atladığı nokta bağlam kavramıdır: Netsis çok şirketli ve dönemli bir yapıda çalıştığı için token, belirli bir şirket/şube/dönem kombinasyonuna bağlı üretilir. Yanlış bağlamla alınan token, “kullanıcı doğru ama veri boş/yetkisiz” tarzı kafa karıştıran sonuçlar doğurur.

İlk İstek: Kavramsal Akış

Aşağıdaki akış temsilîdir — gerçek uç nokta adları ve alan isimleri sürümünüze göre değişir, birebir kopyalamak yerine kendi dokümantasyonunuzdaki karşılıklarını kullanın:

1) POST  /api/.../token          → kimlik bilgileri gönderilir, token alınır
2) GET   /api/.../cariler        → Bearer token ile cari listesi çekilir
3) GET   /api/.../stoklar        → stok kartları ve bakiyeler okunur
4) POST  /api/.../siparisler     → dış sistemden gelen sipariş Netsis'e yazılır

Pratik önerimiz: İlk gün yalnızca okuma yapan bir istek çalıştırın (örneğin cari veya stok listesi). Yazma işlemlerine (sipariş, fatura, cari kartı) ancak okuma tarafı stabil çalıştıktan ve test veritabanında denedikten sonra geçin. Yazma isteklerinde zorunlu alanlar sürüme ve firma parametrelerinize göre değiştiği için ilk denemeleri mutlaka test ortamında yapın.

Sık Karşılaşılan Hatalar

Sahada en çok karşımıza çıkan dört hata sınıfı şunlar:

1. Yetki Hataları (401 / 403)

Kullanıcı adı veya şifre yanlış; kullanıcı Netsis tarafında pasif.
Token süresi dolmuş ama istemci yenilemiyor.
Token doğru fakat şirket/şube/dönem bağlamı yanlış seçilmiş.
API kullanıcısına ilgili modül veya işlem yetkisi verilmemiş.

2. Bağlantı Hataları

REST servisi durmuş (sunucu yeniden başlatıldıktan sonra otomatik kalkmamış olabilir).
Port güvenlik duvarında kapalı veya yanlış port hedefleniyor.
SSL sertifikası süresi dolmuş, istemci bağlantıyı reddediyor.

3. Lisans Hataları

Entegrasyon/web servis lisansı yok veya süresi dolmuş.
Eşzamanlı kullanıcı/oturum limiti dolu olduğu için servis yeni oturum açamıyor.

4. Veri Doğrulama Hataları

Zorunlu alan eksik (yazma isteklerinde en yaygın sebep).
Kod formatı Netsis’teki tanımla uyuşmuyor (stok kodu, cari kodu vb.).
Kapalı döneme veya yanlış şubeye kayıt atılmaya çalışılıyor.

Hata mesajları her zaman kök nedeni doğrudan söylemez; yetki ve lisans hataları özellikle birbirine benzer şekilde raporlanabilir. Takıldığınız noktada log dosyalarıyla birlikte gelin, birlikte bakalım.

Güvenlik En İyi Pratikleri

REST API açmak, ERP’nizin kapısını dışarıya açmaktır; şu asgari listeyi uygulamanızı öneriyoruz:

Ayrı API kullanıcısı: Entegrasyon asla gerçek bir personelin kullanıcısıyla çalışmamalı. Her entegrasyona ayrı kullanıcı açın ki log’larda kimin ne yaptığı ayrışsın.
En az yetki ilkesi: API kullanıcısına yalnızca ihtiyaç duyduğu modül ve işlemlerin yetkisini verin. Sadece stok okuyan bir entegrasyonun fatura kesme yetkisi olmamalı.
HTTPS zorunlu: Kimlik bilgileri ve ticari veri düz metin trafikle taşınmamalı; iç ağda bile HTTPS kullanın.
IP kısıtlama: Servise yalnızca entegrasyon sunucularının IP’lerinden erişilebilsin.
Loglama ve izleme: Başarısız oturum denemelerini ve yazma isteklerini loglayın; olağan dışı yoğunlukta uyarı üretin.
Parola ve token hijyeni: Kimlik bilgilerini kod içine gömmeyin; yapılandırma dosyası veya kasa (vault) kullanın, periyodik olarak değiştirin.

Sırada Ne Var: Entegrasyon Senaryoları

REST API’niz ayağa kalktıktan sonra asıl değer üreten kısım senaryolardır: pazaryeri stok senkronu, kargo takip numarası geri yazımı, banka ekstresi eşleştirme… Bu senaryoların kapsamını, sürelerini ve maliyet aralıklarını Netsis API ile üçüncü parti sistem entegrasyonu rehberinde ayrıntılı anlattık.

💡 API entegrasyon projelerinizde destek: 10+ yıllık Netsis deneyimimiz ve 2018’den beri yetkili bayi kimliğimizle 200+ müşterinin kurulum, entegrasyon ve destek süreçlerini yönetiyoruz. REST API kurulumundan uçtan uca entegrasyon projesine kadar her aşamada Netsis destek paketlerimizle yanınızdayız.

Sıkça Sorulan Sorular

Netsis REST API’yi kullanmak için hangi lisans gerekiyor?

REST/web servis erişimi çoğu kurulumda ayrı bir entegrasyon lisansına tabidir ve gereksinim sürüme göre değişir. Netsis 3 tarafında klasik kanal SOAP web servisleridir; REST desteği sürüm ve pakete bağlıdır. Projeye başlamadan önce mevcut lisans paketinizin API hakkını bayinizden veya Logo Yazılım’dan teyit edin.

Token neden alınıyor ama istekler boş veya yetkisiz dönüyor?

En yaygın neden, token alınırken seçilen şirket/şube/dönem bağlamının hedeflenen veriyle uyuşmamasıdır. İkinci sık neden API kullanıcısına ilgili modül yetkisinin verilmemiş olmasıdır. Önce doğru bağlamla token aldığınızı, sonra kullanıcı yetkilerini kontrol edin.

Netsis REST API’yi internete açmak güvenli mi?

Doğru yapılandırmayla evet: geçerli sertifikalı HTTPS, IP kısıtlaması, ayrı ve en az yetkili API kullanıcısı, güçlü parola ve loglama asgari şartlardır. Mümkünse servisi doğrudan internete açmak yerine VPN veya ters proxy arkasında tutmak riski daha da azaltır.

REST API ile hangi işlemler yapılabilir?

Sürüme göre değişmekle birlikte tipik olarak cari, stok, sipariş, fatura gibi temel nesnelerde okuma ve yazma işlemleri desteklenir. Kendi sürümünüzde hangi nesne ve alanların açık olduğunu dokümantasyondan doğrulayın; e-ticaret, kargo ve banka gibi uygulama senaryoları için API entegrasyon rehberimize göz atabilirsiniz.