Katalog

Bu uçları kim çağırır?Dış API (s2s)

Taban yol: /api/v1/physical-pos
Kimlik: Her istekte Ed25519 istek imzası — X-Key-Id, X-Date, X-Nonce, X-Signature; gövdeli isteklerde ayrıca Digest. Zaman penceresi ±5 dk, nonce tek kullanımlık. Bearer jetonu ya da panel oturumu bu uçlarda kabul edilmez.
Yetki: Anahtarınız Fiziksel POS ürününü (PHYSICAL_POS) ve bu sayfadaki uçların kapsamını taşımalıdır: physical_pos:view. Ürünü olmayan anahtar 403 PRODUCT_NOT_ENABLED, kapsamı olmayan anahtar 403 API_INSUFFICIENT_SCOPE alır. Bkz. Kimlik Doğrulama ve Kapsamlar.
Çapraz yüzey: Bu uçlar s2s yüzeyindedir; kendi sunucunuzdan imzalı istekle çağırırsınız. Aynı kayıtların panelde ekranları var, ama panel uçları API anahtarıyla çağrılamaz; bu uçlar da panel oturumuyla çağrılamaz.

Katalog, platformda tanımlı POS üreticilerini, cihaz modellerini ve fiziksel POS'ta kullanılabilen bankaları listeler. Katalog bütün işletmeler için ortaktır; yalnız okunur ve ortamdan bağımsızdır (test ve canlı anahtar aynı listeyi görür).

Katalog uçları sayfalanmaz: data bütün listeyi içeren bir dizidir. → Ortak Kurallar › Yanıt zarfı

Üreticiler

GET /api/v1/physical-pos/catalog/vendors

Sorgu parametresi almaz; tanımsız parametre 400 VALIDATION_ERROR döner. Liste, devre dışı üreticiler dahil bütün üreticileri code sırasıyla döner.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/catalog/vendors"
lunixi_sign GET "$REQ_PATH"
 
curl "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"

lunixi-sign.sh: Kimlik Doğrulama › İmza yardımcısı.

{
  "status": "success",
  "code": "SUCCESS",
  "data": [
    {
      "code": "PAVO",
      "displayName": "Pavo",
      "status": "ACTIVE",
      "fallbackImage": {
        "assetId": "00000000-0000-4000-8000-000000000a01",
        "url": "https://img.lunixi.com/00000000-0000-4000-8000-000000000a01"
      }
    },
    {
      "code": "PLUSPAY",
      "displayName": "PlusPay",
      "status": "ACTIVE",
      "fallbackImage": null
    }
  ],
  "statusCode": 200,
  "requestId": "00000000-0000-0000-0000-000000000000"
}

Alan	Tip	Açıklama
`code`	string	Üretici kodu. Terminal oluştururken `vendorCode` alanına bu değeri yazarsınız.
`displayName`	string	Üreticinin görünen adı.
`status`	string	`ACTIVE` ya da `DISABLED`. Devre dışı üretici yeni terminalde kullanılamaz.
`fallbackImage`	object \| null	Üreticinin yedek görseli: modelin kendi görseli yoksa gösterilir. → Görsel nesnesi

Cihaz modelleri

GET /api/v1/physical-pos/catalog/device-models

Sorgu parametresi	Tip	Açıklama
`vendorCode`	string	Yalnız bu üreticinin modelleri. Büyük/küçük harf fark etmez. Biçimi doğru ama katalogda olmayan kod boş liste döner; biçim dışı kod `400 physical_pos.input.filter_invalid`.
`deviceType`	string	`PHYSICAL` ya da `SOFTPOS`.
`status`	string	`ACTIVE` ya da `DEPRECATED`. Gönderilmezse iki durum da döner.

deviceType ya da status küme dışındaysa (büyük/küçük harf duyarlı) istek 400 physical_pos.input.filter_invalid alır; details.field süzgecin adını verir.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/catalog/device-models?vendorCode=PAVO&status=ACTIVE"
lunixi_sign GET "$REQ_PATH"
 
curl "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"

