Token Developer Portal
Token AI Support
X Platform - Entegrasyon
X Platform - Entegrasyon
  • Token X Entegrasyon
  • Welcome
  • İş Akışları & Hazır Sepetler
  • Token X Connect (Wire)
    • Hızlı Başlangıç
    • Genel Tanıtım
    • Geliştirici Dokümanı
    • Örnek Uygulamalar
    • Sık Sorulan Sorular
    • Cihaz Bilgilendirme
    • Protokol Bilgileri
    • Sorun Tespit Aracı
  • Token X Connect (Cloud)
    • Genel Tanıtım (TR)
    • Geliştirici Dokümanı (TR)
    • TokenX API Integration (EN)
    • Automation Software Simulator
    • Sık Sorulan Sorular
  • Changelog
    • TokenX Connect
    • Backend
  • DESTEK
    • Geliştirici Destek
  • Test
    • Test Sürecimiz
  • APPSTORE
    • Tanıtım
Powered by GitBook
On this page
  • Giriş
  • Mimari
  • Anahtar Kelimeler ve Terminoloji
  • Entegrasyon
  • 1. API KEY Bilgilerinin Alınması (Authenticate API)
  • 2. Webhook Adreslerinin Ayarlanması (Set Client Settings API)
  • 3. Kısım Listesinin Alınması (Get Fiscal Parameters API)
  • 4. Sepet Oluşturma (Add Basket API)
  • 5. Anlık Sepet Oluşturma (Add Instant Basket API)
  • 6. Terminal'de Olan Tamamlanmamış Sepetleri Alma (Get Open Baskets For Terminal API)
  • 7. Sepet Detaylarını Alma (Get Basket Details API)
  • 8. Sepet Güncelleme (Update Basket API)
  • 9. Sepet Silme (Delete Basket API)
  • 10. Sepet Kilidini Açma (Unlock Basket)
  • 11. Ödeme Sonrası Webhook İle Bildirim
  • 12. Terminal Listesini Alma (GET Terminal)
  • 13. Statü Kodları
  • Kablosuz Entegrasyon Demo Video (Send Basket & Instant Basket)
  • Postman Koleksiyon'u Link'i
  • Otomasyon Yazılım Simülatörü
  1. Token X Connect (Cloud)

Geliştirici Dokümanı (TR)

Sunucu entegrasyonu

PreviousGenel Tanıtım (TR)NextTokenX API Integration (EN)

Last updated 7 days ago

Giriş

Bu dokümantasyon, TokenX Kablosuz 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

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.

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

2. Webhook Adreslerinin Ayarlanması (Set Client Settings 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 Set Client SettingsAPI'ı 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 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.

  • Yanıt:

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

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.

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

  • 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

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.

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.

  • Ö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 {{basketID}} olarak belirtilen kısımda verilmelidir.

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

  • 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 Güncelleme (Update Basket API)

Oluşturduğunuz sepeti güncellemek için Postman Collection'da yer alan PUT isteğinin 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 {{basketID}} olarak belirtilen kısımda verilmelidir.

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

  • Body: Güncellenmek istenen field'lar iletilmelidir (bkz: Sepet Oluşturma Endpointleri). Eğer items veya paymentItems gibi array alanlarda ekleme-çıkarma olmuş ise array'in son hali iletilmelidir:

    Örneğin; Daha önce sepet oluşturulurken iletilen ürün listesinde Pizza isimli ürün varken sepete Cola da eklenmişse PUT isteği şu şekilde iletilmelidir.

    "items": [
        {
            "name": "Pizza",
            "price": 15000,
            "sectionNo": 1,
            "taxPercent": 1000,
            "quantity": 1000
        },
        {
            "name": "Cola",
            "price": 7500,
            "sectionNo": 1,
            "taxPercent": 1800,
            "quantity": 1000
        }
    ]

  • Yanıt:

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

9. 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 {{basketID}} olarak belirtilen kısımda verilmelidir.

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

  • Yanıt:

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

10. Sepet Kilidini Açma (Unlock Basket)

Oluşturduğunuz sepetin kilidi eğer cihazdan açılamamış ise üzerinde işlem yapabilmek için bu /unlock endpointini kullanabilirsiniz. Postman Collection'da yer alan isteğin body 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.

  • Body: Sepetin basketID bilgisi body içinde aşağıdaki şekilde verilmelidir:

    {
      "basketID": "" //your basketID
    }
  • Header: access_token atılan isteğin header'ında yer almalıdır.

  • Yanıt:

    {
        "status": 0,
        "description": "Unlock Operation Successfully Completed"
    }

11. Ödeme Sonrası Webhook İle Bildirim

Ödeme sonrası Webhook ile bildirim alabilmek için Dokümantasyonun 2. Adımındaki Webhook Adreslerinin Ayarlanması (Set Client Settings 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
        }
    }

