inposext kitaplığı Windows ya da Linux (32-bit) PC üzerinde çalışacak uygulamaların yazarkasa uygulamasına bağlanarak satış yapmasına olanak sağlamaktadır.
inposext kullanımına yönelik temel ilkeler:inposext kitaplığı C API'leri içerir. Kitaplığın çalışması için QtCore4, QtNetwork4 ve libeay32 kitaplıkları gerekmektedir. Windows işletim sistemi için bu kitaplık dosyaları inposext ile birlikte dağıtılmaktadır, ancak kitaplık dosyaları qt.io sitesinden indirilebilecek olan Windows 32-bit VC++2010 Qt 4.8.7 paketinde bulunanlarla aynıdır. Kitaplıkların çalışması için Windows makinelerde Visual C++ 2010 Runtime 32-bit (x86) çalışma zamanı kitaplığı kurulu olmalıdır. Linux PC'lerde QtCore4, QtNetwork4 ve libcrypto kitaplıkları kurulu olmalıdır.
InposExt.Net kitaplığı .Net 2.0 ve üzeri .Net sürümleri hedefleyen, inposext'teki C fonksiyonlarının .Net ortamında kolayca kullanılmasını sağlamak için geliştirilmiş bir "wrapper" kitaplıktır. inposext ve inposext için gerekli olan QtCore4, QtNetwork4 ve libeay32 kitaplıkları ile birlikte kullanılmalıdır.
QtGui4 kitaplığı exttest ve inposgmp3 uygulamaları için gereklidir. PC uygulaması ile birlikte bu kitaplıkların dağıtılmasına gerek yoktur.
inposext kullanımı için inposext.h header dosyası yeterlidir:
#include <inposext.h>
inposext_types.h header dosyası inposext.h dosyasında bulunan işlevlerin kullandığı enum ve struct tanımlarını içermektedir.
Yazıcı işlevleri de kullanılacaksa inposext_printer.h header dosyası da eklenmelidir:
#include <inposext_printer.h>inposext kullanımına yönelik açıklama ve öneriler:
inposext API'lerinin kullanılabilmesi için öncelikle cihaz ile PC eşlenmelidir. Test cihazlarında uygulama no'su 1 olan harici uygulama tanımlanmıştır. Geliştirme süresince bu uygulama no'sunu hem cihazda hem de PC uygulamalarında kullanılmalıdır. Her bir harici uygulama entegrasyonu için daha sonra inPOS SDK geliştirme ekibi tarafından tekil bir numara belirlenecektir.
Test cihazlarında Servis hesabının şifresi 4321, diğer kullanıcıların şifresi 1234'tür.
PC'de eşleme hazırlığı:Yukarıdaki hazırlıklar yapıldıktan sonra önce PC'deki inposgmp3 uygulamasında Eşle tuşuna basılır, sonra cihazda Giriş tuşuna basarak eşleme başlatılır. Eşleme sonucu ekranda gösterilir. Eşleme başarılı ise sonraki adımda uygulama etkinleştirilir.
/libinposext/bin/exttest.exe uygulaması açılıp cihaz sicil no'su girilip, Enter'a basılıp, Cihaza Bağlan tuşuna basılarak cihazın uygulama bağlanması sağlanabilir. Eğer 59000'den farklı bir port seçildiyse Cihaza Bağlan'a basılmadan önce port doğru değere ayarlanmalıdır. ExtTest uygulamasına cihaz değil PC IP'si girilmelidir. IP alanı 0.0.0.0 olarak bırakılabilir. 0.0.0.0 PC'deki tüm arayüzlerden bağlantı kabul edilmesini sağlar.
InPOS SDK kullanımı sırasında karşılaştığınız sorunları ya da diğer her türlü sorunuzu sdk@inpos.com.tr adresine gönderebilirsiniz. Karşılaştığınız sorunların inPOS geliştirme ekibi tarafından daha kolay ve doğru şekilde anlaşılabilmesi için aşağıdaki kontrol listesini belirtilen sıra ile uygulayıp başarısız olan adımları bulgu raporunuza ekleyin:
Kimi güncellemelerden sonra ya da alınan kimi hatalardan sonra cihazın tekrar malileştirilmesi gerekebilir. Cihazı malileşme öncesine döndürmek için Servis > 0.Diğer > Cihazı Sıfırlama kullanılabilir.
Malileşmemiş cihaz ya da herhangi bir servis müdahalesi gerektiren bir kullanıcı mesajı görüldüğünde Giriş tuşuna basarak kullanıcı giriş ekranına geçilebilir. Malileşmemiş ya da servis müdahalesi gereken bir cihazda sadece Servis kullanıcısı görülür.
Cihazın malileşmesi için yapılması gerekli işlemlerin adlarının sonunda '*' bulunur. SCR ve MSR testleri çipli kredi kartı kullanılarak yapılabilir. Testler sırasında kart üzerinde herhangi bir işlem yapılmaz. Tarih/saat güncelleme NTP ile yapılabilir. Zorunda kalınırsa elle tarih ve saat de girilebilir. Programlama altında malileşme için yapılması zorunlu olan işlemler:Tüm işlemler yapıldığında Servis ana menüsünde Cihazı malileştir seçeneği görülecektir.
GİB'in 2 Aralık 2015 tarihinde yayımladığı Yeni Nesil Ödeme Kaydedici Cihazlardan Bilgi Fişi Teknik Kılavuzu belgesi ile YNÖKC'ler ayrıntılı bilgi fişleri düzenlemek zorunda olmuşlardır. Faturalı satış bilgi fişleri satış fişlerinde yer alan kısım bilgilerini (KDV oranı ve tutar), ödeme tipini, toplam tutar ve KDV'yi içerir duruma gelmiştir. Bunun yanında VKN/TCKN alanı ve e-fatura ya da e-arşiv fatura bilgi fişlerinin istenirse irsaliye olarak da düzenlenebilmesi öngörülmüştür.
Bilgi fişlerinin, satış kalemleri ve ödeme bilgileri balkımından satış fişleri kadar ayrıntılı olması nedeniyle faturalı satış işleminde normal satış işleminde kullanılan ekranlar ve özellikler devreye alınmıştır. inposext ile faturalı satış başlatıldığında (inposext_start_sale_with_invoice()) yazarkasa yazılımı InposEcrSale durumuna geçecek ve kalem ve ödeme ekleme boyunca bu durumda olacaktır. Bu aşamadan satış ile ilgili fonksiyonlar kullanılacaktır. Toplam tutar ödendiğinde InposEcrSaleWithInvoice durumuna geçilecek ve bilgi fişinde yer alan ek bilgiler beklenecektir. Bu noktada inposext_end_sale_with_invoice() ile ek bilgiler sağlanmalı ve faturalı satış sonlandırılmalıdır.
Faturalı satış akışı şu şekilde olacaktır:Gene GİB'in yayımladığı bir duyuruya göre vergi mükellefi olmayan müşteriler TCKN'lerini işyeri ile paylaşmak zorunda değiller. Bu durumda TCKN alanına 11111111111 girilmeli.
E-fatura ve e-arşiv fatura bilgi fişleri irsaliye olarak düzenlenebilir. Normal faturalı satış bilgi fişi irsaliye olarak düzenlenemez.
inposext_printer.h header dosyasında yazıcıdan basılmak üzere belge hazırlama ve belgeyi basma için fonksiyonlar bulunmaktadır.
Yazıcıdan belge basma işleminin temel adımları şunlardır:inposext_types.h dosyasında bulunan InposEcrSaleState enum'u yazarkasa uygulaması satış (InposEcrSale) durumundayken satış iş akışının bulunabileceği 16 farklı durumu içermektedir. Bu durumların birkaçı dışındakiler farklı hata durumlarına karşılık geliyor. Hata durumları da şu anda kullanıcı müdahalesi gerektiriyor. Bu bölümde InposEcrSaleState enum'undaki değerler incelenecek ve PC uygulamalarının satış sırasında inposext_sale_state() fonksiyonunu kullanarak farklı hata durumlarını belirlemeleri ve kullanıcıları uygun müdaheleye yönlendirmeleri konusu tartışılacak.
inposext_types.h dosyasında yer alan InposEcrState ve InposEcrSaleState enum'larının farkına bu noktada tekrar değinmekte yarar var: InposEcrSaleState enum'u eğer InposEcrState enum'unun InposEcrSale değeri için anlamlı. Yani InposEcrSaleState enum'u InposEcrSale durumunun alt durumlarını listeliyor denebilir. Bu bölümde ve belgenin geri kalanında "yazarkasa durumu" ifadesi inposext_ecr_state() fonksiyonunun döndürdüğü InposEcrState değeri için kullanılacak. InposEcrSaleState değerleri için "satış durumu" ifadesi kullanılacak.
| InposSaleIdle | Yazarkasa satış durumunda değilken yazarkasa yazılımının satış akışını gerçekleştiren kısmı bu durumda bulunur. inposext_sale_satate() fonksiyonu eğer yazarkasa satış durumunda değilse InposInvalidEcrStateError hatası döndüğünden PC uygulamaları bu satış durumunu göremezler. |
| InposSaleWaitingForInput | Satış başladığında bu satış durumuna geçilir. Bu durumda iken inposext'in satış ile ilgili API'leri kullanılabilir. Ancak satış işleminin bulunduğu aşamaya göre her API her zaman kullanılamayabilir. Örneğin ara toplam üzerinden indirim/artırım yapılmışken kalem eklenemez/silinemez. Ya da parçalılş satış yapılıyorken ara toplam üzerinden indirim/artırım yapılamaz. |
| InposSaleWaitingCancelLastItemResponse ve InposSaleWaitingCancelSaleResponse | Bu durumlar inposext API'ler kullanarak satış yapıldığında PC uygulamaları tarafından görülmez. Ancak satış sırasında kasiyerin cihaz üzerinden satışa müdahale etme izni olursa (ki şu anda herhangi bir kısıtlama yok) satış bu durumu bu iki değerden birini alabilir ve PC uygulaması inposext_sale_state() ile bu değerleri görebilir. Bu durumda kullanıcı cihaz üzerinden satışa müdahelesini tamamlamaya yönlendirilmelidir. inposext üzerinden yapılacak satış iptali ya da kalem silme işlemleri için kullancı onayı almak gerekli görülürse bu onaylar PC uygulamaları tarafından alınmalı ve sonra ilgili fonksiyonlar çağrılmalıdır. |
| InposSaleWaitingForSection | Bu durum inposext API'ler kullanarak satış yapıldığında PC uygulamaları tarafından görülmez. Ancak satış sırasında kasiyerin cihaz üzerinden satışa müdahale etme izni olursa, satış sırasında Menü tuşuna basıldığında kullanıcının kısım seçmesi için mevcut kısımlar görülüyorken inposext_sale_state() bu satış durumunu dönebilir. Bu durumda PC uygulaması kasiyeri bir kısım seçmesi ya da tekrer Menü tuşuna basarak kısım seçmeden satışa devam etmesi yönünde yönlendirmeli. |
| InposSaleWaitingForCustomerId | Bu durum inposext API'ler kullanarak satış yapıldığında PC uygulamaları tarafından görülmez. Ancak satış sırasında kasiyerin cihaz üzerinden satışa müdahale etme izni olursa ve cihazda muayene katkı payı işlevi açıksa, kasiyer cihaz üzerinden katkı payı girerken bu satış durumu görülebilir. |
| InposSaleWaitingForTransactionCompleted | Kredi kartıyla tahsilat yapılıyorken işlemin sonucu bu durumda beklenir. Eğer parçalış satış yapılıyorsa ve tahsilat sonunda hala ödenmesi gereken tutar varsa InposSaleWaitingForInput durumuna geçilir. Eğer tahsilat ile tüm/kalan tutar ödenmiş olursa satış sonlandırılır. |
| InposSaleLimitReachedWithLastItem ve InposSaleLimitReachedWithAddedAmount | Bu durumlara Yönetici > Programlama > Satış Limiti ile belirlenen satış limiti eşiği aşıldığında geçilir. Satış limiti faturalı satışın zorunlu olduğu tutarlara geçilmesi engellemek için kullanılan bir işlevdir. PC uygulamasının kullanılacağı işyerleri satış limit ve faturalı satış konusunda eğitilmelidir. |
| InposSaleUndefinedPluItem | Bu durum PC uygulamalrı tarafından görülemez. |
| InposSaleInvalidSectionOfPluItem ve InposSaleInvalidVatRateOfPluItem | inposext_add_sale_item() ile eklenen kalemin kısmı ya da kısmın KDV oranı geçersiz olduğunda bu durumlardan birine geçilir. Aşağıdaki InposSaleUndefinedSection açıklamaları dikkate alınmalı. |
| InposSaleUndefinedSection | Ancak kasiyer elle satış yaparken bu durum görülebilir. inposext_section_data() ile cihazdaki geçerli kısımlar alınabilmektedir. PC uygulaması geçerli kısım göndermek için her açıldığında cihazdaki kısımları daha önce aldığı kısımlarla karşılaştırmalıdır. Cihazda kayıtlı olan kısımların PC uygulaması ile entegrasyon yapıldıktan sonra cihaz üzerinden değiştirilmemesi ya da PC uygulamasıyle eşdügüm sağlanarak değiştirilmesi, PC uygulaması geliştiricilerinin işyerleri ile beraber ele alması gereken bir konu. Diğer yandan, GİB Bilgi Sistemleri'nin devreye alınması sonrasında GİB Yeni Nesil ÖKC'lere KDV oranları gönderebili duruma gelecektir. Her bir kısım, kısım adı yanında bir KDV oranı da içerdiğinden GİB tarafından yapılacak bir KDV güncellemesi kısımların tutarsız bir duruma gelmesine yol açabilir. Yazarkasa uygulaması KDV oranları değiştiğinde kullanıcıları kısımları gözden geçirme konusunda uyarmaktadır. |
| InposSaleUndefinedVatRate | Ancak kasiyer elle satış yaparken bu durum görülebilir. |
| InposSaleInvalidAmount | Örneğin ara toplama yapılan indirim tutarı ara toplamdan büyükse, yani toplam tutar 0 TL'nin altına inecekse bu duruma geçilir. Bu duruma ayrıca kullanıcının cihazdan elle girdiği tutar geçersiz olduğunda da geçilir. |
| InposSaleDataFinalized | Satış bu durumdayken yazarkasa yazılımı satışı sonlandırmaya başlamış demektir. |
Cihaz ile olan bağlantının etkin olduğunu kontrol edip gerektiğinde tekrar cihaza bağlanmak PC uygulamalarının sorumluluğundadır. Bu nedenle düzenli olarak bağlantı kontrolü yapmak inPOS - PC entegrasyonunun en az sorunla yönetilmesi için üzerine önemle eğinilmesi gereken bir konudur.
inposext_ecr_sale_state() ve inposext_ecr_state() fonksiyonu cihaz tarafında diğer fonksiyonlardan farklı şekilde işlenmektedir. Bu sayede, yazarkasa yazılımı örneğin satış sonlandırma ya da Z raporu basımı gibi inposext fonksiyonlarına yanıt veremediği bir işlem yapıyor olsa da inposext_ecr_sale_state() ya da inposext_ecr_state() sorgularına yanıt verilebilmektedir.
PC uygulamaları bu davranışı 2 şekilde kullanabilir:Bağlantı kontrolünü bir işlem yapılacağında yapmak yerine düzenli olarak yapmak daha sorunsuz bir işleyiş sağlayacaktır. inposext_initialize() ilk çağrıldığında görece uzun sürse de sonraki çağrılarda hızlı sonlanmaktadır. Bu nedenle inposext_initialize() kullanımından çekinilmemelidir.