Geliştirici Dökümanı

Bu döküman geliştiriciler için Z-Raporu apilerinin kullanımı için genel bir kılavuz niteliğindedir.

Development ortamında ECR üzerinde çalışan servisler için cloud ortamındahttps://dev-gmu-report.devtokeninc.com/ecr/api/v1/ base url'i tanımlanmıştır.

Servislerde kullanılan generic response yapısı şu şekildedir:

{
    "status": 0, (int)
    "message": "OK", (String)
    "detail": null (Object)
}

Response payload değişkenleri:

status : Cevabın status kodunu belirten integer değerdir. Başarılı durumlar için 0 hata durumları için uygun status kodunu döner.

message: Statuse göre dönen string cevap mesajıdır. Başarılı cevaplar için "OK" olarak döner.

detail: Servisin dönmesi gereken bir detay bilgisi varsa bu alanda döndürülür. Detail alanı herhangi bir obje tipinde olabilir.

Z Raporu Kontrol Servisleri

Get Report Details

Path Variable olarak verilen uuid'li raporun detay bilgilerini döner

Örnek Response Body:

{
    "status": 0,
    "message": "OK",
    "detail": {
        "dateTime": "1706693610000", (Long-Unix Timestamp in MS)
        "terminalId": "TestUserTerminal", (String)
        "ejNo": 1, (short)
        "zNo": 2, (short)
        "receiptNo": 3, (short)
        "documentNum": 4, // Optional (short)
        "saleReceiptNum": 5, (short)
        "fiscalReceiptNum": 6, (short)
        "cumTotal": 3809, (long)
        "cumTotalVat": 761, (long)
        "macTotal": 3809, //Optional (long) 
        "macTotalVat": 761, //Optional(long)
        "total": 3809, (long)
        "surchargeAmount": 0, // Optional (long)
        "discountQuantity": 2, // Optional (short)
        "discountAmount": 200, // Optional (long)
        "cancelItemQuantity": 1, // Optional (short)
        "cancelItemAmount": 100, // Optional (long)
        "cancelReceiptQuantity": 1, // Optional (short)
        "cancelReceiptAmount": 100, // Optional (long)
        "cancelReportQuantity": 1, // Optional (short)
        "cancelReportAmount": 100, // Optional (long)
        "pharmacyQuantity": 1, // Optional (short)
        "pharmacyAmount": 100, // Optional (long)
        "vats": [ // Optional
            {
               "rate" : 10, (short)
               "total":100, (long)
               "totalVat":10 (long)
            }
        ],
        "sections": [ // Optional
            { 
               "sectionNo":1 ,(short)
               "sectionName":Gıda, (String)
               "quantity":50, (int)
               "vatRate":10, (short)
               "amount" : 1000, (long)
            }
         ],
        "payments": [ // Optional 
           { 
               "quantity" : 1, (short)
               "amount": 100,  (int)
               "type"  : 0 (short)
           }
        ],
        "totalVat": 761, (long)
        "cashierRecords": [ // Optional
            {
            "quantity": 15, (short)
            "amount": 15, (long)
            "name": "Kasiyer A" // Optional
            },
            {
            "quantity": 30, (short)
            "amount": 10, (long)
            "name": "Kasiyer B" // Optional
            }
        ] ,  
        "terminalId": "TestUserTerminal",
        "zno": 2
    }
}
İstek Değişkeni
Tanım
Optional/Zorunlu

dateTime

Rapor tarihi

Zorunlu

terminalId

Raporun oluşturulduğu cihazın numarası

Zorunlu

ejNo

Ekü numarası

Zorunlu

zNo

Z numarası

Zorunlu

receiptNo

Fiş numarası

Zorunlu

documentNum

Belge numarası

Optional

saleReceiptNum

Satış fişi numarası

Optional

fiscalReceiptNum

Mali fiş numarası

Optional

cumTotal

Kümülatif toplam değeri

Zorunlu

cumTotalVat

Kümülatif vergi toplamı değeri

Zorunlu

macTotal

Kurtarılan KDV Oran Toplamı

Optional

macTotalVat

Kurtarılan vergi miktarı Toplamı

Optional

surchargeQuantity

Artırım miktarı

Optional

surchargeAmount

Artırım değeri

Optional

discountQuantity

İndirim miktarı

Optional

discountAmount

İndirim değeri

Optional

total

Total değer

Zorunlu

cancelItemQuantity

İptal edilen ürün miktarı

Optional

cancelItemAmount

