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:
| Deger | Aciklama | Ornek |
|---|---|---|
client_id | Uygulama kimlik numarasi | tcmx_ks_abc123 |
client_secret | Uygulama gizli anahtari | tcmx_secret_xyz789 |
Adim 2: OAuth Authorize Endpoint
KeySonar, kullaniciyi asagidaki URL'ye yonlendirir. Ticimax'in bu URL'de bir yetkilendirme sayfasi sunmasi gerekir:
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_STATEadresine yonlendirir
Adim 3: Token Exchange Endpoint
KeySonar, authorization code'u access token'a cevirmek icin POST istegi gonderir:
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"
}{
"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)
| Scope | Aciklama | Kullanim |
|---|---|---|
products:read | Urun listesi ve detay okuma | Envanter tarama, SEO analiz |
products:write | Urun bilgilerini guncelleme | Meta title/description duzeltme |
categories:read | Kategori listesi okuma | Envanter tarama, SEO analiz |
categories:write | Kategori bilgilerini guncelleme | Meta title/description duzeltme |
pages:read | Sayfa listesi okuma | Envanter tarama, SEO analiz |
pages:write | Sayfa iceriklerini guncelleme | SEO 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:
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]"
}| Alan | Tip | Zorunlu | Aciklama |
|---|---|---|---|
store_url | string | Evet | Magaza URL (protokol olmadan) |
store_id | string | Hayir | Ticimax magaza ID |
store_name | string | Hayir | Magaza adi |
api_key | string | Evet | Otomatik uretilmis API anahtari (UyeKodu) |
email | string | Onerilen | Magaza sahibinin e-postasi (hesap eslesmesi icin) |
Adim 3: Uninstall Webhook Gonderme
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.
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}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
/api/integrations/ticimax/authOAuth akisini baslatir, Ticimax authorize URL'i doner
Auth: KeySonar JWT
/api/integrations/ticimax/callbackOAuth callback — code'u token'a cevirir, site olusturur
Auth: State JWT dogrulama
/api/integrations/ticimax/installMarketplace install webhook — otomatik site olusturma
Auth: HMAC-SHA256
/api/integrations/ticimax/uninstallMarketplace uninstall webhook — site deaktive etme
Auth: HMAC-SHA256
/api/integrations/ticimax/status?store_url=xxxBaglanti 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 Kodu | Yanit | Aciklama |
|---|---|---|
| 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:
https://{store_url}/Servis/UrunServis.svc| Metod | Amac |
|---|---|
SelectUrunCount | Baglanti testi, urun sayisi kontrolu |
SelectUrun | Urun listesi cekme (pagination ile) |
SaveUrun | Urun SEO alanlari guncelleme |
SelectKategori | Kategori listesi |
SaveKategori | Kategori SEO alanlari guncelleme |
SelectSayfa | Sayfa listesi |
SaveSayfa | Sayfa 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
| Bilgi | Aciklama |
|---|---|
client_id | KeySonar uygulama ID'si |
client_secret | KeySonar uygulama gizli anahtari |
| OAuth authorize URL formati | Endpoint path (orn: /oauth/authorize) |
| Token exchange URL formati | Endpoint path (orn: /oauth/token) |
| Token suresi | Suresi doluyor mu? Refresh token var mi? |
| Scope listesi | Desteklenen scope'lar |
Webhook Modeli Secilirse
| Bilgi | Aciklama |
|---|---|
webhook_secret | HMAC imzalama icin paylasimli anahtar |
| Install payload | Yukaridaki format uygun mu, farkli alanlar var mi? |
| Uninstall webhook | Destekleniyor mu? |
Her Iki Model Icin
| Bilgi | Aciklama |
|---|---|
| Test magaza URL | Sandbox/test magaza adresi |
| Test API key | Test icin gecerli UyeKodu |
Test Komutlari
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"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
- 1Kullanici KeySonar'a giris yapar
- 2"Site Ekle" → "Ticimax" secer
- 3Magaza URL'sini girer
- 4"Ticimax ile Baglan" butonuna tiklar
- 5Ticimax login/izin sayfasina yonlendirilir
- 6"Izin Ver" tiklar
- 7KeySonar'a geri yonlendirilir
- 8Site otomatik olusturulur, dashboard acilir
API key girisi YOK
Senaryo 2: Marketplace Webhook
- 1Kullanici Ticimax admin panelinde "Uygulamalar" bolumune gider
- 2"KeySonar" uygulamasini bulur, "Kur" tiklar
- 3Ticimax otomatik olarak KeySonar'a webhook gonderir
- 4Kullanici KeySonar'a giris yapar
- 5Site zaten bagli olarak gorunur
API key girisi YOK