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.
| Alan | Tip | Zorunlu | Açıklama |
|---|---|---|---|
lineNo | integer | Evet | Satır numarası, 1'den başlar ve boşluksuz artar (1, 2, 3 …). |
name | string | Evet | Ürün adı, en çok 200 karakter (Unicode kod noktası). Metin kurallarına tabidir; kart numarasına benzeyen değer reddedilir. |
quantityMilli | integer | Evet | Miktar × 1000, 0'dan büyük: 1 adet = 1000, 1,5 kg = 1500. |
unitCode | string | Evet | Birim kodu. → Birim kodları |
unitPriceMinor | string | Evet | Bü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. |
taxGroupCode | string | Evet | Satırın vergi grubu; kalemin tek vergi girdisidir. → Vergi grupları |
lineTotalMinor | string | Evet | Satı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. |
barcode | string | null | Hayır | Ürün barkodu. → Barkod |
- Satırların
lineTotalMinortoplamı ödemeninamountMinordeğerine eşit olmalıdır. - Alanların türü ve temel sınırları istek alınırken denetlenir:
lineNo1–500,quantityMilli1 ya da büyük JSON tam sayı,unitPriceMinorvelineTotalMinorkanonik pozitif minor-unit dize,nameboş olmayan ve en çok 400 karakterlik dize,unitCodeen çok 3,taxGroupCodeen çok 24,barcodeen çok 14 karakter. Bu denetime takılan istek de400 physical_pos.fiscal_document.items_invalidalır:details.fieldalanın noktalı yolunu (items.0.quantityMilligibi),details.reasonalanı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;itemsdizi değilse ya da öğe nesne değilseinvalid). Birden çok hata varsa yanıt ilk hatayı döner. Satırda tanımlanmamış bir alan400 VALIDATION_ERRORalı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.
taxGroupCode | Vergiler |
|---|---|
KDV0_350 | KDV %0, istisna (gerekçe kodu 350) |
KDV1 | KDV %1 |
KDV10 | KDV %10 |
KDV20 | KDV %20 |
KDV10_TEVKIFAT_604 | KDV %10 ve KDV tevkifatı 5/10 (gerekçe kodu 604) |
OTV25_KDV20 | ÖTV %25 ve KDV %20; ÖTV, KDV matrahına dahildir |
KONAKLAMA2_KDV10 | Konaklama vergisi %2 ve KDV %10 |
BSMV5 | BSMV %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ı
unitCode | Birim | unitCode | Birim |
|---|---|---|---|
C62 | Adet | MTQ | Metreküp |
KGM | Kilogram | KWH | Kilovatsaat |
GRM | Gram | HUR | Saat |
TNE | Ton | MIN | Dakika |
LTR | Litre | DAY | Gün |
MLT | Mililitre | MON | Ay |
MTR | Metre | ANN | Yıl |
CMT | Santimetre | PR | Çift |
KMT | Kilometre | SET | Set |
MTK | Metrekare | PA | Paket |
BX | Kutu |
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
barcodeisteğ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. Aksi400 physical_pos.fiscal_document.items_invalid(details.reason:barcode_invalid); değer yanıtta yankılanmaz.- Gönderilmez,
nullya 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.
| Alan | Tip | Açıklama |
|---|---|---|
lineNo, name, quantityMilli, unitCode, unitPriceMinor, taxGroupCode, lineTotalMinor | Gönderdiğiniz değerler. | |
netMinor | string | Satırın vergiler hariç tutarı. |
refundedQuantityMilli | integer | Kalem bazlı iadeyle iade edilen miktar (× 1000). |
refundedMinor | string | Kalem bazlı iadeyle iade edilen tutar. |
reservedQuantityMilli | integer | Sonuçlanmamış kalem iadesinin ayırdığı miktar. |
reservedMinor | string | Sonuçlanmamış kalem iadesinin ayırdığı tutar. |
refundStatus | string | NONE, PARTIAL ya da FULL. → Kalem iade durumu |
taxes | array | Satırın vergi dökümü; aşağıya bakın. |
barcode | string | null | Barkod. |
taxes öğesi:
| Alan | Tip | Açıklama |
|---|---|---|
taxType | string | KDV, KDV_TEVKIFAT, OTV_I, OTV_II, OTV_III, OTV_IV, OIV, BSMV ya da KONAKLAMA. |
taxMode | string | PERCENT (oranlı) ya da FIXED_PER_UNIT (birim başına sabit). |
rateBp | integer | null | Oran, baz puan (1000 = %10). Sabit vergide null. |
unitAmountMinor | string | null | Birim başına sabit tutar. Oranlı vergide null. |
baseMinor | string | Matrah. |
amountMinor | string | Vergi tutarı. |
reasonCode | string | null | %0 KDV satırında istisna kodu, tevkifat satırında tevkifat kodu; diğerlerinde null. |
refundedAmountMinor | string | Kalem bazlı iadeyle geri alınan vergi. |
reservedAmountMinor | string | Sonuç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.reason | Anlamı |
|---|---|
invalid | items dizi değil ya da satırlardan biri nesne değil. |
empty | items boş dizi. |
too_many | 500'den fazla satır. |
line_no_sequence | Satır numaraları 1'den başlayıp boşluksuz artmıyor. |
name_invalid | Ad boş, çok uzun ya da yasak karakter içeriyor. |
quantity_invalid | Miktar 0 ya da geçersiz. |
unit_code_invalid | Birim kodu listede yok. |
unit_price_invalid | Birim fiyat 0 ya da geçersiz. |
tax_group_code_invalid | Vergi grubu kodu boş ya da biçimsiz. |
tax_exceeds_line_total | Grubun sabit vergisi satır toplamını aşıyor. |
line_total_invalid | Satır toplamı geçersiz. |
line_total_mismatch | Satır toplamı hesapla uyuşmuyor; details.expectedMinor beklenen değeri verir (dize). |
total_mismatch | Satır toplamlarının toplamı amountMinor'a eşit değil; details.expectedMinor. |
barcode_invalid | Barkod 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.