DİA Web Servis API: kendi yazılımınızı DİA'ya nasıl bağlarsınız?

DİA Web Servis API nedir?

DİA, kendi sunucunuza kurulmayan, bulutta çalışan bir ERP. Dışarıdan bağlanmanın tek resmi yolu JSON REST web servisi: veri okuma, ekleme, güncelleme, silme ve rapor çağırma işlemlerinin tamamı https://SUNUCUKODU.ws.dia.com.tr/api/v3/ altındaki modül uçlarına JSON gönderilerek yapılıyor. Servis adları modelden türetilmiş; cari kartın modeli scf_carikart ise servisleri scf_carikart_listele, scf_carikart_getir, scf_carikart_ekle, scf_carikart_guncelle ve scf_carikart_sil.

Bu yazı, DİA’nın geliştirici dokümantasyonunda (doc.dia.com.tr) yazan gerçekleri toplar ve üzerine bizim entegrasyon projelerinde uyguladığımız tasarım kurallarını ekler. Teknik gerçekler 2 Eylül 2026’da dokümandan doğrulandı; kendi kurulumunuzdaki servis listesi ve alan setleri için DİA’nın Servis İndeks’i esastır.

Bağlanmak için gereken dört şey

Gereken	Nereden gelir	Neye dikkat edilir
Api key	DİA'dan; uygulamanın amacı ve ayrıntıları e-postayla bildirilir	Yalnızca login çağrısında kullanılır, koda gömülmez
Servis kullanıcısı	DİA kullanıcı listesinde tanımlanır	"Web Servis Çağırabilir" işaretli olmalı; masaüstünde yapamadığı işi servisten de yapamaz
Sunucu kodu	Firmanın DİA sözleşmesinden	Adresin başındaki SUNUCUKODU parçası
Firma ve dönem kodu	DİA App'te firma listesi ve dönem listesinden	Login dışındaki her çağrıda zorunlu

Yetki modeli basit ve sert: servis, oturumu açan kullanıcının masaüstü yetkileriyle çalışır. Kullanıcıda “Cari Kart Listeleme” yetkisi yoksa scf_carikart_listele yetki hatası döner. Kullanıcı için “İzin Verilen IP’ler” tanımlandıysa çağrılar yalnızca o adreslerden kabul edilir — entegrasyon sunucusunun sabit IP’sini buraya yazmak ucuz ve etkili bir koruma. İletişim TLS 1.2 ve üzeriyle şifrelenir; 30 Ekim 2022’den beri daha eski protokoller kabul edilmiyor.

Oturum akışı: login, session_id, timeout

Her şey login ile başlar. Kullanıcı adı, şifre ve api key gönderilir; dönen msg alanı session_id’dir:

POST https://SUNUCUKODU.ws.dia.com.tr/api/v3/sis/json
Content-Type: application/json

{"login": {
  "username": "entegrasyon",
  "password": "•••",
  "disconnect_same_user": "True",
  "params": {"apikey": "•••"}
}}

{"code": "200", "msg": "b2d4820cc43f4d98a8c6698686b6d386"}

Başarısız girişte {"code": "401", "msg": "NOUSER"} döner. Oturumun ömrü 1 saat; yapılan her çağrı süreyi sıfırlar. Süre dolunca servis 419 LOGIN_TIMEOUT verir. Bizim ara katmanımız bu kodu yakalar, yeniden login olur ve isteği bir kez daha dener; çağrıyı yapan uygulama bunu hiç görmez.

Dikkat: disconnect_same_user "True" gönderildiğinde aynı kullanıcının açık oturumu düşürülür. İki ayrı uygulama aynı servis kullanıcısını paylaşırsa birbirlerini sürekli düşürür ve hata sebebi saatlerce anlaşılmaz. Her entegrasyon için ayrı kullanıcı tanımlayın.

Kontör ekonomisi: entegrasyon tasarımını belirleyen sayı

DİA dokümanı açık: her web servis çağrısı 0,0125 kontör düşer; login ve logout gibi bazı özel servisler düşürmez. Kontör bitince çağrılar 406 CREDIT_ERROR ile döner ve entegrasyon durur. IP kısıtı veya işlem sınırı yok — sınırı kontör koyuyor.

İki basit hesap, tasarımın neden önemli olduğunu gösterir:

• Saatte bir tüm cari listesini çekmek: ayda 720 çağrı, yani 9 kontör.
• Her siparişte ürün başına stok sorgulamak: ayda 5.000 sipariş için 62,5 kontör — ve bu sayı sipariş satırıyla çarpılınca büyür.

Bu yüzden kurduğumuz köprüler dört kuralla çalışır:

1. Artımlı çekme. Listeleme servislerine _date filtresi verilir; yalnızca son senkrondan sonra eklenen veya değişen kayıtlar alınır.
2. Dar kolon. params.selectedcolumns ile yalnız gereken alanlar istenir; yanıt küçülür, işleme hızlanır.
3. Sayfalama. limit ve offset ile büyük listeler parça parça alınır; limit: 0 tüm kayıtları döndürür ama DİA optimizasyon için değer girilmesini öneriyor.
4. Önbellek. Ürün ve fiyat gibi yavaş değişen veri kendi veritabanımızda tutulur; DİA’ya yalnız değişiklik için gidilir. Kalan kontör sis_kontor_sorgula ile izlenir ve eşik altına inince uyarı çıkar.

