Ctrlk
GitHubFeedback FormAPI Reference - Beta
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

  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.

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

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

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

2.3 WP Admin → Kolai → Ayarlar

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

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

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

Kolai for WooCommerce

Last updated