Kasalar

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 · physical_pos:manage. Ü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.

Kasa, bir mağazanın içindeki ödeme noktasıdır ve her zaman tek bir mağazaya aittir. Kasanın mağazası ve kodu sonradan değişmez. Kasalar da mağazalar gibi ortamsızdır; test anahtarı kasaları yalnız okuyabilir. → Ortamlar

Yöntem	Yol	Kapsam
`GET`	`/api/v1/physical-pos/stores/{storeId}/registers`	`physical_pos:view`
`POST`	`/api/v1/physical-pos/stores/{storeId}/registers`	`physical_pos:manage`
`PATCH`	`/api/v1/physical-pos/registers/{registerId}`	`physical_pos:manage`
`POST`	`/api/v1/physical-pos/registers/{registerId}/archive`	`physical_pos:manage`
`POST`	`/api/v1/physical-pos/registers/{registerId}/restore`	`physical_pos:manage`
`GET`	`/api/v1/physical-pos/registers/{registerId}/audit`	`physical_pos:view`

cURL örnekleri imzayı lunixi-sign.sh ile hesaplar: Kimlik Doğrulama › İmza yardımcısı.

Kasa nesnesi

Alan	Tip	Açıklama
`id`	string (UUID)	Kasanın kimliği.
`storeId`	string (UUID)	Kasanın mağazası.
`code`	string	Kasa kodu; büyük harfli, mağaza içinde tekil.
`name`	string	Kasa adı.
`registerStatus`	string	`ACTIVE` ya da `ARCHIVED`.
`rowVersion`	integer	Eşzamanlılık sürümü. → rowVersion
`createdAt`	string	Oluşturulma zamanı.
`updatedAt`	string	Son değişiklik zamanı.

Kasaları listeleme

GET /api/v1/physical-pos/stores/{storeId}/registers

Sorgu parametresi	Tip	Açıklama
`status`	string	`ACTIVE` ya da `ARCHIVED`. Gönderilmezse ikisi de döner. Başka değer `400 physical_pos.input.filter_invalid`.
`limit`	integer	Sayfa başına kayıt, 1–100. Varsayılan 25.
`cursor`	string	Önceki yanıttaki `pageInfo.nextCursor`.
`includeTotal`	boolean	`true` ise `pageInfo.totalCount` doldurulur.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/stores/00000000-0000-0000-0000-000000000101/registers?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": {
    "items": [
      {
        "id": "00000000-0000-0000-0000-000000000201",
        "storeId": "00000000-0000-0000-0000-000000000101",
        "code": "KASA-1",
        "name": "Giriş Kasası",
        "registerStatus": "ACTIVE",
        "rowVersion": 1,
        "createdAt": "2026-01-01T07:10:00.000Z",
        "updatedAt": "2026-01-01T07:10:00.000Z"
      }
    ],
    "pageInfo": { "hasMore": false, "nextCursor": null, "totalCount": null }
  },
  "pageInfo": { "hasMore": false, "nextCursor": null, "totalCount": null },
  "statusCode": 200,
  "requestId": "00000000-0000-0000-0000-000000000000"
}

Mağaza yoksa ya da size ait değilse 404 physical_pos.store.not_found.

Kasa oluşturma

POST /api/v1/physical-pos/stores/{storeId}/registers · Idempotency-Key zorunlu

Alan	Tip	Zorunlu	Açıklama
`code`	string	Evet	Kasa kodu: `A-Z`, `0-9`, `.`, `_`, `-`; en çok 64 karakter. Büyük harfe çevrilir; mağaza içinde tekildir (arşivli kasalar dahil).
`name`	string	Evet	Kasa adı, en çok 120 karakter. Metin kurallarına tabidir.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/stores/00000000-0000-0000-0000-000000000101/registers"
BODY='{"code":"kasa-1","name":"Giriş Kasası"}'
lunixi_sign POST "$REQ_PATH" "$BODY"
 
curl -X POST "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "Digest: $DIGEST" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: 4f9b2c1e-0000-4000-8000-000000000002" \
  --data-raw "$BODY"

{
  "status": "success",
  "code": "SUCCESS",
  "data": {
    "register": {
      "id": "00000000-0000-0000-0000-000000000201",
      "storeId": "00000000-0000-0000-0000-000000000101",
      "code": "KASA-1",
      "name": "Giriş Kasası",
      "registerStatus": "ACTIVE",
      "rowVersion": 1,
      "createdAt": "2026-01-01T07:10:00.000Z",
      "updatedAt": "2026-01-01T07:10:00.000Z"
    },
    "replayed": false
  },
  "statusCode": 201,
  "requestId": "00000000-0000-0000-0000-000000000000"
}

Arşivli mağazaya kasa açılamaz: 409 physical_pos.store.archived.
Aynı Idempotency-Key ile başka bir mağazada kasa açmaya çalışmak 409 physical_pos.idempotency_mismatch alır.

Kasayı yeniden adlandırma

PATCH /api/v1/physical-pos/registers/{registerId}

