Demo Talep Et
🔌

API Entegrasyonu

NetEsnaf REST API v1, dış uygulamalarınızın (mobil uygulama, e-ticaret sitesi, muhasebe/entegrasyon yazılımı) ERP verilerinize güvenli ve programatik erişimini sağlar. Tüm istek ve yanıtlar JSON (UTF-8) biçimindedir; kimlik doğrulama güvenli bir oturum anahtarı (token) ile yapılır.

📍 Yönetim > API Kılavuzu 🔐 Token ile kimlik doğrulama 🧩 7 modül grubu · 78+ uç nokta 🤖 OpenAPI 3.0.3 şeması

Bu bölüm ne işe yarar?

Kendi yazılımlarınızı NetEsnaf'a bağlamak, veri senkronizasyonu kurmak veya bir yapay zekâ asistanına otomatik entegrasyon yaptırmak istediğinizde API'yi kullanırsınız. Cari, ürün/stok, fatura, kasa/banka, sipariş, servis ve personel verilerinize dışarıdan güvenle erişebilir; fatura kesme, tahsilat işleme gibi işlemleri kendi uygulamanızdan yapabilirsiniz. Bu özellik yalnızca API lisansı olan firmalar içindir: lisansınızda API modülü tanımlı değilse kılavuz sayfası kilitli görünür ve sizi destek@datanetbilisim.com adresine yönlendirir.

Önemli — API adresi bu site (netesnaf.tr) DEĞİLDİR. API çağrılarını, NetEsnaf uygulamanıza giriş yaptığınız kendi adresinize yaparsınız — örneğin https://firmaniz.netesnaf.net/api/v1/... (veya size tanımlanan özel alan adınız). netesnaf.tr yalnızca tanıtım/pazarlama sitesidir; burada API çalışmaz, netesnaf.tr/api/v1 adresine istek atmayın. Aşağıdaki tüm örneklerde görülen /api/v1/... yolunun başına kendi NetEsnaf adresinizi ekleyin.
1

API'ye Giriş — Ne işe yarar, kimin için

Nerede: Yönetim > API Kılavuzu

API Kılavuzu ekranı; temel adresinizi, kimlik doğrulama yöntemini, ortak kuralları ve tüm uç noktaların referansını tek sayfada gösterir. Dış uygulamalarınızı buradaki bilgilere göre bağlarsınız.

🎯 Ne işe yarar

Mobil uygulamanızın, e-ticaret sitenizin veya muhasebe/entegrasyon yazılımınızın NetEsnaf verilerinize güvenli ve programatik erişimini sağlar. Tüm trafik JSON biçimindedir; kimlik doğrulama güvenli bir oturum anahtarı (token) ile yapılır.

💼 Neden kullanılır

Kendi yazılımlarınızı ERP'ye bağlamak, veri senkronizasyonu kurmak veya bir yapay zekâ asistanına otomatik entegrasyon yaptırmak istediğinizde kullanılır. Yalnızca API lisansı olan firmalar içindir; lisansınız yoksa kılavuz kilitli görünür ve satış temsilcinize yönlendirir.

Adım adım nasıl yapılır

  1. Yönetim menüsünden API Kılavuzu ekranını açın.
  2. Lisansınızda API modülü tanımlıysa kılavuzun tamamı (tanıtım, kimlik doğrulama, kurallar, uç nokta referansı, örnek) görünür; tanımlı değilse kilitli bir uyarı kartı görürsünüz.
  3. Temel adresi (kendi NetEsnaf uygulama adresiniz + /api/v1 — netesnaf.tr değil) ve genel şemayı (/{modül}/{işlem}) not edin.
  4. Önce kimlik doğrulama ile token alın, ardından istediğiniz uç noktaya istek atın.
  5. İsterseniz OpenAPI şemasını bir yapay zekâ asistanına vererek entegrasyonu otomatik kurdurun.

Butonlar / Seçenekler

