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.

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

XML onaylandıktan sonra:
"Kolai üzerinden ürünlerimi satışa açmak istiyorum" anahtarını aktif edin.
API Base URL alanına mağazanızın domain adresini girin (örn.
websitenizinadi.com).Altyapı Sağlayıcı olarak WooCommerce seçin.
Kaydet butonuna basın.

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.

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 üzerinden ulaşabilirsiniz.
2.1 Ön Koşullar
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:
iyzipay-kolai-for-woocommerceeklentisi için GitHub'dan indirilen ZIP'i indirin.Eklentiler → Yeni Ekle → Eklenti Yükle → ZIP dosyasını seçin → Şimdi Kur.
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ı.

Eklenti kurulumundan sonra artık bu adımda, hesap bilgileriniz ile eklentiyi yapılandırabilirsiniz.
2.3 WP Admin → Kolai → Ayarlar

API Ayarları
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 configuredhatasıyla 401 döner.
iyzico İade / İptal Ayarları — WooCommerce paneli üzerinden iade/iptal yapılacaksa doldurulmalıdır.
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://alanadiniz.com/wp-json/kolai/v1/products
Beklenen: HTTP 401 ve şu gövde:
Bu yanıt "her şey doğru" demektir: route kayıtlı, permalink doğru, kimlik doğrulama devrede.
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:
Kolai → Loglar ekranında "Log Tutmayı Etkinleştir" kutusunu işaretleyin, seviye
debug, saklama süresi 7 gün → kaydedin.Kolai tarafından ürün listeleme / kargo seçenekleri / test siparişi tetikleyin.
Log tablosunda
authve istek kayıtlarını kontrol edin (kişisel veriler maskelenir).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
paidPriceile 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
B. WordPress / WooCommerce
C. Kolai → Ayarlar
iyzico anahtarları yalnızca WooCommerce paneli üzerinden iade/iptal yapılacaksa zorunludur; yapılacaksa mutlaka doldurun.
D. Kolai → Sözleşmeler
E. Doğrulama
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/v1uç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
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
Last updated
