Geliştirici Dokümanı (TR)

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.

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

  Copy

  {
      "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ı

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

  Copy

  {
      "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.

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

• 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. JSON Açıklamaları

• 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

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.

• 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 {{basketID}} 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 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.

  Copy

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

• Update Basket API Postman Collection Link: https://documenter.getpostman.com/view/31664195/2sAY4rEQbG#fd33ef0c-44eb-4103-80ae-efe8d97cb870

• Yanıt:

  Copy

  {
      "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.

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

• Yanıt:

  Copy

  {
      "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:

  Copy

  {
    "basketID": "" //your basketID
  }

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

• Unlock Basket API Postman Collection Link: https://documenter.getpostman.com/view/31664195/2sAY4rEQbG#d133b781-056a-4a10-bc20-e695cd132940

• Yanıt:

  Copy

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

11. Ödeme Sonrası Webhook İle Bildirim

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:

  Copy

  {
      "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:

  Copy

  {
      "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:

  Copy

  {
      "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.

• Get Terminal API Postman Collection Link: https://documenter.getpostman.com/view/31664195/2sAY4rEQbG#44a36e8a-d8e3-4d3b-9145-f0478b3ff77a

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

Kablosuz Entegrasyon Demo Video (Send Basket & Instant Basket)

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/