# 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

<figure><img src="https://828363377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTDApe9ujkHROOK7s0JPT%2Fuploads%2FcI3eTegM0MywNA2HzQxr%2FTokenX-Wireless-Integration.jpeg?alt=media&#x26;token=b2dbeada-ba36-412e-bb7c-0aeb3dd9925b" alt=""><figcaption><p>TokenX Kablosuz Entegrasyon Mimari</p></figcaption></figure>

## 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.&#x20;

**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).&#x20;

**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ı&#x72;**.**  Bu **access\_token'ı** almak için entegrasyon yapacak her bir entegratör için tanımlı `client-id` ve `client-secret` bilgilerine ihtiyacınız vardır.

{% hint style="warning" %}
Test aşamasında, `client-id` ve `client-secret` bilgileri developer team tarafından tarafınıza iletilecektir.
{% endhint %}

* **Gerçek Ortamda Bilgilerin Paylaşımı:** Entegratörler için gerçek ortamda oluşturulmuş `client-id` ve `client-secret` bilgileri devops/güvenlik ekibimiz tarafından mail ile paylaşılacaktır.
* **Access Token Bilgilerinin Alınması**: `client-id` ve `client-secret` bilgilerini aldıktan sonra tarafınıza iletilen TEST\_AUTH\_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.&#x20;
* **Authenticate API Postman Collection Link:** <https://documenter.getpostman.com/view/29891759/2sB34hEzUj#8fbe3d5c-ff40-461a-9f7d-324d268bf910>
* **Yanıt:**<br>

  ```json
  {
      "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
      }
  }
  ```

<figure><img src="https://828363377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTDApe9ujkHROOK7s0JPT%2Fuploads%2F1KuSVUhhzurBunMyjYBF%2Fimage.png?alt=media&#x26;token=8e3ea7be-923d-42fa-b231-2b75b12263ac" alt=""><figcaption><p>API KEY Bilgilerinin Alınması İş Akışı Sıra Diyagramı</p></figcaption></figure>

### 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 Settings` 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. ***Her bir entegratörün yani client'ın tanımlı tek bir callback url'i olabilir.***<br>

#### **2.1. Dinamik Parametre Kullanımı**

Callback URL alanı, **dinamik endpoint** tanımlanmasına izin vermektedir. Entegrasyon yapacak firma, webhook adresini sabit bir URL olarak tanımlayabileceği gibi, URL path’i içerisinde dinamik parametreler de kullanabilir.

Dinamik parametreler **`${}`** içerisinde belirtilmelidir.

Desteklenen dinamik parametreler:

* `${terminal-id}`
* `${basket-id}`
* `${branch-or-terminal-id}`

**`${branch-or-terminal-id}` Parametresi Hakkında**

`${branch-or-terminal-id}` parametresi, işlemin gönderim moduna göre farklı değerler alır:

* **Anlık (Terminal bazlı/Sepet ödemesini hemen al) sepet gönderimlerinde:**\
  Bu alana ilgili **terminal-id** değeri yazılır.
* **Liste (Şube bazlı/birden fazla sepeti listele) gönderimleride:**\
  Bu alana ilgili **branch-id** değeri yazılır.

Bu sayede, webhook endpoint’i tek bir URL üzerinden hem terminal bazlı hem de şube bazlı senaryoları karşılayacak şekilde dinamik olarak kurgulanabilir.

**Örnek Callback URL’ler**

```
https://example.com/webhook/${terminal-id}
```

```
https://example.com/webhook/${branch-or-terminal-id}/basket/${basket-id}
```

```
https://example.com/api/v1/callback/${branch-or-terminal-id}
```

> Not: Webhook çağrısı sırasında, tanımlanan dinamik parametreler sistem tarafından otomatik olarak ilgili değerlerle doldurularak POST isteği gönderilir.

#### **2.2. ClientSettings/Set API Detayları**

{% hint style="warning" %}
**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.**
  {% endhint %}

* **Header**:&#x20;
  * İ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/29891759/2sB34hEzUj#62622419-8b6c-41f2-bbbb-a50d8e80e39d>

* **Yanıt:**<br>

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

<figure><img src="https://828363377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTDApe9ujkHROOK7s0JPT%2Fuploads%2FENilZTTvNw5gtYxAXAsW%2Fimage.png?alt=media&#x26;token=65a73778-197e-4620-a6c4-4550d607bc50" alt=""><figcaption><p>Client Settings API İş Akışı Sıra Diyagramı</p></figcaption></figure>

### 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/29891759/2sB34hEzUj#0fb73616-dafa-45b2-8cfe-9779bdf3d7bf>
* **Yanıt**:&#x20;

