Geliştirici Dokümanı

Bu doküman geliştiriciler için adım adım Token Integration Hub Protokolüne nasıl entegre olunacağını anlatır.

Kendi Yazılımınız ile Token integration Hub DLL'i Entegre Edin

C# .NET Forms App Örneği

Adım 1: Yeni Bir Proje Açın

Adım 2: Sağladığımız IntegrationHub Kütüphanesini Projeye Ekleyin

• “Add Reference…” butonuna tıkalyın.

• “IntegrationHub.dll” adlı dosyayı seçip OK tuşuna basın.

• Proje ayarlarından “Prefer 32-bit” kutucuğunun tikini kaldırın.

• Bu aşamalardan sonra kod içinde IntegrationHub kütüphanesini kullanabilirsiniz:

  using IntegrationHub;
  public static IntegrationHub.POSCommunication communication = IntegrationHub.POSCommunication.Instance;

Adım 3 (Opsiyonel): Yardımcı Json Classlarımızı ve Json Kütüphanesini Ekleyin

Bu kısım isteğe bağlıdır, ancak önerilmektedir; çünkü JSON oluşturacak ve ayrıştıracaksınız. Sağladığımız sınıflar ve kütüphaneler, bunu yapmanızı kolaylaştıracaktır. Bu dokuman, bu adımı tamamlamışsınız gibi devam edecektir. Kendi JSON dönüştürme sistemlerinizi yazmak isterseniz, bunu yapmaktan çekinmeyin; ancak bu dokumanla ilerlemek zorlaşabilir.

• Newtonsoft.Json paketini NuGet ile indirin

• Projenize, şablon dosyalarında sağlanan Basket.cs, FiscalInfo.cs ve ReceiptInfo.cs sınıflarını ekleyin.

Adım 4: Communication Objesinin Oluşturulması

Communication nesnesini, uygulama genelinde erişilebilir olmasını sağlamak için Program sınıfı kapsamında bir singleton olarak başlatın. İletişimin uygulama başlayınca hemen başlamasını istemiyorsanız Objeyi bir buton yardımı ile kullanıcı butona basınca oluşturabilirsiniz.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using System.Windows.Forms;

namespace TokenDotNet
{
    internal static class Program
    {
        /// <summary>
        /// The main entry point for the application.
        /// </summary>
        /// 
				
        public static IntegrationHub.POSCommunication communication = IntegrationHub.POSCommunication.Instance;

        [STAThread]
        static void Main()
        {

            Application.EnableVisualStyles();
            Application.SetCompatibleTextRenderingDefault(false);

            Application.Run(new MainForm());
        }
    }
}

Adım 5: Sepet Objesi ve Callbackleri Ayarlamak

Cihaz durumu ve seri iletişimi yönetmek için callback'leri ayarlayın ve sepet nesnesini ana formun içinde bir üye değişkeni olarak ayarlayın. Aşağıdaki kod parçası, şablon projedeki kodun basitleştirilmiş bir versiyonudur.

namespace TokenDotNet
{
    public partial class MainForm : Form
    {
        private Basket basket;
        private IntegrationHub.POSCommunication communication = Program.communication;

	public void deviceStateCallback(bool isConnected, string id)
	{
	    Control.CheckForIllegalCrossThreadCalls = false;
	    if (isConnected)
	    {
	        //Device connect
	    }
	    else
	    {
	       //Device disconnect
	    }
	}
			
	public int serialInCallback(int type, string value) {
	    //Do what you want with the data which is passed as type,value pair. 
	    //Types can be found in documentation. 
	    return 1;
	}
        
        private void setUpCallbacks()
        {
            communication.setDeviceStateCallback(deviceStateCallback);
            communication.setSerialInCallback(serialInCallback);
        }
        
        public MainForm()
        {
            InitializeComponent();

						//init callbacks non-blocking way
            Thread thread = new Thread(setUpCallbacks);
            thread.Start();

						//create basket
            basket = new Basket();
            basket.basketID = "93ced0be-99f5-4e42-b0ca-bc781c778d69";
            basket.createInvoice = false;
            basket.documentType = 0;
            basket.isVoid = false;
        }
        
        private void clearBasket()
        {
            basket = new Basket();
        }
        
