Üç adımda kullanım
Akış sıralıdır: önce kimlik bilgisi tanımlanır, sonra token alınır, en son veri çekilir.
Kimlik bilgisi
Yönetim panelinden firmaya kullanıcı adı, şifre ve
apiKey tanımlanır; hangi ETA veritabanlarına erişebileceği ve
(isteğe bağlı) izinli IP adresleri de burada belirlenir.
Token al
POST /api/auth/token ile üç bilgi gönderilir, karşılığında bir
JWT döner. Sonraki tüm isteklerde
Authorization: Bearer … başlığı olarak taşınır.
Veri çek
Önce /api/v1/firmalar ile geçerli etaDb değerleri alınır,
ardından /api/v1/cariler seçilen firmanın cari kartlarını
sayfalı döner.
Uç noktaları
Açık uçlar kimlik istemez; JWT uçları geçerli bir token
ve kiracının IP kısıtından geçmeyi gerektirir. Yetkisiz IP 403 alır.
| Metot | Uç | Erişim | Açıklama |
|---|---|---|---|
| GET | /api/v1/ping | Açık | Servis ayakta mı ve hangi sürüm. |
| POST | /api/auth/token | Açık | Kullanıcı adı + şifre + apiKey → JWT token. |
| GET | /api/v1/firmalar | JWT | Token sahibinin erişebildiği ETA veritabanları (geçerli etaDb değerleri). |
| GET | /api/v1/cariler | JWT | Cari kartlar; her kayıtta adres ve kimlik satırları iç içe. Sayfalı. |
| GET | /api/v1/stoklar | JWT | Stok kartları; istenirse fiyat satırları iç içe. Sayfalı. |
| GET | /api/v1/stoklar/birimler | JWT | Birim tanımları (STKBIRIM). Kurulum geneli küçük bir katalog; stok kartına bağlı değildir. Sayfalı. |
| GET | /api/v1/stoklar/fiyatlar | JWT | Fiyat satırları (STKFIYAT) — stok kartından bağımsız, kendi başına sayfalı. Sayfalı. |
| GET | /api/v1/hizmetler | JWT | Hizmet kartları. Sayfalı. |
| GET | /api/v1/masraf-merkezleri | JWT | Masraf merkezleri (MASRAFMER). Sayfalı. |
| GET | /api/v1/gelen-faturalar | JWT | Entegratörden gelen e-Fatura başlıkları. Sayfalı, tarih aralığı zorunlu (azami 31 gün). |
| GET | /api/v1/gelen-faturalar/{uuid} | JWT | Tek e-Faturanın UBL'inden çözümlenmiş tam detayı (taraflar, satırlar, vergiler). |
| GET | /api/v1/gelen-faturalar/{uuid}/xml | JWT | Aynı belgenin ham UBL XML'i (application/xml). Çözümlenmez, e-imza bozulmasın diye içeriğine dokunulmaz. |
| GET | /api/v1/gelen-faturalar/{uuid}/pdf | JWT | Aynı belgenin entegratörün ürettiği PDF görüntüsü (application/pdf, dosya adı {uuid}.pdf). |
| GET | /api/v1/giden-faturalar | JWT | Entegratörden gönderdiğiniz (satış) e-Fatura / e-Arşiv başlıkları. Gelen listesiyle aynı biçim; müşteri filtresi aliciVkn. Sayfalı, tarih aralığı zorunlu (azami 31 gün). |
| GET | /api/v1/giden-faturalar/{uuid} · /xml · /pdf | JWT | Giden faturanın çözümlenmiş detayı, ham UBL XML'i ve PDF görüntüsü. |
| GET | /api/v1/e-irsaliyeler/{giden|gelen}/{belgeNo}/{pdf|xml|html|xslt} | JWT | Giden ya da gelen e-İrsaliyenin PDF'i, imzalı UBL XML'i, HTML görüntüsü ya da XML'in içindeki görüntü şablonu (XSLT). Belge, e-İrsaliye entegratöründen (Park Entegrasyon) GİB numarasıyla bulunur. |
| GET | /api/v1/e-irsaliyeler/gelen | JWT | Tarih aralığındaki gelen e-İrsaliyelerin listesi, Park Entegrasyon'dan: belge no, tarih, durum, gönderen VKN ve ünvan. |
| GET | /api/v1/gelen-irsaliyeler | JWT | Entegratörden gelen e-İrsaliye başlıkları. Sayfalı, tarih aralığı zorunlu (azami 31 gün). |
| GET | /api/v1/gelen-irsaliyeler/{uuid} | JWT | Tek e-İrsaliyenin tam detayı (teslimat adresi, taşıyıcı, satırlar). |
| GET | /api/v1/faturalar | JWT | ETA'ya işlenmiş fatura fişleri (FATFIS): fiş tarihi, evrak no, cari kod, cari ünvan, genel toplam. Alış ve satış birlikte. Sayfalı, tarih aralığı zorunlu. |
| GET | /api/v1/irsaliyeler | JWT | ETA'ya işlenmiş irsaliye fişleri (IRSFIS), aynı beş alan. Sayfalı, tarih aralığı zorunlu. |
| GET | /api/v1/irsaliyeler/bagli-faturalar | JWT | İrsaliye numaralarından, ETA'da bağlı oldukları faturanın numarası ve tarihi. Bir istekte en fazla 25 numara; tarih aralığı istemez. |
| GET | /api/v1/master/fatura-fis-tipleri | JWT | Fatura fiş tipleri (FATGENFISTIP). Master veritabanından. Sayfalı. |
| GET | /api/v1/master/irsaliye-fis-tipleri | JWT | İrsaliye fiş tipleri (IRSGENFISTIP). Master veritabanından. Sayfalı. |
| GET | /api/v1/master/cari-fis-tipleri | JWT | Cari fiş tipleri (CARGENFISTIP). Master veritabanından. Sayfalı. |
| GET | /api/v1/master/stok-fis-tipleri | JWT | Stok fiş tipleri (STKGENFISTIP). Master veritabanından. Sayfalı. |
| GET | /api/v1/master/muhasebe-fis-tipleri | JWT | Muhasebe fiş tipleri (MUHGENFISTIP). Master veritabanından. Sayfalı. |
| GET | /api/v1/master/kdv-kisimlari | JWT | KDV kısımları / oran tanımları (KDVKISIM). Master veritabanından. Sayfalı. |
| GET | /api/v1/master/doviz-tanimlari | JWT | Döviz cinsi tanımları (DOVTAN). Master veritabanından. Sayfalı. |
| GET | /api/v1/master/doviz-kur-turleri | JWT | Kur türü tanımları (DOVTUR). Master veritabanından. Sayfalı. |
| GET | /api/v1/master/doviz-kurlari | JWT | Döviz kuru geçmişi (DOVHAR). Master veritabanından. Sayfalı, tarih aralığı filtreli. |
| POST | /api/v1/rf-fisleri | JWT | YAZMA. Fatura ya da irsaliyeyi ETA aktarım (RF) tablolarına yazar. Gerçek ETA belgesi burada oluşmaz; onu üreten saklı yordamı ETA tarafındaki kendi işiniz çağırır. |
| POST | /api/v1/rf-fisleri/onizleme | JWT | YAZMAZ. Yazma ucuyla aynı gövdeyi alır; fiş ETA'ya aktarılsaydı oluşacak toplamları, KDV kırılımını ve satır tutarlarını döner. Hiçbir tabloya kayıt eklenmez. |
| GET | /api/v1/rf-fisleri/{masterSatirId} | JWT | Yazılan fişin aktarım durumu: ETA belgesine çevrildi mi, hangi referans numaraları üretildi. |
| GET | /api/v1/rf-fisleri?dipNot24={guid} | JWT | FISDIPNOT24'e yazdığınız GUID ile fişleri bulur; RF_FISMASTER, RF_FISHAREKET ve RF_FISTOPLAM'ın tüm alanlarını ham döner. Eşleşme yoksa boş liste. |
| GET | /api/v1/rf-fisleri/fatura-durumlari?dipNot24={guid}&dipNot24={guid} | JWT | En fazla 25 GUID ile tek istekte: RF fişi (3 tablo), fişten oluşan ETA faturası (FATFIS, FATHAR, FATFISTOPLAM) ve faturanın EDM'deki durumu. |
| GET | /swagger/v1/swagger.json | Açık | OpenAPI 3 belgesi. Uygulamanın kendi uç tanımlarından üretilir; istemci modelleri buradan üretilebilir. |
| GET | /swagger | Açık | Aynı belgenin gezilebilir arayüzü (Swagger UI). |
/api/v1/cariler parametreleri: etaDb (zorunlu),
kodOnek, aktif (true/false), skip,
take (öntanımlı 100, azami 500).
/api/v1/stoklar parametreleri: etaDb (zorunlu),
kodOnek, aktif (true/false),
fiyatlar (true/false), skip, take.
fiyatlar öntanımlı olarak kapalıdır — açılırsa her kayda
fiyatlar dizisi eklenir; bir stokta 70'e kadar fiyat satırı
bulunabildiği için yanıt hızla büyür.
/api/v1/hizmetler parametreleri: etaDb (zorunlu),
kodOnek, skip, take.
aktif parametresi yoktur: ETA'nın HIZMET tablosunda
aktiflik alanı bulunmamaktadır.
/api/v1/masraf-merkezleri parametreleri: etaDb (zorunlu),
kodOnek, skip, take; aktiflik parametresi yoktur.
Fişe masraf merkezi yazmak için kod hamAlanlar ile FISMASMER
(başlık) ya da satırda HARMASMER olarak gönderilir; fatura yordamı ikisini
de ETA'ya taşır.
/api/v1/faturalar ve /api/v1/irsaliyeler parametreleri:
etaDb, baslangicTarihi, bitisTarihi (üçü de zorunlu,
tarihler dahil), carKod ve evrakNo (tam eşleşme),
skip, take. Gelen belge uçlarındaki 31 gün sınırı burada
yoktur. evrakNo ETA'da tekil değildir; satırı
evrakNo + carKod + fisTar birlikte tanımlar.
İrsaliyeye bağlı fatura: /api/v1/irsaliyeler/bagli-faturalar.
etaDb ve irsaliyeNo zorunludur; birden çok numara için
parametreyi tekrarlayın (?irsaliyeNo=A&irsaliyeNo=B, en fazla 25).
Bulunan her irsaliye için irsaliyeNo, irsaliyeTarihi,
cariKodu, faturaNo, faturaTarihi döner.
Faturalanmamış irsaliyede (ya da bağlı fatura silinmişse) fatura alanları
null'dır; ETA'da bulunmayan numara yanıtta yer almaz. Fatura numarası
faturanın kendisinden okunur — irsaliyenin üzerindeki "fatura no"
kopyası, fatura sonradan numara değiştirince güncellenmediği için kullanılmaz.
⚠ İrsaliye numarası tekil olmadığından aynı numaralı her irsaliye ayrı satırdır;
ayırt etmek için tarih ve cari kodu kullanın.
Belge uçları (/api/v1/gelen-faturalar, /api/v1/gelen-irsaliyeler)
Bu uçlar entegratörden (EDM / Digital Planet) okur, ETA
veritabanından değil. etaDb alırlar ama oradan veri çekmezler:
entegratör kimliği (kullanıcı, şifre, tip) ETA'daki SABITLER
tablosundan okunur ve istek müşterinin entegratör hesabına gider. Yani aynı uç,
kiracıdan kiracıya farklı bir dış servise bağlanır.
Liste parametreleri: etaDb (zorunlu),
baslangicTarihi, bitisTarihi
(ikisi de zorunlu, yyyy-MM-dd, dahil),
gonderenVkn (10 hane VKN veya 11 hane TCKN), belgeNo,
skip, take. Tarih aralığı en fazla 31
gündür; daha genişi 400 TARIH_ARALIGI_GECERSIZ döner.
Detay uçları yalnız etaDb alır, belge uuid'si yoldadır.
Yalnız GELEN (alış) belgeler listelenir ve entegratördeki
okundu işareti değiştirilmez. Liste ucu belgenin UBL'ini
indirmez; satır ayrıntısı için detay ucu kullanılır.
⚠ toplam alanı bu uçlarda null gelebilir
— entegratör gerçek bir eşleşen kayıt sayısı vermez, sayfalamanın bittiği dönen
kayıt sayısının take'ten küçük olmasıyla anlaşılır.
Entegratör o belge türünü sunmuyorsa 501 BELGE_TURU_DESTEKLENMIYOR
döner; bu bir yetki hatası değildir.
e-İrsaliyede skip pahalıdır. EDM'in irsaliye arama
anahtarında fatura tarafındaki OFFSET alanının karşılığı yoktur;
atlama, entegratörden skip + take kadar kayıt çekilip fazlası API
tarafında atılarak yapılır. Sonuç doğrudur ama derin sayfalamada (ör.
skip=5000) her istek entegratörden 5000+ kayıt çeker. Geniş
taramaları skip ile değil tarih aralığını daraltarak
yapın.
Gelen e-Faturanın PDF'i: GET /api/v1/gelen-faturalar/{uuid}/pdf?etaDb=….
uuid, liste ucunun döndüğü belge kimliğidir. Görüntü entegratörde
(EDM) üretilir ve olduğu gibi döner; belge yoksa 404 BELGE_BULUNAMADI,
entegratör PDF yerine başka bir içerik dönerse 502 ENTEGRATOR_HATA alınır.
Belgenin okundu işareti değiştirilmez.
Giden (satış) faturalar: /api/v1/giden-faturalar.
Gelen fatura uçlarının aynısıdır: liste, /{uuid} (detay), /{uuid}/xml
ve /{uuid}/pdf. Parametreler de aynıdır; tek fark müşteriye göre daraltmak için
gonderenVkn yerine aliciVkn kullanılmasıdır. Listede
gonderenVkn firmanızın, aliciVkn müşterinin VKN/TCKN'sidir
(aliciVkn alanı gelen fatura listesinde de doludur). Gelen bir faturanın
uuid'si giden uçlarında, giden bir faturanınki gelen uçlarında
404 döner.
e-İrsaliye belgeleri (/api/v1/e-irsaliyeler)
GET /api/v1/e-irsaliyeler/{yon}/{belgeNo}/{bicim}?etaDb=….
e-İrsaliyeler e-Faturadan ayrı bir entegratörde (Park Entegrasyon)
durur; bu uç oraya yalnız okumak için bağlanır.
yon:giden(sizin kestiğiniz) ya dagelen(size gelen).belgeNo: e-İrsaliyenin GİB numarası (ör.STK2026000007182; harf ve rakam, en fazla 50 karakter).bicim:pdf(görüntü),xml(imzalı UBL, değiştirilmeden;ublda kabul edilir),html(görüntü),xslt(XML'in içine gömülü görüntü şablonu; XML ile birlikte kullanılarak belge kendi görünümüyle açılır).gonderenVkn(isteğe bağlı, 10 ya da 11 hane): aynı numara farklı gönderenlerde bulunabileceği için gelen irsaliyede eşleşmeyi daraltır.
Yanıtlar: belge yoksa 404 BELGE_BULUNAMADI; numara birden çok belgeyle
eşleşirse 400 PARAMETRE_GECERSIZ (gonderenVkn ile daraltın);
e-İrsaliye entegratör hesabı tanımlı değilse 409 ENTEGRATOR_TANIMSIZ;
entegratöre ulaşılamazsa 502 ENTEGRATOR_HATA ya da
504 ENTEGRATOR_ZAMAN_ASIMI.
Gelen e-İrsaliye listesi:
GET /api/v1/e-irsaliyeler/gelen?etaDb=…&baslangicTarihi=2026-10-20&bitisTarihi=2026-11-12.
Tarihler zorunlu ve dahil; aralık en fazla 31 gün (daha genişi 400 TARIH_ARALIGI_GECERSIZ).
skip (varsayılan 0), take (varsayılan 100, azami 200),
gonderenVkn (isteğe bağlı, 10 ya da 11 hane). Yanıt
/api/v1/gelen-irsaliyeler ile aynı yapıdadır (toplam, skip,
take, kayitlar[]: uuid, belgeNo,
duzenlemeTarihi, durum, gonderenVkn, gonderenUnvan).
/api/v1/gelen-irsaliyeler EDM'den okur; gelen e-İrsaliyeleri Park'ta olan firma bu ucu
kullanır. Satırlar için /api/v1/e-irsaliyeler/gelen/{belgeNo}/xml. Okundu işareti değişmez.
/api/v1/stoklar/birimler parametreleri: etaDb (zorunlu),
kodOnek, skip, take.
STKBIRIM stok kartına bağlı değildir: kurulum geneli
bir birim kataloğudur (ölçülen dört kurulumda 21–31 satır) ve stok kartlarındaki
birim alanları buna atıfta bulunur. ⚠ stkbirimcarpan ve
stkbirimbolen ölçülen kurulumların tamamında 0'dır;
birim dönüşümünde doğrudan kullanılamazlar.
/api/v1/stoklar/fiyatlar parametreleri: etaDb (zorunlu),
stokKodu (tam eşleşme), kodOnek (ön ek),
depoKodu (tam eşleşme), fiyatNo, skip,
take. Tek bir stokun fiyatları için stokKodu kullanın:
kodOnek=159 ön eki 159 03 01 001 gibi alt kodları da getirir.
⚠ depoKodu bazı kurulumlarda tamamen boştur ve filtre
o kurulumlarda hiç sonuç döndürmez.
⛔ /api/v1/stoklar/fiyatlar ucunda mükerrer satırlar
bulunabilir. STKFIYAT tablosunda hiçbir kolon bileşimi tekil
değildir; ölçülen kurulumlarda 26 kolonun tamamı aynı olan tam kopya
satırlar bulundu (bir kurulumda 12.170 satırın 11.975'i farklı, bir grupta 7 kopya).
Bunun sonucu: art arda çekilen iki sayfada bir kopya iki kez görünüp diğeri hiç
görünmeyebilir. Satırlar birbirinin aynısı olduğu için veri kümesi yine de doğrudur —
"kayıt kayboldu" diye yorumlanmamalıdır.
Aynı fiyat satırları /api/v1/stoklar?fiyatlar=true ile stok kartının
içinde de dönebilir. Ayrı uç, fiyatları karttan bağımsız çekmek
içindir: fiyatlar sık, katalog seyrek değişir — ayrı uç olmasaydı fiyat tazelemek
için 157 kolonluk stok kartlarını da her seferinde indirmek gerekirdi.
Fiş yazma uçları (/api/v1/rf-fisleri)
Bu uçlar veri okumaz, ETA'ya kayıt yazar. Fiş, ETA'nın aktarım
(RF) tablolarına — RF_FISMASTER, RF_FISHAREKET,
RF_FISTOPLAM — tek bir veritabanı işlemi içinde
yazılır: ya üçü de yazılır ya da hiçbiri.
⚠ Gerçek ETA belgesi (FATFIS / IRSFIS) bu uçta OLUŞMAZ. Fişi
belgeye çeviren saklı yordamı (SP_RFCREATEINVOICERECEIPT /
SP_RFCREATEDISPATCHORDER) ETA tarafındaki kendi işiniz çağırır.
Aktarımın gerçekleşip gerçekleşmediği
GET /api/v1/rf-fisleri/{masterSatirId} ile izlenir; yanıttaki
aktarildi alanı bayrağa değil, belge türüne karşılık gelen
referans numarasının üretilmiş olmasına bakar.
Mükerrer yazım engellenir. disReferans alanı
(çağıran sistemdeki belge kimliği) zorunludur ve benzersizdir; aynı değerle
ikinci bir istek 409 FIS_ZATEN_KAYITLI ile reddedilir ve hata
detayında mevcut kaydın masterSatirId'si bildirilir. Aynı
disReferans ile aynı anda gelen istekler sıraya
alınır: yalnız ilki yazılır, ilk kayıt aktarılmış olsun olmasın diğerleri
409 alır. Yani zaman aşımına uğrayan bir istek güvenle yeniden denenebilir.
Faturayı mevcut irsaliye(ler)e bağlama: irsaliyeler.
Yalnız fatura fişinde, en fazla 20 irsaliye:
"irsaliyeler": [ { "refNo": 4711 }, { "belgeNo": "SHP2026000004091", "tarih": "2026-11-10" } ].
Her irsaliye refNo (ETA IRSFISREFNO) ya da belgeNo
(irsaliye numarası, en fazla 40 karakter) ile verilir; tarih isteğe bağlıdır.
İrsaliyeler aynı caride, aynı yönde, iptal edilmemiş ve henüz faturalanmamış olmalıdır.
Bağlanan faturada yeni stok fişi açılmaz (stok irsaliyeyle düşmüştür), irsaliyelerin
hepsi "faturalandı" olarak işaretlenir, faturada ilk irsaliyenin numarası
ve tarihi görünür. Aynı yılın irsaliyelerinden biri bile bulunamazsa fatura oluşturulmaz,
kayıt RF'de bekler ve neden GET /api/v1/rf-fisleri/{masterSatirId}
yanıtındaki sonAktarimHatasi'nda görünür. Tarihi faturadan önceki yılda olan
irsaliye (Aralık irsaliyesi → Ocak faturası) aranmaz, faturaya yalnız numara ve tarih
olarak yazılır. ⚠ Birden fazla irsaliye ETA'daki fatura yordamının
13.11.2026 sürümünü ([U6]) ister; yordam eski ise istek
409 AKTARIM_YORDAMI_ESKI ile reddedilir ve fiş yazılmaz.
irsaliyeler gönderildiğinde hamAlanlar ile
FISIRSFLAG / FISIRSREFNO / FISIRSNO /
FISIRSTAR gönderilemez (eski yöntem, irsaliyeler olmadan, tek
irsaliye için çalışmaya devam eder).
İade faturasında iade edilen fatura: iadeEdilenFaturalar.
Yalnız fatura fişinde, en fazla 10 satır:
"iadeEdilenFaturalar": [ { "belgeNo": "FT32026000000007", "tarih": "2026-09-11" } ].
belgeNo (en fazla 30 karakter) ve tarih zorunludur. Bilgi,
ETA'da elle kesilen iade faturalarındaki yere yazılır ve e-Faturada "iade edilen
fatura" bilgisi olarak gider.
Uzun fatura açıklaması: aciklama. Yalnız fatura fişinde,
en fazla 10.000 karakter. Metin kelime sınırından 80'er karakterlik satırlara bölünür:
ilk üç satır faturanın açıklama 1-3 alanlarına, sığmayan kısmı faturanın
açıklamalar bölümüne yazılır. Satır sonları boşluğa çevrilir.
aciklama gönderildiğinde aciklama1-aciklama3
boş bırakılmalıdır; metin üç satırı aşıyorsa hamAlanlar ile
FISDIPNOT1-FISDIPNOT10 gönderilemez (bu alanları API doldurur;
metnin doldurmadığı olanlara boş metin yazılır).
⚠ 13 satırı (yaklaşık 1000 karakteri) aşan metin ETA'daki fatura
yordamının 13.11.2026 sürümünü ([U7]) ister; yordam eski ise istek
409 AKTARIM_YORDAMI_ESKI ile reddedilir ve fiş yazılmaz.
KDV tevkifatı: satirlar[].tevkifat. Yalnız faturada ve KDV'li
satırda: "tevkifat": { "kod": "606", "oran": 90, "tutar": 180.00 }.
kod GİB tevkifat kodu (en fazla 4 rakam), oran KDV'nin yüzdesi
(9/10 için 90; 10'un katı), tutar isteğe bağlı (verilmezse satır KDV'si × oran).
Fişteki tevkifatlı satırların oranı aynı olmalıdır. ETA faturasında genel toplam ve cari
hareket tevkifat düşülmüş olur; kod, oran ve tutar satıra ve faturanın
toplam satırlarına ETA'nın elle girişteki yerine yazılır. Yanıttaki
genelToplam tevkifat düşülmüş tutardır, tevkifatTutari ayrıca
döner. ⚠ ETA'daki fatura yordamının 15.11.2026 sürümünü ([U9]) ister; yordam eski ise
istek 409 AKTARIM_YORDAMI_ESKI ile reddedilir.
Belge düzeyinde iskonto: belgeIskontoTutari. Yalnız faturada,
KDV hariç fişte; KDV hariç TL tutar. API tutarı stok satırlarına (kalem
iskontosu sonrası matrahları oranında; hizmet satırına pay verilmez) dağıtır, satırların KDV'sini yeniden hesaplar ve ETA'nın genel
iskonto alanlarına yazar (HARDIGERIND, FISGENINDTOP, toplam
satırı "Genel İndirim 1"). Belge düzeyindeki ek tutar (masraf) için alan
yoktur: ayrı bir hizmet satırı olarak gönderin (kartTuru: "hizmet"). Hizmet
kartının muhasebe kodu (HIZMUHKOD) dolu olmalıdır; boşsa muhasebe fişi kurulamaz.
Tutar alanları (ETA kuralı). Satırın HARTUTAR'ı ve fişin
FISMALTOP'u (yanıttaki malToplam) iskonto
öncesi tutardır (miktar × fiyat); iskonto HARISKYTUT1-5 ve
FISTOPISK'ta, net tutar HARKDVMATRAH /
FISKDVMATRAHI'nda durur: malToplam − toplamIskonto = kdvMatrahi.
Dövizli fişte (doviz.kod ve doviz.kur verildiğinde) satırın döviz
fiyatı ve tutarı (HARDOVFIYAT / HARDOVTUTAR, iskonto öncesi) ve
fişin döviz genel toplamı (FISGENDOVTOP) API tarafından kura bölünerek
yazılır; bunları hamAlanlar ile göndermeniz gerekmez.
Aktarılamayan kayıt. ETA tarafındaki aktarım işleri hata veren kaydı
atlayıp diğerlerine devam eder ve nedeni günlük tablosuna yazar: faturada
RF_INVOICERECEIPT_LOG, irsaliyede RF_DISPATCHORDER_LOG
(BASARILI = 0, HATAMESAJI). Hatalı kayıt düzeltilene kadar
her çalışmada yeniden denenir; GET /api/v1/rf-fisleri/{masterSatirId}
yanıtında aktarildi = false olan kayıt hâlâ bekliyordur ve son denemesi
hata verdiyse yanıttaki sonAktarimHatasi (mesaj,
tarih) günlükteki son hatayı gösterir. Kurulumun günlük tablosunda tarih kolonu
yoksa tarih null gelir.
Ön koşul: cariKodu ETA'da CARKART'ta,
tüm stokKodu değerleri STKKART'ta tanımlı olmalıdır;
değilse istek 409 KART_BULUNAMADI ile reddedilir. ⚠ Kod
karşılaştırması ETA'nın harmanlamasına göre büyük/küçük harf
duyarlı olabilir.
Hizmet kartı satırı: satırda "kartTuru": "hizmet"
gönderin ve hizmet kodunu stokKodu alanına yazın (ETA hizmet kodunu da
stok kodunun kolonunda taşır). Kod HIZMET tablosunda tanımlı olmalıdır;
değilse 409 KART_BULUNAMADI döner. kartTuru verilmezse
satır stok kabul edilir; hizmet satırı yalnız faturada kullanılabilir.
⚠ ETA'nın standart SP_RFCREATEINVOICERECEIPT yordamı satırın kod tipini
aktarım tablosundan okumaz, her satırı stok satırı olarak aktarır; hizmet satırının
ETA'ya hizmet olarak geçmesi için yordamın HARKODTIP kolonunu taşıyacak
şekilde güncellenmesi gerekir.
⚠ Belge numarasında iki tür arasında fark vardır. İrsaliyede
belgeNo zorunludur — ETA irsaliye numarasını
kendisi üretmez, gönderdiğinizi kullanır. Faturada ise isteğe bağlıdır ve
aktarım sırasında ETA kendi evrak sayacından ürettiği numarayı bu alanın
üzerine yazar; kendi numaranızı korumak için
disReferans kullanın (o alan ETA belgesine değişmeden taşınır).
Tutarları API hesaplar. Satır tutarı, KDV matrahı, KDV tutarı,
kalem iskontoları ve KDV kırılımı gönderdiğiniz miktar,
fiyat, kdvOrani ve iskontoYuzdeleri
değerlerinden türetilir; yanıtta hesaplanan toplamlar döner ve kendi
hesabınızla karşılaştırabilirsiniz. kdvDahil=true gönderilirse
fiyatlar KDV dahil kabul edilip matrah geriye hesaplanır.
Yazmadan önce kontrol: POST /api/v1/rf-fisleri/onizleme.
Aynı gövdeyi gönderin; uç hiçbir tabloya yazmadan, fiş ETA'ya
aktarılsaydı oluşacak toplamları, oran bazında KDV kırılımını ve satır satır
tutarları döner (200). Yazma ucunun bütün denetimleri — gövde
doğrulaması, cari/stok kartı ve mükerrer disReferans — burada da
çalışır; önizleme 200 dönüyorsa aynı gövdeyle yazma da bu
denetimlerden geçer ve yanıtındaki toplamlar aynıdır. ⚠ ETA'nın fatura aktarım
yordamı başlık toplamlarını satırların toplamından yeniden
hesaplar, irsaliye yordamı başlıktakini aynen alır; önizleme bu kuralla hesaplar.
Faturanın ETA'daki numarası ise aktarım anında ETA'nın sayacından verildiği için
önceden bilinemez.
Kendi kimliğinizle geri okuma: GET /api/v1/rf-fisleri?etaDb=…&dipNot24={guid}.
Yazarken dipNot24 alanına (eskiden hamAlanlar.FISDIPNOT24) koyduğunuz GUID ile arar; eşleşen her fiş
için master (RF_FISMASTER), hareketler (RF_FISHAREKET,
HARSIRANO sırasıyla) ve toplamlar (RF_FISTOPLAM, TKONU
sırasıyla) satırlarının tüm kolonlarını döner. Kolon adları küçük harfle,
değerler ETA'daki gibi (dolgu boşluklu) gelir. Eşleşme yoksa 200 ve boş
fisler listesi döner. ⚠ GUID tireli 36 karakter olmalıdır ve olduğu gibi
aranır; kolon bazı kurulumlarda büyük/küçük harf duyarlıdır, yazarken kullandığınız
biçimle gönderin.
Birden çok GUID, fatura ve EDM durumu: GET /api/v1/rf-fisleri/fatura-durumlari?etaDb=…&dipNot24=A&dipNot24=B.
Parametreyi tekrarlayarak en fazla 25 GUID gönderin; yanıt sonuclar dizisidir ve
istekteki sırayı korur. Her GUID'in her fişinde, yukarıdaki ucun master /
hareketler / toplamlar alanlarına ek olarak fatura gelir:
fişin FATFISREFNO ile bağlı olduğu ETA faturasının fatfis (FATFIS),
fathar (FATHAR) ve fatfistoplam (FATFISTOPLAM) satırları — tüm
kolonlarıyla — ve edmDurumu. Fiş henüz faturaya aktarılmamışsa ya da fatura ETA'da
silinmişse fatura null'dır.
edmDurumu.sonuc: BULUNDU (EDM'in durum,
durumAciklamasi, gibDurumKodu, yanitKodu … alanları dolu),
BULUNAMADI, SORGULANMADI (ETA'da faturanın e-belge UUID'si yok: kâğıt
fatura ya da henüz e-belge olarak gönderilmemiş; neden aciklama'da) ya da
HATA (hataKodu + aciklama). Satış faturası EDM'in giden,
alış faturası gelen faturalarında aranır. ⚠ EDM'e ulaşılamazsa yanıt yine 200'dür ve
ETA verisi döner; yalnız edmDurumu HATA olur. İlk EDM sorgusu hata
verirse (ör. EDM şifresi hatalı) aynı istekteki diğer faturalar EDM'e hiç gönderilmez — hesabınız
hatalı giriş denemeleriyle kilitlenmesin diye. EDM durumu yalnız okunur.
Adlı alanlar (13.11): tcKimlikNo (FISTCKIMLIKNO; 11 ya da 10 hane;
boşsa yordam cari kartın kimlik bilgisinden doldurur), dipNot24 (FISDIPNOT24; en fazla
36 karakter, aramada kullanılan anahtar), hazirlamaTarihi (FISHAZTAR; verilmezse
yazım anı). Aynı kolon ayrıca hamAlanlar ile gönderilirse 400.
FISEFATFLAG göndermeyin: fatura ve irsaliye yordamları e-belge türünü cari karttan
(CAREFATFLAG) kendileri belirler, RF'deki değeri okumaz. Satır hamAlanlar'ı
iskonto/KDV tutarlarını değiştirirse RF_FISTOPLAM'ın iskonto ve KDV satırları değiştirilmiş
satırlardan kurulur.
Adlandırılmış alanların yetmediği yerde hamAlanlar sözlüğüyle
istediğiniz ETA kolonunu doğrudan yazabilirsiniz (satır bazında da vardır).
Tanınmayan bir kolon adı sessizce yok sayılmaz,
400 döner; kolona sığmayan bir metin de kırpılmaz, reddedilir.
Kimlik, mükerrer koruması ve aktarım durumu kolonları API tarafından yönetilir
ve bu yolla yazılamaz.
Kurulum adımı: mükerrer korumasını API kendisi yapar;
database/04_rf_fis_yazma.sql betiğiyle kurulan filtreli benzersiz
indeks buna ek, veritabanı düzeyinde bir güvencedir (API dışından yazılan kayıtları
da kapsar). Betik kiracıya tanımlı her ETA veritabanında ayrı ayrı çalıştırılmalıdır.
Master uçları (/api/v1/master/…)
Bu uçlar kart uçlarından farklı bir kaynaktan okur: fiş tipleri,
KDV kısımları, döviz ve kur türü tanımları ile döviz kurları bir firmaya değil
ETA kurulumunun tamamına aittir ve firma veritabanlarında
bulunmazlar. Bu yüzden
etaDb değil masterDb alırlar;
/api/v1/firmalar listesindeki değerler burada
kullanılamaz (tersi de geçerlidir — her iki durumda
403).
Beş fiş tipi ucu ile /api/v1/master/kdv-kisimlari,
/api/v1/master/doviz-tanimlari ve
/api/v1/master/doviz-kur-turleri parametreleri:
masterDb, kodOnek, skip,
take. masterDb zorunlu değildir:
kiracıda tek master tanımlıysa o kullanılır; birden fazla tanımlıysa (ör. hem
ETA_MASTER hem ETA_MASTERV8) hangisinin okunacağı
belirsiz olduğu için 400 döner ve ad açıkça istenir. Hiç tanım
yoksa 409 MASTER_DB_TANIMSIZ döner — bu yetki hatası değildir,
yönetim panelinden tanım eklenmesi gerekir. KDV kısımlarında
kodOnek filtresi KDVKISOZELKOD alanına uygulanır ve
bu alan çoğu kurulumda boştur; oran değeri kdvkisoran alanındadır
(20 = %20), açıklamadaki yüzde eskimiş olabilir.
/api/v1/master/doviz-kurlari parametreleri: masterDb,
dovizKodu, kurTuru, baslangicTarihi,
bitisTarihi (ikisi de yyyy-MM-dd ve dahil),
skip, take. dovizKodu ve
kurTuru ön ek değil TAM EŞLEŞMEDİR: aynı kurulumda hem
EUR hem EURO kodu bulunabildiği için ön ek araması
ikisini birden getirirdi. Kur türleri kuruluma göre değişir
(MBNKALS, MBNKSAT, MBNKEALS,
MBNKESAT…). Tarih aralığında gün sınırı yoktur;
sıralama dovhartar + dovharkod + dovhartur üzerinde artandır, yeni
kurlar listenin sonuna eklendiği için devam eden bir tarama kaymaz.
Döviz üçlüsü — biri diğerinin sözlüğü değildir.
kurTuru parametresinin tanımlı değerleri
/api/v1/master/doviz-kur-turleri ucundan okunabilir; ancak liste
“kur bulunan türler” değil “tanımlı türler”dir (ölçülen bir kurulumda 13 türden
8'inin hiç kur satırı yoktu). dovizKodu için
/api/v1/master/doviz-tanimlari YETMEZ: iki tablo birbirini
kapsamaz — ölçülen kurulumda DOVHAR'da kur satırı bulunan sekiz kod
(AZN, AED, EUR, KRW,
PKR, QAR, STERLİN, XDR)
DOVTAN'da hiç yoktu, DOVTAN'daki üç kod (ILS, JOD,
SYP) için ise DOVHAR'da tek satır yoktu. Kod kümesi kur verisinin
kendisinden öğrenilmelidir. Döviz tanımlarındaki dovtaneslkod
ETA kodunun ISO 4217 karşılığıdır (EURO → EUR);
dovtancarpan / dovtanbolen ölçülen kurulumların
hepsinde 0 geldi.
Örnek akış
POST /api/auth/token Content-Type: application/json { "kullaniciAdi": "delta", "sifre": "***", "apiKey": "e5174e75e807c8bfe…" }
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6…",
"gecerlilikBitis": "2026-07-27T20:00:00Z"
}
GET /api/v1/firmalar Authorization: Bearer eyJhbGciOiJ… → [ { "etaDb": "ETA_IZYAPIAS_2026", "gorunenAd": "İZYAPI 2026" } ]
GET /api/v1/cariler?etaDb=ETA_IZYAPIAS_2026&kodOnek=120&aktif=true&take=100
Authorization: Bearer eyJhbGciOiJ…
Kurallar & sınırlar
- Çok kiracılı izolasyon: Token yalnız kendi kiracısının tanımlı ETA veritabanlarını açar;
etaDbbu listeden olmalıdır. Başka firmanın verisi hiçbir koşulda dönmez. - IP beyaz listesi: Kiracıya IP tanımlıysa, listede olmayan adresten gelen istek
403alır. Liste boşsa kısıt uygulanmaz. - Token süresi: JWT, yapılandırılan süre kadar geçerlidir (öntanımlı 8 saat). Süre dolunca yeniden token alınır.
- Ham ETA verisi: Cari alanları ETA kolon adlarının küçük harfli halidir (
CARKOD → carkod) ve değerler ham döner: boş tarihler1900-01-01, metinlerde dolgu boşlukları. Karşılaştırmadan önce istemci kenditrim'ini uygular. - Delta yok: Cari kartta güncelleme damgası tutulmadığı için “değişenleri ver” desteklenmez; senkron eden istemci katalogu sayfalayarak tam çeker. Bir taramada görülmeyen kayıt silinmiş sayılmamalıdır.
- Sayfalama:
takeen fazla 500 (öntanımlı 100). OFFSET tabanlıdır; sayfalama sürerken araya kayıt eklenirse bir kayıt iki sayfa arasına düşebilir. - Hata biçimi: Hatalar
application/problem+json(ProblemDetails) olarak döner. Kimlik hataları tek tip yanıt verir — hangi alanın yanlış olduğu sızdırılmaz. - Sözleşme takibi:
/swagger/v1/swagger.jsonbelgesi uygulamanın kendi uç tanımlarından çalışma zamanında üretilir; elle güncellenen bir kopya yoktur. Sürüm yükseltmelerinde değişiklikleri buradan izleyebilir, istemci modellerinizi (NSwag, openapi-generator vb.) doğrudan bu adresten üretebilirsiniz.