{
  "status": "success",
  "code": "SUCCESS",
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000b01",
      "vendorCode": "PAVO",
      "modelCode": "EXAMPLE-M1",
      "displayName": "Örnek Model M1",
      "deviceType": "PHYSICAL",
      "formFactor": "COUNTERTOP",
      "fiscalCapable": true,
      "status": "ACTIVE",
      "image": {
        "assetId": "00000000-0000-4000-8000-000000000a02",
        "url": "https://img.lunixi.com/00000000-0000-4000-8000-000000000a02"
      },
      "vendorFallbackImage": {
        "assetId": "00000000-0000-4000-8000-000000000a01",
        "url": "https://img.lunixi.com/00000000-0000-4000-8000-000000000a01"
      }
    }
  ],
  "statusCode": 200,
  "requestId": "00000000-0000-0000-0000-000000000000"
}

Alan	Tip	Açıklama
`id`	string (UUID)	Modelin kimliği.
`vendorCode`	string	Modelin üreticisinin kodu.
`modelCode`	string	Üretici içinde modelin kodu.
`displayName`	string	Modelin görünen adı.
`deviceType`	string	`PHYSICAL`: ayrı POS donanımı. `SOFTPOS`: kart kabul eden mobil cihaz.
`formFactor`	string	`COUNTERTOP` (masaüstü), `PORTABLE` (taşınabilir), `MOBILE` (mobil), `UNATTENDED` (gözetimsiz, ör. kiosk), `PINPAD`.
`fiscalCapable`	boolean	Model mali (ödeme kaydedici) cihaz olarak kullanılabiliyorsa `true`.
`status`	string	`ACTIVE` ya da `DEPRECATED`. `DEPRECATED` model katalogda kalır, yeni kurulumlarda tercih edilmemelidir.
`image`	object \| null	Modelin kendi görseli. → Görsel nesnesi
`vendorFallbackImage`	object \| null	Üreticinin yedek görseli (üretici listesindeki `fallbackImage` ile aynı).

Bankalar

GET /api/v1/physical-pos/catalog/acquirers

Sorgu parametresi almaz; tanımsız parametre 400 VALIDATION_ERROR döner. Liste yalnız etkin bankaları acquirerCode sırasıyla döner.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/catalog/acquirers"
lunixi_sign GET "$REQ_PATH"
 
curl "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"

{
  "status": "success",
  "code": "SUCCESS",
  "data": [
    { "acquirerCode": "0000", "providerCode": "EXAMPLEBANK", "displayName": "Örnek Bank" }
  ],
  "statusCode": 200,
  "requestId": "00000000-0000-0000-0000-000000000000"
}

Alan	Tip	Açıklama
`acquirerCode`	string	Bankanın dört haneli banka kodu. Terminalin banka satırlarında `acquirerCode` alanı bu değeri taşır.
`providerCode`	string	Lunixi'nin bu bankayı tanıdığı sağlayıcı kodu.
`displayName`	string	Bankanın görünen adı.

Banka satırı eklerken bankayı acquirerCode ile değil, POS üreticisinin bankaya verdiği kodla (vendorAcquirerRef) bildirirsiniz; Lunixi bu kodu katalogdaki bankayla eşler. → Banka Satırları

Görsel nesnesi

Görseller her zaman { assetId, url } nesnesi olarak döner; görsel yoksa alan null'dır.

Alan	Tip	Açıklama
`assetId`	string (UUID)	Görselin kimliği. Görsel değiştirildiğinde yeni bir kimlik alır; önbellek anahtarı olarak kullanabilirsiniz.
`url`	string	Görselin herkese açık `https` adresi. Adresi olduğu gibi kullanın; kendiniz üretmeyin.

Görseller PNG, JPEG ya da WebP biçimindedir. Bir modeli gösterirken şu sırayı izlemenizi öneririz: image → vendorFallbackImage → kendi genel görseliniz (cihaz tipi ve form faktörüne göre).

Hatalar

HTTP	`code`	Ne zaman
`400`	`VALIDATION_ERROR`	Tanımsız sorgu parametresi.
`400`	`physical_pos.input.filter_invalid`	`vendorCode`, `deviceType` ya da `status` süzgeci geçersiz.
`400`	`physical_pos.input.environment_invalid`	Sorguda `environment` gönderildi.
`403`	`PRODUCT_NOT_ENABLED` / `API_INSUFFICIENT_SCOPE`	Anahtarda ürün ya da `physical_pos:view` yok.

Bütün kodlar: Hata Kodları.

Ortak Kurallar Mağazalar