Listeleme örneği: son 24 saatte değişen cariler

POST https://SUNUCUKODU.ws.dia.com.tr/api/v3/scf/json

{"scf_carikart_listele": {
  "session_id": "b2d4820cc43f4d98a8c6698686b6d386",
  "firma_kodu": 34,
  "donem_kodu": 1,
  "filters": [{"field": "_date", "operator": ">=", "value": "2026-09-01"}],
  "sorts":   [{"field": "carikartkodu", "sorttype": "ASC"}],
  "params":  {"selectedcolumns": ["carikartkodu", "unvan", "bakiye"]},
  "limit": 200,
  "offset": 0
}}

Filtre operatörleri <, >, <=, >=, !, =, IN ve NOT IN; operatör verilmezse “içinde geçen” olarak çalışır. _date alanı kaydın son işlem tarihini tutar — artımlı senkronun anahtarı budur. Yanıt her zaman aynı iskelettedir: code, msg ve listeleme servislerinde result içinde satırlar. Ekleme ve güncelleme servisleri işlem yapılan kaydın key değerini ve sistem kaydını msg içinde döndürür.

Dokümandaki bir ayrıntı projede sürpriz yaratmasın: _listele servisleri veriyi modelden değil, ilgili ekrandan getirir. Fatura listesi servisi, DİA’daki Fatura Listesi ekranında görünen kolonları verir; ekranda olmayan bir alanı orada aramayın, _getir servisine gidin.

Hata kodları

Kod	Anlamı	Köprü ne yapar
200	İşlem başarılı	Sonucu işler
400	Parametre hatası; ayrıntı msg içinde	Kuyruğa alır, sorumluya gösterir; tekrar denemez
401	Yetki sorunu veya kullanıcı adı/şifre hatası	Durur, uyarı üretir
402 / 405	Lisans sorunu	Durur, uyarı üretir
406	Yeterli kontör yok	Kuyruğu bekletir, kontör alarmı çalar
419	Oturum zaman aşımı	Yeniden login, isteği tekrar eder
500 / 501	Geçersiz işlem veya sunucu hatası	Bekleyerek tekrar dener, üçüncüde sorumluya düşer

Firma bilgisi yanlış verildiğinde de yetki hatası (INSUFFICIENT_PRIVILEGES) alınabiliyor; “yetki yok” mesajının ilk kontrolü firma ve dönem kodudur.

E-belge servisleri: e-fatura, e-arşiv, e-irsaliye

E-Devlet modülünün servisleri .../api/v3/efa/json adresinde toplanır ve kontör düşer. Bir satış sisteminden DİA’ya giden faturanın tipik yolu şöyle:

1. efa_kayitli_kullanici_sorgula — alıcının vergi veya TC numarasıyla e-fatura mükellefi olup olmadığı ve posta kutusu adresi sorgulanır.
2. Mükellefse efa_efatura_olustur ve efa_efatura_gonder; değilse efa_earsiv_gonder.
3. efa_fatura_durum_sorgula ile belge durumu okunur, gelen ret veya kabul efa_efatura_redkabul akışında işlenir.
4. Sevkiyat tarafında efa_eirsaliye_olustur, efa_eirsaliye_gonder ve efa_eirsaliye_durum_sorgula aynı düzeni izler.

Senaryo seçimini, durum takibini ve hata kuyruğunu programdan bağımsız olarak e-fatura entegrasyonu rehberinde anlattık; DİA’da bu akışın her adımı yukarıdaki servislere karşılık gelir.

Test aracı ve demo sunucu

DİA, Windows, Linux ve macOS için bir Web Service Tester dağıtıyor. Araç servis adlarını ve örnek JSON çağrılarını gösteriyor, demo sunucuya çağrı atıp dönen cevabı inceletiyor. Projede ilk günün işi, hedef servislerin tamamını bu araçla bir kez çağırıp gerçek alan adlarını not etmektir; dokümandaki alan adıyla kurulumdaki alan adı her zaman birebir örtüşmez.

DİA’nın Logo, Netsis ve Mikro’dan farkı

Diğer programların ayrıntısı için Logo entegrasyonu, Netsis REST API ve Mikro entegrasyonu yazılarına bakın.

En sık kurulan DİA entegrasyon senaryoları

Entegrasyonda dikkat edilecek noktalar

1. Belge numarasıyla tekrarlanabilirlik. Ağ koptuğunda aynı sipariş ikinci kez gönderilmesin diye her kayıt kendi belge numarasıyla gönderilir; köprü aynı numarayı ikinci kez görünce yeni kayıt açmaz, mevcut kaydın durumunu döner.
2. Tek oturum, tek kullanıcı. Köprü oturumu bir yerde tutar ve bütün uygulamalar onun üzerinden geçer; her uygulama kendi login’ini atarsa oturumlar birbirini düşürür.
3. Kontör alarmı. sis_kontor_sorgula günlük çalışır; eşik altına inince sorumluya bildirim gider. Entegrasyonun kontör bitince durduğunu ay sonunda öğrenmek istemezsiniz.
4. Yetkiyi dar tutmak. Servis kullanıcısına yalnız gereken ekranların yetkisi verilir; api key ve şifre uygulama sunucusunda tutulur, tarayıcıya veya mobil cihaza inmez.

