joi-ulupinar-api // kontrol düzlemi

ETA · REST API

ETA verinize güvenli, kiracı bazlı erişim

Firmaların ETA muhasebe sistemindeki cari kartlarına ve firma (veritabanı) listesine; token tabanlı, IP kısıtlı ve her kiracının yalnız kendi verisini gördüğü bir REST API üzerinden ulaşın.

Üç adımda kullanım

Akış sıralıdır: önce kimlik bilgisi tanımlanır, sonra token alınır, en son veri çekilir.

01

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.

02

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.

03

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.

MetotUçErişimAçı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.

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ış

1 · Token iste
POST /api/auth/token
Content-Type: application/json

{
  "kullaniciAdi": "delta",
  "sifre": "***",
  "apiKey": "e5174e75e807c8bfe…"
}
Yanıt
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6…",
  "gecerlilikBitis": "2026-07-27T20:00:00Z"
}
2 · Erişilebilir firmalar
GET /api/v1/firmalar
Authorization: Bearer eyJhbGciOiJ…

→ [ { "etaDb": "ETA_IZYAPIAS_2026", "gorunenAd": "İZYAPI 2026" } ]
3 · Cari kartlar (120 ile başlayan, aktif, ilk 100)
GET /api/v1/cariler?etaDb=ETA_IZYAPIAS_2026&kodOnek=120&aktif=true&take=100
Authorization: Bearer eyJhbGciOiJ…

Kurallar & sınırlar

JOI_ULUPINAR.API · ETA REST API · 2026