Geliştirici Dokümanı (TR)
Sunucu entegrasyonu
Last updated
Sunucu entegrasyonu
Last updated
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.
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 için aşağıdaki adımların takip edilmesi gerekmektedir.
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.
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.
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.
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.
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.
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.
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 |
0001 | JWT token algoritması beklenen ile eşleşmiyor. | Token algoritma doğrulama hatası |
0002 | JWT token süresi dolmuş ve artık geçerli değil. | Token süresi dolma hatası |
0003 | JWT token imzası geçersiz veya beklenen imza ile eşleşmiyor. | Token imza doğrulama hatası |
0004 | Authorization başlığı eksik veya yanlış formatlanmış. | Authorization başlığı hatası |
0005 | JWT token'den belirli bir alan (örneğin "claim") alınamıyor. | Token alanı çıkarma hatası |
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 |
Aşağıda belirtilen Postman Koleksiyonu'nu kullanarak, yukarıda belirtilen TokenX API'larının detaylarına ulaşabilirsiniz ve TokenX API'larını verimli ve hızlı bir şekilde test edebilirsiniz: https://documenter.getpostman.com/view/31664195/2sAY4rEQbG