        private FiscalInfo constructFiscalInfoFromJson(string json)
        {
            return JsonConvert.DeserializeObject<FiscalInfo>(json);
        }
        private ReceiptInfo constructReceiptInfoFromJson(string json)
        {
            return JsonConvert.DeserializeObject<ReceiptInfo>(json);
        }

        private string constructJsonFromBasket(Basket basket)
        {
            return JsonConvert.SerializeObject(basket, Formatting.Indented);
        }
        
        private void sendBasketToPOS()
        {
            int basketStatus = communication.sendBasket(constructJsonFromBasket(basket));
				}
    }
}

Integration Hub API C# Dokümanı

USB Üzerinden Seri Haberleşme İçin Communication Objesi

Communication, kodunuz ile Android ÖKC cihazı arasında Integration Hub API'sini kullanarak iletişimi kolaylaştıran bir objedir. İletişimi başlatmak için öncelikle bu nesneyi oluşturmalısınız. Bu nesne oluştuktan sonra arka planda DLL bağlanmış olacak ve dokumanın ileri kısımlarında anlatıldığı gibi cihaz bağlanması veya bağlantı kopması durumlarında sizi callback mekanizması ile bilgilendiriyor olacak. Detaylı kullanım için Token Template Simulator uygulamasının kaynak kodlarına bakabilirsiniz.

//Init the communication object using Instance of it.
public static IntegrationHub.POSCommunication communication = IntegrationHub.POSCommunication.Instance;

ÖKC Bağlantısı

Cihaz durumundaki değişiklikleri dinlemek

• Cihaz durumlarındaki değişiklikleri dinlemek için setDeviceStateCallback() komutunu kullanın. Bu callback, yeni bir cihaz bağlandığında veya mevcut cihaz bağlantısı kesildiğinde yürütülecektir.

• isConnected parametresi, callbackin bir cihaz bağlantısı mı yoksa bağlantı kesilmesi mi olduğunu temsil eder. True değeri, bir cihazın bağlı olduğu anlamına gelir; false değeri ise bir cihazın bağlantısının kesildiğini gösterir.

• id cihazın mali numara bilgisini döndürür.

Bu fonksiyon, senkron olarak çalışan getDeviceInfo()'u çağırdığı için ana program akışınızı engelleyebilir. Kullanırken dikkatli olun, ana programınızın engellenmemesi için thread'ler veya diğer yapılar kullanın. Optimal bir durumda çalıştırılması çok az zaman alır, ancak sorunlara yol açabilir.

//Signature of the function
public delegate void DeviceStateCallback(bool isDeviceConnected, string id);

public void deviceStateCallback(bool isConnected, string id)
{
    Control.CheckForIllegalCrossThreadCalls = false;
    if (isConnected)
    {
        //Device connect
    }
    else
    {
       //Device disconnect
    }
}

communication.setDeviceStateCallback(deviceStateCallback);

ÖCK'den Fiscal Bilgilerinin Alınması

• Device state callback'i ile bağlantının sağlandığına emin olduktan sonra getFiscalInfo() komutunu kullanarak ÖKC cihazından bölüm ve kaydedilmiş ürün bilgilerini alın. Bağlantının sağlandığına nasıl emin olunacağı ile alakalı kod örneği Token Template Simulator'ün kaynak dosyalarında bulunmaktadır. Bu fonksiyon, bir JSON dizesi döndürür; bu JSON dizesinin örneği örnekler bölümünde bulunabilir.

• Fiscal bilgilerini almak protokolü kullanmak için zorunludur fiscal bilgileri alınmadan satış işlemlerine başlamayın.

Bu fonksiyon senkron olarak çalıştığı için ana program akışınızı engelleyebilir. Kullanırken dikkatli olun; ana programınızın engellenmemesi için thread'ler veya diğer yapılar kullanın. Optimal bir durumda çalıştırılması çok az zaman alır, ancak sorunlara yol açabilir.

//Returns the sections and saved products as a json string.
string fiscalInfo = communication.getFiscalInfo()

Protokolün İletişim Fonksiyonları

ÖKC'ye Sepet Yollamak

