Banka 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.

Bir mantıksal terminal birden çok bankayla çalışabilir. Her banka için terminalde bir banka satırı bulunur: bankanın size verdiği üye işyeri numarası (MID), terminal numarası (TID) ve bu satırla kabul edilen para birimleri. Banka satırları terminalin ortamındadır; test anahtarı banka satırlarını yalnız okur, yazma istekleri 403 physical_pos.environment.test_key_read_only alır.

Yöntem	Yol	Kapsam
`GET`	`/api/v1/physical-pos/terminals/{terminalId}/acquirers`	`physical_pos:view`
`POST`	`/api/v1/physical-pos/terminals/{terminalId}/acquirers`	`physical_pos:manage`
`PATCH`	`/api/v1/physical-pos/terminal-acquirers/{terminalAcquirerId}`	`physical_pos:manage`

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

Banka satırı nesnesi

Alan	Tip	Açıklama
`id`	string (UUID)	Satırın kimliği; güncellemede `terminalAcquirerId` olarak kullanılır.
`terminalId`	string (UUID)	Satırın terminali.
`environment`	string	`TEST` ya da `LIVE`; terminalin ortamı.
`vendorAcquirerRef`	string	POS üreticisinin bu bankaya verdiği kod, gönderdiğiniz gibi.
`acquirerCode`	string \| null	Eşlenen bankanın dört haneli kodu (katalogdaki `acquirerCode`). Eşleme yoksa `null`.
`acquirerDisplayName`	string \| null	Eşlenen bankanın adı. Eşleme yoksa `null`.
`mappingStatus`	string	`MAPPED`: `vendorAcquirerRef` katalogdaki bir bankayla eşlendi. `UNMAPPED`: eşleme yok.
`merchantNumber`	string	Bankanın verdiği üye işyeri numarası (MID).
`terminalNumber`	string	Bankanın verdiği terminal numarası (TID).
`label`	string \| null	Satır için kendi etiketiniz.
`currencies`	string[]	Bu satırla kabul edilen para birimleri (ISO 4217), alfabetik sırada.
`verificationStatus`	string	`UNVERIFIED`: bilgiler elle girildi, üreticiyle teyit edilmedi. `VENDOR_CONFIRMED`: üretici tarafından teyit edildi.
`source`	string	Satırın kaynağı: `MANUAL` (panelden ya da API'den eklendi), `VENDOR_ACCOUNT` ya da `DEVICE_REPORTED`.
`acquirerStatus`	string	`ACTIVE` ya da `DISABLED`.
`lastSyncedAt`	string \| null	Satırın üreticiden en son güncellendiği zaman; elle eklenen satırda `null`.
`rowVersion`	integer	Satırın eşzamanlılık sürümü. → rowVersion
`createdAt`	string	Oluşturulma zamanı.
`updatedAt`	string	Son değişiklik zamanı.

Banka satırlarını listeleme

GET /api/v1/physical-pos/terminals/{terminalId}/acquirers

Sorgu parametresi	Tip	Açıklama
`limit`	integer	Sayfa başına satır, 1–100. Varsayılan 25.
`cursor`	string	Önceki yanıttaki `pageInfo.nextCursor`.
`includeTotal`	boolean	`true` ise `pageInfo.totalCount` doldurulur.

Terminal ayrıntısı ilk 100 satırı zaten içerir: Terminal ayrıntısı.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/terminals/00000000-0000-0000-0000-000000000301/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": {
    "items": [
      {
        "id": "00000000-0000-0000-0000-000000000601",
        "terminalId": "00000000-0000-0000-0000-000000000301",
        "environment": "LIVE",
        "vendorAcquirerRef": "B01",
        "acquirerCode": "0000",
        "acquirerDisplayName": "Örnek Bank",
        "mappingStatus": "MAPPED",
        "merchantNumber": "000000000000001",
        "terminalNumber": "PS000001",
        "label": "Örnek Bank TL",
        "currencies": ["TRY"],
        "verificationStatus": "UNVERIFIED",
        "source": "MANUAL",
        "acquirerStatus": "ACTIVE",
        "lastSyncedAt": null,
        "rowVersion": 1,
        "createdAt": "2026-01-01T07:30:00.000Z",
        "updatedAt": "2026-01-01T07:30:00.000Z"
      }
    ],
    "pageInfo": { "hasMore": false, "nextCursor": null, "totalCount": null }
  },
  "pageInfo": { "hasMore": false, "nextCursor": null, "totalCount": null },
  "statusCode": 200,
  "requestId": "00000000-0000-0000-0000-000000000000"
}

Banka satırı ekleme

POST /api/v1/physical-pos/terminals/{terminalId}/acquirers · Idempotency-Key zorunlu

Alan	Tip	Zorunlu	Açıklama
`vendorAcquirerRef`	string	Evet	POS üreticisinin bankaya verdiği kod: `A-Z`, `a-z`, `0-9`; en çok 16 karakter. Büyük/küçük harf korunur.
`merchantNumber`	string	Evet	Üye işyeri numarası (MID): `A-Z`, `0-9`; en çok 32 karakter. Büyük harfe çevrilir.
`terminalNumber`	string	Evet	Terminal numarası (TID): `A-Z`, `0-9`; en çok 32 karakter. Büyük harfe çevrilir.
`label`	string	Hayır	Kendi etiketiniz, en çok 64 karakter. Metin kurallarına tabidir.
`currencies`	string[]	Evet	ISO 4217 para birimi kodları (ör. `["TRY"]`); tekrarsız, en çok 16. Büyük harfe çevrilir ve alfabetik sırada saklanır.

