=== Futurecode Muhasebe Köprüsü for WooCommerce ===
Contributors: futurecodetr
Tags: e-arşiv, e-fatura, invoice, accounting, woocommerce
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Requires Plugins: woocommerce
Stable tag: 1.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Send WooCommerce orders to Paraşüt or Uyumsoft for e-Arşiv / e-Fatura: checkout invoice fields with TCKN / VKN check, KDV mapping, retry queue, log.

== Description ==

**English**

Muhasebe Köprüsü ("accounting bridge") passes your WooCommerce orders to the e-invoice provider you already use, so the e-Arşiv or e-Fatura is issued without typing the order again.

**Important — what the plugin is and is not**

* In Türkiye, e-Fatura and e-Arşiv invoices are issued **only through an integrator licensed by the Revenue Administration (GİB)**. This plugin is **not** an integrator and **does not issue invoices**. It sends the order data to your own Paraşüt or Uyumsoft account; the provider issues, signs and reports the invoice.
* The plugin is **not tax advice**. Which KDV rate, exemption code, series or cancellation is right for your business is a question for your accountant (mali müşavir).
* Nothing is sent before you enter your own account details and switch invoicing on.

**Features**

* **Providers:** Paraşüt (API v4, OAuth2) or Uyumsoft (e-Fatura / e-Arşiv web service). You enter your own API details; passwords, client secret and tokens are stored encrypted (AES-256-GCM with a key derived from your site's salts). "Test the connection" button, live / test environment.
* **Checkout fields (optional):** individual / company, T.C. identity number or tax number (VKN) with checksum validation, tax office and company name. Works with the classic checkout and the block checkout. Editable later in the order screen.
* **Invoicing:** automatic when an order reaches the status you choose, or by hand with "Create invoice" in the order, or with the bulk action "Invoice the selected orders".
* **What goes on the invoice:** customer details, every line with its KDV rate (WooCommerce tax class → KDV mapping: 1 %, 10 %, 20 %, 0 % with an exemption code), shipping, fees, coupons as line discounts, currency.
* **e-Fatura or e-Arşiv:** with a TCKN / VKN the provider is asked whether the buyer is an e-Fatura user; e-Fatura users get an e-Fatura, everybody else an e-Arşiv invoice with the internet-sale details.
* **Back in the order:** invoice number, ETTN and the PDF are written to the order with an order note; the customer gets an e-mail with the invoice link and sees the invoice in "My account".
* **Cancellations and refunds:** e-Arşiv invoices can be cancelled from the order (automatically on cancellation / full refund if you want) within the period your provider allows. Where the provider does not allow it (e-Fatura, partial refunds) the plugin says so clearly and adds an order note; it never issues return invoices on its own.
* **Queue:** Action Scheduler (bundled with WooCommerce) works in the background. Temporary errors are retried after 1, 5, 15, 60 minutes and 3 hours; wrong data stops with a clear message. Every step is logged; the log can be filtered and an order can be sent again with one click. An order is never invoiced twice, even when it is triggered twice.
* **Lists:** invoice status column in the order list, a queue screen with filters and search, CSV export of invoices.
* **Product mapping (Paraşüt):** WooCommerce products ↔ Paraşüt products, automatic by SKU or by hand, CSV export / import / template. Optional one-way stock sync from Paraşüt to WooCommerce.
* HPOS (high-performance order storage) and block checkout compatible. Every action shows a notification with a spinner.

**Coming soon (separate Pro plugin, not part of this one):** local agent for Logo and Zirve, e-İrsaliye (e-waybill) and customer (cari) sync. Nothing in this plugin is locked or limited by a licence.

**Türkçe**

Muhasebe Köprüsü, WooCommerce siparişlerinizi zaten kullandığınız e-fatura sağlayıcısına iletir; e-Arşiv ya da e-Fatura, siparişi yeniden yazmadan kesilir.

**Önemli — eklenti ne yapar, ne yapmaz**

* Türkiye'de e-Fatura ve e-Arşiv fatura **yalnız GİB lisanslı özel entegratör üzerinden** kesilir. Bu eklenti entegratör **değildir** ve **fatura kesmez**. Sipariş verisini kendi Paraşüt ya da Uyumsoft hesabınıza iletir; faturayı sağlayıcı keser, imzalar ve GİB'e bildirir.
* Eklenti **vergi danışmanlığı değildir**. Hangi KDV oranının, istisna kodunun, serinin ya da iptalin işletmenize uygun olduğunu mali müşavirinize sorun.
* Siz kendi hesap bilgilerinizi girip faturalamayı açmadan hiçbir veri gönderilmez.

**Özellikler**

* **Sağlayıcılar:** Paraşüt (API v4, OAuth2) ya da Uyumsoft (e-Fatura / e-Arşiv web servisi). API bilgilerinizi kendiniz girersiniz; parola, client secret ve token şifreli saklanır. "Bağlantıyı test et" düğmesi, canlı / test ortamı seçimi.
* **Ödeme sayfasında fatura alanları (isteğe bağlı):** bireysel / kurumsal, algoritmayla doğrulanan TCKN ya da VKN, vergi dairesi ve firma adı. Klasik ve blok ödeme sayfasıyla çalışır; sipariş ekranında sonradan düzenlenebilir.
* **Faturalama:** sipariş seçtiğiniz duruma gelince otomatik; ya da siparişteki "Fatura oluştur" düğmesiyle veya "Seçili siparişleri faturala" toplu işlemiyle.
* **Faturaya gidenler:** müşteri bilgileri, her satır kendi KDV oranıyla (WooCommerce vergi sınıfı → KDV eşleme: %1, %10, %20, istisna kodlu %0), kargo, ek ücretler, satır indirimi olarak kuponlar, para birimi.
* **e-Fatura mı e-Arşiv mi:** TCKN / VKN varsa sağlayıcıya alıcının e-Fatura mükellefi olup olmadığı sorulur; mükelleflere e-Fatura, diğerlerine internet satışı bilgileriyle e-Arşiv kesilir.
* **Siparişe dönenler:** fatura numarası, ETTN ve PDF siparişe yazılır, sipariş notu düşülür; müşteriye fatura bağlantılı e-posta gider, fatura "Hesabım"da görünür.
* **İptal ve iade:** e-Arşiv fatura, sağlayıcının izin verdiği süre içinde siparişten iptal edilebilir (isterseniz sipariş iptal ya da tam iade edilince otomatik). Sağlayıcının izin vermediği durumlarda (e-Fatura, kısmi iade) eklenti bunu açıkça yazar ve sipariş notu düşer; kendiliğinden iade faturası kesmez.
* **Kuyruk:** WooCommerce ile gelen Action Scheduler arka planda çalışır. Geçici hatalar 1, 5, 15, 60 dakika ve 3 saat sonra yeniden denenir; hatalı veri açık bir mesajla durur. Her adım kayda geçer; kayıtlar süzülebilir, sipariş tek tıkla yeniden gönderilir. Bir sipariş iki kez tetiklense de iki fatura kesilmez.
* **Listeler:** sipariş listesinde fatura durumu sütunu, süzgeçli ve aramalı kuyruk ekranı, faturaların CSV dışa aktarımı.
* **Ürün eşleme (Paraşüt):** WooCommerce ürünleri ↔ Paraşüt ürünleri, SKU ile otomatik ya da elle; CSV dışa / içe aktarım ve şablon. Paraşüt'ten WooCommerce'e tek yönlü, isteğe bağlı stok senkronu.
* HPOS ve blok ödeme sayfası uyumlu. Her eylemde dönen göstergeli bildirim.

**Yakında (ayrı Pro eklenti; bu eklentinin parçası değildir):** Logo ve Zirve için yerel ajan, e-İrsaliye ve cari senkronu. Bu eklentide hiçbir özellik lisansla kilitlenmez ya da sınırlanmaz.

== External services ==

The plugin connects to **one** provider, the one you choose on the *Connection* tab, and only after you have entered your own account details **and** switched on "Send orders to the provider". With invoicing off, nothing is sent, not even by the buttons. There is no tracking, no statistics and no connection to Futurecode.

**Paraşüt (Paraşüt API v4)** — https://api.parasut.com (or the test address you enter)

* Documentation: https://apidocs.parasut.com/ — Terms: https://www.parasut.com/kullanici-sozlesmesi — Privacy: https://www.parasut.com/kisisel-verilerin-korunmasi-ve-islenmesine-iliskin-aydinlatma-metni
* *Test the connection:* your client id, client secret, e-mail and password are sent to the token endpoint (/oauth/token); then your user and company list is read (/v4/me).
* *When an order is invoiced* (automatically at the status you chose, by the "Create invoice" button or the bulk action): customer name, e-mail, phone, billing address, TCKN / VKN and tax office (looked up, created when missing), the order lines (name, SKU as product code, quantity, net price, KDV rate, discount), shipping and fees, currency, order number and date, payment type and date, your shop address (for the e-Arşiv internet-sale details). With a TCKN / VKN, that number is sent to the e-Fatura user lookup. Then the e-document, its job status and its PDF are read.
* *Cancel* (button or, if switched on, order cancellation): the invoice id.
* *Product mapping / stock sync (optional):* SKUs are searched among your Paraşüt products; with stock sync on, the stock levels of mapped products are read. Nothing is written to Paraşüt by the stock sync.

**Uyumsoft (e-Fatura / e-Arşiv Integration web service)** — https://edonusumapi.uyum.com.tr/Services/Integration (live), https://efatura-test.uyumsoft.com.tr/Services/Integration (test), or the address you enter

* Service description: https://edonusumapi.uyum.com.tr/Services/Integration?wsdl — Company: https://www.uyumsoft.com/ — Privacy (KVKK): https://www.uyumsoft.com/kisisel-verilerin-korunmasi
* Every call carries your web service user name and password (WS-Security header).
* *Test the connection:* the TestConnection operation.
* *When an order is invoiced:* with a TCKN / VKN, that number is sent to IsEInvoiceUser / GetUserAliasses. Then a UBL-TR invoice with your company details (VKN, title, tax office, address), the customer details (name, TCKN / VKN, tax office, address, e-mail, phone), the order lines with KDV, shipping, fees, discounts, totals, order number and date, payment type and date and your shop address is sent with SendInvoice; the PDF is read with GetOutboxInvoicePdf. After a lost answer the invoice status is asked with QueryOutboxInvoiceStatus before anything is sent again.
* *Cancel:* the ETTN and the cancel date (CancelEArchiveInvoice).

The PDF of an invoice is downloaded once and kept in a protected folder of your site (wp-content/uploads/fcmk-faturalar), so customers never get a temporary provider link. Your provider's own terms and privacy policy apply to the data you send it; check that your privacy notice mentions the provider.

**Türkçe:** Eklenti yalnız *Bağlantı* sekmesinde seçtiğiniz sağlayıcıya (Paraşüt ya da Uyumsoft) bağlanır ve bunu da ancak kendi hesap bilgilerinizi girip "Siparişleri sağlayıcıya gönder" seçeneğini açtıktan sonra yapar. Bağlantı testinde giriş bilgileriniz; faturalamada müşteri bilgileri (ad, e-posta, telefon, adres, TCKN / VKN, vergi dairesi), sipariş kalemleri, KDV, kargo, indirim, sipariş no ve tarihi, ödeme tipi ve mağaza adresiniz; iptalde fatura kimliği gönderilir. Futurecode'a hiçbir veri gitmez, izleme ya da istatistik yoktur.

== Installation ==

1. Install and activate WooCommerce, then this plugin.
2. Open *Muhasebe Köprüsü → Connection*, choose Paraşüt or Uyumsoft and enter your own API details (Paraşüt gives the client id and secret on request; Uyumsoft gives the web service user). For Uyumsoft also enter your company details.
3. Click *Test the connection*. When it works, switch on *Send orders to the provider* and save.
4. On *Invoice rules* check the KDV mapping of your tax classes, the shipping KDV and when invoices should be created.
5. Try it with one order ("Create invoice" in the order screen), then switch on automatic invoicing.

**Türkçe:** WooCommerce'i ve eklentiyi etkinleştirin. *Muhasebe Köprüsü → Bağlantı* ekranında sağlayıcıyı seçip kendi API bilgilerinizi girin, *Bağlantıyı test et*'e tıklayın, başarılıysa *Siparişleri sağlayıcıya gönder*'i açıp kaydedin. *Fatura kuralları*nda KDV eşlemesini ve faturanın ne zaman kesileceğini ayarlayın. Önce bir siparişte "Fatura oluştur" ile deneyin.

== Frequently Asked Questions ==

= Bu eklenti fatura keser mi? / Does this plugin issue invoices? =

Hayır. e-Fatura ve e-Arşiv yalnız GİB lisanslı entegratör üzerinden kesilir. Eklenti sipariş verisini sizin Paraşüt ya da Uyumsoft hesabınıza iletir; faturayı onlar keser. / No. Only a GİB-licensed integrator issues e-Fatura and e-Arşiv invoices. The plugin sends the order data to your Paraşüt or Uyumsoft account; they issue the invoice.

= Vergi danışmanlığı veriyor mu? / Is this tax advice? =

Hayır. KDV oranları, istisna kodu, seri ve iptal kararları için mali müşavirinize danışın. / No. Ask your accountant about KDV rates, exemption codes, series and cancellations.

= Hangi bilgilerle bağlanırım? / What do I need to connect? =

Paraşüt: client id ve client secret (Paraşüt destek ekibi verir), Paraşüt kullanıcı e-postanız ve parolanız, firma numaranız (Paraşüt adresinizdeki sayı). Uyumsoft: web servis kullanıcı adı ve parolası ile e-fatura kaydınızdaki firma bilgileri. / Paraşüt: client id and secret (from Paraşüt support), your Paraşüt e-mail and password, your company number. Uyumsoft: web service user and password and your company details.

= Müşteri TCKN girmezse ne olur? / What if an individual gives no TCKN? =

Bireysel faturada TCKN girilmezse e-Arşiv faturada kimliği bilinmeyen tüketici için yaygın olarak kullanılan "11111111111" değeri gönderilir. Sağlayıcınızın ve mali müşavirinizin bu kullanımı onayladığından emin olun. / For an individual without a TCKN the e-Arşiv invoice carries the commonly used "11111111111" placeholder; confirm with your provider and accountant that this suits you.

= Aynı sipariş iki kez faturalanır mı? / Can an order be invoiced twice? =

Hayır. Sipariş kuyruktayken, sağlayıcıdayken ya da faturalanmışken yeniden kuyruğa alınmaz; işlem sipariş başına kilitlenir; sağlayıcıda oluşan her kayıt anında siparişe yazılır ve yeniden denemede kullanılır. Uyumsoft'ta yanıt kaybolursa önce ETTN ile sorgulanır. / No. The order is locked while it is processed, every remote id is stored at once and re-used by a retry, and after a lost Uyumsoft answer the invoice is looked up by its ETTN before anything is sent again.

= İade ve iptal nasıl çalışır? / How do cancellations and refunds work? =

e-Arşiv fatura, sağlayıcının izin verdiği süre içinde sipariş ekranındaki "İptal et" düğmesiyle (ya da ayarı açarsanız sipariş iptal / tam iade olunca otomatik) iptal edilir. e-Fatura iki sağlayıcının API'siyle de iptal edilemez: alıcı reddeder ya da iade faturası düzenler. Kısmi iadede eklenti belge kesmez, sipariş notu düşer. / e-Arşiv invoices can be cancelled within the provider's period; e-Fatura cannot be cancelled through the API; partial refunds get an order note only.

= KDV oranları nereden gelir? / Where do the KDV rates come from? =

*Fatura kuralları* sekmesinde her WooCommerce vergi sınıfına bir KDV oranı (%0, %1, %10, %20) atarsınız. Kargo ve ek ücretlerin KDV'si ayrıca seçilir. WooCommerce'te vergi kapalıysa fiyatlar KDV dahil sayılır (ayardan değiştirilebilir). / You map each WooCommerce tax class to a KDV rate on the *Invoice rules* tab.

= Kaldırınca ne silinir? / What does uninstalling remove? =

Ayarlar (şifreli bilgiler ve token dahil), kayıt tablosu, zamanlanmış görevler, ürün eşlemesi, sitede tutulan PDF kopyaları ve eklentinin sipariş alanları. Sipariş notları (fatura no ve ETTN) siparişlerde kalır; resmî faturalar sağlayıcınızda durur. / Settings, log, schedules, product mapping, local PDF copies and the plugin's order fields. Order notes with the invoice number and ETTN stay; the official invoices stay at your provider.

== Screenshots ==

1. Connection: provider choice, encrypted API details, live / test environment, connection test and status. / Bağlantı ekranı.
2. Queue and log: invoice counts, filterable invoice list with status, number, ETTN, PDF and "Send again", and the log. / Kuyruk ve kayıtlar.
3. Invoice box in the order: status, number, ETTN, PDF, cancel and the editable invoice details. / Siparişteki fatura kutusu.
4. Invoice rules: when to invoice, KDV mapping, numbering, customer and cancellation settings. / Fatura kuralları.
5. Product mapping with Paraşüt and stock sync. / Ürün eşleme ve stok senkronu.
6. Invoice fields on the block checkout with TCKN / VKN check. / Blok ödeme sayfasında fatura alanları.
7. Mobile view (390 px). / Mobil görünüm.

== Changelog ==

= 1.0.1 =
* Fix: with HPOS off (orders in the posts table) the status counts, "Issued today", the invoice list filters and the CSV export were wrong because WooCommerce ignored the meta query there. Both order stores are supported now.
* Düzeltme: HPOS kapalı mağazada (siparişler yazı tablosunda) durum sayıları, "Bugün kesilen", fatura listesi süzgeçleri ve CSV dışa aktarım yanlıştı; WooCommerce orada meta sorgusunu yok sayıyordu. Artık iki sipariş deposu da doğru çalışıyor.

= 1.0.0 =
* First release: Paraşüt API v4 (OAuth2 with refresh) and Uyumsoft (SOAP, UBL-TR) providers, encrypted credentials, connection test with live / test environment, checkout invoice fields for the classic and block checkout with TCKN / VKN validation, automatic / manual / bulk invoicing, KDV mapping per tax class, shipping, fees and discounts, e-Fatura user check, invoice number, ETTN and PDF on the order, customer e-mail and "My account", e-Arşiv cancellation, Action Scheduler queue with growing retry delays and duplicate protection, filterable log, invoice CSV export, Paraşüt product mapping with CSV and optional one-way stock sync, HPOS compatibility.

== Sources ==

* Paraşüt API v4: https://apidocs.parasut.com/ and https://apidocs.parasut.com/swagger.json
* Uyumsoft Integration service: https://edonusumapi.uyum.com.tr/Services/Integration?wsdl and https://efatura-test.uyumsoft.com.tr/Services/Integration?wsdl
* GİB UBL-TR 1.2.1 guides: https://ebelge.gib.gov.tr/dosyalar/kilavuzlar/UBLTR_1.2.1_Kilavuzlar.zip