İptal edilen ürün değeri

Optional

cancelReceiptQuantity

İptal fişi miktarı

Optional

cancelReceiptAmount

İptal fişi değeri

Optional

cancelReportQuantity

İptal edilen rapor miktarı

Optional

cancelReportAmount

İptal edilen rapor değeri

Optional

pharmacyQuantity

Eczane katkı payı miktarı

Optional

pharmacyAmount

Eczane katkı payı değeri (Matrah dışı tutar)

Optional

vats

kdv oran ve miktarları

Optional

sections

kısım listesi

Optional

payments

Optional

totalVat

toplam kdv

Zorunlu

cashierRecords

kasiyer kayıtları

Optional

Dönen detay bilgileri z raporu gönderme servisinde gönderilen değişkenlerin aynılarını kapsar. Kaydedilmemiş optional alanlar null olarak döner.

Status:

0: Başarılı

3: Rapor Bulunamadı

Get Totals Between Dates

İstek parametresinde verilen unix timestamp ms formatındaki tarihler arasındaki rapor toplam bilgilerini döner

Örnek Response Body:

{
    "status": 0,
    "message": "OK",
    "detail": [
        {
            "sum": 3809,
            "dateTime": "1704067200000"
        },
        {
            "sum": 3655,
            "dateTime": "1704153600000"
        },
        {
            "sum": 3395,
            "dateTime": "1704240000000"
        },
        {
            "sum": 3094,
            "dateTime": "1704326400000"
        }
    ]

Status Kodları:

0: Başarılı

3: Rapor Bulunamadı

4: Datetime formatı hatalı

5: Vkn Bulunamadı

Get Summary By Terminal ID

İstekte path variable olarak verilen terminal id'ye ait tarih parametreleri arasındaki rapor özet bilgilerini döner

Örnek Response Body:

{
    "status": 0,
    "message": "OK",
    "detail": [
        {
            "dateTime": 1704101610000,
            "total": 3809,
            "totalVat": 761,
            "uuid": "85a5da69-8a4c-42d6-9cb1-b3c40e15e2e8",
            "zNo": 2
        },
        {
            "dateTime": 1704188010000,
            "total": 3655,
            "totalVat": 731,
            "uuid": "f079a017-3530-46c1-84c1-fc4db885536a",
            "zNo": 2
        }
    ]
}

total : O günki total değer

totalVat : O günki toplam kdv değeri.

uuid : Rapor uuid'si.

zNo : Z numarası.

dateTime : Unix Timestamp ms formatında tarih.

Status Kodları:

0: Başarılı

2: İki tarih arasında 32 günden fazla olamaz.

3: Rapor bulunamadı

5:Terminal bulunamadı

Get Summary By Tax ID

İstekte path variable olarak verilen tax id'ye ait tarih parametreleri arasındaki rapor özet bilgilerini döner

Örnek Response Body:

{
    "status": 0,
    "message": "OK",
    "detail": [
        {
            "dateTime": 1704101610000,
            "total": 3809,
            "totalVat": 761,
            "uuid": "85a5da69-8a4c-42d6-9cb1-b3c40e15e2e8",
            "zNo": 2
        },
        {
            "dateTime": 1704188010000,
            "total": 3655,
            "totalVat": 731,
            "uuid": "f079a017-3530-46c1-84c1-fc4db885536a",
            "zNo": 2
        }
    ]
}

total : O günki total değer

totalVat : O günki toplam kdv değeri.

uuid : Rapor uuid'si.

zNo : Z numarası.

dateTime : Unix Timestamp ms formatında tarih.

Status Kodları:

0: Başarılı

2: İki tarih arasında 32 günden fazla olamaz.

3: Rapor bulunamadı

5:Tax Id bulunamadı

Ödeme Tipleri

Ödeme Tipi

Değer

Açıklama

PAYMENT_CASH

1

Nakit

PAYMENT_CHEQUE

2

Çek

PAYMENT_CREDITCARD

3

Kredi Kartı

PAYMENT_FOOD

7

Yemek Kartı

PAYMENT_ODEMESIZ

8

Ödemesiz

PAYMENT_IKRAM

9

İkram

PAYMENT_VERESIYE

10

Veresiye

PAYMENT_PUAN

11

Puan

PAYMENT_VPOS

12

EPOS Ödeme

PAYMENT_MOBILE

13

Mobil Ödeme

PAYMENT_EMONEY

14

E-Para Ödeme

PAYMENT_CHARITY

15

Bağış

PAYMENT_BOND

16

Bond ile Ödeme

PAYMENT_OPENACCOUNT

17

Açık Hesap

PAYMENT_MONEYTRANSFER

18

Para Transferi

PAYMENT_TRANSPORTATIONCARD

19

Ulaşım Kartı

PAYMENT_GIFTCARD

20

Hediye Kartı

Yemek Kartı Kodları:

Yemek Kartı

Kod

EDENRED

1001

MULTINET

1002

SETCARD

1003

SODEXO

1004

TOKENFLEX

1005

Banka Kodları:

Kod
Banka/Özel Finans Kurumu

001

Türkiye Cumhuriyet Merkez Bankası A.Ş.

004

İller Bankası

010

Türkiye Cumhuriyeti Ziraat Bankası A.Ş.

012

Türkiye Halk Bankası A.Ş.

013

Denizbank

014

Türkiye Sınai Kalkınma Bankası A.Ş.

015

Türkiye Vakıflar Bankası T.A.O.

016

Türkiye İhracat Kredi Bankası A.Ş. (Eximbank)

017

Türkiye Kalkınma Bankası A.Ş.

029

Birleşik Fon Bankası A.Ş. (Bayındırbank A.Ş.)

032

Türk Ekonomi Bankası A.Ş.

034

Aktif Yatırım Bankası A.Ş.

046

Akbank T.A.Ş.

048

HSBC Bank A.Ş.

058

Sınai Yatırım Bankası A.Ş.

059

Şekerbank T.A.Ş.

062

Türkiye Garanti Bankası A.Ş.

064

Türkiye İş Bankası A.Ş.

067

Yapı ve Kredi Bankası A.Ş.

071

Fortis Bank (TEB)

087

Banca di Roma

088

The Royal Bank of Scotland PLC Merkezi Amsterdam İstanbul Merkez Şubesi

091

Arap Türk Bankası A.Ş.

092

Citibank N.A.

094

Bank Mellat

095

BCCI

096

Turkish Bank A.Ş.

097

Habib Bank Limited

098

JP Morgan Chase Bank İstanbul Türkiye Şubesi

099

Oyak Bank A.Ş. - ING BANK

100

Adabank A.Ş.

101

Türk Sakura Bank A.Ş.

103

Fiba Bank A.Ş.

104

IMPEXBANK

106

PORTIGON A.G.

107

BNP-Ak-Dresdner Bank A.Ş.

108

Turkland Bank A.Ş.

109

Tekstil Bankası A.Ş.

110

Credit Lyonnais

111

Finansbank A.Ş.

113

Marbank

115

Deutsche Bank A.Ş.

116

TAİB Yatırım Bank A.Ş.

117

Turizm Yatırım ve Ticaret Bank A.Ş.

118

Kıbrıs Kredi Bankası

119

Birleşik Yatırım

121

Standard Chartered Yatırım Bankası Türk A.Ş.

122

Societe Generale

123

HSBC Bank A.Ş.

124

Alternatifbank A.Ş.

125

Burganbank A.Ş.

127

KentBank

128

Park Yatırım Bankası

129

Tat Yatırım Bankası A.Ş.

132

IMKB Takas ve Saklama Bankası A.Ş.

133

ING BANK

134

Denizbank A.Ş.

135

Anadolubank A.Ş.

136

Okan Yatırım Bankası A Ş

137

Rabobank Nederland İstanbul Merkez Şubesi

138

Diler Yatırım Bankası A.Ş.

139

GSD Yatırım Bankası A.Ş.

140

Credit Suisse First Boston İstanbul Şubesi

141

Nurol Yatırım Bankası A.Ş.

142

Bank Pozitif Kredi ve Kalkınma Bankası A.Ş.

144

Atlas Yatırım Bankası A.Ş.

145

Morgan Guarenty Trusy Company

146

OdeaBank A.Ş.

147

Bank of Tokyo -Mitsubishi UFJ Turkey A.Ş.

148

Intesa SanPaolo SPA İtalya-İstanbul Merkez Şubesi

203

Al Baraka Türk Katılım Bankası A.Ş.

204

Family Finans Kurumu

205

Kuveyt Türk Katılım Bankası A.Ş.

206

Türkiye Finans Katılım Bankası A.Ş.

208

Asya Katılım Bankası A.Ş.

210

Vakıf Katılım Bankası A.Ş.

223

Al Baraka Türk Katılım Bankası A.Ş.

PreviousTanıtım

Last updated