Bütçe ve süre

DİA köprüsü, kendi sisteminizin yanına ek modül olarak kurulur: kapsama göre 8.000 - 45.000 ₺ bandında, tek yönlü aktarım 2-3 haftada, çift yönlü sipariş-stok-fatura akışı 2-4 haftada devreye girer. Bantların tamamı fiyat sayfasında yazılı; DİA’nın kontör bedeli sizinle DİA arasındaki sözleşmeye göre ayrıca işler.

Hangi ekranların DİA’da kalıp hangi işin yanına yazılacağını netleştirmek için sürecinizi anlatın; servis listesi ve kontör hesabıyla birlikte ilk fazın kapsamını çıkaralım.

---

İlgili Bayi ve Sipariş Rehberleri

• B2B Bayi Sipariş Portalı Fiyatları 2026 — Toptancı ve distribütör bayi portalları maliyet analizi.
• Elle İş Maliyeti Hesaplayıcı — Manuel sipariş girişi ve mutabakat için harcanan yıllık emek kaybını hesaplayın.
• En İyi B2B Bayi Portalı Yazılımları 2026 — T-Soft, Ticimax, Logo ve özel bayi portalı incelemesi.
• Saha Satış ve Plasiyer Programı Fiyatları — Plasiyer mobil sipariş ve cari takip sistemleri.

Sıkça sorulan sorular

DİA Web Servis API nedir?

DİA ERP'nin JSON REST Web Service katmanıdır. Veri okuma, ekleme, güncelleme, silme ve rapor çağırma işlemleri https://SUNUCUKODU.ws.dia.com.tr/api/v3/ adresi altındaki modül uçlarına JSON gönderilerek yapılır. Servis adları modelden türetilir: scf_carikart_listele, scf_carikart_ekle, scf_siparis_ekle gibi.

DİA api key nasıl alınır?

Api key DİA tarafından verilir; uygulamanın amacını ve ayrıntılarını bildiren bir e-posta ile talep edilir. Api key yalnızca login çağrısında kullanılır; login ile alınan session_id sonraki bütün çağrılarda bu anahtarla ilişkilendirilir. Ayrıca DİA'da 'Web Servis Çağırabilir' işaretli ve yeterli yetkiye sahip bir kullanıcı, sunucu kodu, firma kodu ve dönem kodu gerekir.

DİA web servisi kontör düşer mi, ne kadar?

Evet. DİA dokümanına göre her web servis çağrısı 0,0125 kontör düşer; login ve logout gibi bazı özel servisler kontör düşürmez. Kalan kontör sis_kontor_sorgula servisiyle sorgulanır. Kontör bitince çağrılar 406 CREDIT_ERROR ile döner; bu yüzden entegrasyonda kontör alarmı ve çağrı sayısını azaltan tasarım şarttır.

DİA session (oturum) ne kadar sürer?

Oturum zaman aşımı 1 saattir ve yapılan her çağrı süreyi sıfırlar. Süre dolunca servis 419 LOGIN_TIMEOUT döner; doğru kurgu bu kodu yakalayıp sessizce yeniden login olmak ve isteği tekrar etmektir. Aynı kullanıcıyla ikinci bir login, disconnect_same_user parametresine göre öncekini düşürebilir; bu yüzden her entegrasyon için ayrı bir servis kullanıcısı tanımlanır.

DİA'da e-fatura ve e-arşiv web servisten gönderilebilir mi?

Evet. E-Devlet modülünün efa_ ön ekli servisleri vardır: efa_kayitli_kullanici_sorgula ile alıcının e-fatura mükellefi olup olmadığı sorgulanır, efa_efatura_olustur ve efa_efatura_gonder ile belge oluşturulup gönderilir, efa_fatura_durum_sorgula ile durum okunur; e-arşiv ve e-irsaliye için de karşılıkları bulunur. Bu servisler kontör düşer.

DİA veritabanına doğrudan bağlanabilir miyim?

DİA bulutta çalışan bir ERP olduğu için standart kurulumda veritabanına doğrudan bağlantı verilmez; okuma da yazma da web servis üzerinden yapılır. Raporlama için _listele servisleri ve rapor çağırma servisleri kullanılır. Bu, Logo veya Mikro gibi kendi sunucunuzda çalışan programlardan temel farkıdır.

İlgili rehberler

• Logo ve Netsis entegrasyon rehberi: REST API, Objects ve özel web/mobil arayüz köprüsü
• Nebim V3 Entegratör REST API: perakende ERP'nizi dış sistemlere nasıl bağlarsınız?
• Paraşüt API: kendi yazılımınızdan fatura kesmek ve e-faturayı tetiklemek

Hizmet sayfası: Entegrasyon hizmeti