Chatvia Entegrasyon API v1

Bu paket Marvigo'nun Entegrasyonlar → Chatvia bölümünü ve ileride başka altyapı adaptörlerini geliştirmek içindir. Chatvia tarafındaki servis hazırdır; bu paket Marvigo'nun kendisine otomatik yama yapmaz.

Kararlaştırılan bağlantı modeli

1. İşletme sahibi Chatvia'da ücretsiz hesap açar. Her işletme hesabına bir merchant anahtarı verilir.
2. Chatvia → Entegrasyonlar bölümündeki anahtarı Marvigo'nun güvenli bağlantı ayarına girer.
3. Marvigo'nun backend'i oturumu, mağaza sahipliğini ve CSRF tokenını doğrular.
4. Backend, anahtarla Chatvia API'sine bağlanır; mağazanın kendi kayıtlarından okunan sabit kimlik, ad ve HTTPS alan adını gönderir.
5. API aynı Chatvia işletmesine ait siteyi oluşturur veya tekrar kullanır. Her istek yeni bir hesap oluşturmaz.
6. Marvigo yalnızca açık site kodunu vitrine ekler. Merchant anahtarı ziyaretçiye gönderilmez.

Paketin içindekiler

• API.md: tam istek/yanıt, hata kodları ve yaşam döngüsü.
• openapi.json: OpenAPI 3.0.3 şeması.
• index.html: çevrimdışı okunabilen Türkçe doküman.
• ChatviaClient.php: bağımlılıksız PHP 8.1+ / cURL sunucu istemcisi.
• examples/marvigo-activate.php.example: güvenli ayar kaydetme akışı.
• examples/marvigo-storefront.php.example: mağaza vitrininin yalnızca açık kodu yüklemesi.
• examples/marvigo-disconnect.php.example: bağlantıyı kapatma akışı.
• examples/connect-node.mjs: sunucu taraflı Node.js örneği.

Marvigo'da eklenecek arayüz ve kayıtlar

Entegrasyon kartında Chatvia adı, ücretsiz etiketi, merchant anahtarı için parola alanı, Bağlan, Bağlantıyı kontrol et, Bağlantıyı kes ve Chatvia panelini aç düğmeleri olsun. Anahtarı ayarlara kaydederken şifreleyin; form geri yüklendiğinde gerçek anahtarı istemciye döndürmeyin. Alan boş bırakılırsa mevcut şifreli anahtarı koruyun. Bağlantı durumunu ve alan adını kullanıcıya gösterin.

Mağaza başına enabled, merchant_key_encrypted, website_public_key, installation_id, store_id ve gerekiyorsa son kontrol zamanı saklanır. store_id, mağazanın yaşamı boyunca sabit olmalı; örneğin Marvigo veritabanı kimliği 1042 ise marvigo-1042. İstek gövdesindeki mağaza bilgileri tarayıcıdan alınmaz, yetkili mağaza kaydından okunur.

Eklentinin bağlantı kaydetme ve durum kontrolü işlemleri sunucuda yapılır. Vitrindeki her sayfa görüntülemesinde merchant API'si çağrılmaz; vitrinde yalnızca saklanan açık site kodu kullanılır. Kontrol isteği gerekiyorsa mağaza başına yaklaşık 5 dakika önbellek kullanılabilir. Anahtarı hata/erişim günlüklerine, analitiklere, HTML'e veya JavaScript'e yazmayın.

Anahtar yenilenince Marvigo ayarlarındaki anahtarın da güncellenmesi gerekir. Eski anahtar API erişimini kaybeder; mevcut açık sohbet kodu otomatik silinmez. Mağaza panelindeki kapatma işlemi her durumda yerel widget yüklemesini durdurmalıdır.

Bu paket gerçek merchant anahtarı, uygulama şifresi veya müşteri verisi içermez. Örnekler üretime alınmadan Marvigo'nun mevcut yetkilendirme, CSRF, şifreleme ve tenant ayar saklama akışına bağlanmalıdır.

Chatvia Merchant API v1

Sürüm: 1.1.0 · API sürümü: v1 · Mevcut kullanım: ücretsiz