OpenAPI 3.0 JSON
Tanıtım alanındaki bağlantı; makine-okunur şemayı (/api/v1/spec/openapi) yeni sekmede açar.Sonuç: Tarayıcıda OpenAPI JSON açılır; bir yapay zekâ asistanına verilebilir.
Tümünü Aç / Kapat
Uç nokta referansındaki tüm modül panellerini aynı anda açar veya kapatır.Sonuç: Bütün uç nokta tabloları görünür olur ya da gizlenir.
İpucu: Temel adres sabit değildir; örnek adreslerde host yerine kendi NetEsnaf uygulama adresinizi kullanın (bu tanıtım sitesi netesnaf.tr'yi değil). Genel şema: https://sizin-netesnaf-adresiniz/api/v1/{modül}/{işlem}. API lisansınız yoksa uç noktalar hiç çalışmaz; önce satış temsilcinizle iletişime geçin.
İlgili konular:Kimlik DoğrulamaUç NoktalarOpenAPI
2

Kimlik Doğrulama / Token Alma

Nerede: /api/v1/auth/login ve /api/v1/auth/refresh

Kullanıcı adı ve şifre ile 12 saat geçerli bir oturum anahtarı (token) alırsınız. Sonraki tüm isteklerde bu anahtarı gönderek kimliğinizi ve firmanızı doğrularsınız. Kısaca: token = firma.

🎯 Ne işe yarar

Veri uç noktalarına (cari, fatura, kasa vb.) erişim için gereken oturum anahtarını almanızı sağlar. Anahtar firmaya izole erişim verir; başka bir firmanın verisine geçmez.

💼 Neden kullanılır

API'deki veri uçları token olmadan çalışmaz. Anahtar 12 saat geçerlidir; süresi dolmadan yenilenebilir, dolduysa yeniden giriş yapmanız gerekir.

Adım adım nasıl yapılır

  1. POST /auth/login adresine JSON gövdeyle { "kullaniciadi": "...", "sifre": "..." } gönderin. (email / password alan adları da kabul edilir.)
  2. Yanıttaki token değerini ve bitiş zamanını (expireAt) uygulamanızda saklayın.
  3. Sonraki her istekte HTTP başlığına Authorization: Bearer <token> ekleyin.
  4. Süre dolmadan yenilemek için POST /auth/refresh adresini, elinizdeki geçerli token ile çağırın.
  5. Yenileme yalnızca geçerli ve süresi dolmamış anahtar için çalışır; süresi dolmuşsa yeniden giriş yapmanız istenir.
YaparsanızNe olur
Doğru kullanıcı adı ve şifre ile giriş yaparsanızToken, bitiş zamanı ve kullanıcı bilgileri (ad-soyad, e-posta) döner; anahtarı saklayıp kullanmaya başlarsınız.
Kullanıcı bulunamaz veya firma pasifseKimlik doğrulanamaz; giriş reddedilir (yetkisiz uyarısı).
Kullanıcı adı ya da şifreyi boş gönderirsenizEksik alan uyarısı döner; alanları tamamlayıp tekrar denersiniz.
Bir korumalı uca token göndermeden istek atarsanız"Token bulunamadı" uyarısıyla istek reddedilir; her korumalı istekte anahtar zorunludur.
İpucu: Anahtar 12 saat geçerlidir; uygulamanızda bitiş zamanını takip edip süre dolmadan yenileyin. Müşteri portalı (B2B) anahtarı bu genel API uçlarında kullanılamaz — ayrı bir anahtar türüdür ve kullanılırsa erişim reddedilir.
İlgili konular:GirişUç NoktalarHata Yönetimi
3

Yanıt Yapısı ve Genel Kurallar

Nerede: Tüm uç noktalar için ortak kurallar

Tüm uç noktalar aynı yanıt sözleşmesini ve aynı veri format kurallarını (sayfalama, tarih, tutar, silme davranışı) paylaşır. Bu ortak kuralları bilirseniz her uca özel tahmin yapmadan tutarlı kod yazarsınız.

🎯 Ne işe yarar

Yanıtları doğru ayrıştırmanızı ve geçerli veri göndermenizi sağlar. Liste, tekil ve hata yanıtlarının ortak biçimi tek yerde tanımlıdır.

💼 Neden kullanılır

Sağlam bir entegrasyon her yanıtı aynı mantıkla işlemelidir. Ortak kurallar sayesinde tek bir işleme ve doğrulama mantığı tüm uçlar için yeterli olur.

Adım adım nasıl yapılır

  1. Liste yanıtlarını { status, data:[...], meta:{ sayfa, limit, toplam, toplam_sayfa } } yapısında bekleyin.
  2. Tekil/işlem yanıtlarını { status:true, data:{...} } veya { status:true, message, data:{id} } olarak işleyin.
  3. Hataları { status:false, message } olarak yakalayın — her yanıtta önce status alanına bakın.
  4. Sayfalama için ?sayfa=1&limit=50 kullanın (limit en fazla 200).
  5. Tarihleri YYYY-AA-GG, tutar ve miktarı nokta ondalıklı (örn. 1250.50) gönderin.
  6. Silme işlemlerinin yumuşak silme olduğunu unutmayın: kayıt pasife alınır, fiziksel olarak silinmez.
YaparsanızNe olur
Bir liste ucuna istek atarsanızDurum + veri dizisi + sayfalama bilgisi (sayfa/limit/toplam/toplam_sayfa) döner; toplam sayfa ile döngü kurabilirsiniz.
Detay ya da kaydet/sil işlemi yaparsanızDurum + tek bir kayıt nesnesi (veya mesaj + oluşan/etkilenen kaydın kimliği) döner.
Bir kaydı silersenizKayıt fiziksel silinmez, pasife alınır; bağlı kayıtlar korunur (örn. fatura silinince stok ve cari geri alınır).
İpucu: limit değeri 200'ü aşamaz; daha fazla veri için sayfa numarasını artırın. Tutarlarda virgül değil nokta kullanın, aksi halde geçersiz alan uyarısı alabilirsiniz.
İlgili konular:Hata YönetimiUç Noktalar
4

Uç Noktalar (Modül Modül Özet)

Nerede: Uç nokta referansı — genel şema /api/v1/{modül}/{işlem}

Kullanılabilir tüm uç noktalar modül gruplarına göre listelenir: yöntem (GET/POST), yol, ne yaptığı ve parametreleri. Zorunlu alanlar koyu gösterilir. GET okuma, POST yazma/silme içindir. Bu liste OpenAPI şemasıyla birebir aynıdır.

🎯 Ne işe yarar

Hangi verinin nasıl okunacağını veya yazılacağını görmenizi ve entegrasyon akışınızı planlamanızı sağlar. Katalog tek kaynaktır; ekrandaki tablolar ile makine-okunur şema hiç ayrışmaz.

💼 Neden kullanılır

İhtiyacınız olan işlemi (liste, detay, kaydet, sil, durum değiştir vb.) doğru yol ve parametrelerle çağırmak için başvuru noktanızdır.

Adım adım nasıl yapılır

  1. İlgili modül başlığına tıklayarak paneli açın: Cari, Ürün/Stok, Fatura, Kasa/Banka, Sipariş, Servis, Personel, Takvim.
  2. Yöntem, Yol, Ne yapar ve Parametreler sütunlarını inceleyin.
  3. GET uçlarında parametreleri adres sonuna (?ad=değer), POST uçlarında JSON gövdeye koyun.
  4. Zorunlu (koyu) alanları mutlaka gönderin; dizi alanlar (örn. satırlar) "(= dizi)" etiketiyle işaretlidir.
  5. Tam tipler ve teknik detay için OpenAPI şemasını (/api/v1/spec/openapi) kullanın.

Modül grupları ve kapsam

Modül grubuNeler yapabilirsiniz
Cari (13 uç)Müşteri/tedarikçi listesi, detay, kaydet, sil; bakiye ve bakiye raporu; hareketler; gruplar (kaydet/sil); yetkililer (ekle/sil).
Ürün / Stok (26 uç)Ürün listesi, detay, kaydet, sil; stok bakiye ve hareketler; stok fişi (kaydet/detay/sil); gruplar, birimler, depolar, seri numarası; abonelik (liste, detay, kaydet, sil, yenile, yaklaşanlar, istatistik).
Fatura (4 uç)Fatura listesi, detay, kaydet, sil. Satış ve alış faturası; kalem detayı satırlar dizisiyle gönderilir. Silmede stok ve cari geri alınır.
Kasa / Banka (16 uç)Kasa/banka listesi, güncel durum, detay, kaydet, sil; hareketler; tahsilat/ödeme fişi; virman; işlem tipleri; masraf fişi ve masraf kartı.
Sipariş (6 uç)Sipariş listesi, detay, kaydet, durum değiştir, durumlar, sil. Alınan ve verilen siparişler; silmede rezerve stok geri alınır.
Servis (19 uç)İş emri (liste/detay/kaydet/durum güncelle/sil), talep, cihaz, kategori, bakım anlaşması ve işçilik süresi ekleme.
Personel (1 uç)Personel listesi (arama, koda göre, limitli) — yalnızca okuma.
Takvim (4 uç)Takvime dışarıdan etkinlik/hatırlatma yazma: liste (tarih/tip/arama), ekle, güncelle, sil. Yalnızca elle/harici eklenen etkinlikler yönetilir; fatura vadesi, servis randevusu gibi modülden gelen otomatik olaylara dokunulmaz.

Butonlar / Seçenekler

Tümünü Aç / Kapat
Tüm modül panellerini toplu açar veya kapatır.Sonuç: Bütün uç nokta tabloları görünür ya da gizli olur.
Modül başlığı
Akordeon başlığına tıklayınca ilgili modülün uç nokta tablosunu açar veya kapatır.Sonuç: O modülün endpoint listesi görünür.
İpucu: Kaydet uçlarında kimlik (id) gönderirseniz güncelleme, göndermezseniz yeni kayıt oluşur; cari kaydette yalnızca gönderdiğiniz alanlar güncellenir. Fatura ve sipariş kaydette satırlar dizisi zorunludur; fatura satırında en az ürün, miktar, birim fiyat ve KDV oranı bulunur.
İlgili konular:Kimlik DoğrulamaYanıt KurallarıOpenAPIUçtan Uca Örnek
5

İş Takip (CRM) Ucu — Aday, Görüşme, Fırsat

Nerede: /api/v1/istakip/... — İş Takip ve Entegrasyon/API modülleri gerekir

Web sitesi formundan, WhatsApp botundan veya otomasyon akışınızdan gelen kişiyi İş Takip (CRM) modülüne mükerrer kayıt açmadan yazarsınız. Aday kaydı ucu «varsa güncelle, yoksa oluştur» mantığıyla çalışır: telefon numarası biçim farkı gözetmeksizin (boşluk, parantez, +90) tanınır ve mevcut aday güncellenir. Telefon yoksa e-posta ikincil anahtardır.

Neden önemli? Otomatik yazmaya çalışan bir akış, koruma olmadan her mesajda yeni aday kartı açar; CRM aynı kişinin kopyalarıyla dolar, görüşme geçmişi parçalanır ve iki temsilci aynı kişiyi ayrı ayrı arar.

Tipik akış

  1. POST /auth/login ile token alın.
  2. GET /istakip/durumlar ile geçerli kod sözlüklerini okuyun (kaynaklar, aday durumları, fırsat aşamaları, görüşme türleri). Değerleri tahmin etmeyin.
  3. POST /istakip/ilgilenenkaydet ile adayı yazın. En az ad veya firma gönderin; telefon gönderirseniz mükerrer koruma çalışır.
  4. Yanıttaki olusturuldu alanına bakın: true = yeni aday açıldı, false = mevcut aday güncellendi. Karşılama mesajınızı buna göre ayırabilirsiniz.
  5. POST /istakip/gorusmekaydet ile her teması not olarak düşün (ilgilenen_id veya cari_id zorunlu).
  6. İş somutlaşınca POST /istakip/firsatkaydet ile fırsat açın, POST /istakip/firsatasamaguncelle ile aşamayı ilerletin.
  7. Takip için GET /istakip/ilgilenenler (durum, kaynak, tarih, telefon filtreli) ve GET /istakip/gorusmeler (hatırlatma tarihi filtreli) uçlarını kullanın.

İş Takip uç noktaları (tümü /api/v1/istakip/...)

Yöntem · YolNe yapar
GET durumlarGeçerli kod sözlükleri: kaynaklar, aday durumları, fırsat aşamaları, görüşme türleri. Değerleri buradan okuyun.
GET gruplarİlgilenen (aday) gruplarının listesi (ad + renkler).
POST ilgilenenkaydetAday ekle/güncelle (UPSERT). Telefon (yoksa e-posta) ile eşleştirir; mükerrer açmaz. Yanıtta olusturuldu true/false.
GET ilgilenenlerAday listesi (durum, grup_id, kaynak, telefon, başlangıç/bitiş, arama filtreleri).
GET ilgilenendetay?id=Tek adayın detayı + son 20 görüşmesi + fırsatları.
POST ilgilenendurumguncelleAday durumunu güncelle (1-5). 7 "Tekrar Aranacak" API'de kabul edilmez.
POST ilgilenensilAdayı pasife alır (yumuşak silme).
POST gorusmekaydetGörüşme/not ekle. ilgilenen_id veya cari_id zorunlu; adayın son görüşme tarihi güncellenir.
GET gorusmelerGörüşme listesi (ilgilenen, tür, yapıldı, hatırlatma tarihi filtreli).
POST gorusmeyapildiGörüşmeyi "yapıldı" işaretle (opsiyonel not). Yeni görüşme için ayrıca gorusmekaydet kullanılır.
POST gorusmesilGörüşmeyi pasife alır.
POST firsatkaydetFırsat (teklif süreci) oluştur. ilgilenen_id veya cari_id/musteri_ad zorunlu; aşama verilmezse 1 (İlk Konuşma).
GET firsatlarFırsat listesi (aşama, ilgilenen_id, cari_id, tarih filtreli); bekleme günü ile.
POST firsatasamaguncelleAşamayı ilerlet (1-6). 5 = Anlaştık (kazanıldı) kapanma tarihi yazar.
POST firsatolmadiFırsatı kaybedildi kapat. id + olmadi_neden (fiyat/rakip/zamanlama/vazgecti/diger) zorunlu; iş Olmayan İşler'e taşınır, bağlı aday "Olmadı" olur.
POST firsatsilFırsatı pasife alır.
İpuçları
  • Adayın ilk geldiği kaynak (WhatsApp, web, telefon...) korunur; sonraki güncellemelerde ezilmez, böylece Kaynak Analizi raporu doğru kalır.
  • Gönderilmeyen veya boş gönderilen alan mevcut değerini korur. Bir alanı boş string göndererek temizleyemezsiniz.
  • Telefonu 7 haneden kısa gönderirseniz eşleştirmede kullanılmaz (çöp değerlerin farklı kişileri tek kartta birleştirmesini önlemek için); numara yine kaydedilir.
  • /istakip/durumlar listesinde guncellenebilir alanı false olan durumu göndermeyin.
  • Silme uçları kaydı tamamen silmez, pasife alır.
  • Adayı cari karta dönüştürme API'de yoktur — bu adım bilerek panelde, insan kararına bırakılmıştır.
  • Fırsatı kazanıldı kapatmak için firsatasamaguncelle ile asama=5 (Anlaştık); kaybedildi için firsatolmadi ucunu (neden zorunlu) kullanın.
  • Bir adayın tüm geçmişini (görüşmeler + fırsatlar) tek çağrıda almak için GET /istakip/ilgilenendetay?id= kullanın; grup renk sözlüğü için GET /istakip/gruplar.
  • Bu uçlar hem İş Takip (CRM) hem API (Entegrasyon) lisansını gerektirir; biri yoksa istek 403 döner.
6

Takvim Ucu — Dışarıdan Etkinlik / Hatırlatma Yazma

Nerede: /api/v1/takvim/... — Entegrasyon/API modülü gerekir

Kendi web siteniz, mobil uygulamanız veya otomasyon akışlarınız (n8n gibi) NetEsnaf takvimine etkinlik, hatırlatma ve görev yazabilir; güncelleyebilir, silebilir ve tarih aralığına göre listeleyebilir. Böylece randevu ya da hatırlatmayı hem dışarıda hem NetEsnaf'ta ikinci kez elle girmeniz gerekmez.

Neden önemli? Aynı bilgi iki yere elle girildiğinde biri er ya da geç unutulur; takvim eksik kalır ve randevu kaçar. İş büyüdükçe veri girişi yükü ve insan hatası artar.
Dikkat: API yalnızca dışarıdan eklenen etkinlikleri yönetir. Fatura vadesi, çek vadesi, servis randevusu gibi modüllerden otomatik düşen olaylar bu uçlarla değiştirilemez ve silinemez; böylece modül kaynaklı kayıtlar yanlışlıkla bozulmaz.

Tipik akış

  1. POST /auth/login ile token alın.
  2. POST /takvim/ekle ile etkinlik yazın. baslik ve baslama zorunludur; tarih biçimi YYYY-MM-DD HH:MM.
  3. tip değeri: 1=Görev, 2=Hatırlatma, 3=Bilgi Notu. Belirli bir kullanıcıya atamak için kullanici_id gönderin.
  4. Dönen data.id değerini saklayın; güncelleme ve silme bu kimlikle yapılır.
  5. POST /takvim/guncelle kısmi çalışır — yalnız gönderdiğiniz alanlar değişir.
  6. GET /takvim/liste ile tarih aralığına göre listeleyin (baslangic, bitis, tip, arama filtreleri).
  7. POST /takvim/sil ile etkinliği kaldırın.
İpuçları
  • GET /takvim/liste yalnız manuel/harici etkinlikleri döndürür; modül kaynaklı olaylar (fatura vadesi vb.) bu uçta çıkmaz. Onları ilgili modülün kendi ucundan sorgulayın.
  • Tarihleri her zaman YYYY-MM-DD HH:MM biçiminde gönderin.
  • Aynı randevuyu iki kez yazmamak için dış sistemdeki kaydınızla dönen id değerini eşleştirip saklayın; ikinci çağrıda ekleme yerine güncelleme yapın.
  • Uç, Entegrasyon/API modülü lisansı gerektirir.
7

OpenAPI Şemasını Alma ve Yapay Zekâya Verme

Nerede: /api/v1/spec/openapi — token gerekmez

Tüm uç noktaların makine-okunur OpenAPI 3.0.3 spesifikasyonunu tek bir JSON olarak alırsınız. Bunu bir yapay zekâ asistanına veya kod üretim aracına verip entegrasyonu otomatik kurdurabilirsiniz.

🤖 Örnek OpenAPI şemasını aç → yapay zekâya ver Canlı örnek netesnaf.net üzerinden sunulur; kendi çağrılarınızı kendi NetEsnaf adresinize yaparsınız.

🎯 Ne işe yarar

Elle her uca kod yazmak yerine, şemayı bir asistana verip istemci kodunu otomatik ürettirmenizi sağlar. Şemadaki sunucu adresi kendi alan adınızdan üretilir; demo ve ürün ortamı otomatik ayrışır.

💼 Neden kullanılır

Entegrasyonu kurmanın en hızlı yolu budur. Şema ile ekrandaki tablolar aynı kaynaktan üretildiği için doküman ile gerçek davranış arasında uyumsuzluk (drift) olmaz.

Adım adım nasıl yapılır

  1. Tarayıcıdan veya bir HTTP GET isteğiyle /api/v1/spec/openapi adresini açın (token gerekmez).
  2. Dönen JSON'u kaydedin ya da adresi doğrudan yapay zekâ asistanınıza / kod üretim aracınıza verin.
  3. Asistana "bu şemaya göre istemci oluştur" veya "şu işlemi yap" gibi talimat verin.
  4. Şemadaki sunucu adresinin kendi alan adınızdan üretildiğini doğrulayın (adres sabit değildir).
  5. Güvenlik yöntemi token (JWT) olduğundan, üretilen istemcide önce giriş yapıp token alma adımını eklettirin.

Butonlar / Seçenekler

OpenAPI 3.0 JSON
Tanıtım alanındaki bağlantı; şema adresini yeni sekmede açar.Sonuç: Tam OpenAPI JSON şeması tarayıcıda görünür.
İpucu: Şema token istemez, ama üretilen istemci veri uçları için token gerektirir — giriş adımını atlamayın. Şema ile kılavuz tabloları aynı kaynaktan üretildiği için asla uyuşmazlık olmaz.
İlgili konular:Uç NoktalarKimlik DoğrulamaGiriş
8

Sağlık Kontrolü (Health Check)

Nerede: /api/v1/health/check — token gerekmez

API'nin ayakta olup olmadığını token gerektirmeden hızlıca test edersiniz. Entegrasyon öncesi en basit bağlantı doğrulamasıdır.

🎯 Ne işe yarar

API'nin erişilebilir olduğunu tek bir istekle doğrulamanızı sağlar. Kimlik doğrulama gerektirmez.

💼 Neden kullanılır

Entegrasyonu kurmadan önce veya bir izleme (monitoring) sisteminde erişilebilirliği kontrol etmek için idealdir.

Adım adım nasıl yapılır

  1. GET /api/v1/health/check adresine istek atın (token göndermenize gerek yok).
  2. Yanıtta durum, servis adı (NetEsnaf API), sürüm (v1) ve zaman bilgisini kontrol edin.
  3. Alternatif olarak /api/v1/health/ping veya /api/v1/system/ping adreslerini kullanabilirsiniz.
  4. Yanıt başarılıysa ve durum olumluysa API erişilebilir demektir.
İpucu: Sağlık uçları kimlik doğrulama istemez; izleme için idealdir. Yanıt gelmiyorsa önce alan adınızı ve /api/v1 yolunu, sonra lisansınızı kontrol edin.
İlgili konular:GirişKimlik Doğrulama
9

Hata / Durum Yönetimi Kuralları

Nerede: Tüm uç noktalar için ortak hata sözleşmesi

API'nin döndürdüğü HTTP durum kodlarını ve hata yanıt yapısını bilirseniz entegrasyonunuz hataları doğru yakalar. Hata sözleşmesi tüm uçlarda aynı olduğu için tek bir yakalama mantığı yeterlidir.

🎯 Ne işe yarar

Token geçersizse, yanlış anahtar türü kullanıldıysa, uç yoksa, alan eksikse veya sunucu hatası olursa farklı davranmanızı sağlar. Her yanıtta önce durum alanına bakarsınız.

💼 Neden kullanılır

Sağlam bir entegrasyon her yanıtı kontrol etmelidir. Ortak hata biçimi sayesinde tüm hataları tek bir mantıkla ele alabilirsiniz.

Adım adım nasıl yapılır

  1. Her yanıtta önce status alanına bakın; false ise message değerini okuyun.
  2. Durum kodlarını işleyin (aşağıdaki tablo).
  3. Yetkisiz (401) alınca token'i yenileyin ya da yeniden giriş yapın.
  4. Eksik/geçersiz alan (422) alınca gönderdiğiniz zorunlu alanları ve format kurallarını (tarih/tutar) kontrol edin.
  5. Sunucu hatasında (500) yanıt yine JSON kalır; destek@datanetbilisim.com ile iletişime geçin.
Durum koduAnlamı ve ne yapmalısınız
200 / 201Başarılı / oluşturuldu. İşleme devam edin.
401 — YetkisizToken yok, geçersiz, süresi dolmuş veya eşleşen kullanıcı yok / firma pasif. Token yenileyin ya da yeniden giriş yapın.
403 — YasakYanlış anahtar türü (örn. müşteri portalı anahtarı genel API'de kullanılmış). Doğru anahtarı kullanın.
404 — BulunamadıVar olmayan bir yol çağrıldı. Katalogdaki geçerli yolu kullanın.
422 — GeçersizZorunlu alan eksik veya geçersiz. Gönderdiğiniz alanları ve formatı düzeltin.
500 — Sunucu hatasıBeklenmeyen bir hata. Yanıt yine JSON kalır (ham hata sayfası dönmez); destekle iletişime geçin.
İpucu: Tüm hatalar aynı { status:false, message } yapısındadır; tek bir hata yakalama mantığı yeterlidir. 401 ile 403'ü ayırın: 401 kimlik sorunu (yeniden giriş), 403 yanlış anahtar türü. Web uygulamalarından çapraz-kaynak (cross-origin) çağrılar da desteklenir.
İlgili konular:Kimlik DoğrulamaYanıt Kuralları
10

Uçtan Uca Örnek: Satış Faturası Kes

Nerede: Pratik akış — giriş > cari bul > fatura kes > tahsilat

Token almadan faturayı kesip tahsilat işlemeye kadar tipik bir entegrasyon akışını adım adım gösterir. Gerçek bir iş akışının nasıl zincirlendiğini görmek entegrasyonu hızlandırır.

🎯 Ne işe yarar

Uç noktaları tek tek okumak yerine, gerçek bir satış akışının uçtan uca nasıl kurulacağını gösterir.

💼 Neden kullanılır

Kendi uygulamanızdan otomatik fatura kesme ve tahsilat işleme senaryosunu en kısa yoldan hayata geçirmek için başvuru akışıdır.

Adım adım nasıl yapılır

  1. Token alın: POST /auth/login ile kullanıcı adı/şifre gönderip anahtarı alın.
  2. Cariyi bulun: GET /musteritedarikci/liste?arama=... ile müşteriyi bulun, ilk sonucun kimliğini (data[0].id) alın.
  3. Faturayı kesin: POST /fatura/kaydet ile satış faturası tipi, fatura tarihi, cari ve satırlar dizisini gönderin; yanıtta kaydın kimliği ve evrak numarası döner.
  4. (Opsiyonel) Tahsilatı işleyin: POST /kasa/fiskaydet ile kasa, tahsilat tipi, tarih ve tutarı gönderin; cari bakiyesi güncellenir.
  5. Her adımda (giriş hariç) Authorization: Bearer <token> başlığını eklemeyi unutmayın.
AdımNe olur
1 — GirişToken üretilir; sonraki adımlar için kimlik sağlanır.
2 — Cari bulEşleşen cari(ler) döner; faturaya bağlanacak cari belirlenir.
3 — Fatura kesSatış faturası oluşur; stok ve cari hareketi otomatik işlenir, evrak numarası döner.
4 — Tahsilat (opsiyonel)Tahsilat fişi oluşur, cari bakiyesi güncellenir; fatura karşılığında ödeme kayda geçer.
İpucu: Fatura ve tahsilat türlerini karıştırmayın (satış faturası ile alış, tahsilat ile ödeme ayrı tiplerdir). Tarihleri YYYY-AA-GG, tutar ve birim fiyatı nokta ondalıklı gönderin. Fatura satırlarında en az ürün, miktar, birim fiyat ve KDV oranı bulunmalıdır.
İlgili konular:Kimlik DoğrulamaUç Noktalar
← Tüm ModüllerDemo Talep Et →