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.
Opsiyonel Parametreler: İsteğe bağlı olarak checkNumber (çek numarası), title (başlık), note (not), filter (filtre) bilgileri de gönderilebilir. Bu bilgiler ÖKC arayüzünde görüntülenir.
Hazır Örnek Sepetler: Hazır istek örnekleri ve detaylarına aşağıdaki link'ten ulaşabilirsiniz. Hazır Örnek Sepetler
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
İ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.
