Entegrasyon Kılavuzu
Bu servis tedarikçilerin ürün, stok, sipariş, kategori, kargo vb. işlemlerini dış sistemlerden entegre bir şekilde yönetebilmesi için geliştirilmiş bir entegrasyon servisidir. Dokümantasyonda yer alan endpoint’ler, bu işlemlerin SOAP servis üzerinden yapılmasını sağlar. Aşağıda, bu servise en doğru şekilde nasıl entegre olunacağına dair adımları bulabilirsiniz. Evrensel olması ve kolay test edilebilirlik açısından entegrasyon servisleri soapui veya postman üzerinden anlatılacaktır. Buradaki adımlara emin olduktan sonra siz istediğiniz yazılım dilinde entegre olabilirsiniz.
WSDL Adresi: https://ws.pttavm.com:93/service.svc/service?wsdl
WSDL İstek Adresi: https://ws.pttavm.com:93/service.svc
SoapUI’dan Proje Oluşturulması
Sol üstten SOAP logosuna tıklayarak gelen new soap project ekranında wsdl adresi verilerek ilgili servisteki endpoint’ler görüntülenebilir.
Daha sonrasında ekranın solunda navigator altında proje olarak gelmeli.
Kimlik Doğrulama
Tüm endpoint’ler kimlik doğrulaması gerektirir. Kullanıcı adı-şifre bilgileri basic-auth olarak gönderilen isteğe eklenmelidir.
İlk adımda en basit kontrol olarak GetVersion metoduna istek atılabilir.
SoapUI’den atarken istekte ilgili auth alanları doldurulmalıdır. Username: kullanıcı adınız, Password: şifreniz, WSS-Password Type: PasswordText olarak seçilmeli.
Sonrasında ekran görüntüsündeki gibi istek atılabilir.
Kontrol amaçlı aynı isteği postman’den atmak isterseniz ekran görüntüsündeki header’ları ekledikten sonra benzer şekilde istek atabilirsiniz. Postman’den istek atarken basic auth eklemek için request’in içindeki header’a örnekteki gibi security tag’i altında eklenebilir. SOAP mesajında kullanılan her XML etiketi (örneğin s:Header, o:Username, tem:GetVersion) belirli bir ad alanı (xmlns) ile tanımlanmıştır. Bu nedenle bu etiketler, WSDL dosyasında veya örnek dökümanda tanımlandıkları ad alanı ön ekleriyle (namespace prefix) birebir aynı şekilde kullanılmalı ve buna dikkat edilmeli; farklı bir isimlendirme ya da prefix kullanılması, servis tarafından hata olarak dönebilir.
Request Headers:
Content-Type: text/xml;charset=UTF-8
SOAPAction: “http://tempuri.org/IService/GetVersion”
Request Body:
<s:Envelope xmlns:s=”http://schemas.xmlsoap.org/soap/envelope/” xmlns:tem=”http://tempuri.org/”>
<s:Header>
<o:Security s:mustUnderstand=”1″ xmlns:o=”http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd”>
<o:UsernameToken>
<o:Username>kadi</o:Username>
<o:Password>sifre</o:Password>
</o:UsernameToken>
</o:Security>
</s:Header>
<s:Body>
<tem:GetVersion/>
</s:Body>
</s:Envelope>
İstek Türüne Göre Doğru Sırayla Endpoint Seçimi:
Entegrasyon metodlarını ne amaçla kullanabileceğinizden sırasıyla bahsedilecektir. Daha detaylı anlatımlar ve request-response modelleri için dokümantasyonda ilgili metodları inceleyebilirsiniz.
Genel Entegrasyon Kontrol Servisleri:
GetVersion PttAvm entegrasyon servisini erişilebiliyor mu diye kontrol amaçlı kullanılabilir.
KullaniciTedarikciBilgisiGetir mağaza auth bilgilerinde problem var mı diye kontrol amaçlı kullanılabilir.
Ürün Entegrasyon Servisleri:
Ön Bilgi Servisleri Olarak;
GetMainCategories güncelleme metodlarında kullanmak üzere kategori bilgisi öğrenmek için kullanılabilir.
GetCategoryTree bir kategorinin altındaki tüm child kategorileri parent_id’den leaf node’lara kadar çekmek için kullanılabilir.
GetCategory bir kategorinin kendisini ve sadece 1 seviye parent kategori bilgilerini id’den çekmek için kullanılabilir.
GetCargoProfiles mağazanın ürün kargo profillerini çekmek için kullanılabilir.
Buralardan aldığınız bilgileri güncelleme metodlarında kullanabilirsiniz.
Güncelleme Metodları Olarak;
Komple ürün güncellemesi için kullanmanız gereken yeni metod UpdateProductsV3’dır. Diğer StokGuncelleV2’de benzer işi yapsa da deprecated durumdadır ve yakın zamanda kullanıma kapatılacaktır.
Sadece stok, fiyat, aktiflik, kdv oranı, kargo tedarikçiden gibi hızlı güncellenmesi gerekebilen alanlarla ilgili güncelleme yapacaksanız kullanmanız gereken metod UpdateProductsStockPrice’dır. StokFiyatGuncelle3’e ve AktifYap metodunaentegre olmayınız yakın zamanda kullanıma kapatılacaktır. Ayrıca UpdateProductsStockPrice’da varyant stok ve fiyat güncellemeleri de yapabilirsiniz.
Yeni metodlardan toplu bir şekilde de güncelleme yapabilirsiniz. Güncellemeleri tek tek göndermektense toplu bir şekilde yapmanız işlemin daha performanslı olması adına tavsiye olunur. Tek bir işlemde 1000 ürüne kadar güncelleme yapabilirsiniz. Bu metodlar eskilerden farklı olarak gönderdiğin alanı güncelle, göndermediğine dokunma prensibine göre çalışmaktadır. Dolayısıyla request’te tüm alanları göndermektense sadece ihtiyacınız olan alanı göndererek de güncelleme yapabilirsiniz.
UpdateProductsV3 ve UpdateProductsStockPrice metodları işleminizi sıraya alıp, sistemin yoğunluğuna güncellemeleri yapacaktır. İşlem sonucunda anında birtrackingId dönecektir.
İşlem Sonuçlarıyla Alakalı Olarak;
GetProductsTrackingResult metodunda bu trackingId’yi kullanarak işlem durumuyla alakalı progress bilgisini, işlem status durumunu, ürün bazlı güncelleme belirli aralıkla kontrol edebilirsiniz. İşlem status’lerinden dokümantasyonda bahsedilmiştir. İşleminiz sırada bekliyorsa durumu Waiting olacaktır. Sıraya alındığında InProgress olacaktır. İşlem başarıyla tamamlanırsa Completed olacaktır(ürün bazlı olarak bazı ürünlerle alakalı validasyon hataları vs. olabilir bu durumda sadece o üründe Cancelled olur). Eğer işlem tamamen başarısız olursa işlemin status’u Cancelled olacaktır. Progress 100 olduğunda işlem tamamlanmış demektir(status Completed veya Cancelled olacaktır).
GetAllProductImagesWithError metodunda pagination’lı bir şekilde veya verilen ürün barkodları üzerinden resimler yüklenirken hata olup, olmadığıyla ilgili takip yapılabilir. Son yapılan güncellemede resim yüklemesi başarılı olduysa hata kaydı silinecektir.
BarkodKontrol metodundan ürün barkoduyla ilgili ürünün güncel bilgilerini çekebilirsiniz.
BarkodKontrolBulk metodundan ürün barkodlarıyla ilgili ürünlerin güncel bilgilerini toplu olarak çekebilirsiniz.
StokKontrolListesi metodundan ilgili filtrelere göre ürün bilgilerini pagination’lu bir şekilde çekebilirsiniz. Örneğin SearchAktifPasif(0: Hepsi, 1:Sadece Aktif Olanlar, 2: Sadece Pasif Olanlar) ve SearchPage alanı göndererek aktif olan tüm ürünleri pagination’lu bir şekilde getir, SearchUrunAdi göndererek ürün adı eşleşeni getir, SearchBarkod gönderererek barkodu eşleşeni getir, SearchYeniKategoriId(Kategori metodlarından alacağınız id ile) göndererek kategorisi eşleşenleri getir gibi işlemler yapabilirsiniz.
Sipariş Entegrasyon Servisleri:
Sipariş Bilgileriyle İlgili Olarak;
SiparisKontrolListesi, SiparisKontrolListesiV2 servislerini mağazanın siparişlerini çekmek için kullanabilirsiniz. SiparisKontrolListesiV2 daha detaylı bilgiler dönmekte veürün bilgilerini tek bir sipariş kaydı ieçrisinde bir alan içerisinde dönmektedir. SiparisKontrolListesi ise örneği bir siparişi her bir ürün için ayrı bir kayıt olarak dönmektedir. SiparisKontrolListesiV2’ye entegre olunması tavsiye olunur.
Kargo Bilgileriyle İlgili Olarak;
KargoBilgiListesi ilgili siparişin kargo bilgilerini çekmek için kullanılabilir.
Fatura Yükleme İşlemiyle İlgili Olarak;
SaveInvoince ilgili siparişle ilgili olarak ürün bazlı fatura yükleme işlemi için kullanılabilir.
