v1.02026-04-22

Ticimax Integration API

KeySonar, Ticimax magazalariyla entegre calisarak urun, kategori ve sayfa icerikleri uzerinde AI destekli SEO optimizasyonu yapar. Bu sayfa, entegrasyon icin teknik referans saglar.

OAuth 2.0

Tek tikla baglanti. Kullanici Ticimax'a yonlendirilir, izin verir, otomatik baglanir.

Marketplace Webhook

Ticimax marketplace'den uygulama kurulunca otomatik bildirim ve baglanti.

Manuel API Key

Kullanici Ticimax panelinden API key alir ve manuel girer. (Fallback)

Ticimax Tarafinin Yapmasi Gerekenler

Bu bolum Ticimax yazilim ekibine yoneliktir. Secilen entegrasyon modeline gore asagidaki adimlarin tamamlanmasi gerekir.

OAuth 2.0 Modeli

Adim 1: Partner Uygulama Kaydi

KeySonar icin bir uygulama kaydi olusturun ve asagidaki bilgileri KeySonar'a iletin:

DegerAciklamaOrnek
client_idUygulama kimlik numarasitcmx_ks_abc123
client_secretUygulama gizli anahtaritcmx_secret_xyz789

Adim 2: OAuth Authorize Endpoint

KeySonar, kullaniciyi asagidaki URL'ye yonlendirir. Ticimax'in bu URL'de bir yetkilendirme sayfasi sunmasi gerekir:

Authorize URL
GET https://{magaza}.ticimax.com/oauth/authorize
    ?client_id={client_id}
    &redirect_uri=https://keysonar.com/api/integrations/ticimax/callback
    &scope=products:read,products:write,categories:read,categories:write,pages:read,pages:write
    &response_type=code
    &state={opaque_string}

Bu sayfa:

  • Magaza sahibinin Ticimax oturumunu dogrular
  • "KeySonar su izinleri istiyor" seklinde izin ekrani gosterir
  • Onay sonrasi redirect_uri?code=AUTH_CODE&state=SAME_STATE adresine yonlendirir

Adim 3: Token Exchange Endpoint

KeySonar, authorization code'u access token'a cevirmek icin POST istegi gonderir:

Token Exchange — Request
POST https://{magaza}.ticimax.com/oauth/token
Content-Type: application/json

{
  "client_id": "{client_id}",
  "client_secret": "{client_secret}",
  "code": "{authorization_code}",
  "grant_type": "authorization_code"
}
Token Exchange — Beklenen Yanit
{
  "access_token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "token_type": "bearer",
  "expires_in": 0
}

Not: access_token, mevcut UyeKodu formatinda olabilir. expires_in: 0 = suresi dolmaz. Sureli ise refresh_token da donulmeli.

Gereken Scope'lar (Erisim Izinleri)

ScopeAciklamaKullanim
products:readUrun listesi ve detay okumaEnvanter tarama, SEO analiz
products:writeUrun bilgilerini guncellemeMeta title/description duzeltme
categories:readKategori listesi okumaEnvanter tarama, SEO analiz
categories:writeKategori bilgilerini guncellemeMeta title/description duzeltme
pages:readSayfa listesi okumaEnvanter tarama, SEO analiz
pages:writeSayfa iceriklerini guncellemeSEO icerik optimizasyonu

Marketplace Webhook Modeli

Adim 1: Webhook Secret Olusturma

HMAC imzalama icin bir webhook_secret olusturun ve KeySonar'a iletin.

Adim 2: Install Webhook Gonderme

Magaza sahibi KeySonar uygulamasini kurdugunda asagidaki istegi gonderin:

Install Webhook
POST https://keysonar.com/api/integrations/ticimax/install
Content-Type: application/json
X-Ticimax-Hmac-SHA256: {hmac_signature}

{
  "store_url": "almodjewellery.ticimax.com",
  "store_id": "12345",
  "store_name": "Almod Jewellery",
  "api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "email": "[email protected]"
}
AlanTipZorunluAciklama
store_urlstringEvetMagaza URL (protokol olmadan)
store_idstringHayirTicimax magaza ID
store_namestringHayirMagaza adi
api_keystringEvetOtomatik uretilmis API anahtari (UyeKodu)
emailstringOnerilenMagaza sahibinin e-postasi (hesap eslesmesi icin)

Adim 3: Uninstall Webhook Gonderme

Uninstall Webhook
POST https://keysonar.com/api/integrations/ticimax/uninstall
Content-Type: application/json
X-Ticimax-Hmac-SHA256: {hmac_signature}

{
  "store_url": "almodjewellery.ticimax.com",
  "store_id": "12345"
}

HMAC Imza Dogrulama

Tum webhook isteklerinde X-Ticimax-Hmac-SHA256 header'i ile HMAC-SHA256 imzasi gonderilmelidir.

C# Ornegi
using System.Security.Cryptography;
using System.Text;

string webhookSecret = "whsec_ticimax_abc123";
string requestBody = "{...}";  // raw JSON body

using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(webhookSecret));
byte[] hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(requestBody));
string signature = BitConverter.ToString(hash).Replace("-", "").ToLower();

