# Solk Bağlantı Ajanı

> ETA, Zirve, Akınsoft Wolvox ve SQL Server / Firebird kullanan diğer masaüstü programların veritabanını okuyup cari, bakiye, fatura, ürün ve stok bilgisini Solk'a gönderen Windows programı — kurulum, komutlar, tablo keşfi, kendi sorgularınız, güvenlik.

Masaüstü muhasebe programlarının internete açık bir servisi yoktur; veri şirketteki bir bilgisayarın veritabanındadır. **Solk Bağlantı Ajanı** (`SolkAjan.exe`) o veritabanına erişebilen bir Windows bilgisayarda çalışır, veritabanını **yalnız okur** ve verileri [Solk ERP API](/guides/erp#api) ile gönderir. Programa hiçbir şey yazmaz: yalnız `SELECT` çalışır, SQL Server'da kilit koymadan okur (*READ UNCOMMITTED*), Firebird'de salt okunur işlem açar.

| Program | Veritabanı | Önce denenen tablolar |
|---|---|---|
| **ETA** (ETA:SQL · ETA:V8) | SQL Server | `CARKART` · `CARHAR` · `FATFIS` · `STKKART` |
| **Zirve** | SQL Server | `CARI` · `CARI_HAREKET` · `FATURA` · `STOK` |
| **Akınsoft Wolvox** | Firebird (`WOLVOX.FDB`) | `CARI` · `CARIHR` · `FATURA` · `STOK` (`BLKODU` bağlarıyla) |
| Diğer | SQL Server ya da Firebird | tablo keşfi ya da [kendi sorgularınız](#queries) |

:::warning
Bağlantı **beta**'dır. Tablo ve sütun adları sürüme göre değişebilir; ajan önce [keşif](#discovery) yapar ve `dene` komutu ne bulduğunu gösterir. İlk kurulumda çıktıyı kontrol edin, gerekirse [Solk desteğine](/guides/support) `SolkAjan.exe tablolar` çıktısıyla yazın.
:::

## Kurulum {#setup}

:::steps
### Bağlantıyı oluşturun
**Ayarlar → Muhasebe ve ERP → Bağlantı ekle** altında **ETA**, **Zirve** ya da **Akınsoft Wolvox** → **Bağlantıyı ve ajan dosyasını hazırla**. Açılan sayfada **solk_ajan.json indir** — dosya bağlantının API anahtarını içerir ve **yalnız o an** indirilebilir (kaybolursa **Yeni anahtar ve dosya**).

### Ajanı indirin
[SolkAjan.zip](https://solk.app/indir/SolkAjan.zip)'i veritabanına erişebilen bir Windows 10 / 11 ya da Windows Server bilgisayara indirip bir klasöre çıkarın (ör. `C:\SolkAjan`). `solk_ajan.json`'u `SolkAjan.exe`'nin yanına koyun.

### Veritabanını yazın
`solk_ajan.json`'daki `db` bölümü:
- **ETA / Zirve:** `server` = SQL Server örneği (ör. `SUNUCU\ETA`), `database` = şirket veritabanı. Windows oturumuyla `"trusted": true`; SQL kullanıcısıyla `user` / `password` ve `"trusted": false`. Bilgisayarda SQL Server ODBC sürücüsü yoksa Microsoft'un *ODBC Driver 18 for SQL Server*'ını kurun.
- **Akınsoft Wolvox:** `database` = `WOLVOX.FDB` yolu, `user` / `password` = Firebird kullanıcısı. Veritabanı başka bilgisayardaysa `server` = o bilgisayarın adı; `fbclient.dll` standart yerde değilse yolunu `fbclient`'a yazın.

### Deneyin
`SolkAjan.exe dene` — Solk bağlantısını, veritabanını ve her liste için bulunan tabloyu, kurulan sorguyu ve örnek kayıtları gösterir. Hiçbir şey göndermez.

### Gönderin ve zamanlayın
`SolkAjan.exe calis` hemen gönderir; `SolkAjan.exe kur` Windows Görev Zamanlayıcı'ya 30 dakikada bir çalışan görevi ekler (`--dakika 15` ile değişir). Windows oturumuyla bağlanıyorsanız görev yalnız oturum açıkken çalışır; sürekli çalışsın isterseniz SQL kullanıcısı yazıp `kur --sistem` kullanın.
:::

Gönderim bitince bağlantı sayfasında **Son veri** güncellenir, cariler [eşleştirmeye](/guides/erp#matching) düşer; firma kartında bakiye ve faturalar görünür.

## Komutlar {#commands}

| Komut | Ne yapar |
|---|---|
| `dene` | Solk + veritabanı bağlantısı, bulunan tablolar, sorgular, örnek kayıtlar (gönderim yok) |
| `tablolar [ad]` | Tabloları listeler; ad verilirse eşleşen tabloların bütün sütunlarını |
| `calis [--kuru]` | Okur ve gönderir (`--kuru`: okur, sayar, göndermez) |
| `kur [--dakika N] [--sistem]` | Zamanlanmış görev ekler |
| `kaldir` | Zamanlanmış görevi siler |
| `surum` | Sürüm |

Her çalıştırma `solk_ajan.log`'a yazılır; aynı anda iki çalıştırma olmaz.

## Keşif {#discovery}

Ajan veritabanındaki tablolar arasından her liste için gereken sütunları taşıyan tabloyu seçer — program için bilinen tablo adları önce denenir, yedek / arşiv tabloları geri planda kalır:

| Liste | Gereken | İsteğe bağlı |
|---|---|---|
| Cariler | cari kodu, unvan | vergi no / dairesi, il, telefon, e-posta, döviz, bakiye, risk limiti |
| Bakiyeler | cari hareketlerinde cari (kod ya da bağ), borç, alacak | — (bakiye = borç − alacak) |
| Faturalar | fatura no, cari, tarih, tutar | vade, ara toplam, kalan, döviz, tür — son `invoice_days` gün (varsayılan 365) |
| Ürünler | stok kodu, ad | birim, satış fiyatı, döviz |
| Stok | stok kodu (ya da bağ), miktar | depo |

Sütun adları Türkçe ya da programın kendi adlarıyla tanınır (*CARIKODU*, *TICARI_UNVANI*, *CARKOD*, *FATFISGENTOPLAM*, *STOK_ADI* …). Wolvox'taki gibi kayıtların numara (`BLKODU`) ile bağlandığı yapılarda ajan cari ve stok kodlarını birleştirmeyle alır.

## Kendi sorgularınız {#queries}

Keşif yanlış tabloyu seçerse zorlayın:

```json
"tablolar": {"customers": "CARI", "invoices": "FATURA", "stock": "STOK_DEPO"}
```

Ya da sorguyu kendiniz yazın — sütun takma adları (`AS`) Solk alanlarıdır, faturalarda `?` başlangıç tarihidir:

```json
"sorgular": {
  "customers": "SELECT CARIKODU AS code, TICARI_UNVANI AS name, VERGI_NUMARASI AS tax_no, ILI AS city FROM CARI",
  "balances":  "SELECT c.CARIKODU AS code, SUM(h.BORC) - SUM(h.ALACAK) AS balance FROM CARIHR h JOIN CARI c ON c.BLKODU = h.BLCRKODU GROUP BY c.CARIKODU",
  "invoices":  "SELECT f.FATURA_NO AS no, c.CARIKODU AS customer, f.TARIHI AS date, f.GENEL_TOPLAM AS total FROM FATURA f JOIN CARI c ON c.BLKODU = f.BLCRKODU WHERE f.TARIHI >= ?",
  "stock":     "SELECT s.STOKKODU AS code, d.DEPO_ADI AS wh, d.MIKTARI AS qty FROM STOK_DEPO d JOIN STOK s ON s.BLKODU = d.BLSTKODU"
}
```

Yalnız satış faturaları için keşifle kurulan sorguya koşul ekleyin: `"filtreler": {"invoices": "FATURA_TURU = 'SATIS'"}`. Bir listeyi kapatmak için `"sets": {"stock": false}`. Sorgular yalnız tek bir `SELECT` olabilir; yazma ya da yürütme komutu içeren sorgu çalıştırılmaz.

| Liste | Solk alanları (* gerekli) |
|---|---|
| customers | `code`*, `name`*, `tax_no`, `tax_office`, `city`, `phone`, `email`, `currency`, `balance`, `credit_limit` |
| balances | `code`*, `balance` (pozitif = müşteri borçlu) |
| invoices | `no`*, `customer`* (cari kodu), `date`*, `total`*, `due`, `net`, `remaining`, `currency`, `kind`, `ext_id` |
| products | `code`*, `name`*, `unit`, `price`, `currency` |
| stock | `code`*, `qty`*, `wh` (satır başına bir depo) |

## Güvenlik {#security}

- `solk_ajan.json` API anahtarı içerir; yalnız ajanın çalıştığı bilgisayarda tutun. Anahtar sızarsa bağlantı sayfasında **Yeni anahtar ve dosya** — eski anahtar hemen geçersiz olur.
- Anahtar yalnız bu bağlantıya veri gönderebilir; Solk'taki başka hiçbir şeye erişemez.
- Veritabanı kullanıcısına yalnız okuma yetkisi yeter (SQL Server'da `db_datareader`).
- Ajan dışarıya yalnız Solk adresinize (HTTPS 443) bağlanır; veritabanı internete açılmaz.