TokenX API Integration

Giriş

Bu dokümantasyon, TokenX API ile entegrasyon sürecini ayrıntılı bir şekilde açıklamaktadır. Entegrasyon süreci, gerekli API KEY bilgilerini almak, webhook adreslerini ayarlamak ve çeşitli API çağrıları yapmak gibi adımları içerir. Aşağıda, TokenX API ile entegrasyon için izlenmesi gereken ana adımlar detaylandırılmaktadır.

Mimari

Entegrasyon

Entegrasyon için aşağıdaki adımların takip edilmesi gerekmektedir.

1. API KEY Bilgilerinin Alınması

API istekleri sırasında, header kısmında iki önemli değişken olan client-id ve client-secret bulunmalıdır. Bu değerler, kimlik doğrulama amacıyla kullanılmakta ve tüm API isteklerinde zorunludur.

• İş Yeri Sahibi ve Bilgilerin Paylaşımı: İş yerine özgü bu bilgiler, iş yeri sahibinden alınmalıdır. İş Yeri sahibi, TokenX İş yeri Paneli’ndeki Kablosuz Entegrasyon sayfasından client-id ve client-secret bilgilerini alabilir.

2. Webhook Adreslerinin Ayarlanması

İşlem sonuçları, entegrasyon yapacak firmanın sunucularına webhook şeklinde POST edilerek gönderilir. Entegrasyon yapacak firma, bu isteği karşılayacak webhook adresini kurulum esnasında bu aşamada ayarlamalıdır.

• Webhook URL Ayarları: Webhook URL'i ve kimlik doğrulama header'ı, Postman koleksiyonunda bulunan ClientSettings API'ı aracılığıyla ayarlanabilir. (Not: Testler sırasında, herhangi bir sunucu ayağa kaldırılmadan gelen işlem sonucunu görebilmek adına https://webhook.site/ gibi REST API karşılayan bir adres verilebilir.)

• IP Whitelist (Opsiyonel): İletişimin güvenliği için belirli TokenX IP adresleri isteğe bağlı olarak beyaz listeye alınabilir.

  • Test Ortamı: Dokümantasyon'a eklenecektir.

  • Production Ortamı: Dokümantasyon'a eklenecektir.

3. Kısım Listesinin Alınması (Get Fiscal Parameters)

Harici sistem ile Token ÖKC'nin mali olarak eşleşmesi için zorunlu adımdır. Mali parametreleri almak için Postman Collection'da yer alan isteğin header kısmında terminalId bilgisi bulunmalıdır.

• Gerekli Parametre: terminalId mutlaka header’da yer almalıdır.

• Yanıt: Yanıt formatı ve içeriği ile ilgili detaylar yakında dokümantasyon'a eklenecektir.

4. Sepet Oluşturma (Send Basket)

• Bir Terminal İçin Sepet Oluşturma: Sadece bir terminale istek atılması isteniyor ise Postman Collection'da yer alan isteğin header kısmına terminalId eklenmelidir.

• Şube'ye Tanımlanmış Tüm Terminal'ler İçin Sepet Oluşturma: Şube'ye tanımlanmış tüm terminallere istek atılması isteniyor ise Postman Collection'da yer alan isteğin header kısmına branchId eklenmelidir.

• İstek Body'si Detayları ve Yanıt'ı: İsteğin body kısmına eklenecek diğer alanlar ile ilgili detaylar'a aşağıdaki link'ten ulaşabilirsiniz. Token Integration Protocol

• Opsiyonel Parametreler: İsteğe bağlı olarak checkNumber (çek numarası), title (başlık), note (not) bilgileri de gönderilebilir. Bu bilgiler ÖKC arayüzünde görüntülenir.

Buraya Figma'dan design eklenecek

5. Sepet Detaylarını Alma (Get Basket)

Oluşturduğunuz sepetin bilgilerini almak için Postman Collection'da yer alan isteğin path kısmında sepetin id bilgisi belirtilmelidir. Bu id bilgisi 4. adımda (Send Basket) gönderdiğiniz isteğin body kısmında bulunan id alanı ile aynı olmalıdır.

• Path Parametresi: Sepetin id bilgisi isteğin URL path'inde verilmelidir.

• Yanıt: Yanıt formatı ve içeriği ile ilgili detaylar yakında dokümantasyon'a eklenecektir.

6. Sepet Silme (Delete Basket)

Oluşturduğunuz sepeti silmek için Postman Collection'da yer alan isteğin path kısmında sepetin id bilgisi belirtilmelidir. Bu id bilgisi 4. adımda (Send Basket) gönderdiğiniz isteğin body kısmında bulunan id alanı ile aynı olmalıdır.

• Path Parametresi: Sepetin id bilgisi isteğin URL path'inde verilmelidir.

• Yanıt: Yanıt formatı ve içeriği ile ilgili detaylar yakında dokümantasyon'a eklenecektir.

7. Status Codes

Sepet işlemlerine ait durum kodları aşağıdaki gibidir (Güncel değildir):

• POS (ÖKC) Kodları: Dokümantasyon'a eklenecektir.

• Banka Kodları: 5xxx ile başlayan ve bankacılık işlemleri için kullanılan kodlar.

• Yeni Kodlar: Dokümantasyona'a eklenecektir

Status	Description	Type
0	Successful	success
-1	User Cancelled	warn
1	Missing Info	error
2	Invalid E-Invoice Customer	error
3	E-Invoice Integrator Error	error
4	Network Error	error
5	Offline Invoice	success
6	Onboarding error	error
7	Invalid E-invoice Id	error
8	Missing Customer Info	error
9	POS is Busy	warn
10	Payment Plan Error	error
11	Payment is cancelled	warn
12	Unknown E-Invoice Integrator	error
13	Integrator Response Parsing Error	error
1001	Missing ClientId	error
1002	Missing TerminalId	error
1003	Timeout	warn
1004	Missing Info	error
1005	Locked Transaction	warn
1006	Record not Found	error
1007	Duplicate ID	error
1008	Unauthorized Terminal Error	error
1009	Callback URL Error	warn
1010	Timeout	warn
1011	Transaction was not delivered to the terminal	warn
1012	Transaction is not completed yet	info
1013	Wrong data format	error
1014	General Error	error
5001	Error	error
5002	Cancelled	warn
5003	Offline Decline	error
5004	Unable Decline	error
5005	Online Decline	error
5006	Payment App Not Found	error
5008	Bank App Not Found	error
5009	Bank App Crashed	error
5101	Card Validation Error	error
5102	Card Validation User Cancelled	warn
5104	Card Validation Timeout	error
5105	Card Validation Fallback Auth	error
5106	Card Validation Parsing Error	error
5107	BIN Query Error	warn
5108	Card Type is not Credit	warn
5109	Card Type is not Debit	warn
5110	Card Type is not Domestic	warn
5111	Card is not Issued by Requested Bank	warn
5112	Card Type is not Foreign	warn

Postman Koleksiyon'u Link'i

İlgili Postman Koleksiyon'u dokümantasyon'a eklenecektir.