Geliştirici Dokümanı (TR)

Sunucu entegrasyonu

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

TokenX Kablosuz Entegrasyon Mimari

Anahtar Kelimeler ve Terminoloji

Sepet: Satın alma işleminin Token ÖKC tarafından işlenmesi gereken detaylarını içerir. Bu detaylar, fiş veya fatura kesmek için gerekli olan ürün isimleri, fiyatlar, miktarlar ve vergi bilgilerini kapsar.

Access_token: API isteklerini doğrulamak ve yetkilendirmek için kullanılan bir kimlik doğrulama anahtarı, yalnızca yetkili kullanıcıların sistemle etkileşimde bulunmasını sağlar.

Terminal: İşlemleri ve ödemeleri işlemek için kullanılan POS cihazı.

BranchId: Bir veya birden fazla terminal ile ilişkili belirli bir şubeyi tanımlayan benzersiz id.

ÖKC (Ödeme Kaydedici Cihaz): Satış ve vergi bilgilerinin yasal düzenlemelere uygun olarak kaydedilmesi için kullanılan bir mali cihaz.

Entegrasyon

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

1. API KEY Bilgilerinin Alınması

API istekleri sırasında, tüm işlemlerin header kısmında access_token bulunmalıdır. Access Token'ı almak için entegrasyon yapacak iş yerine özel olarak tanımlanan client-id ve client-secret bilgilerine ihtiyacınız vardır.

• İş 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.

Test aşamasında, client-id ve client-secret bilgileri developer team tarafından tarafınıza iletilecektir.

• Access Token Bilgilerinin Alınması: client-id ve client-secret bilgilerini aldıktan sonra tarafınıza iletilen TEST_URL/v1/auth/token endpoint'ine client-id ve client-secret'ı header'da Basic Auth tekniğini kullanarak POST isteği şeklinde gönderilir. İsteğin sonucunda kullanıcıya access-token.

API KEY Bilgilerinin Alınması İş Akışı Sıra Diyagramı

2. Webhook Adreslerinin Ayarlanması (ClientSettings API)

Asenkron iş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 ve bu adrese erişmek için gereken Auth bilgisini Postman koleksiyonunda bulunan ClientSettings API'ı aracılığıyla ayarlamalıdır. Aksi takdirde, entegrasyonun ilerleyen aşamalarında yapılacak işlemlerin (lock, unlock, payment) asenkron statüleri hakkında bilgi sahibi olamayacaktır. ClientSettings API Detayları

IP Whitelist

Entegrasyon yapacak işyerleri, IP kısıtlamaları var ise, iletişimin güvenliğini sağlamak amacıyla belirli TokenX IP adreslerini isteğe bağlı olarak IP listelerine ekleyebilirler.

• Test Ortamı: Dokümantasyona eklenecektir.

• Production Ortamı: Dokümantasyona eklenecektir.

• Header:

  • İsteğin header kısmında, Auth tekniği olarak Bearer Token seçilmelidir ve Bearer Token değeri, bir önceki adımda yapılan TEST_URL/v1/auth/token isteği sonucunda elde edilen Access Token bilgisidir.

• Body:

  • Callback URL: Bu alana, kullanıcının kendi Webhook adresini girmesi gerekmektedir. Bu URL, entegrasyon sürecinde asenkron olarak gönderilecek işlem durumlarının iletileceği adrestir. (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 site kullanarak kolaylıkla webhook adresi edinebilirsiniz.)

  • Callback Auth: Bu alana, sizin tarafınızdan sağlanacak olan Callback URL'inizin Auth tekniğini girmeniz gerekmektedir.

Client Settings API İş Akışı Sıra Diyagramı

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ği inceleyebilirsiniz.

• Header: terminalId ve access_token atılan isteğin header'ında 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 ve access_token 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 ve access_token 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.

Sepetin Cihaza İletilip Ödemenin Tamamlanması Akış Diyagramı

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

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.

• Header: terminalId ve access_token atılan isteğin header'ında yer almalıdır.

• 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.

• Header: terminalId ve access_token atılan isteğin header'ında yer almalıdır.

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

7. Statü Kodları

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.