• sendBasket() fonksiyonu, sepet bilgilerini ÖKC cihazına göndermek için kullanılır. Parametre olarak bir sepet JSON'u sağlanmalıdır. Bu JSON'un örneğini 'JSON Örnekleri' bölümünde bulabilirsiniz.

//Returns 1 if succeed, 0 if fail
int basketStatus = communication.sendBasket(REQUEST_BODY);

ÖCK'den Gelen Paketleri Dinlemek

• setSerialInCallback() komutunu kullanarak ÖKC'den gelen yanıtları dinleyin. Bu komutu girdikten sonra, ayrı bir thread'de izlenen iletişim, gelen bilgileri belirlediğiniz callback fonksiyonuna yönlendirilecektir.

• Type, ÖKC'den gelen verinin türünü temsil eder; türler ve tanımları bu belgede bulunan Türler tablosunda bulunabilir.

• Value, veriyi temsil eden JSON dizesidir.

//Signature of the function
public delegate int SerialInCallback(int type, string value);

public int serialInCallback(int type, string value) {
	//Do what you want with the data which is passed as type,value pair. 
	//Types can be found in documentation. 
	return 1;
}

communication.setSerialInCallback(serialInCallback);

Satış Bilgilerini Dinlemek

• Callback fonksiyonu ayarlandığında, gönderilen satışların durumu belirttiğiniz callback fonksiyonuna iletilecektir.

• Aşağıda callback fonksiyonunun örnek kullanımı görülebilir. Satış JSON'u örneği 'Örnek JSON' bölümünde bulunabilir.

public int serialInCallback(int type, string value) {
	 //Since type of sale info is 3.
	 if(type == 3){
		 //This will print 3 to the console since type of sale info is 3.
		 //See request types table in documentation.
		 Console.WriteLine(type);
		 //This will write the sale json to console.
		 Console.WriteLine(value);
	 }
	 return 1;
 }

İletişimin Kapatılması

İletişimin kapatılması ideal koşullar altında kütüphane tarafından otomatik olarak yapılır.

İletişim Protokolü Bilgileri

TLV (Tag-Length-Value) protokolü, verileri yapılandırılmış bir şekilde depolamak ve taşımak için kullanılan bir veri kodlama şemasını ifade eder. Bu protokolde, veriler TLV paketleri adı verilen birimlere ayrılmıştır. Her TLV paketi üç bileşen içerir: Tür (Type), Uzunluk (Length) ve Değer (Value).

• Type (Tag): Bu, değer alanında bulunan verinin türünü tanımlayan 2 baytlık bir tanımlayıcıdır.

• Length: Bu, değer alanında bulunan verinin uzunluğunu tanımlayan 4 baytlık bir tanımlayıcıdır.

• Value: Bu, değer alanında bulunan verinin kendisin tanımlayan boyutu değişebilen bir tanımlayıcıdır.

Protokolümüzde veri bütünlüğünü sağlamak amacı ile tüm TLV ile iletilen verilerde belirli bir şema kullandık. Bu şemaya göre veri akışın TLV Başlangıç Paketi - TLV Veri Paketi - TLV Bitiş Paketi şeklinde sağlıyoruz böylece aradaki bozulmaları engellemiş ve eksik paketleri tespit edebilmiş oluyoruz. Aynı zamanda her TLV paketinin sonunda bir checksum ile veri bütünlüğünü kontrol ediyoruz.

Paketlerin hepsi sıkıştırılmış ve şifrelenmiş halde gönderiliyor. Şifreleme PC tarafından handshake adımları bittikten sonra oluşan anahatar ile sağlanıyor. Handshake'in detayları aşağıda bulunmaktadır.

Protokolümüzde, cihaz güvenliği ve doğrulamasını sağlamak için bir yöntem uygulanmıştır. Süreç, PC'den ÖKC'ye bir mesaj gönderilmesiyle başlar. ÖKC, bu mesajı cihaz sertifikasıyla imzalar. İmzalama işleminden sonra, ÖKC cihaz sertifikasını PC ile paylaşır. PC, gönderilen mesajın sağlanan sertifika ile oluşturulabileceğini doğrulamak için sertifikanın açık anahtarını ve ECDSA (Eliptik Eğri Dijital İmza Algoritması) kullanır. Bu doğrulama adımı, cihazın geçerli olduğunu onaylar ve iletişime güvenle devam etmemize olanak tanır. Doğrulamada bir sorun varsa, iletişime devam edilmez.