Temel URL: https://chatvia.com.tr/api/v1

Kimlik doğrulama

Tüm merchant uçları aşağıdaki başlığı gerektirir:

Authorization: Bearer cv_live_SIZIN_GIZLI_ANAHTARINIZ
Accept: application/json
Content-Type: application/json

Örnek anahtar bir yer tutucudur. Gerçek anahtar cv_live_ ve ardından 64 küçük onaltılık karakterden oluşur (256 bit rastgelelik). Anahtarı Chatvia panelindeki Entegrasyonlar bölümünden işletme sahibi/yöneticisi alır. Her işletmenin ayrı anahtarı vardır. Yeni hesapta otomatik oluşturulur; mevcut hesaplara da verilmiştir.

Anahtar yalnızca sunucuda kullanılır. URL, sorgu parametresi, tarayıcı depolaması, tema veya JavaScript içinde tutulmaz. Chatvia anahtar doğrulaması için SHA-256 hash'i kullanır; sahibine tekrar gösterebilmek için ayrı şifreli kopya tutar. Merchant API mesaj okuma/yazma veya panel oturumu açma yetkisi sağlamaz.

1. Anahtarı doğrula

GET /merchant → 200

{
  "merchant": {"id": "01ARZ3NDEKTSV4RRFFQ69G5FAV", "name": "Örnek İşletme"},
  "plan": {"id": "free", "name": "Ücretsiz", "price": 0, "currency": "TRY"},
  "api_version": "v1"
}

Bu cevap doğru işletmeye bağlanıldığını göstermek içindir. Kullanıcıya işletme adını gösterin; isim eşleşmesini kimlik doğrulamasının yerine kullanmayın.

2. Mağazayı bağla veya yeniden etkinleştir

POST /integrations/{provider}/connect

Marvigo için provider=marvigo, özel yazılım için custom. Başka adaptörler kendilerine ait sabit bir platform kodu kullanabilir. Kod: 2–32 karakter; küçük Latin harfiyle başlar, küçük harf/rakam/tire içerir. Örnek: woocommerce. Bu, ilgili platform için hazır eklenti bulunduğu anlamına gelmez.

{
  "store_id": "marvigo-1042",
  "store_name": "Örnek Mağaza",
  "store_url": "https://magazam.example.com"
}

İlk bağlantı 201, aynı mağazanın tekrar bağlantısı 200 döndürür. Aynı işletmeye ait alan adı zaten varsa mevcut site kullanılır. provider + store_id çiftini başka işletme hesabıyla bağlamak 409 hatası verir. Eşzamanlı ilk bağlantılarda 409 alınırsa aynı istek kontrollü olarak tekrar denenebilir.

Tam yanıt (kimlikler temsilidir):

{
  "installation_id": "01ARZ3NDEKTSV4RRFFQ69G5FAW",
  "provider": "marvigo",
  "store_id": "marvigo-1042",
  "status": "connected",
  "website": {
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAX",
    "name": "Örnek Mağaza",
    "domain": "magazam.example.com",
    "enabled": true,
    "public_key": "site_0123456789abcdef0123456789abcdef"
  },
  "widget": {
    "script_url": "https://chatvia.com.tr/embed.js?v=1.1.0",
    "website_id": "site_0123456789abcdef0123456789abcdef",
    "embed_html": "<script src=\"https://chatvia.com.tr/embed.js?v=1.1.0\" data-website-id=\"site_0123456789abcdef0123456789abcdef\" async></script>"
  },
  "dashboard_url": "https://chatvia.com.tr/app",
  "already_connected": false
}

already_connected, bağlantı kaydının daha önce var olduğunu belirtir; daha önce kesilmiş kaydın yeniden açılmasında da true döner. website.name mevcut Chatvia sitesinin adı olabilir; yeniden bağlama site adını veya widget tasarımını sıfırlamaz.

Alan adı değiştiğinde aynı sabit store_id ile yeni HTTPS kökünü gönderin. Dönen yeni açık site kodunu kaydedip vitrini güncelleyin. Önceki siteye bağlı başka aktif API kurulumu kalmamışsa eski sitenin widget'ı durdurulur. Eski sohbet kayıtları silinmez.

