Fiziksel POS
API Referansı
Cihaz Kimliği

Cihaz Kimliği

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:identity. Ü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.

Her fiziksel POS cihazı Lunixi'ye kendi kimlik anahtarıyla bağlanır. Anahtar cihazda üretilir ve cihazdan çıkmaz; Lunixi yalnız açık anahtarı ve parmak izini saklar.

Cihazı bağlamanın yolu eşleştirmedir: cihazdaki Lunixi uygulaması ekranda bir eşleştirme kodu gösterir; kodu panelde girip cihazın seri numarasının son 4 hanesiyle onaylarsınız. Eşleşen cihaz anahtarını alır, sahipliği doğrulanır ve PENDING ise ACTIVE olur. Aktivasyon kodu yedek bir yoldur; panelden üretilir, API'den üretilmesi şu an kapalıdır. → Panelde cihaz kimliği

Bu sayfadaki uçlarla cihazın kimlik anahtarlarını görür ve iptal eder, aktivasyon kodlarını yönetir ve aktivasyon koduyla yapılan bir bağlamayı geri alırsınız.

YöntemYolKapsam
POST/api/v1/physical-pos/devices/{deviceId}/activation-codephysical_pos:identity
POST/api/v1/physical-pos/devices/{deviceId}/activation-code/revokephysical_pos:identity
GET/api/v1/physical-pos/devices/{deviceId}/keysphysical_pos:view
POST/api/v1/physical-pos/devices/{deviceId}/keys/{keyId}/revokephysical_pos:identity
POST/api/v1/physical-pos/devices/{deviceId}/keys/{keyId}/revert-enrollmentphysical_pos:identity
  • physical_pos:identity kapsamı anahtarınıza kendiliğinden eklenmez; bu uçları kullanacak anahtarda açıkça seçin. → Kapsamlar
  • Test anahtarı yalnız anahtar listesini okur; yazma istekleri 403 physical_pos.environment.test_key_read_only alır. → Ortamlar
  • Başka organizasyonun ya da diğer ortamın cihazı, olmayan cihazla aynı cevabı alır: 404 physical_pos.device.not_found. Emekli cihazda yazma istekleri 409 physical_pos.device.retired alır.
  • Yazma istekleri oran sınırına tabidir: 60 saniyede API anahtarı başına 10, organizasyonunuz başına 30 istek. Organizasyon sayacı paneldeki aynı işlemlerle ortaktır. → Oran sınırı
  • Her yazma işlemi cihazın değişiklik geçmişine yazılır: physical_pos.audit.device_activation_code_issued, …device_activation_code_revoked, …device_key_revoked, …device_enrollment_reverted. Cihaz anahtarı aldığında …device_key_activated yazılır.

Panelde cihaz kimliği

EkranNeredeNe yaparsınız
Kodla cihaz ekleFiziksel POS › Cihazlar › Kodla cihaz ekleCihaz ekranındaki eşleştirme kodunu girersiniz. Cihazın bildirdiği üretici, model, seri numarası ve anahtar parmak izini cihazla karşılaştırır, seri numarasının son 4 hanesini yazarak onaylarsınız. Cihaz yeni bir kayıtla ya da var olan kaydıyla eşleşir.
Kimlik sekmesiCihazlar › cihaz detayı › KimlikBu cihaz için eşleştirme kodu girme, yedek aktivasyon kodu üretme ve iptal etme, anahtarları görme ve iptal etme, bağlamayı geri alma.
Eşleştirme detayı/physical-pos/pairings/{pairingId}Eşleştirmenin bilgileri ve geri alma. "Yeni cihaz eşleştirildi" güvenlik bildirimindeki bağlantı bu sayfayı açar.

Kimlik işlemleri için panel kullanıcınızda cihaz kimliği yönetim yetkisi (physical_pos:identity) gerekir; bu yetkisi olmayan kullanıcı anahtarları yalnız görür.

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

Anahtar nesnesi

AlanTipAçıklama
keyIdstringAnahtarın kimliği: pdk_ önekli 28 karakter.
algorithmstringED25519 ya da P256.
keyAlgorithmstring | nullAnahtar profili, küçük harfle: ed25519 ya da p256.
keyStatusstringACTIVE: cihaz bu anahtarla bağlanır. SUPERSEDED: anahtar değişiminde yerini yenisine bıraktı. REVOKED: iptal edildi. Bir cihazın aynı anda en çok bir ACTIVE anahtarı olur.
enrolledViastringAnahtarın nasıl alındığı: PAIRING (eşleştirme), ACTIVATION_CODE (aktivasyon kodu) ya da ROTATION (önceki anahtarın yerine geçen anahtar).
fingerprintstringAçık anahtarın kısa parmak izi, XXXX-XXXX biçiminde (SHA-256 özetinin ilk 8 onaltılık hanesi). Cihaz ekranında ve panelde aynı değeri görürsünüz. Anahtarın kendisi hiçbir yanıtta yer almaz.
lineageRootKeyIdstringAnahtar soyunun ilk anahtarı. Anahtar değişimleri aynı soyu sürdürür; soyun ilk anahtarında kendi keyId değeridir.
rotatedFromKeyIdstring | nullROTATION anahtarında yerine geçtiği anahtar; diğerlerinde null.
activatedAtstringAnahtarın etkinleştiği zaman.
supersededAtstring | nullYerini yenisine bıraktığı zaman.
revokedAtstring | nullİptal zamanı.
revokeReasonstring | nullİptal sebebi: iptalde verdiğiniz reasonCode ya da bağlama geri alındıysa PAIRING_REVERTED.
rowVersionintegerKaydın sürümü; anahtar iptalinde gönderirsiniz.
lineageRootPairingIdstring | nullSoy eşleştirmeyle başladıysa o eşleştirmenin kimliği; aktivasyon koduyla başladıysa null. Bağlamanın nasıl geri alınacağını bu alan belirler. → Bağlamayı geri alma

