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 Token ÖKC.

terminal-id: Terminalinize özel olan benzersiz bir id (AV veya AT ile başlayan).

branch-id: 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 mali cihaz.

Entegrasyon

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

1. API KEY Bilgilerinin Alınması (Authenticate API)

TokenX Kablosuz Entegrasyon'da bulunan tüm API istekleri atılırken, her bir işlemin header kısmında access_token bulunmalıdır. Bu access_token'ı almak için entegrasyon yapacak iş yerine özel olarak tanımlanan client-id ve client-secret bilgilerine ihtiyacınız vardır.

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

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

• 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 dönülür.

• Authenticate API Postman Collection Link: https://documenter.getpostman.com/view/31664195/2sAY4rEQbG#a222daa0-2bd0-4448-862a-b911529a0f82
• Yanıt:

  {
      "status": 201,
      "description": "User authenticated successfully.",
      "result": {
          "accessToken": "Abc.", // Entegrasyon sağlayan firmaya özel bir token.
          "expiresIn": 86400, // Access Token'ın kullanılabilirsik süresi.
          "tokenType": "Bearer" // Authorization tipi
      }
  }

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

2. Webhook Adreslerinin Ayarlanması (ClientSettings/Set API)

Asenkron işlem sonuçları, entegrasyon yapacak firmanın sunucularına Webhook şeklinde POST isteği atılarak 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/Set 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/Set 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ı: İsteğe bağlı olarak developer team tarafından paylaşılacaktır.

• Production Ortamı: İsteğe bağlı olarak developer team tarafından paylaşılacaktır.

• 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 edinip asenkron işlemlerine rahatlıkla ulaşabilirsiniz.)
  • Callback Auth: Bu alana, sizin tarafınızdan sağlanacak olan Callback URL'inizin Auth tekniğini girmeniz gerekmektedir. Bir Auth mekanizması kullanmak istemediğiniz takdirde, bu alanı body'de belirtmenize/göndermenize gerek yoktur.

• ClientSettings/Set API Postman Collection Link: https://documenter.getpostman.com/view/31664195/2sAY4rEQbG#abf6615d-c0d2-47e7-b25f-06b4b607bb81
• Yanıt:

  {
      "status": 0,
      "description": "Your client settings has been set successfully"
  }

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

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

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: terminal-id ve access_token atılan isteğin header'ında yer almalıdır.

• Get Fiscal Parameters API Postman Collection Link: https://documenter.getpostman.com/view/31664195/2sAY4rEQbG#3bc1f2da-d73d-4bca-a1ce-1b1c78c2e5bc
• Yanıt:

{
    "status": 0,
    "description": "Successfully Fetched Fiscal Parameters",
    "result": {
        "sections": [
            {
                "limit": 0,
                "name": "İçecek",
                "price": 0,
                "sectionNo": 1,
                "taxPercent": 1000,
                "type": 0,
                "plus": []
            }
        ],
        "terminal": "AV0000000658",
        "createdAt": "2025-03-20T13:51:06.961Z",
        "updatedAt": "2025-03-20T13:51:06.961Z"
    }
}

4. Sepet Oluşturma (Add Basket API)

Oluşturulan, tamamlanmamış (açık kalan) ve iptal edilen sepetler azami 2 hafta boyunca tutulmaktadır.

• 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 terminal-id 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 branch-id 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
• Add Basket API Postman Collection Link: https://documenter.getpostman.com/view/31664195/2sAY4rEQbG#3baaa40f-e0de-4e5c-b2c4-29c921b05832
• 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

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

5. Anlık Sepet Oluşturma (Add Instant Basket API)

Bir sepeti direkt bir terminal üzerinde anında ödeme alma amaçlı kullanım için kullanılır. 4. maddedeki opsiyonel parametreler ve body aynen geçerli olup header'da terminal-id girilmelidir. Yine authentication için access_token da header'da sağlanmalıdır.

• Bu isteği kullanarak cihaza direkt sepet gönderebilmek için cihazın modu 'sepet ödemesini hemen al' şeklinde değiştirilmiş olmalıdır.

• Bu isteğin header'ına branch-id girilmemelidir.

• Oluşturulan, tamamlanmamış (açık kalan) ve iptal edilen sepetler azami 2 hafta boyunca tutulmaktadır.

• Add Instant Basket API Postman Collection Link: https://documenter.getpostman.com/view/31664195/2sAY4rEQbG#849e3f7b-6da9-4de3-8034-1a43353a6c87

6. Terminal'de Olan Tamamlanmamış Sepetleri Alma (Get Open Baskets For Terminal API)

Bu istek terminalinizde olan, 4. veya 5. adımda oluşturduğunuz ve tamamlamadığınız sepetlerin bilgilerine ulaşabilmeniz için kullanılır.

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

• Get Open Basket For Terminal API Postman Collection Link: https://documenter.getpostman.com/view/31664195/2sAY4rEQbG#da0b02d6-c49e-4440-b920-54b1a906aa13
• Örnek kullanım senaryoları: - 4. veya 5. adımda bir sepet oluşturdunuz ancak bu sepetin basketID'sini kayıt etmeyi unuttunuz. - Günler önce oluşturduğunuz bir sepetin bilgilerini almak istiyorsunuz ancak bu sepete dair elinizde bir veri yok (basketId, checkNumber gibi). - Terminalinizde bulunan tamamlanmamış sepetleri incelemek istiyorsunuz.

7. Sepet Detaylarını Alma (Get Basket Details API)

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

• Path Parametresi: Sepetin basketID bilgisi isteğin URL path'inde {{BASKET_ID}} olarak belirtilen kısımda verilmelidir.

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

