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

Üç adımda kullanım

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

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.

/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.

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.

/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 veritabanı düzeyinde benzersizdir; aynı değerle ikinci bir istek 409 FIS_ZATEN_KAYITLI ile reddedilir ve hata detayında mevcut kaydın masterSatirId'si bildirilir. Yani zaman aşımına uğrayan bir istek güvenle yeniden denenebilir.

Ö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.

⚠ 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.

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ı, ETA veritabanınızda database/04_rf_fis_yazma.sql betiğiyle kurulan filtreli benzersiz indekse dayanır. Betik çalıştırılmadan uç çalışır ama aynı fiş ikinci kez yazılabilir. 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; etaDb bu 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 403 alı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ş tarihler 1900-01-01, metinlerde dolgu boşlukları. Karşılaştırmadan önce istemci kendi trim'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: take en 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.json belgesi 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.