FatihGörgülü

TROIA Web Service Rehberi: Session, callService, Encryption ve Response Yapısını Anlamak

TROIA Web Service, CANIAS ile dış sistemler arasında çalışan sade ama kritik bir köprü. Bu rehber; oturum açma, callService akışı, XML parametreleri, response okumayı ve şifreleme/sıkıştırma ayrımlarını sahada en çok karışan noktalar üzerinden netleştirir.

İçindekiler

TROIA Web Service'e hızlı bakış

Akışın özü basit: login ile oturum açılır, callService ile TROIA sınıf metodu çalıştırılır, CaniasResponse ile dönüş okunur. Ama sahada, küçük teknik detaylar çoğu zaman büyük entegrasyon hatalarına dönüşür.

  • login() yalnızca oturum açar; iş callService() ile yapılır.
  • callService() her çağrıda SessionId ve SecurityKey ister.
  • Response tek string değildir; CaniasResponse içinde çoklu alan vardır.
  • Encryption ve compression isteğe bağlıdır; sırayı ve flag'leri doğru yönetmek gerekir.

login(): oturum ve güvenlik anahtarı

login() başarılı olduğunda SessionId ve SecurityKey döner. SessionId oturumu, SecurityKey ise istemcinin doğrulandığını gösterir.

  • SessionId tüm callService çağrılarında taşınmalı.
  • SecurityKey her çağrıda gönderilmeli; aksi halde çağrı reddedilir.
  • Encrypted bayrağı true ise sunucu EncryptionKey üretir.
  • Compression niyetini oturumda doğru beyan etmek, sonraki çağrılarda uyumu kolaylaştırır.

callService(): servis çağrısının merkezi

callService(), kayıtlı bir TROIA sınıf metodunu çalıştırır ve CaniasResponse döner. Yanlış ServiceId, eksik güvenlik anahtarı veya hatalı Parameters XML en sık hata kaynağıdır.

  • ServiceId, hangi TROIA metodunun çalışacağını belirler.
  • Parameters, XML string olarak gönderilir.
  • Compressed ve Permanent bayrakları, davranışı etkiler.
  • ExtraVariables ve RequestId, izleme ve tanılama için kritik ipuçlarıdır.

Parameters XML: primitive, base64 ve CDATA

Parameters alanı XML string'dir. Her parametre <PARAM> ile taşınır. encoding='base64' kullanıldığında sistem değeri UTF-8 olarak çözümler. Özel karakterler için CDATA güvenli bir tercihtir.

  • Basit tiplerde type attribute gerekmez.
  • Base64 parametreler UTF-8'e çözülür.
  • CDATA, özel karakter içeren alanlarda parser sorununu azaltır.
  • Varsayılan encoding: plain.

Table ve vector parametreleri

Table veya vector geçirmek istediğinizde <PARAM> içine TYPE bilgisi eklemek gerekir. Sunucu bu XML'den uygun sembolü üretir.

  • TYPE="TABLE" kullanıldığında satır/kolon yapısı gönderilir.
  • TYPE="VECTOR" ile name/type/value üçlüsü taşınır.
  • Vector içinde primitive tipler kullanılabilir (string, long, date vb.).
  • XML hiyerarşisi bozulursa parametre parse edilemez.

CaniasResponse nasıl okunur?

callService() tek bir string değil, CaniasResponse döner. Response, SYSStatus, SYSStatusError, Messages ve ExtraVariables birlikte okunmalıdır.

  • Response alanı StringResponse tipindedir; Compressed bayrağı varsa açılmalıdır.
  • SYSStatus, TROIA tarafında son durum değerini verir.
  • Messages alanı, çalışma sırasında üretilen TROIA mesajlarını taşır.
  • ExtraVariables, istenen değişkenleri XML formatında döndürür.
  • RequestId, çağrı eşlemesi için geri döner.

Encryption: ne zaman, nasıl?

Encryption varsayılan değildir; login sırasında talep edilmelidir. EncryptionKey sunucudan gelir, UTF-8 byte dizisine çevrilir ve AES/CBC/PKCS7/128 yapılandırmasıyla kullanılır.

  • Encrypted bağlantıda Parameters string'i şifrelenir.
  • Response çözmek için Base64 → byte → decrypt → UTF-8 adımları gerekir.
  • EncryptionKey'i byte dizisine çevirmeden kullanmak sık hata kaynağıdır.
  • Şifreleme istemiyorsanız Encrypted=false bırakılmalıdır.

Compression: eşik ve sıraya dikkat

Compression, yanıt uzunluğu eşik değeri aştığında devreye girer. Sistem, şifreli veriye compression uygulamaz. Hem encryption hem compression kullanılıyorsa istemci sıralamayı doğru kurgulamalıdır.

  • Compressed=true ise Base64 → byte → decompress → UTF-8 adımı gerekir.
  • Yanıt 4000 karakter üzerindeyse sıkıştırma devreye girebilir.
  • Şifreli bağlantıda parametre sıkıştırılıyorsa önce şifrele, sonra sıkıştır.
  • Sunucu şifreli response'u sıkıştırmaz.

Hızlı referans: alanlar ve işaretler

Saha için kısa kontrol listesi. En çok unutulan alanları tek yerde özetler.

  • login response: Success, SessionId, SecurityKey, ErrorMessage, EncryptionKey.
  • callService input: SessionId, SecurityKey, ServiceId, Parameters, Compressed, Permanent, ExtraVariables, RequestId.
  • CaniasResponse: Response (Value/Compressed), SYSStatus, SYSStatusError, Messages, ExtraVariables, RequestId.
  • Parameters XML: <PARAMETERS><PARAM encoding="base64">...</PARAM></PARAMETERS>.
  • ExtraVariables/Messages dönüşleri XML formatındadır.

XML template pack (kısa şablonlar)

Kopyala-uyarla kullanımı için kısa iskeletler.

  • Basic: <PARAMETERS><PARAM>value</PARAM></PARAMETERS>
  • Base64: <PARAM encoding="base64">cGFyYW0x</PARAM>
  • Table: <PARAM TYPE="TABLE"><TABLE_NAME><ROW><COL1>...</COL1></ROW></TABLE_NAME></PARAM>
  • Vector: <PARAM TYPE="VECTOR"><VECTOR_NAME><ITEM><NAME>...</NAME><TYPE>STRING</TYPE><VALUE>...</VALUE></ITEM></VECTOR_NAME></PARAM>
  • ExtraVariables isteği: "VAR1,VAR2,VAR3" (virgülle).

İlgili sayfalar:

İlgili yazılar ve kaynaklar

İlgili yazılar burada listelenecek.

TROIA Web Service Rehberi: Session, callService, Encryption ve Response Yapısı | Fatih Görgülü | Fatih Görgülü