// Header: X-Ticimax-Hmac-SHA256: {signature}
Python Ornegi
import hmac, hashlib

webhook_secret = 'whsec_ticimax_abc123'
request_body = b'{"store_url":"store.ticimax.com","api_key":"xxx"}'

signature = hmac.new(
    webhook_secret.encode('utf-8'),
    request_body,
    hashlib.sha256
).hexdigest()

# Header: X-Ticimax-Hmac-SHA256: {signature}

Endpoint Referansi

POST
/api/integrations/ticimax/auth

OAuth akisini baslatir, Ticimax authorize URL'i doner

Auth: KeySonar JWT

GET
/api/integrations/ticimax/callback

OAuth callback — code'u token'a cevirir, site olusturur

Auth: State JWT dogrulama

POST
/api/integrations/ticimax/install

Marketplace install webhook — otomatik site olusturma

Auth: HMAC-SHA256

POST
/api/integrations/ticimax/uninstall

Marketplace uninstall webhook — site deaktive etme

Auth: HMAC-SHA256

GET
/api/integrations/ticimax/status?store_url=xxx

Baglanti durumu kontrolu (KeySonar dahili)

Auth: KeySonar JWT

Yanit Formatlari

Install — Basarili

HTTP 200 OK
{ "success": true }

Uninstall — Basarili

HTTP 200 OK
{ "success": true, "deactivated": 1 }

Hata Yanitlari

HTTP KoduYanitAciklama
400{"error": "store_url and api_key are required"}Eksik zorunlu alan
400{"error": "Invalid JSON body"}Gecersiz JSON formati
401{"error": "Invalid signature"}HMAC imzasi dogrulanamadi
500{"error": "..."}Sunucu hatasi

KeySonar'in Kullandigi Ticimax Servisleri

Entegrasyon kurulduktan sonra KeySonar, magazanin SOAP servislerini kullanarak SEO islemleri yapar:

SOAP Endpoint
https://{store_url}/Servis/UrunServis.svc
MetodAmac
SelectUrunCountBaglanti testi, urun sayisi kontrolu
SelectUrunUrun listesi cekme (pagination ile)
SaveUrunUrun SEO alanlari guncelleme
SelectKategoriKategori listesi
SaveKategoriKategori SEO alanlari guncelleme
SelectSayfaSayfa listesi
SaveSayfaSayfa icerik ve SEO guncelleme

Her SOAP isteginde UyeKodu parametresi olarak access token gonderilir.

Ticimax'tan Beklenen Ciktilar

Entegrasyonun tamamlanmasi icin Ticimax'in KeySonar'a iletmesi gereken bilgiler:

OAuth Modeli Secilirse

BilgiAciklama
client_idKeySonar uygulama ID'si
client_secretKeySonar uygulama gizli anahtari
OAuth authorize URL formatiEndpoint path (orn: /oauth/authorize)
Token exchange URL formatiEndpoint path (orn: /oauth/token)
Token suresiSuresi doluyor mu? Refresh token var mi?
Scope listesiDesteklenen scope'lar

Webhook Modeli Secilirse

BilgiAciklama
webhook_secretHMAC imzalama icin paylasimli anahtar
Install payloadYukaridaki format uygun mu, farkli alanlar var mi?
Uninstall webhookDestekleniyor mu?

Her Iki Model Icin

BilgiAciklama
Test magaza URLSandbox/test magaza adresi
Test API keyTest icin gecerli UyeKodu

Test Komutlari

Install Webhook Testi (curl)
BODY='{"store_url":"test.ticimax.com","store_id":"99999","store_name":"Test","api_key":"test-key","email":"[email protected]"}'
SECRET="webhook_secret_buraya"
HMAC=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST https://keysonar.com/api/integrations/ticimax/install \
  -H "Content-Type: application/json" \
  -H "X-Ticimax-Hmac-SHA256: $HMAC" \
  -d "$BODY"
Uninstall Webhook Testi (curl)
BODY='{"store_url":"test.ticimax.com","store_id":"99999"}'
HMAC=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST https://keysonar.com/api/integrations/ticimax/uninstall \
  -H "Content-Type: application/json" \
  -H "X-Ticimax-Hmac-SHA256: $HMAC" \
  -d "$BODY"

Kullanici Senaryolari

Senaryo 1: OAuth ile Baglanti

  1. 1Kullanici KeySonar'a giris yapar
  2. 2"Site Ekle" → "Ticimax" secer
  3. 3Magaza URL'sini girer
  4. 4"Ticimax ile Baglan" butonuna tiklar
  5. 5Ticimax login/izin sayfasina yonlendirilir
  6. 6"Izin Ver" tiklar
  7. 7KeySonar'a geri yonlendirilir
  8. 8Site otomatik olusturulur, dashboard acilir

API key girisi YOK

Senaryo 2: Marketplace Webhook

  1. 1Kullanici Ticimax admin panelinde "Uygulamalar" bolumune gider
  2. 2"KeySonar" uygulamasini bulur, "Kur" tiklar
  3. 3Ticimax otomatik olarak KeySonar'a webhook gonderir
  4. 4Kullanici KeySonar'a giris yapar
  5. 5Site zaten bagli olarak gorunur

API key girisi YOK