1. Genel Bakış
Yazılım geliştiricilerin API sayesinde entegrasyonlar gerçekleştirebilmeleri amaçlanmaktadır. JSON REST Web Service çağrıları ile veri okuma, veriler üzerinde ekleme, değiştirme, silme işlemleri yapabilme, rapor çağırıp sonucunu çeşitli formatlarda alabilme gibi işlemler gerçekleştirilebilmektedir.
30 Ekim 2022 tarihi itibariyle, DİA Web Servislerini kullanmak için güvenli iletişim protokolü olarak TLS 1.2 ve üzeri sürümlerin kullanımı zorunlu hale gelecektir. Güvenlik gereksinimi nedeniyle yapılacak bu değişiklikten etkilenmemek için DİA Web Servislerini kullanan uygulamalarda gerekli değişikliklerin yapılması gerekmektedir. 30 Ekim 2022 tarihinden sonra sadece TLS 1.2 kullanımda olacaktır.
1.1. Nereden Başlamalıyız?
- Öncelikle Test Aracı (Dia Web Service Tester) aşağıdaki linkler üzerinden işletim sisteminize göre bilgisayarınıza kurarak başlayabilirsiniz.
- Bu araç sayesinde servis isimlerini ve örnek json çağrılarını gözlemleyebilir, demo sunucuya çağrılar atıp dönen cevapları inceleyebilirsiniz.
- Servis çağrılarında kontör düşme mantığı ve takibinin nasıl yapılacağı öğrenilmelidir.
- Servis çağırabilmek ilk adımı login olmak ve
session_idalmaktır. - Firma, dönem mantığını öğrenmek gerekiyor (Yetkili Firma, Dönem Bilgilerinin Alınması), neredeyse bütün servislerde firma, dönem bilgisi istenmektedir.
- Tüm servislerin detaylı açıklamalarının olduğu Servis İndex incelenebilir.
1.2. Kontör Takibi
Her web servis çağrısı için 0.0125 kontör düşmektedir. Bazı özel servislerden kontör düşülmemektedir (login, logout gibi). Kontör takip işlemleri için masaüstü istemciden Kontör Hareketleri (msj1900) ekranına bakılabilir. Mevcut kontör sayısı, hangi servis ne zaman çağrılmış, son kontör yüklemeleri gibi işlemler izlenebilir. Kontör yükleme işlemi de bu ekran üzerinden yapılabilir.
Kalan kontör sayısını servis ile sorgulayarak da öğrenebilirsiniz. Bunun için sis_kontor_sorgula servisini kullanabilirsiniz.
1.3. Güvenlik
Web servis çağrıları için oturum (session) açılması gerekmektedir. Bu kısım Session (Oturum) kısmında detaylı anlatılmaktadır. Oturum Dia sisteminde tanımlı olan kullanıcı bilgileriyle oluşturulmaktadır, bu yüzden yetkilendirme işleminin bu kullanıcıda itinayla yapılması gerekmektedir. Yani ilgili kullanıcının web servis yoluyla benzer işlemi yapabilmesi için masaüstü istemcide de yapabiliyor olması gerekmektedir. Örneğin masaüstünde “Cari Kart Listeleme” yetkisi yoksa, “scf_carikart_listele” servisini çalıştırırken yetki hatası alacaktır.
Kullanıcı için “İzin Verilen IP'ler” tanımlaması yapıldıysa, yalnızca belirtilen IP adreslerinde servis çağrılabilmektedir.
Haberleşme SSL ile şifrelenerek yapılmaktadır.
1.4. Servis İsimlendirmesi
Servis isimleri verilirken ilgili model bağlantıları kullanılmıştır. Örneğin cari kart bilgilerinin kayıtlı tutulduğu model ismi scf_carikart, ilgili servis isimlendirmeleri de scf_carikart_ekle, scf_carikart_getir, scf_carikart_guncelle, scf_carikart_listele, scf_carikart_sil gibi verilmiştir. Yine cari kart ile ilgisi olan ama modelle aslında çok ilgisi olmayan bazı servislerde benzer ön ekle başlayabilmektedir, örneğin scf_carikart_hareket_listele, scf_carikart_hesapdurumu_getir gibi.
1.5. Input/Response Genel Özellikleri
İnput (Servis çağrılarının) benzer özellikleri bulunmaktadır. Login çağrısı haricindeki bütün çağrılar için session_id, firma_kodu, donem_kodu zorunludur. Ekleme ve güncelleme servisleri kart bilgisi zorunlu, getirme ve silme servislerinde key bilgisi zorunludur.
Response (çıktı) içinde benzer özellikler vardır. Ekleme ve güncelleme servisleri işlem yapılan kayda ait key bilgisini döndürür, işlem sonucunda atılan sistem kaydını (logu) da msg içerisinde döndürür. Getir servisi result içerisinde kayda ait bilgileri döndürür. Listele servisi result içerisinde liste değerlerini döndürür.