Paket Tipleri ve Açıklamaları

Aşağıdaki tablo, kütüphanede mevcut olan istek türlerini açıklamaktadır. Bu türler, seri iletişimdeki callback aracılığıyla dinlenebilir.

Tip	Açıklama
0	Cihaz bilgisini döner.
1	Sepet'in gönderildiği paket.
2	Fiscal bilgisinin döndüğü paket.
3	Satış bilgisini döner.
4	Hello paketi.
5	Sertifika paketi.
6	Anahtar paylaşımı paketi.
7	Bağlantı sonlandırma paketi.
9	Sepet işlenme durumu hakkında bilgi veren paket.
49	TLV başlangıç paketi.
50	TLV bitiş paketi.
60	Error bilgisi paketi.

JSON Açıklamaları

Sepet JSON'ı

Örnek

{
  "basketID": "93ced0be-99f5-4e42-b0ca-bc781c778d69",
  "createInvoice": false,
  "documentType": 0,
  "isVoid": false,
  "items": [
    {
      "name": "Su",
      "pluNo": 0,
      "price": 500,
      "sectionNo": 1,
      "unit": "Adet",
      "quantity": 1000
    },
    {
      "barcode": "",
      "name": "Armut",
      "pluNo": 0,
      "price": 1500,
      "sectionNo": 1,
      "quantity": 1000
    }
  ],
  "paymentItems": [
    {
      "amount": 1000,
      "type": 1
    },
    {
      "amount": 1000,
      "type": 3
    }
  ],
  "customerInfo": {
    "buildingName": "Building B",
    "buildingNumber": "202",
    "cityName": "City Y",
    "citySubdivisonName": "Subdivision 2",
    "country": "Country B",
    "email": "[e-mail]",
    "isLock": false,
    "name": "Ege Yardımcı",
    "postalZone": "67890",
    "region": "Region Y",
    "room": "20",
    "street": "Street B",
    "taxID": "0987654321",
    "taxScheme": "Scheme B",
    "telefax": "654321",
    "telephone": "0123456789"
  },
  "adjust": {
    "description": "İndirim Açıklaması",
    "discountOrSurcharge": 0,
    "type": 0,
    "value": 2000
  }
}

Açıklama

{
  "basketID": "93ced0be-99f5-4e42-b0ca-bc781c778d69",
  "createInvoice": false,
  "documentType": 0,
  "isVoid": false,
  "items": [],
  "paymentItems": [],
  "customerInfo": null,
  "adjust": null
}

Alan	Tip	Açıklama	Örnek Değer
basketID	string	UUID	“93ced0be-99f5-4e42-b0ca-bc781c778d69”
createInvoice	bool	Fiş oluştur.	true
documentType	int	Satış tipi.	SATIS(0), AVANS(9000), FATURA TAHSILATI(9001), CARI TAHSILAT(9002), FATURA BILGI FISI(9005), E-FATURA BILGI FISI(9006), E-ARSIV BILGI FISI(9007), ECZANE(9008)
isVoid	bool	Eğer true ise iptal fisi basilacaktir.	false
items	[object]	Sepetteki ürünlerin listesi.
paymentItems	[object]	Ödeme planının listesi.
customerInfo	object	Müşteri Bilgisi.
adjust	object	İndirim/Arttırım bilgisi.
note	string	Fiş altı notu (Henüz fişe basılmamaktadır )

Items Objesi

"items": [
  {
    "barcode": "",
    "name": "Su",
    "pluNo": 0,
    "price": 500,
    "sectionNo": 1,
    "taxPercent": 1000,
    "unit": "Adet",
    "quantity": 1000
  }]

Alan	Tip	Açıklama	Örnek Değer
barcode	string	Eşya barkodu.	8690006200
name	string	Eşya adı.	"Su"
pluNo	int	Eşya PLU numarası.	0
price	int	Eşyanın kuruş cinsinden fiyatı	500
sectionNo	int	Kısım no.	1
unit	string	Ölçü birimi.	"Adet"
quantity	int	Miktarın 100 ile çarpılmış hali.	1000