12. Terminal Listesini Alma (GET Terminal)

İş yerinin veya opsiyonel olarak iş yerinin belli bir şubesinin çalıştığı cihaz listesini alabilmek için Postman Collection'da Organization folder altında yer alan Get Terminal isteği kullanılabilir.

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

  • Yanıt:

    "mode" alanı cihazın hangi şekilde sepet beklediğini gösterir.

    • 0: Birden fazla sepeti listele (Masada/Kapıda Ödeme)

    • 1: Sepet ödemesini hemen al (Kasada Ödeme)

{
    "status": 0,
    "description": "Terminal List Successfully Fetched",
    "result": [
        {
            "id": "AV0000000823",
            "mode": 1
        }
    ]
}

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

1105

This baskets status is not suitable for this operation

error

1106

The device with this id was not found in the system

error

Kablosuz Entegrasyon Demo Video (Send Basket & Instant Basket)

Postman Koleksiyon'u Link'i

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

Authenticate API Postman Collection Link:

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 gibi REST API karşılayan bir site kullanarak kolaylıkla webhook adresi edinip asenkron işlemlerine rahatlıkla ulaşabilirsiniz.)

ClientSettings/Set API Postman Collection Link:

Get Fiscal Parameters API Postman Collection Link:

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

Add Basket API Postman Collection Link:

Add Instant Basket API Postman Collection Link:

Get Open Basket For Terminal API Postman Collection Link:

Get Basket Details API Postman Collection Link:

Update Basket API Postman Collection Link:

Delete Basket API Postman Collection Link:

Unlock Basket API Postman Collection Link:

Get Terminal API Postman Collection Link:

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:

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://documenter.getpostman.com/view/31664195/2sAY4rEQbG#a222daa0-2bd0-4448-862a-b911529a0f82
https://webhook.site/
https://documenter.getpostman.com/view/31664195/2sAY4rEQbG#abf6615d-c0d2-47e7-b25f-06b4b607bb81
https://documenter.getpostman.com/view/31664195/2sAY4rEQbG#3bc1f2da-d73d-4bca-a1ce-1b1c78c2e5bc
https://documenter.getpostman.com/view/31664195/2sAY4rEQbG#3baaa40f-e0de-4e5c-b2c4-29c921b05832
https://documenter.getpostman.com/view/31664195/2sAY4rEQbG#849e3f7b-6da9-4de3-8034-1a43353a6c87
https://documenter.getpostman.com/view/31664195/2sAY4rEQbG#da0b02d6-c49e-4440-b920-54b1a906aa13
https://documenter.getpostman.com/view/31664195/2sAY4rEQbG#3c34e620-5edc-493c-8be6-40d28be240b4
https://documenter.getpostman.com/view/31664195/2sAY4rEQbG#fd33ef0c-44eb-4103-80ae-efe8d97cb870
https://documenter.getpostman.com/view/31664195/2sAY4rEQbG#da0b02d6-c49e-4440-b920-54b1a906aa13
https://documenter.getpostman.com/view/31664195/2sAY4rEQbG#d133b781-056a-4a10-bc20-e695cd132940
https://documenter.getpostman.com/view/31664195/2sAY4rEQbG#44a36e8a-d8e3-4d3b-9145-f0478b3ff77a
https://documenter.getpostman.com/view/31664195/2sAY4rEQbG
https://xci.devtokeninc.com/
TokenX Kablosuz Entegrasyon Mimari
API KEY Bilgilerinin Alınması İş Akışı Sıra Diyagramı
Client Settings API İş Akışı Sıra Diyagramı
Sepetin Cihaza İletilip Ödemenin Tamamlanması Akış Diyagramı
JSON Açıklamaları