Aktivasyon kodu üretme

POST /api/v1/physical-pos/devices/{deviceId}/activation-code

⚠️

API anahtarıyla aktivasyon kodu üretimi şu an kapalı. İstek 403 physical_pos.device.api_activation_code_disabled alır. Cihazı eşleştirmeyle bağlayın.

Aktivasyon kodunu iptal etme

POST /api/v1/physical-pos/devices/{deviceId}/activation-code/revoke

Cihazın açık (kullanılmamış ve süresi dolmamış) aktivasyon kodunu iptal eder. İptal edilen kodla cihaz bağlanamaz.

AlanTipZorunluAçıklama
reasonCodestringEvetMERCHANT_REVOKED, DEVICE_LOST, DEVICE_STOLEN ya da OTHER.
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/devices/00000000-0000-0000-0000-000000000401/activation-code/revoke"
BODY='{"reasonCode":"MERCHANT_REVOKED"}'
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" \
  --data-raw "$BODY"

Yanıt (200) data alanında { "deviceId": "…", "revokedAt": "…", "revokeReason": "MERCHANT_REVOKED" } döner. Cihazın açık kodu yoksa 409 physical_pos.device.activation_code_not_open.

Anahtarları listeleme

GET /api/v1/physical-pos/devices/{deviceId}/keys · physical_pos:view

Cihazın bütün kimlik anahtarlarını (etkin, değişmiş ve iptal edilmiş) en yeni önce listeler. limit (1–100, varsayılan 25) ve cursor alır. Yanıt { "items": [ … ], "pageInfo": { … } }; öğe anahtar nesnesidir.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/devices/00000000-0000-0000-0000-000000000401/keys?limit=25"
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"
{
  "items": [
    {
      "keyId": "pdk_AAAAAAAAAAAAAAAAAAAAAAAA",
      "algorithm": "ED25519",
      "keyStatus": "ACTIVE",
      "enrolledVia": "PAIRING",
      "fingerprint": "3F2A-91C4",
      "lineageRootKeyId": "pdk_AAAAAAAAAAAAAAAAAAAAAAAA",
      "rotatedFromKeyId": null,
      "activatedAt": "2026-01-02T09:00:00.000Z",
      "supersededAt": null,
      "revokedAt": null,
      "revokeReason": null,
      "rowVersion": 1,
      "lineageRootPairingId": "01900000-0000-7000-8000-000000000701"
    }
  ],
  "pageInfo": { "hasMore": false, "nextCursor": null, "totalCount": null }
}

Anahtar iptali

POST /api/v1/physical-pos/devices/{deviceId}/keys/{keyId}/revoke

Cihazın etkin anahtarını iptal eder. Kayıp, çalıntı ya da ele geçirildiğinden şüphelendiğiniz cihaz için kullanın. İptalden sonra cihazın Lunixi bağlantısı kesilir ve cihaz bu anahtarla yeniden bağlanamaz; cihazı yeniden kullanmak için yeniden eşleştirmeniz gerekir.

AlanTipZorunluAçıklama
rowVersionintegerEvetAnahtarın listede okuduğunuz rowVersion değeri.
reasonCodestringEvetDEVICE_LOST, DEVICE_STOLEN, KEY_COMPROMISED, DEVICE_REPLACED, MERCHANT_REQUEST ya da OTHER.
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/devices/00000000-0000-0000-0000-000000000401/keys/pdk_AAAAAAAAAAAAAAAAAAAAAAAA/revoke"
BODY='{"rowVersion":1,"reasonCode":"DEVICE_STOLEN"}'
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" \
  --data-raw "$BODY"

Yanıt (200): { "key": { … }, "lifecycleStatus": "ACTIVE", "replayed": false }. key iptal edilmiş anahtardır (keyStatus: "REVOKED"); lifecycleStatus cihazın güncel yaşam döngüsü durumudur.

  • Zaten iptal edilmiş anahtarda istek aynı sonucu replayed: true ile döner; ikinci kez yazılmaz.
  • Yerini yenisine bırakmış (SUPERSEDED) anahtar 409 physical_pos.device.key_not_active alır.
  • rowVersion güncel değilse 409 physical_pos.version_conflict.

