Cihaz Kimliği
- 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ıcaDigest. 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 anahtar403 PRODUCT_NOT_ENABLED, kapsamı olmayan anahtar403 API_INSUFFICIENT_SCOPEalı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öntem | Yol | Kapsam |
|---|---|---|
POST | /api/v1/physical-pos/devices/{deviceId}/activation-code | physical_pos:identity |
POST | /api/v1/physical-pos/devices/{deviceId}/activation-code/revoke | physical_pos:identity |
GET | /api/v1/physical-pos/devices/{deviceId}/keys | physical_pos:view |
POST | /api/v1/physical-pos/devices/{deviceId}/keys/{keyId}/revoke | physical_pos:identity |
POST | /api/v1/physical-pos/devices/{deviceId}/keys/{keyId}/revert-enrollment | physical_pos:identity |
physical_pos:identitykapsamı 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_onlyalı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 istekleri409 physical_pos.device.retiredalı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_activatedyazılır.
Panelde cihaz kimliği
| Ekran | Nerede | Ne yaparsınız |
|---|---|---|
| Kodla cihaz ekle | Fiziksel POS › Cihazlar › Kodla cihaz ekle | Cihaz 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 sekmesi | Cihazlar › cihaz detayı › Kimlik | Bu 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
| Alan | Tip | Açıklama |
|---|---|---|
keyId | string | Anahtarın kimliği: pdk_ önekli 28 karakter. |
algorithm | string | ED25519 ya da P256. |
keyAlgorithm | string | null | Anahtar profili, küçük harfle: ed25519 ya da p256. |
keyStatus | string | ACTIVE: 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. |
enrolledVia | string | Anahtarın nasıl alındığı: PAIRING (eşleştirme), ACTIVATION_CODE (aktivasyon kodu) ya da ROTATION (önceki anahtarın yerine geçen anahtar). |
fingerprint | string | Açı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. |
lineageRootKeyId | string | Anahtar soyunun ilk anahtarı. Anahtar değişimleri aynı soyu sürdürür; soyun ilk anahtarında kendi keyId değeridir. |
rotatedFromKeyId | string | null | ROTATION anahtarında yerine geçtiği anahtar; diğerlerinde null. |
activatedAt | string | Anahtarın etkinleştiği zaman. |
supersededAt | string | null | Yerini yenisine bıraktığı zaman. |
revokedAt | string | null | İptal zamanı. |
revokeReason | string | null | İptal sebebi: iptalde verdiğiniz reasonCode ya da bağlama geri alındıysa PAIRING_REVERTED. |
rowVersion | integer | Kaydın sürümü; anahtar iptalinde gönderirsiniz. |
lineageRootPairingId | string | null | Soy 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.
| Alan | Tip | Zorunlu | Açıklama |
|---|---|---|---|
reasonCode | string | Evet | MERCHANT_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.
| Alan | Tip | Zorunlu | Açıklama |
|---|---|---|---|
rowVersion | integer | Evet | Anahtarın listede okuduğunuz rowVersion değeri. |
reasonCode | string | Evet | DEVICE_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: trueile döner; ikinci kez yazılmaz. - Yerini yenisine bırakmış (
SUPERSEDED) anahtar409 physical_pos.device.key_not_activealır. rowVersiongüncel değilse409 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:
lineageRootPairingId | Nası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).
| Alan | Tip | Zorunlu | Açıklama |
|---|---|---|---|
reasonCode | string | Evet | NOT_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
SUSPENDEDolur; 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ınlineageRootPairingIddeğeri eşleştirme detay sayfasını gösterir. - Soyda etkin anahtar kalmadıysa da
409 physical_pos.device.enrollment_not_revertibledöner; bu durumda anahtar iptali ya da emeklilik kullanın. - Geri almanın süre sınırı yoktur.
Hatalar
| HTTP | code | Ne zaman |
|---|---|---|
400 | VALIDATION_ERROR | Tanımsız gövde alanı; rowVersion JSON tam sayısı değil. |
400 | physical_pos.input.reason_code_invalid | reasonCode listede yok ya da işleme uymuyor. |
400 | physical_pos.input.environment_invalid | İstekte environment. |
400 | physical_pos.cursor.invalid | Anahtar listesinde cursor bozuk. |
403 | physical_pos.environment.test_key_read_only | Yazma isteği test anahtarıyla yapıldı. |
403 | physical_pos.device.api_activation_code_disabled | API anahtarıyla aktivasyon kodu üretimi şu an kapalı. |
404 | physical_pos.device.not_found | Cihaz yok, size ait değil ya da diğer ortamda. |
404 | physical_pos.device.key_not_found | Anahtar bu cihaza ait değil ya da yok. |
409 | physical_pos.device.activation_code_not_open | İptal edilecek açık aktivasyon kodu yok. |
409 | physical_pos.device.key_not_active | Anahtar yerini yenisine bırakmış; iptal edilemez. |
409 | physical_pos.device.enrollment_not_revertible | Bağlama aktivasyon koduyla yapılmamış ya da soyda etkin anahtar kalmamış. |
409 | physical_pos.device_key.invalid_transition | Anahtarın durumu bu işleme izin vermiyor. |
409 | physical_pos.device.retired | Emekli cihaz. |
409 | physical_pos.version_conflict | rowVersion güncel değil. |
429 | RATE_LIMITED | Cihaz kimliği yazma sınırı aşıldı. → Oran sınırı |
503 | physical_pos.service.busy | Kayıt başka bir işlemle meşgul; aynı istekle yeniden deneyin. |
Bütün kodlar: Hata Kodları.