```json
{
    "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-aciklamalari](https://developer.tokeninc.com/token-developer-portal-1/x-platform/token-x-connect-wire/gelistirici-dokumani#json-aciklamalari "mention")
* **Add Basket API Postman Collection Link:** <https://documenter.getpostman.com/view/29891759/2sB34hEzUj#bebec308-ae0e-4a22-8117-d05fe80dd6e7>
* **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.&#x20;
* **Hazır Örnek Sepetler**: Hazır istek örnekleri ve detaylarına aşağıdaki link'ten  ulaşabilirsiniz. \
  [hazir-ornek-sepetler](https://developer.tokeninc.com/token-developer-portal-1/x-platform/token-x-connect-wire/hazir-ornek-sepetler "mention")<br>

<figure><img src="https://828363377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTDApe9ujkHROOK7s0JPT%2Fuploads%2FWCNZfQQg0wihDByokGjL%2Fimage.png?alt=media&#x26;token=cb9e055f-9962-4502-8247-53fbddaebc1f" alt=""><figcaption><p>Sepetin Cihaza İletilip Ödemenin Tamamlanması Akış Diyagramı</p></figcaption></figure>

### 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. &#x20;

{% hint style="warning" %}

* 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.&#x20;

* Bu isteğin header'ına `branch-id` **girilmemelidir**.&#x20;

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

* **Add Instant Basket API Postman Collection Link:** \
  <https://documenter.getpostman.com/view/29891759/2sB34hEzUj#c2ee89a1-e1c1-42d2-ab65-b0135d74238b>

### 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.&#x20;

* **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/29891759/2sB34hEzUj#68a3fa13-438e-4fd8-9e2d-b3cd6d760a8f>
* **Ö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/29891759/2sB34hEzUj#b1bb5053-d6aa-4a20-a174-257c6cc03a95>
* **Yanıt**:&#x20;

```json
{
    "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:&#x20;

  Ö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.&#x20;

  ```json
  "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/29891759/2sB34hEzUj#a7d6c4cc-09bc-48d8-a69b-a697f42eaae5>

* **Yanıt**:<br>

  ```json
  {
      "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/29891759/2sB34hEzUj#06296a04-2985-4f78-9b1f-e65d5a5dad25>
* **Yanıt**:<br>

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

  ```json
  {
    "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/29891759/2sB34hEzUj#6425942f-3157-4b85-bbe3-ae00d5c70089>
* **Yanıt**:<br>

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

### 11. Webhook İle Bildirim

{% hint style="warning" %}

### Ö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.&#x20;

{% endhint %}

Dokümantasyonun 2. adımında tanımladığınız webhook adresine, olayın türüne göre farklı içeriklere sahip JSON formatında bir `POST` isteği gönderilir. Gelen isteğin `operation` alanını kontrol ederek hangi olayın gerçekleştiğini anlayabilirsiniz.

#### **11.1. Ödeme Sonuç Bildirimleri (`BASKET_COMPLETED`)**

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

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

  <pre class="language-json"><code class="lang-json">{
      "terminalId": "AV00000000001",
      "clientId": "ece000ef-6023-409f-9d9c-f0dc53a872c8",
      "operation": "BASKET_COMPLETED",
  <strong>    "operationDate": "2025-03-10T08:42:18.640Z",
  </strong>    "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
      }
  }
  </code></pre>
* **Status = -1**\
  **Ödemeden vazgeçildi:**<br>

  ```json
  {
      "terminalId": "AV00000000001",
      "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:**<br>

  <pre class="language-json"><code class="lang-json">{
  <strong>    "terminalId": "AV00000000001",    
  </strong>    "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
      }
  }
  </code></pre>

#### **11.2. Sepet Durum Bildirimleri**

Daha önceden oluşturulumuş sepetlerin kilitlenme durumları da, girdiğiniz webhook adresine (girildi ise), aşağıdaki payload örneği gibi iletilecektir. İletilecek payload, iki farklı şekilde olabilir; sepet kilitlenebilir ya da kilidi açılabilir.&#x20;

**Sepeti Kilitlendi** (`BASKET_LOCKED`)**:**

```json
{
  "terminalId": "AV0000000001",
  "clientId": "ece000ef-6023-409f-9d9c-f0dc53a872c8",
  "operation": "BASKET_LOCKED",
  "operationDate": "2025-07-28T12:35:42.178Z",
  "data": {
    "basketID": "c6ffdfeb-9897-489c-a81e-4e4cf41f1175",
    "lockedBy": "AV0000000001"
  }
}       
```

**Sepet Kilidi Açıldı** (`BASKET_UNLOCKED`)**:**

```json
{
  "terminalId": "AV0000000001",
  "clientId": "ece000ef-6023-409f-9d9c-f0dc53a872c8",
  "operation": "BASKET_UNLOCKED",
  "operationDate": "2025-07-28T12:35:44.069Z",
  "data": {
    "basketID": "c6ffdfeb-9897-489c-a81e-4e4cf41f1175"
  }
}
```

### 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` / `merchant-id` / `terminal-id` (üç parametreden birisi) ve `access_token` atılan isteğin header'ında yer almalıdır.
* **Get Terminal API Postman Collection Link:** <https://documenter.getpostman.com/view/29891759/2sB34hEzUj#60c7e9bd-955b-42b0-aeed-7a8a16cb4f32>
* **Yanıt**:&#x20;

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

  * 0: Birden fazla sepeti listele (Masada/Kapıda Ödeme)&#x20;
  * 1: Sepet ödemesini hemen al (Kasada Ödeme)

```json
{
    "status": 0,
    "description": "Terminal List Successfully Fetched",
    "result": [
        {
            "id": "AV0000000001",
            "branchId": "b81bb869-d45c-43df-a078-9337900ff84e",
            "mode": 0
        },
        {
            "id": "AV0000000002",
            "branchId": "b81bb869-d45c-43df-a078-9337900ff84e",
            "mode": 0
        }
    ]
}
```

### 13. Statü Kodları

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

* **Token-X Connect API Entegrasyon Kodları**

<table data-header-hidden><thead><tr><th></th><th></th><th></th><th data-hidden></th><th data-hidden></th></tr></thead><tbody><tr><td><strong>Status</strong></td><td><strong>Description</strong></td><td><strong>Type</strong></td><td><strong>Step</strong></td><td><strong>Source</strong></td></tr><tr><td>0001</td><td>JWT token algoritması beklenen ile eşleşmiyor.</td><td>Token algoritma doğrulama hatası</td><td></td><td></td></tr><tr><td>0002</td><td>JWT token süresi dolmuş ve artık geçerli değil.</td><td>Token süresi dolma hatası</td><td></td><td></td></tr><tr><td>0003</td><td>JWT token imzası geçersiz veya beklenen imza ile eşleşmiyor.</td><td>Token imza doğrulama hatası</td><td></td><td></td></tr><tr><td>0004</td><td>Authorization başlığı eksik veya yanlış formatlanmış.</td><td>Authorization başlığı hatası</td><td></td><td></td></tr><tr><td>0005</td><td>JWT token'den belirli bir alan (örneğin "claim") alınamıyor.</td><td>Token alanı çıkarma hatası</td><td></td><td></td></tr><tr><td>0006</td><td>One of terminal-id, branch-id, merchant-id must be present.</td><td>No credential header provided</td><td></td><td></td></tr><tr><td>0007</td><td>Only one of terminal-id, branch-id, merchant-id must be present.</td><td>Multiple credential headers provided</td><td></td><td></td></tr><tr><td>0011</td><td>Forbidden access.</td><td>Forbidden access</td><td></td><td></td></tr><tr><td>0012</td><td>Internal server error.</td><td>Internal server error</td><td></td><td></td></tr><tr><td>0013</td><td>x-application-resource header is required.</td><td>Application resource header is missing</td><td></td><td></td></tr><tr><td>0</td><td>Successful</td><td>success</td><td>-</td><td>POS</td></tr><tr><td>1006</td><td>No record found</td><td>error</td><td>1</td><td>API</td></tr><tr><td>1007</td><td>DB error: Duplicate record</td><td>error</td><td>1</td><td>API</td></tr><tr><td>1013</td><td>Wrong data format</td><td>error</td><td>1</td><td>API</td></tr><tr><td>1018</td><td>Error: Order locked! For this operation you must first unlock the order.</td><td>error</td><td>1</td><td>API</td></tr><tr><td>1100</td><td>There is already an open basket assigned to this terminal</td><td>error</td><td>1</td><td>API</td></tr><tr><td>1101</td><td>There is already an open basket for this check number</td><td>error</td><td>3</td><td>API</td></tr><tr><td>1102</td><td>This basket has already been completed</td><td>error</td><td>1</td><td>API</td></tr><tr><td>1103</td><td>The total of the items and the total payment amount are not equal!'</td><td>error</td><td>1</td><td>API</td></tr><tr><td>1104</td><td>This terminals mode is not suitable for receiving instant baskets</td><td>error</td><td>1</td><td>API</td></tr><tr><td>1105</td><td>This baskets status is not suitable for this operation</td><td>error</td><td></td><td></td></tr><tr><td>1106</td><td>The device with this id was not found in the system</td><td>error</td><td></td><td></td></tr></tbody></table>

## Kablosuz Entegrasyon Demo Video (Send Basket & Instant Basket)

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTDApe9ujkHROOK7s0JPT%2Fuploads%2FmBWpEXaMyz2bv9uGcB7C%2FScreen%20Recording%202025-03-24%20at%2015.19.15%201.mp4?alt=media&token=7483adc6-9b45-48ed-8ad5-1bafb74d8df8>" %}

## 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/29891759/2sB34hEzUj>

## Otomasyon Yazılım Simülatörü&#x20;

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/>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.tokeninc.com/token-developer-portal-1/x-platform/token-x-connect-cloud/gelistirici-dokumani-tr.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.