Anahtar iptali cihazın yaşam döngüsünü değiştirmez. Cihazın ödeme almasını da durdurmak istiyorsanız cihazı askıya alın.

Bağlamayı geri alma

POST /api/v1/physical-pos/devices/{deviceId}/keys/{keyId}/revert-enrollment

Aktivasyon koduyla yapılan bir bağlamayı geri alır. Cihazı siz bağlamadıysanız ya da yanlış cihaz bağlandıysa kullanın.

Hangi yolu kullanacağınızı anahtarın lineageRootPairingId alanı belirler:

lineageRootPairingIdNasıl geri alınır
null (aktivasyon koduyla bağlandı)Bu uçla ya da panelde cihazın Kimlik sekmesinden.
Dolu (eşleştirmeyle bağlandı)Yalnız panelden: cihazın Kimlik sekmesi ya da eşleştirme detay sayfası /physical-pos/pairings/{lineageRootPairingId}. Bu işlemin API ucu yoktur.

Eşleştirmeyi geri almanın etkileri aşağıdakiyle aynıdır; tek fark, cihaz kaydı eşleştirme sırasında açıldıysa cihaz askıya alınmaz, emekliye ayrılır (RETIRED).

AlanTipZorunluAçıklama
reasonCodestringEvetNOT_MY_DEVICE, SUSPECTED_PHISHING, WRONG_DEVICE ya da OTHER.

keyId olarak soydaki herhangi bir anahtarı verebilirsiniz; işlem bütün soyu kapsar. Aynı işlemde:

  • Soyun etkin anahtarı iptal edilir (revokeReason: "PAIRING_REVERTED") ve cihazın bağlantısı kesilir.
  • Cihaz SUSPENDED olur; sahiplik doğrulaması korunur.
  • Bu bağlama üzerinden doğrulanmış mantıksal terminallerin doğrulaması geri alınır. Terminalin başka bir doğrulaması yoksa terminal ownershipStatus: "UNVERIFIED" olur ve ödeme alamaz.
  • Organizasyonunuzun yetkililerine "cihaz eşleştirmesi geri alındı" bildirimi gönderilir.
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/devices/00000000-0000-0000-0000-000000000401/keys/pdk_BBBBBBBBBBBBBBBBBBBBBBBB/revert-enrollment"
BODY='{"reasonCode":"NOT_MY_DEVICE"}'
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" \
  --data-raw "$BODY"

Yanıt (200): { "key": { … }, "lifecycleStatus": "SUSPENDED", "replayed": false }.

  • Soyu eşleştirmeyle başlamış anahtar (enrolledVia: "PAIRING" kökü) bu uçla geri alınmaz: 409 physical_pos.device.enrollment_not_revertible. Eşleştirmeyi panelden geri alın: anahtarın lineageRootPairingId değeri eşleştirme detay sayfasını gösterir.
  • Soyda etkin anahtar kalmadıysa da 409 physical_pos.device.enrollment_not_revertible döner; bu durumda anahtar iptali ya da emeklilik kullanın.
  • Geri almanın süre sınırı yoktur.

Hatalar

HTTPcodeNe zaman
400VALIDATION_ERRORTanımsız gövde alanı; rowVersion JSON tam sayısı değil.
400physical_pos.input.reason_code_invalidreasonCode listede yok ya da işleme uymuyor.
400physical_pos.input.environment_invalidİstekte environment.
400physical_pos.cursor.invalidAnahtar listesinde cursor bozuk.
403physical_pos.environment.test_key_read_onlyYazma isteği test anahtarıyla yapıldı.
403physical_pos.device.api_activation_code_disabledAPI anahtarıyla aktivasyon kodu üretimi şu an kapalı.
404physical_pos.device.not_foundCihaz yok, size ait değil ya da diğer ortamda.
404physical_pos.device.key_not_foundAnahtar bu cihaza ait değil ya da yok.
409physical_pos.device.activation_code_not_openİptal edilecek açık aktivasyon kodu yok.
409physical_pos.device.key_not_activeAnahtar yerini yenisine bırakmış; iptal edilemez.
409physical_pos.device.enrollment_not_revertibleBağlama aktivasyon koduyla yapılmamış ya da soyda etkin anahtar kalmamış.
409physical_pos.device_key.invalid_transitionAnahtarın durumu bu işleme izin vermiyor.
409physical_pos.device.retiredEmekli cihaz.
409physical_pos.version_conflictrowVersion güncel değil.
429RATE_LIMITEDCihaz kimliği yazma sınırı aşıldı. → Oran sınırı
503physical_pos.service.busyKayıt başka bir işlemle meşgul; aynı istekle yeniden deneyin.

Bütün kodlar: Hata Kodları.