• Get Basket Details API Postman Collection Link: https://documenter.getpostman.com/view/31664195/2sAY4rEQbG#3c34e620-5edc-493c-8be6-40d28be240b4
• Yanıt:

{
    "status": 0,
    "description": "Successfully Fetched the Basket",
    "result": {
        "basketID": "1dbd5ae8-1761-4b30-9a19-d4edde582d89",
        "createdAt": "2025-04-15T08:51:33.913Z",
        "deletedAt": null,
        "status": 0,
        "clientId": "ece000ef-6023-409f-9d9c-f0dc53a872c8",
        "branchId": "7cd82b38-db01-4fc3-8c7f-5850efc9b85f",
        "total": 22500,
        "filter": "Bahçe",
        "checkNumber": 540,
        "title": "Masa 16",
        "isLocked": false,
        "items": [
            {
                "name": "Pizza",
                "price": 15000,
                "sectionNo": 1,
                "taxPercent": 1000,
                "quantity": 1000
            },
            {
                "name": "Cola",
                "price": 7500,
                "sectionNo": 1,
                "taxPercent": 1800,
                "quantity": 1000
            }
        ],
        "paymentItems": []
    }
}

8. Sepet Silme (Delete Basket API)

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

• Path Parametresi: Sepetin basketID bilgisi isteğin URL path'inde {{BASKET_ID}} olarak belirtilen kısımda verilmelidir.

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

• Delete Basket API Postman Collection Link: https://documenter.getpostman.com/view/31664195/2sAY4rEQbG#da0b02d6-c49e-4440-b920-54b1a906aa13
• Yanıt:

  {
      "status": 0,
      "description": "Basket Record Successfully Deleted"
  }

9. Ödeme Sonrası Webhook İle Bildirim

Ödeme sonrası Webhook ile bildirim alabilmek için Dokümantasyonun 2. Adımındaki Webhook Adreslerinin Ayarlanması (ClientSettings API) işlemini yapmış olmanız gerekmektedir.

Oluşturduğunuz bir sepetin ödemesini yaptıktan sonra 2. Adımda girdiğiniz webhook adresine (girildi ise) ödemenin detaylarını içeren bir data iletilecektir. İletilecek data ödeme sonucuna göre değişecektir, aşağıda iletilebilecek data'ların örneklerini bulabilirsiniz:

• Status = 0 Başarılı ödenen bir sepet sonrası giden webhook içeriği:

  {
      "terminalId": "AV00000000001",
      "clientId": "ece000ef-6023-409f-9d9c-f0dc53a872c8",
      "operation": "BASKET_COMPLETED",
      "operationDate": "2025-03-10T08:42:18.640Z",
      "data": {
          "basketID": "f85d8ce7-4306-4141-a52d-39aa6bef0955",
          "documentType": 0,
          "InstanceIdentifier": "XXXX",
          "invoiceID": "",
          "message": "OK",
          "paymentCount": 1,
          "paymentItems": [
              {
                  "amount": 4000,
                  "BatchNo": 0,
                  "currencyId": 0,
                  "description": "Payment with cash",
                  "operatorId": 0,
                  "status": -1,
                  "TxnNo": 0,
                  "type": 1
              }
          ],
          "receiptNo": 2,
          "status": 0,
          "UUID": "afae6f21-5391-4232-9d60-14aa1f5d9188",
          "zNo": 87
      }
  }

• Status = -1 Ödemeden vazgeçildi:

  {
      "clientId": "a524101f-9a44-479d-a291-357eb867d751",
      "operation": "BASKET_COMPLETED",
      "operationDate": "2025-03-10T08:50:09.916Z",
      "data": {
          "basketID": "f530e8cf-1cfc-4c57-a863-3570109ea958",
          "documentType": 9006,
          "message": "CANCELLED",
          "status": -1
      }
  }

• Status = 99 Fiş İptali:

  {
      "clientId": "a524101f-9a44-479d-a291-357eb867d751",
      "operation": "BASKET_COMPLETED",
      "operationDate": "2025-03-10T10:54:02.614Z",
      "data": {
          "basketID": "b4769601-d904-4a2a-ab83-ba0ae8981391",
          "documentType": 0,
          "InstanceIdentifier": "XXXX",
          "invoiceID": "",
          "message": "CANCELLED",
          "paymentCount": 0,
          "receiptNo": -1,
          "status": 99,
          "UUID": "4baf7eb9-f9dc-4714-b87d-a04367e9efd3",
          "zNo": -1
      }
  }

10. Statü Kodları

Sepet işlemlerine ait durum kodları aşağıdaki gibidir:

• Token-X Connect API Entegrasyon Kodları

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
1006	No record found	error
1007	DB error: Duplicate record	error
1013	Wrong data format	error
1018	Error: Order locked! For this operation you must first unlock the order.	error
1100	There is already an open basket assigned to this terminal	error
1101	There is already an open basket for this check number	error
1102	This basket has already been completed	error
1103	The total of the items and the total payment amount are not equal!'	error
1104	This terminals mode is not suitable for receiving instant baskets	error

Demo Video (Send Basket & Instant Basket)

https://tokenfintech-my.sharepoint.com/:v:/g/personal/25200284_tokeninc_com/EfUk29I2H-RGqda7K31B6qkBXwRB_HZiY1scYVc-p-rmBA?e=fo4OJW

Postman Koleksiyon'u Link'i

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

Otomasyon Yazılım Simülatörü

Aşağıda belirtilen link'e tıklayarak, yukarıda belirtilen TokenX API'larını dinamik simülatör uygulamamız aracılığıyla kolayca test edebilirsiniz: https://xci.devtokeninc.com/