> For the complete documentation index, see [llms.txt](https://docs.iyzico.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iyzico.com/platformlar/woocommerce/iyzico-kolai-icin-woocommerce-entegrasyonu.md).

# iyzico kolai için WooCommerce Entegrasyonu

kolai, iyzico uygulaması içinde yer alan yapay zeka destekli alışveriş asistanıdır. Kullanıcılar kolai ile sohbet ederek ürün önerisi alır ve önerilen ürünleri doğrudan iyzico uygulaması üzerinden satın alabilir. Bu doküman, WooCommerce mağazanızı kolai’ye bağlamak için iyzico panelinde ve WordPress’te yapılması gereken adımları anlatır.

Entegrasyon iki ayrı aşamadan oluşur:

1\. **iyzico Panelinde Ön Hazırlık** — ürünlerin kolai’ye XML ile tanıtılması ve kolai API anahtarlarının üretilmesi.

2\. **WordPress Tarafında Eklenti Kurulumu** — iyzico kolai for WooCommerce eklentisinin kurulup yapılandırılması.

Adımlar sırayla takip edilmelidir; ikinci aşama, birinci aşama tamamlanmadan başlatılamaz.

### 1. iyzico Panelinde Ön Hazırlık

#### 1.1 Ürün XML ’inizi Yükleyin

kolai'nin ürünlerinizi önerebilmesi için önce mağazanızdaki ürünlerin iyzico'ya XML üzerinden tanıtılması gerekir.

iyzico Merchant Panel'de **Ayarlar > Firma Ayarları > Firma Ayarları** sekmesine gidin ve **"XML ile Ürünlerinizi Yükleyin"** bölümünü bulun.

<figure><img src="https://1970365243-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkTpM8Bc8GIRKlQDusDr3%2Fuploads%2FUINtyitcL5PeCQVfzLOl%2FEkran%20Resmi%202026-08-28%2014.38.47.png?alt=media&amp;token=2b0fe085-53bc-439b-bc7d-16a33059f84f" alt=""><figcaption></figcaption></figure>

* **XML Linki** alanına, mağazanızdaki ürünleri listeleyen XML linkini girin. XML formatı Google Merchant Center standardına uygun olmalıdır; detaylı bilgi için Google Merchant Center sayfasına bakabilirsiniz.

*Örnek bir ürün için kullanmanız gereken XML formatını aşağıda bulabilirsiniz:*

```xml
<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:g="http://base.google.com/ns/1.0" version="2.0">
<channel>
<item>
<g:id>847362</g:id>
<g:title>Uzun Süre Kalıcı &amp; Mat Bitişli Kalem Ruj Seti</g:title>
<g:description>Uzun süre kalıcı ve mat bitişli kalem ruj setini inceleyebilir, avantajlı fiyatlarla satın alabilirsiniz.</g:description>
<g:google_product_category>Anasayfa &gt; Makyaj &gt; Dudak Makyajı &gt; Ruj</g:google_product_category>
<g:product_type>Anasayfa&gt;Makyaj&gt;Dudak Makyajı&gt;Ruj</g:product_type>
<g:link>https://www.example.com/847362918273645</g:link>
<g:image_link>https://images.unsplash.com/photo-1586495777744-4413f21062fa</g:image_link>
<g:condition>new</g:condition>
<g:availability>in stock</g:availability>
<g:identifier_exists>yes</g:identifier_exists>
<g:mpn>84736291-001</g:mpn>
<g:brand>Example</g:brand>
<g:price>2329.99 TRY</g:price>
<g:sale_price>1249.99 TRY</g:sale_price>
<g:additional_image_link>https://images.unsplash.com/photo-1596462502278-27bfdc403348</g:additional_image_link>
<g:shipping>
<g:price>105.00</g:price>
</g:shipping>
</item>
</channel>
</rss>
```

* **Güncelleme Aralığı** olarak Saatlik, Günlük veya Haftalık seçeneklerinden birini belirleyin. Bu, ürün listenizin ne sıklıkla yenileneceğini belirler.
* **Kaydet** butonuna basın.

> **Önemli:** XML linki iyzico tarafından değerlendirilip onaylanmadan kolai ile ürün satışı özelliği aktif edilemez. XML'inizin production ortamda aktif ve onaylı olduğundan emin olun.

#### 1.2 kolai ile Ürün Satışını Aktif Edin

XML onayı tamamlandıktan sonra aynı sayfada (Ayarlar > Firma Ayarları) yer alan **"kolai ile Ürün Satışı"** bölümüne dönün.

XML onaylanmadan önce bu bölüm pasif görünür.

<figure><img src="https://1970365243-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkTpM8Bc8GIRKlQDusDr3%2Fuploads%2FmRK4tzbRFYLmZ4QPIdoi%2FEkran%20Resmi%202026-08-28%2014.45.39.png?alt=media&amp;token=0d3c4b70-8cbb-4723-b9b8-2d93dd22470c" alt=""><figcaption></figcaption></figure>

XML onaylandıktan sonra:

1. **"kolai üzerinden ürünlerimi satışa açmak istiyorum"** anahtarını aktif edin.
2. **API Base URL** alanına mağazanızın domain adresini girin (örn. `websitenizinadi.com`).
3. **Altyapı Sağlayıcı** olarak **WooCommerce** seçin.
4. **Kaydet** butonuna basın.

<figure><img src="https://1970365243-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkTpM8Bc8GIRKlQDusDr3%2Fuploads%2FJrHcpAfd5gUtuFMystWv%2FEkran%20Resmi%202026-08-28%2014.46.11.png?alt=media&amp;token=6fa35182-2763-4fb4-9441-6c9a1f8a4996" alt=""><figcaption></figcaption></figure>

#### 1.3 kolai API Anahtarlarını Alın

Yukarıdaki adım kaydedildikten sonra sayfada **"kolai API Anahtarları"** bölümü görünür hale gelir.

<figure><img src="https://1970365243-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkTpM8Bc8GIRKlQDusDr3%2Fuploads%2FVD3ETxnRZZBAJALG3lbO%2F3.png?alt=media&amp;token=0c7ade48-d636-4334-98bc-8b0a5e92ec25" alt=""><figcaption></figcaption></figure>

* **API Anahtarı** ve **Güvenlik Anahtarı** burada listelenir; göz ikonuna tıklayarak değerleri görüntüleyebilirsiniz.
* Anahtarları yenilemek isterseniz **"Yeniden Oluştur"** butonunu kullanabilirsiniz.

Bu üç adım tamamlandığında panel tarafındaki hazırlık bitmiş olur ve WordPress eklentisinin kurulumuna geçilebilir.

### 2. WordPress Tarafında Eklenti Kurulumu

Bu aşamada `iyzico kolai for WooCommerce` eklentisi kurulur ve panelden alınan bilgilerle yapılandırılır. Eklentiye [bu adres](https://github.com/iyzico/iyzipay-kolai-for-woocommerce) üzerinden ulaşabilirsiniz.

#### 2.1 Ön Koşullar

| Gereksinim                     | Minimum                       | Not                                                          |
| ------------------------------ | ----------------------------- | ------------------------------------------------------------ |
| WordPress                      | 5.0+ (6.9 ile test edildi)    |                                                              |
| WooCommerce                    | 5.0+ (10.9.1 ile test edildi) | **Aktif** olmalı; değilse eklenti kendini devre dışı bırakır |
| PHP                            | 7.2+                          | 8.1+ önerilir                                                |
| HTTPS                          | Zorunlu                       | kolai yalnızca `https://` uçlara istek atar                  |
| Kalıcı Bağlantılar (Permalink) | "Sade" **olmamalı**           | Aşağıda detaylandırılmıştır                                  |

**Permalink ayarı — atlanırsa imza doğrulaması çalışmaz:** **Ayarlar → Kalıcı Bağlantılar** ekranında "Sade / Plain" dışında bir seçenek (örn. "Yazı adı") seçili olmalıdır. kolai imzası isteğin URL path'i üzerinden hesaplanır (`/wp-json/kolai/v1/products`). Permalink "Sade" ise REST çağrısı `?rest_route=...` biçiminde gider, path `/index.php` olur ve **tüm istekler `Invalid signature` hatasıyla 401 döner.**

**Google Merchant XML:** 1.1 adımında yüklediğiniz XML'in onaylanmış olması gerekir; onaylanmadan kolai ürün eşleştirmesi başlatılamaz.

#### 2.2 Eklentiyi Kurun

**WP Admin üzerinden:**

1. `iyzipay-kolai-for-woocommerce` eklentisi için GitHub'dan indirilen ZIP'i indirin.
2. **Eklentiler → Yeni Ekle → Eklenti Yükle** → ZIP dosyasını seçin → **Şimdi Kur**.
3. **Etkinleştir**.

> Etkinleştirme sırasında WooCommerce aktif değilse eklenti kendini kapatır ve "kolai plugin'i WooCommerce gerektirir" uyarısı verir.

**Doğrulama:** Sol menüde **kolai** görünmeli, altında Sözleşmeler, "Meta Eşleşme, Loglar" alt menüleri olmalı.

<figure><img src="https://1970365243-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkTpM8Bc8GIRKlQDusDr3%2Fuploads%2FGV5qypBVrJvHakXikeVT%2Fimage.png?alt=media&amp;token=158fec67-89ef-4995-bbbe-752fecefc868" alt=""><figcaption></figcaption></figure>

Eklenti kurulumundan sonra artık bu adımda, hesap bilgileriniz ile eklentiyi yapılandırabilirsiniz.

#### 2.3 WP Admin → kolai → Ayarlar

<figure><img src="https://1970365243-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkTpM8Bc8GIRKlQDusDr3%2Fuploads%2F3Kn59CJoAtEsVMFhKDJR%2Fimage.png?alt=media&amp;token=b8f26a98-b7dc-4ddc-ab4d-cb8417319495" alt=""><figcaption></figcaption></figure>

**API Ayarları**

| Alan                         | Açıklama                                                                                                                    |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **API Key**                  | iyzico panelinde 1.3 adımında aldığınız kolai API Key                                                                       |
| **Secret Key**               | iyzico panelinde 1.3 adımında aldığınız kolai Secret Key. Maskeli alandır: boş bırakırsanız kayıtlı değer korunur, silinmez |
| **Aydınlatma Metni Sayfası** | Yayınlanmış WordPress sayfalarından seçilir; `GET /contracts/clarification-text` bu sayfanın içeriğini döner                |

> API Key veya Secret Key boşsa eklenti **fail-closed** çalışır: tüm kolai istekleri `Server credentials not configured` hatasıyla 401 döner.

**iyzico İade / İptal Ayarları** — WooCommerce paneli üzerinden iade/iptal yapılacaksa doldurulmalıdır.

| Alan                  | Açıklama                                           |
| --------------------- | -------------------------------------------------- |
| **iyzico API Key**    | iyzico Merchant Panel API anahtarı                 |
| **iyzico Secret Key** | Maskeli alan; boş bırakılırsa mevcut değer korunur |
| **iyzico Ortam**      | Test için `Sandbox`, canlı için **`Production`**   |

Bu bilgiler girilmezse sipariş oluşturma çalışır, ancak WooCommerce'ten yapılan iade/iptal iyzico'ya iletilmez.

**Kargo Yöntemleri (iyzico)** — WooCommerce kargo bölgelerinizdeki aktif yöntemler listelenir. İşaretini kaldırdığınız yöntem yalnızca `/shipment-options` ucundan gizlenir; normal WooCommerce ödeme akışı etkilenmez. Varsayılan: hepsi açık.

Tüm alanları doldurduktan sonra **Ayarları Kaydet** deyin.

#### 2.4 WP Admin → kolai → Sözleşmeler

Bu ekrandaki değerler sözleşme şablonlarındaki yer tutucuları otomatik doldurur.

**Satıcı Bilgileri** (hepsi zorunlu):

* Satıcı Adı / Unvanı, Adresi, Telefonu, E-posta Adresi
* **Vergi Kimlik Numarası (VKN)**
* **MERSİS Numarası**

**Teslimat ve Cayma Hakkı:**

* Tahmini Teslim Tarihi (örn. "3 iş günü")
* Cayma Hakkı Süresi (örn. "14 gün")

**Sözleşme metinleri:** Mesafeli Satış Sözleşmesi ve Ön Bilgilendirme Formu varsayılan metinlerle gelir. Hukuk biriminizle kontrol edip gerekirse düzenleyin; düzenlemiyorsanız varsayılanları kabul edip kaydetmeniz yeterlidir.

**Sözleşmeleri Kaydet** deyin.

#### 2.5 Meta Alan Eşleşme (Opsiyonel)

**kolai → Meta Eşleşme** ekranı, siparişe yazılan meta anahtar adlarını özelleştirmenizi sağlar (fatura tipi, TCKN/VKN, vergi dairesi, iyzico Payment ID, taksit sayısı, vade farkı vb.). Fatura/muhasebe eklentileriniz farklı anahtar adları bekliyorsa burada eşleyin. Ayrıca `personal` / `company` fatura tipi değerlerini kendi eklentinizin beklediği değerlere çevirebilirsiniz.

> Anahtar adını değiştirmek yalnızca **bundan sonraki** siparişleri etkiler.

#### 2.6 Kurulumu Doğrulayın

**REST route ayakta mı?**

Terminalden imzasız bir istek atın: curl -i [https://websitenizinadi.com/wp-json/kolai/v1/products](https://alanadiniz.com/wp-json/kolai/v1/products)

**Beklenen:** HTTP `401` ve şu gövde:

```json
{
  "status": "failure",
  "errorCode": "1005",
  "errorMessage": "Missing or invalid authorization header"
}
```

Bu yanıt "her şey doğru" demektir: route kayıtlı, permalink doğru, kimlik doğrulama devrede.

| Aldığınız yanıt | Anlamı                                            |
| --------------- | ------------------------------------------------- |
| `401` + `1005`  | ✅ Doğru                                           |
| `404`           | Permalink sade kalmış ya da eklenti aktif değil   |
| `200` + veri    | ⛔ Kimlik doğrulama devre dışı,iyzico'ya bildirin. |
| `1004`          | WooCommerce aktif değil                           |

**Uçtan uca test:**

1. **kolai → Loglar** ekranında "Log Tutmayı Etkinleştir" kutusunu işaretleyin, seviye `debug`, saklama süresi 7 gün → kaydedin.
2. kolai tarafından ürün listeleme / kargo seçenekleri / test siparişi tetikleyin.
3. Log tablosunda `auth` ve istek kayıtlarını kontrol edin (kişisel veriler maskelenir).
4. Devreye alma bittikten sonra **logları kapatın** — sürekli açık kalması gerekmez.

Kontrol edilecekler:

* Ürünler doğru fiyat ve KDV dökümüyle geliyor mu?
* Kargo seçenekleri doğru bölge/ücretle dönüyor mu?
* Test siparişi WooCommerce'te oluşuyor, adres (il/ilçe) doğru doluyor mu?
* Sipariş toplamı iyzico `paidPrice` ile birebir eşleşiyor mu (taksitli işlemde "Vade Farkı" satırı)?
* WooCommerce'ten kısmi iade yapıldığında iyzico'ya iletiliyor mu?

***

### 3. Canlıya Alma Checklist

**A. iyzico Merchant Panel**

* [ ] XML alanında production XML aktif
* [ ] Google Merchant XML girilmiş ve onaylanmış
* [ ] kolai ile Ürün Satışı özelliği aktif
* [ ] kolai API Base URL tanımlı (domain adresiniz)
* [ ] Altyapı sağlayıcısı seçimi tanımlı (WooCommerce)
* [ ] kolai API Key tanımlı
* [ ] kolai Secret Key tanımlı

**B. WordPress / WooCommerce**

* [ ] WooCommerce kurulu ve aktif
* [ ] Site HTTPS üzerinden yayında
* [ ] Kalıcı bağlantılar "Sade" değil
* [ ] Eklenti etkinleştirildi, sol menüde "kolai" göründü

**C. kolai → Ayarlar**

* [ ] API Key girildi (platformdaki değerle birebir)
* [ ] Secret Key girildi (platformdaki değerle birebir)
* [ ] Aydınlatma Metni sayfası seçildi (sayfa yayında)
* [ ] iyzico API Key girildi
* [ ] iyzico Secret Key girildi
* [ ] iyzico Ortam = Production (canlı için)
* [ ] Kargo yöntemleri gözden geçirildi

> iyzico anahtarları yalnızca WooCommerce paneli üzerinden iade/iptal yapılacaksa zorunludur; yapılacaksa mutlaka doldurun.

**D. kolai → Sözleşmeler**

* [ ] Satıcı adı / unvanı, adresi, telefonu, e-postası girildi
* [ ] VKN girildi
* [ ] MERSİS numarası girildi
* [ ] Tahmini teslim tarihi girildi
* [ ] Cayma hakkı süresi girildi
* [ ] Mesafeli satış sözleşmesi metni kontrol edildi (veya varsayılan kabul edildi)
* [ ] Ön bilgilendirme formu metni kontrol edildi (veya varsayılan kabul edildi)

**E. Doğrulama**

* [ ] `curl https://websitenizinadi.com/wp-json/kolai/v1/products` → `401` + `1005`
* [ ] kolai'den ürün listeleme başarılı
* [ ] Kargo seçenekleri doğru dönüyor
* [ ] Test siparişi WooCommerce'te oluştu, adres ve toplam doğru
* [ ] Test iadesi iyzico'ya iletildi
* [ ] Devreye alma sonrası loglar kapatıldı

***

### 4. Canlıya Alma Talebi

Yukarıdaki tüm maddeler tamamlandığında **<entegrasyon@iyzico.com>** adresine canlıya alınabilir bilgisini gönderin.

**Örnek e-posta:**

> **Konu:** kolai canlıya alma talebi — \[Mağaza Adı] / \[Merchant ID]
>
> Merhaba,
>
> kolai WooCommerce entegrasyonu için gerekli tüm adımları tamamladık:
>
> * Merchant Panel: production XML aktif, Google Merchant XML onaylı, kolai ile Ürün Satışı aktif, Base URL + altyapı sağlayıcısı + API/Secret Key tanımlı.
> * WordPress: iyzico kolai for WooCommerce eklentisi kurulu ve aktif; kolai API anahtarları, aydınlatma metni sayfası, iyzico iade/iptal anahtarları (ortam: production) ve sözleşme bilgileri (VKN/MERSİS, teslimat ve cayma hakkı süreleri dahil) girildi.
> * Doğrulama: `/wp-json/kolai/v1` uçları imza doğrulamasıyla yanıt veriyor; test ürün listeleme, kargo seçenekleri, sipariş ve iade akışları başarılı.
>
> Mağaza URL: \[alanadiniz.com] Merchant ID: \[...]
>
> Canlıya alınabilir. Teşekkürler.

***

### 5. Sorun Giderme

| Belirti                                    | Olası neden                                  | Çözüm                                                 |
| ------------------------------------------ | -------------------------------------------- | ----------------------------------------------------- |
| Tüm istekler `Invalid signature`           | Permalink "Sade"                             | Kalıcı bağlantıları değiştirin                        |
| `Server credentials not configured`        | API Key veya Secret Key boş                  | kolai → Ayarlar'dan girin                             |
| `Invalid client credentials`               | API Key platformdakiyle uyuşmuyor            | Değeri birebir kopyalayın                             |
| `Replayed request rejected`                | Aynı istek aynı `salt` ile tekrar gönderildi | Normal koruma; istemci her istekte yeni salt üretmeli |
| `Request timestamp outside allowed window` | Sunucu saati kaymış                          | NTP ile saati senkronlayın (±300 sn)                  |
| `1004 WooCommerce inactive`                | WooCommerce devre dışı                       | WooCommerce'i etkinleştirin                           |
| Sipariş `city` alanı boş                   | Eski eklenti sürümü                          | Eklentiyi güncelleyin                                 |
| Sipariş toplamı taksitte tutmuyor          | Eski eklenti sürümü                          | Eklentiyi güncelleyin                                 |
| Loglar boş                                 | Log tutma kapalı                             | kolai → Loglar → "Log Tutmayı Etkinleştir"            |

Detaylı teknik dokümantasyon için eklenti reposundaki README.md ve ilgili AUTH.md / PRODUCT.md / ORDER.md / SHIPPING.md / CONTRACT.md / REFUND.md / LOGS.md dosyalarına bakabilirsiniz.

### 6. Eklenti İndirme Linki

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-kolai-for-woocommerce/archive/refs/heads/master.zip">kolai for WooCommerce</a></td></tr></tbody></table>