PaymentItems Objesi

"paymentItems": [
  {
    "amount": 1000,
    "type": 1
  }
]

Alan	Tip	Açıklama	Örnek Değer
amount	int	Kuruş cinsinden ödeme miktarı.	1000
type	int	Ödeme türü	1

Ödeme Tipleri

Ödeme Tipi	Değer	Açıklama
PAYMENT_CASH	1	Nakit
PAYMENT_CHEQUE	2	Çek
PAYMENT_CREDITCARD	3	Kredi Kartı
PAYMENT_FOOD	7	Yemek Kartı
PAYMENT_ODEMESIZ	8	Ödemesiz
PAYMENT_IKRAM	9	İkram
PAYMENT_VERESIYE	10	Veresiye
PAYMENT_PUAN	11	Puan
PAYMENT_VPOS	12	EPOS Ödeme
PAYMENT_MOBILE	13	Mobil Ödeme
PAYMENT_EMONEY	14	E-Para Ödeme
PAYMENT_CHARITY	15	Bağış
PAYMENT_BOND	16	Bond ile Ödeme
PAYMENT_OPENACCOUNT	17	Açık Hesap
PAYMENT_MONEYTRANSFER	18	Para Transferi
PAYMENT_TRANSPORTATIONCARD	19	Ulaşım Kartı
PAYMENT_GIFTCARD	20	Hediye Kartı

CustomerInfo Objesi

"customerInfo": {
  "buildingName": "Building B",
  "buildingNumber": "202",
  "cityName": "City Y",
  "citySubdivisonName": "Subdivision 2",
  "country": "Country B",
  "email": "[e-mail]",
  "isLock": false,
  "name": "Ege Yardımcı",
  "postalZone": "67890",
  "region": "Region Y",
  "room": "20",
  "street": "Street B",
  "taxID": "0987654321",
  "taxScheme": "Scheme B",
  "telefax": "654321",
  "telephone": "0123456789"
}

Alan	Tip	Açıklama	Örnek Değer
buildingName	string	Bina adı.	"Building B"
buildingNumber	string	Bina numarası.	"202"
cityName	string	Şehir adı.	"City Y"
citySubdivisonName	string	İlçe adı.	"Subdivision 2"
country	string	Ülke adı.	"Country B"
email	string	Email.	"[e-mail]"
isLock	bool	Eğer true ise gonderilen bilgiler ÖKC'de değiştirilemez.	false
name	string	İsim.	"Ege Yardımcı"
postalZone	string	Posta kodu.	"67890"
region	string	Bölge.	"Region Y"
room	string	Oda numarası.	"20"
street	string	Sokak adı.	"Street B"
taxID	string	Vergi numarası.	"0987654321"
taxScheme	string	Vergi dairesi.	"Scheme B"
telefax	string	Telefax numarası.	"654321"
telephone	string	Telefon numarası.	"0123456789"

Adjust Objesi

"adjust": {
  "description": "Açıklama",
  "discountOrSurcharge": 0,
  "type": 0,
  "value": 2000
}

Alan	Tip	Açıklama	Örnek Değer
description	string	İndirim/Arttırım açıklaması. Fişte bastırılır.	"İndirim"
discountOrSurcharge	int	0 indirim, 1 arttırım.	0
type	int	0 fiyat indirim/arttırımı, 1 yüzdelik indirim arttırım.	0
value	int	Adet başına İndirim veya arttırım değerinin 100 ile çarpılmış hali	2000
totalValue	int	Ürüne yapılan toplam indirim veya artırım değerinin 100 ile çarpılmış hali	2000

2 adet olan bir ürüne value=1000 gönderirseniz 20 TL, totalValue=1000 gönderirseniz 10 TL indirim/artırım yapılmış olur.

Sepete indirim/artırım yaparken sadece value gönderilebilir. totalValue kullanılamaz.

Fiscal Bilgisi JSON'ı

Örnek