Koşullar:

Terminalin bir üreticisi olmalıdır; üreticisiz terminale satır eklenemez: 400 physical_pos.terminal.vendor_required. Üreticiyi terminal güncellemesiyle atayın.
Kapatılmış terminale satır eklenemez: 409 physical_pos.terminal.closed.
Aynı terminalde aynı vendorAcquirerRef ve terminalNumber ile bir satır varsa ya da bu ortamdaki terminallerinizden birinde aynı ikiliyle etkin bir satır varsa 409 physical_pos.acquirer.duplicate.

Lunixi, vendorAcquirerRef değerini üreticinin banka kodu eşlemesine göre katalogdaki bankayla eşler. Eşleme varsa mappingStatus: "MAPPED" ve acquirerCode dolu; yoksa mappingStatus: "UNMAPPED" ve acquirerCode: null döner. Elle eklenen satır source: "MANUAL" ve verificationStatus: "UNVERIFIED" ile başlar.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/terminals/00000000-0000-0000-0000-000000000301/acquirers"
BODY='{"vendorAcquirerRef":"B01","merchantNumber":"000000000000001","terminalNumber":"ps000001","label":"Örnek Bank TL","currencies":["try"]}'
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-000000000004" \
  --data-raw "$BODY"

Yeni satırda 201, aynı anahtar ve aynı gövdeyle tekrarda 200 döner. data: { "acquirer": { … }, "replayed": false }; acquirer alanları listedeki gibidir.

MID, TID ve banka kodu satır oluşturulduktan sonra değişmez. Bankanız size yeni bir terminal numarası verdiyse yeni bir satır ekleyin ve eski satırı DISABLED yapın.

Banka satırı güncelleme

PATCH /api/v1/physical-pos/terminal-acquirers/{terminalAcquirerId}

Alan	Tip	Zorunlu	Açıklama
`rowVersion`	integer	Evet	Satırın son okuduğunuz `rowVersion` değeri (terminalinki değil).
`label`	string \| null	Hayır	Yeni etiket; `null` etiketi kaldırır.
`currencies`	string[]	Hayır	Yeni para birimi listesi; eskisinin yerine geçer.
`status`	string	Hayır	`ACTIVE` ya da `DISABLED`. Başka değer `400 physical_pos.input.code_invalid`.

label, currencies ya da status alanlarından en az biri gönderilmelidir; hiçbiri yoksa 400 physical_pos.input.empty_patch. Gönderilen değerler mevcut değerlerle aynıysa satır değişmez, rowVersion artmaz ve 200 döner.
Kapatılmış terminalin satırı güncellenemez: 409 physical_pos.terminal.closed.
DISABLED bir satırı yeniden ACTIVE yapmak, aynı ortamda aynı banka kodu ve TID ile etkin başka bir satır varsa 409 physical_pos.acquirer.duplicate alır.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/terminal-acquirers/00000000-0000-0000-0000-000000000601"
BODY='{"rowVersion":1,"currencies":["EUR","TRY","USD"]}'
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: { "acquirer": { … } }, yeni rowVersion ile.

Hatalar

HTTP	`code`	Ne zaman
`400`	`physical_pos.idempotency.key_required` / `physical_pos.idempotency.key_invalid`	Eklemede `Idempotency-Key` yok ya da biçim dışı.
`400`	`physical_pos.input.ref_invalid`	`vendorAcquirerRef` biçim dışı.
`400`	`physical_pos.input.bank_terminal_number_invalid`	`merchantNumber` ya da `terminalNumber` biçim dışı.
`400`	`physical_pos.input.text_invalid`	`label` kurala uymuyor.
`400`	`physical_pos.acquirer.currency_invalid`	Para birimi listesi geçersiz: bilinmeyen kod, tekrar ya da 16'dan fazla.
`400`	`physical_pos.input.code_invalid`	`status` geçersiz.
`400`	`physical_pos.terminal.vendor_required`	Terminalin üreticisi yok.
`400`	`physical_pos.input.empty_patch`	Boş güncelleme.
`400`	`physical_pos.cursor.invalid`	Bozuk imleç.
`403`	`physical_pos.environment.test_key_read_only`	Yazma isteği test anahtarıyla yapıldı.
`404`	`physical_pos.terminal.not_found`	Terminal yok, size ait değil ya da diğer ortamda.
`404`	`physical_pos.acquirer.not_found`	Satır yok, size ait değil ya da diğer ortamda.
`409`	`physical_pos.terminal.closed`	Terminal kapatılmış.
`409`	`physical_pos.acquirer.duplicate`	Aynı banka kodu ve TID ile satır var.
`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`	Terminal ailesi yazma sınırı aşıldı. → Oran sınırı

Bütün kodlar: Hata Kodları.

Mantıksal Terminaller Cihazlar