Fiziksel POS
Ödeme İşlemleri
Satış Kalemleri

Satış Kalemleri

Fatura no, alıcı ve mali belge alanları ile yayın bekleyen satış uygulaması kaydının kapsamı: Satış verisi ve destek durumu. merchantReference, fatura numarası/doğrulaması yerine geçmez.

Satışı (SALE) ürün satırlarıyla başlatabilirsiniz. Kalemli satışta vergi dökümü kalem başına sunucuda hesaplanır, iade adet üzerinden yapılabilir ve vergi raporu kalemlerden üretilir. Kalem göndermek isteğe bağlıdır; kalemsiz satış tutar bazlı iade ile geri alınır.

Satış kalemleri

Ödeme başlatma isteğinde items dizisi yalnız SALE'de gönderilir; en çok 500 satır. Kalemsiz satışta alanı göndermeyin, boş dizi reddedilir.

AlanTipZorunluAçıklama
lineNointegerEvetSatır numarası, 1'den başlar ve boşluksuz artar (1, 2, 3 …).
namestringEvetÜrün adı, en çok 200 karakter (Unicode kod noktası). Metin kurallarına tabidir; kart numarasına benzeyen değer reddedilir.
quantityMilliintegerEvetMiktar × 1000, 0'dan büyük: 1 adet = 1000, 1,5 kg = 1500.
unitCodestringEvetBirim kodu. → Birim kodları
unitPriceMinorstringEvetBütün vergiler dahil birim fiyat, en küçük birimde, 0'dan büyük. İndirimli satırı indirimli birim fiyatla gönderin; ayrı indirim alanı yoktur.
taxGroupCodestringEvetSatırın vergi grubu; kalemin tek vergi girdisidir. → Vergi grupları
lineTotalMinorstringEvetSatır toplamı = quantityMilli × unitPriceMinor / 1000, kesin aritmetik ile hesaplanıp yarım yukarı yuvarlanır. Gönderdiğiniz değer bu hesapla birebir aynı olmalıdır.
barcodestring | nullHayırÜrün barkodu. → Barkod
  • Satırların lineTotalMinor toplamı ödemenin amountMinor değerine eşit olmalıdır.
  • Alanların türü ve temel sınırları istek alınırken denetlenir: lineNo 1–500, quantityMilli 1 ya da büyük JSON tam sayı, unitPriceMinor ve lineTotalMinor kanonik pozitif minor-unit dize, name boş olmayan ve en çok 400 karakterlik dize, unitCode en çok 3, taxGroupCode en çok 24, barcode en çok 14 karakter. Bu denetime takılan istek de 400 physical_pos.fiscal_document.items_invalid alır: details.field alanın noktalı yolunu (items.0.quantityMilli gibi), details.reason alanın sebebini verir (line_no_sequence, name_invalid, quantity_invalid, unit_code_invalid, unit_price_invalid, tax_group_code_invalid, line_total_invalid, barcode_invalid; items dizi değilse ya da öğe nesne değilse invalid). Birden çok hata varsa yanıt ilk hatayı döner. Satırda tanımlanmamış bir alan 400 VALIDATION_ERROR alır. → Hatalar
  • Vergi tutarı göndermezsiniz; vergi dökümü kalemin vergi grubundan hesaplanır ve ödeme okunduğunda kalem görünümünde döner.
{
  "operation": "SALE",
  "target": { "vendorCode": "PAVO", "serialNumber": "SN0000000001" },
  "amountMinor": "4500",
  "currency": "TRY",
  "merchantReference": "ORD-2026-000124",
  "items": [
    { "lineNo": 1, "name": "Çay", "quantityMilli": 2000, "unitCode": "C62", "unitPriceMinor": "1500", "taxGroupCode": "KDV10", "lineTotalMinor": "3000", "barcode": "8690000000005" },
    { "lineNo": 2, "name": "Simit", "quantityMilli": 1000, "unitCode": "C62", "unitPriceMinor": "1500", "taxGroupCode": "KDV1", "lineTotalMinor": "1500" }
  ]
}

Vergi grupları

taxGroupCode satırın hangi vergilere tabi olduğunu söyler. Grup listesi büyüyebilir: tanınmayan grup 422 physical_pos.fiscal_document.unsupported (details.reason: tax_group_unsupported) alır.

taxGroupCodeVergiler
KDV0_350KDV %0, istisna (gerekçe kodu 350)
KDV1KDV %1
KDV10KDV %10
KDV20KDV %20
KDV10_TEVKIFAT_604KDV %10 ve KDV tevkifatı 5/10 (gerekçe kodu 604)
OTV25_KDV20ÖTV %25 ve KDV %20; ÖTV, KDV matrahına dahildir
KONAKLAMA2_KDV10Konaklama vergisi %2 ve KDV %10
BSMV5BSMV %5; KDV yok

Biçimsiz ya da boş grup kodu 400 physical_pos.fiscal_document.items_invalid (details.reason: tax_group_code_invalid) alır. Grubun birim başına sabit vergisi satır toplamını aşıyorsa tax_exceeds_line_total.