{
  "businessMode": 0,
  "pluCount": 1,
  "plus": [
    {
      "barcode": "",
      "name": "Elma",
      "pluNo": 0,
      "price": 2000,
      "sectionNo": 1,
      "taxPercent": 1000,
      "type": 0,
      "unit": "Adet",
      "vatID": 1
    }
  ],
  "receiptLimit": null,
  "sectionCount": 2,
  "sections": [
    {
      "limit": 0,
      "name": "GİDA",
      "price": 0,
      "sectionNo": 1,
      "taxPercent": 1000,
      "type": 0
    },
    {
      "limit": 0,
      "name": "TEKEL",
      "price": 0,
      "sectionNo": 2,
      "taxPercent": 2000,
      "type": 0
    }
  ]
}

Açıklama

{
  "businessMode": 0,
  "pluCount": 1,
  "plus": []
  "receiptLimit": null,
  "sectionCount": 2,
  "sections": []
}

Alan	Tip	Açıklama	Örnek Değer
businessMode	int	Isletme modu.	Standart(0), Eczane(1), Konaklama(2)
pluCount	int	Cihazda kayitli PLU adeti.	1
plus	[object]	Cihazda kayıtlı ürünlerin listesi.	[{"barcode": "", "name": "Elma", "pluNo": 0, "price": 2000, "sectionNo": 1, "taxPercent": 1000, "type": 0, "unit": "Adet", "vatID": 1}]
receiptLimit	int	Fiş limiti. Bu tutarın üstüne bilgi fişi oluşturulmalıdır.	6900
sectionCount	int	Cihazda kayıtlı kısımların sayısı.	2
sections	[object]	Cihazda kayıtlı kısımların listesi.	[{"limit": 0, "name": "GİDA", "price": 0, "sectionNo": 1, "taxPercent": 1000, "type": 0}, {"limit": 0, "name": "TEKEL", "price": 0, "sectionNo": 2, "taxPercent": 2000, "type": 0}]

Plus Objesi

"plus": [
  {
    "barcode": "",
    "name": "Elma",
    "pluNo": 0,
    "price": 2000,
    "sectionNo": 1,
    "taxPercent": 1000,
    "type": 0,
    "unit": "Adet",
    "vatID": 1
  }
]

Alan	Tip	Açıklama	Örnek Değer
barcode	string	Ürün barkodu.	""
name	string	Ürün ismi	"Elma"
pluNo	int	PLU numarası.	0
price	int	Ürün fiyatı kuruş cinsinden.	2000
sectionNo	int	Bağlı oldugu kısım numarası.	1
taxPercent	int	Vergi dilimi.	1000
type	int	Ürün tipi.	Standart(0), Konaklama(1)
unit	string	Ölçü birimi.	"Adet"
vatID	int	-	1

Section Objesi

"sections": [
  {
    "limit": 0,
    "name": "GİDA",
    "price": 0,
    "sectionNo": 1,
    "taxPercent": 1000,
    "type": 0
  }
]

Alan	Tip	Açıklama	Örnek Değer
limit	int	-	0
name	string	Kısım adı.	"GİDA"
price	int	-	0
sectionNo	int	Kısım numarası.	1
taxPercent	int	Vergi dilimi.	1000
type	int	-	0

Satış Durumu JSON'ı

Satış durumu JSON'u, ÖKC tarafından ana makineye gönderilecektir. İşte bu JSON'un iki örneği: biri başarılı bir satış, diğeri ise başarısız bir satış. Bu bilgiler callback'ler aracılığıyla gözlemlenebilir.

Örnek

//Başarılı Satış
{
  "basketID": "93ced0be-99f5-4e42-b0ca-bc781c778d69",
  "documentType": 0,
  "InstanceIdentifier": "XXXX",
  "invoiceID": "",
  "message": "OK",
  "paymentCount": 1,
  "paymentItems": [
    {
      "amount": 2000,
      "BatchNo": 0,
      "currencyId": 0,
      "description": "Tum tutarı nakit olarak odet",
      "operatorId": 0,
      "status": -1,
      "TxnNo": 0,
      "type": 1
    }
  ],
  "receiptNo": 2,
  "status": 0,
  "UUID": "aa2c8046-f0bd-4617-9f5d-0bb6eb4f4ed7",
  "zNo": 12
}

//Başarısız Satış
{
	"basketID":"",
	"message":"CANCELLED",
	"status":-1
}