Fiziksel POS
API Referansı
Kart Sağlayıcı Satırları

Kart Sağlayıcı Satırları

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.

Yemek kartı gibi kapalı devre kartlarla ödeme almak için mantıksal terminale, kart sağlayıcısının size verdiği üye işyeri ve terminal kodlarını bir sağlayıcı satırı olarak eklersiniz. Banka kartları için kullanılan banka satırlarının kapalı devre karşılığıdır. Satışta hangi satırın kullanılacağı: Yemek Kartıyla Satış.

YöntemYolKapsam
GET/api/v1/physical-pos/terminals/{terminalId}/providersphysical_pos:view
POST/api/v1/physical-pos/terminals/{terminalId}/providersphysical_pos:manage
PATCH/api/v1/physical-pos/terminal-providers/{terminalProviderId}physical_pos:manage

Satır, sağlayıcının üretici hesabına bağlanır (vendorAccountId). Sağlayıcı hesabını ve gizli kimlik bilgilerini panelde Entegrasyonlar ekranından eklersiniz; bu işlemin API ucu yoktur. Bugün desteklenen sağlayıcı: METROPOL.

  • Test anahtarı satırları okur; yazma 403 physical_pos.environment.test_key_read_only alır.
  • Yazma istekleri terminal yazma oran sınırına tabidir: 60 saniyede API anahtarı başına 30 istek.

Sağlayıcı satırı nesnesi

AlanTipAçıklama
idstringSatırın kimliği. Ödemede terminalProviderId olarak gönderirsiniz.
terminalIdstringMantıksal terminal.
environmentstringLIVE ya da TEST.
providerCodestringKart sağlayıcısı, ör. METROPOL. Bağlı üretici hesabından gelir.
vendorAccountIdstringSağlayıcının üretici hesabı.
merchantCodestringSağlayıcıdaki üye işyeri kodu.
terminalCodestringSağlayıcıdaki terminal kodu.
productCodestring | nullSağlayıcıdaki ürün kodu.
labelstring | nullKendi açıklamanız.
providerStatusstringACTIVE ya da DISABLED. Ödeme yalnız ACTIVE satırla alınır.
rowVersionintegerKaydın sürümü; güncellemede gönderirsiniz.
createdAt, updatedAtstringOluşturma ve son değişiklik zamanı.

Listeleme

GET /api/v1/physical-pos/terminals/{terminalId}/providers · physical_pos:view

limit (1–100, varsayılan 25), cursor ve includeTotal alır. Yanıt { "items": [ … ], "pageInfo": { … } }; öğe sağlayıcı satırıdır.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/terminals/00000000-0000-0000-0000-000000000301/providers"
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"

Ekleme

POST /api/v1/physical-pos/terminals/{terminalId}/providers · physical_pos:manage

Idempotency-Key başlığı zorunludur. Yeni satır 201, aynı anahtar ve aynı gövdeyle tekrar 200 ve replayed: true döner.

AlanTipZorunluAçıklama
vendorAccountIdstring (UUID)EvetSağlayıcının aynı ortamdaki üretici hesabı.
merchantCodestringEvetÜye işyeri kodu. METROPOL: 10 rakam.
terminalCodestringEvetTerminal kodu. METROPOL: 10 rakam.
productCodestringSağlayıcıya göreÜrün kodu. METROPOL'de zorunlu: 1–5 rakam, sıfırla başlamaz.
labelstringHayırEn çok 64 karakter.

Biçime uymayan kod 400 physical_pos.input.code_invalid (details.field) alır; değer yanıtta yer almaz.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/terminals/00000000-0000-0000-0000-000000000301/providers"
BODY='{"vendorAccountId":"00000000-0000-0000-0000-000000000601","merchantCode":"1234567890","terminalCode":"0987654321","productCode":"1","label":"Kasa 1 yemek kartı"}'
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: 5f2a7c9e-1b4d-4a8e-9c3f-6d0b8e2a4c71" \
  --data-raw "$BODY"

Örnekte data alanı gösterilmiştir.

{
  "provider": {
    "id": "00000000-0000-0000-0000-000000000351",
    "terminalId": "00000000-0000-0000-0000-000000000301",
    "environment": "LIVE",
    "providerCode": "METROPOL",
    "vendorAccountId": "00000000-0000-0000-0000-000000000601",
    "merchantCode": "1234567890",
    "terminalCode": "0987654321",
    "productCode": "1",
    "label": "Kasa 1 yemek kartı",
    "providerStatus": "ACTIVE",
    "rowVersion": 1,
    "createdAt": "2026-01-02T09:00:00.000Z",
    "updatedAt": "2026-01-02T09:00:00.000Z"
  },
  "replayed": false
}
  • Terminalde aynı sağlayıcının etkin bir satırı varsa ya da aynı üye işyeri ve terminal kodu çifti hesabınızda başka bir terminalde etkinse 409 physical_pos.terminal_provider.duplicate.
  • Üretici hesabı ödeme sağlayıcısı hesabı değilse 400 physical_pos.vendor_account.vendor_not_supported; hesap yoksa 404 physical_pos.vendor_account.not_found.

Güncelleme

PATCH /api/v1/physical-pos/terminal-providers/{terminalProviderId} · physical_pos:manage

Satırın açıklamasını değiştirir ya da satırı devre dışı bırakır. Kodlar değiştirilemez; yanlış kodlu satırı devre dışı bırakıp yenisini ekleyin.

AlanTipZorunluAçıklama
rowVersionintegerEvetSatırın okuduğunuz rowVersion değeri.
labelstring | nullHayırYeni açıklama; null ya da "" kaldırır.
statusstringHayırACTIVE ya da DISABLED.

label ya da status'tan en az biri gönderilmelidir; ikisi de yoksa 400 physical_pos.input.empty_patch. Yanıt { "provider": { … } }.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/terminal-providers/00000000-0000-0000-0000-000000000351"
BODY='{"rowVersion":1,"status":"DISABLED"}'
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"

Hatalar

HTTPcodeNe zaman
400physical_pos.idempotency.key_required · .key_invalidEklemede Idempotency-Key yok ya da biçim dışı.
400physical_pos.input.code_invalidKod ya da status biçim dışı (details.field).
400physical_pos.input.empty_patchGüncellemede değişecek alan yok.
400physical_pos.vendor_account.vendor_not_supportedÜretici hesabı kapalı devre kart sağlayıcısı değil.
403physical_pos.environment.test_key_read_onlyYazma test anahtarıyla yapıldı.
404physical_pos.terminal.not_foundTerminal yok, size ait değil ya da diğer ortamda.
404physical_pos.terminal_provider.not_foundSağlayıcı satırı bulunamadı.
404physical_pos.vendor_account.not_foundÜretici hesabı bulunamadı.
409physical_pos.terminal_provider.duplicateAynı sağlayıcının etkin satırı ya da aynı kod çifti zaten var.
409physical_pos.terminal.closedTerminal kapatılmış.
409physical_pos.version_conflictrowVersion güncel değil.
409physical_pos.idempotency_mismatchAnahtar başka bir gövdeyle kullanılmış.
429RATE_LIMITEDOran sınırı aşıldı.

Bütün kodlar: Hata Kodları.