Alan	Tip	Zorunlu	Açıklama
`rowVersion`	integer	Evet	Son okuduğunuz `rowVersion`.
`name`	string	Hayır	Yeni ad, en çok 120 karakter.

Kasanın yalnız adı değişir; code ve storeId gövdede gönderilirse 400 VALIDATION_ERROR. name gönderilmezse istek 400 physical_pos.input.empty_patch, boş ad 400 physical_pos.input.text_invalid alır. Arşivli kasa güncellenemez: 409 physical_pos.register.archived.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/registers/00000000-0000-0000-0000-000000000201"
BODY='{"rowVersion":1,"name":"Ana Kasa"}'
lunixi_sign PATCH "$REQ_PATH" "$BODY"
 
curl -X PATCH "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "Digest: $DIGEST" \
  -H "X-Signature: $SIGNATURE" \
  --data-raw "$BODY"

Yanıt: { "register": { … } }.

Kasa arşivleme

POST /api/v1/physical-pos/registers/{registerId}/archive

Alan	Tip	Zorunlu	Açıklama
`rowVersion`	integer	Evet	Son okuduğunuz `rowVersion`.
`reasonCode`	string	Evet	`STORE_ARCHIVED`, `REGISTER_REMOVED`, `REGISTER_REPLACED`, `STORE_CLOSED`, `TEMPORARILY_CLOSED`, `CREATED_IN_ERROR`, `DATA_CORRECTION`, `OTHER`. → Gerekçe kodları

Yanıt: { "register": { … } }, registerStatus: "ARCHIVED".

Engel	Hata
Kasaya atanmış cihaz var	`409 physical_pos.register.has_devices` — cihazları başka bir kasaya ya da mağazaya taşıyın, depoya alın ya da emekliye ayırın.
Kasa zaten arşivli	`409 physical_pos.register.invalid_transition`

Kasayı yeniden açma

POST /api/v1/physical-pos/registers/{registerId}/restore

Alan	Tip	Zorunlu	Açıklama
`rowVersion`	integer	Evet	Son okuduğunuz `rowVersion`.
`reasonCode`	string	Evet	`REOPENED`, `ARCHIVED_IN_ERROR`, `DATA_CORRECTION`, `OTHER`.

Kasanın mağazası aktif olmalıdır; mağaza arşivliyse 409 physical_pos.store.archived — önce mağazayı yeniden açın. Kasa zaten aktifse 409 physical_pos.register.invalid_transition.

Yanıt: { "register": { … } }, registerStatus: "ACTIVE".

Değişiklik geçmişi

GET /api/v1/physical-pos/registers/{registerId}/audit — limit ve cursor alır; yanıt biçimi mağaza geçmişiyle aynıdır.

Kasa olayları: physical_pos.audit.register_created, …register_updated, …register_archived, …register_restored. Mağaza arşivlenirken kapanan kasaların olayında reasonCode STORE_ARCHIVED'dır; mağazanın gerekçesi changes.storeReason alanındadır.

Hatalar

HTTP	`code`	Ne zaman
`400`	`physical_pos.idempotency.key_required` / `physical_pos.idempotency.key_invalid`	Oluşturmada `Idempotency-Key` yok ya da biçim dışı.
`400`	`physical_pos.input.code_invalid`	`code` biçim dışı.
`400`	`physical_pos.input.text_invalid`	`name` kurala uymuyor.
`400`	`physical_pos.input.reason_code_invalid`	`reasonCode` listede yok ya da işleme uymuyor.
`400`	`physical_pos.cursor.invalid`	Bozuk imleç.
`400`	`physical_pos.input.filter_invalid`	Liste süzgeci geçersiz.
`400`	`physical_pos.input.empty_patch`	Boş güncelleme.
`403`	`physical_pos.environment.test_key_read_only`	Yazma isteği test anahtarıyla yapıldı.
`404`	`physical_pos.store.not_found`	Mağaza yok ya da size ait değil.
`404`	`physical_pos.register.not_found`	Kasa yok ya da size ait değil.
`409`	`physical_pos.register.code_taken`	Bu mağazada aynı kodla bir kasa var.
`409`	`physical_pos.store.archived`	Arşivli mağazaya kasa açma ya da arşivli mağazanın kasasını yeniden açma.
`409`	`physical_pos.register.archived`	Arşivli kasa güncellenmek istendi.
`409`	`physical_pos.register.has_devices`	Cihaz atanmış kasa arşivlenmek istendi.
`409`	`physical_pos.register.invalid_transition`	Arşivli kasayı arşivleme ya da aktif kasayı yeniden açma.
`409`	`physical_pos.version_conflict`	`rowVersion` güncel değil.
`409`	`physical_pos.idempotency_mismatch`	Aynı `Idempotency-Key` farklı bir istekle kullanılmış.
`429`	`RATE_LIMITED`	Mağaza ve kasa yazma sınırı aşıldı. → Oran sınırı

Bütün kodlar: Hata Kodları.

Mağazalar Mantıksal Terminaller