Bu API alan adına sahipliğinizi kanıtlayan bir DNS doğrulaması yapmaz. Adaptör mağaza sahipliğini kendi sisteminde doğrulamalı ve alan adını yetkili mağaza kaydından okumalıdır.

3. Bağlantı durumunu oku

GET /integrations/{provider}/stores/{store_id} → 200

Yanıt, bağlama yanıtıyla aynı bağlantı nesnesidir; already_connected alanı bulunmaz. Mağaza bu anahtarın işletmesine ait değilse veya hiç bağlanmadıysa 404 döner. Vitrin yüklemesi için hem status=connected hem de website.enabled=true olmalıdır.

4. Bağlantıyı kes

DELETE /integrations/{provider}/stores/{store_id} → 200

{"installation_id":"01ARZ3NDEKTSV4RRFFQ69G5FAW","status":"disconnected"}

Kayıt ve sohbet geçmişi silinmez. Aynı siteye bağlı başka aktif API kurulumu yoksa sitenin widget'ı da devre dışı bırakılır. Bu siteye elle eklenen JavaScript kodu varsa o da durur. Başka aktif API kurulumu kalırsa site etkin kalır; Marvigo yine de yerel vitrinden kendi yükleyicisini kaldırmalıdır. Aynı kaydı tekrar kesmek güvenlidir. Tekrar connect çağrısı aynı siteyi etkinleştirir.

Hatalar ve tekrar deneme

Kimlik doğrulama hatası:

{"error":{"code":"invalid_merchant_key","message":"Merchant anahtarı geçersiz veya yenilenmiş."}}

Doğrulama/diğer uygulama hataları Laravel biçimini kullanır: {"message":"...","errors":{"store_url":["..."]}}. errors yalnızca alan doğrulama hatalarında bulunur. İç hata metnini HTML olarak basmayın; arayüzde kaçış uygulayın. Anahtarı günlüklerden çıkarın.

Sınırlar: anahtar başına dakikada 120 merchant isteği; IP başına dakikada 300 merchant isteği. Anahtar başlığı eksik tüm istekler de ortak bir boş-anahtar kovasında sınırlanır. Bu sayılar sınırsız kullanım veya hosting kapasitesi garantisi değildir.

Anahtar yenileme ve kaldırma

İşletme sahibi/yöneticisi Chatvia → Entegrasyonlar → Anahtarı yenile ile yeni anahtar alabilir. Eski anahtar derhal yeni API isteklerinde geçersiz olur. Marvigo'nun kayıtlı şifreli anahtarı güncellenmelidir. Var olan widget kodu anahtar yenilemeyle otomatik kapanmaz; widget'ın kapatılması için bağlantıyı kesme işlemi yapılmalıdır.

Standart JavaScript kurulumu

API zorunlu değildir. Bir işletme Chatvia paneline sitesini ekleyip sitenin gerçek kurulum kodunu kopyalayabilir. WordPress/WooCommerce veya özel altyapının izin verilen özel HTML/altbilgi alanına eklenir. Her site kendi açık site kodunu kullanır; merchant anahtarı bu koda eklenmez.

Site CSP kullanıyorsa script-src ve frame-src izinleri arasında https://chatvia.com.tr bulunmalıdır. CSP'nin geri kalanını gevşetmeyin. Sitenin www/kök alan adı yönlendirmesiyle paneldeki alan adı eşleşmelidir. Iframe/harici script eklenmesine izin vermeyen platformlarda platforma özel adaptör gerekir.

Kapsam

API sürüm numarası v1, anahtarlar işletme bazında ve platformdan bağımsızdır. Bu sürümde OAuth/SSO, sipariş/sepet verisi, mesaj okuma/yazma API'si, dosya yükleme ve webhooks sunulmaz. Merchant anahtarıyla Chatvia paneline otomatik giriş yapılmaz; kullanıcı panelde kendi hesabıyla giriş yapar.

Resmî uygulama bileşenleri: Laravel şifreleme servisi ve named rate limiter. Referans: https://laravel.com/framework/docs/13.x/encryption ve https://laravel.com/framework/docs/13.x/routing#rate-limiting .