Birim kodları

unitCodeBirimunitCodeBirim
C62AdetMTQMetreküp
KGMKilogramKWHKilovatsaat
GRMGramHURSaat
TNETonMINDakika
LTRLitreDAYGün
MLTMililitreMONAy
MTRMetreANNYıl
CMTSantimetrePRÇift
KMTKilometreSETSet
MTKMetrekarePAPaket
BXKutu

Listede olmayan kod 400 physical_pos.fiscal_document.items_invalid (details.reason: unit_code_invalid) alır. Kodlar büyük harfle ve birebir yazılır.

Barkod

  • barcode isteğe bağlıdır ve yalnız rakamdan oluşur: GTIN-8, GTIN-12, GTIN-13 ya da GTIN-14, kontrol hanesi geçerli. Aksi 400 physical_pos.fiscal_document.items_invalid (details.reason: barcode_invalid); değer yanıtta yankılanmaz.
  • Gönderilmez, null ya da "" ise barkod yoktur.
  • Barkod satışla birlikte saklanır ve değişmez; yalnız ödeme okunduğunda döner.
  • Ürün adına (name) bitişik yazılmış 13 ya da 14 haneli, kontrol hanesi geçerli bir barkod kart numarası sayılmaz. 15–19 haneli rakam dizileri ve boşluk ya da tireyle ayrılmış yazımlar kart numarası olarak taranır.

Kalem görünümü

Kalemler yalnız GET /payments/{paymentId} ve işlem ayrıntısı yanıtlarında, satış ödemesinin items dizisinde döner. Liste ve yazma yanıtlarında items boş dizidir.

AlanTipAçıklama
lineNo, name, quantityMilli, unitCode, unitPriceMinor, taxGroupCode, lineTotalMinorGönderdiğiniz değerler.
netMinorstringSatırın vergiler hariç tutarı.
refundedQuantityMilliintegerKalem bazlı iadeyle iade edilen miktar (× 1000).
refundedMinorstringKalem bazlı iadeyle iade edilen tutar.
reservedQuantityMilliintegerSonuçlanmamış kalem iadesinin ayırdığı miktar.
reservedMinorstringSonuçlanmamış kalem iadesinin ayırdığı tutar.
refundStatusstringNONE, PARTIAL ya da FULL. → Kalem iade durumu
taxesarraySatırın vergi dökümü; aşağıya bakın.
barcodestring | nullBarkod.

taxes öğesi:

AlanTipAçıklama
taxTypestringKDV, KDV_TEVKIFAT, OTV_I, OTV_II, OTV_III, OTV_IV, OIV, BSMV ya da KONAKLAMA.
taxModestringPERCENT (oranlı) ya da FIXED_PER_UNIT (birim başına sabit).
rateBpinteger | nullOran, baz puan (1000 = %10). Sabit vergide null.
unitAmountMinorstring | nullBirim başına sabit tutar. Oranlı vergide null.
baseMinorstringMatrah.
amountMinorstringVergi tutarı.
reasonCodestring | null%0 KDV satırında istisna kodu, tevkifat satırında tevkifat kodu; diğerlerinde null.
refundedAmountMinorstringKalem bazlı iadeyle geri alınan vergi.
reservedAmountMinorstringSonuçlanmamış kalem iadesinin ayırdığı vergi.

Hatalar

400 physical_pos.fiscal_document.items_invalid (satış kalemleri). details.field istekteki alanın yolunu verir (items[0].unitCode gibi; listenin bütününe ait kuralda items; istek alınırken yapılan tür ve sınır denetiminde items.0.unitCode gibi noktalı yol), details.reason sebebi, satır kuralında details.lineNo satır numarasını. Değer yanıtta yankılanmaz.

details.reasonAnlamı
invaliditems dizi değil ya da satırlardan biri nesne değil.
emptyitems boş dizi.
too_many500'den fazla satır.
line_no_sequenceSatır numaraları 1'den başlayıp boşluksuz artmıyor.
name_invalidAd boş, çok uzun ya da yasak karakter içeriyor.
quantity_invalidMiktar 0 ya da geçersiz.
unit_code_invalidBirim kodu listede yok.
unit_price_invalidBirim fiyat 0 ya da geçersiz.
tax_group_code_invalidVergi grubu kodu boş ya da biçimsiz.
tax_exceeds_line_totalGrubun sabit vergisi satır toplamını aşıyor.
line_total_invalidSatır toplamı geçersiz.
line_total_mismatchSatır toplamı hesapla uyuşmuyor; details.expectedMinor beklenen değeri verir (dize).
total_mismatchSatır toplamlarının toplamı amountMinor'a eşit değil; details.expectedMinor.
barcode_invalidBarkod GTIN biçiminde değil ya da kontrol hanesi tutmuyor.

422 physical_pos.fiscal_document.unsupported (details.reason: tax_group_unsupported): vergi grubu kodu biçimce doğru ama tanınmıyor.

Bütün kodlar: Hata Kodları.

Kalemli satışın iadesi: Kalem Bazlı İade.