Tecof Uygulamaları ve Entegrasyonlar
Tecof uygulama entegrasyonu iki ayrı yüzeye ayrılır: satıcı panelinde çalışan JWT korumalı yönetim API'leri ve canlı mağazanın kullandığı secret-key korumalı storefront API'leri.
Mevcut kodda doğrulanan entegrasyon modeli REST tabanlıdır. OAuth 2.0 ve GraphQL, bu kod tabanında aktif public contract olarak görünmediği için bu dokümanda ana akış olarak anlatılmaz.
Entegrasyon Katmanları
Merchant Admin API
Satıcı panelindeki kaynaklar /api/merchant/* altında bulunur ve JWT role/team doğrulaması ister. Örnek kaynaklar:
| Alan | Örnek endpoint |
|---|---|
| CMS collections | GET /api/merchant/cms/collections |
| CMS items | GET /api/merchant/cms/collections/:collectionId/items |
| Webhook yönetimi | GET /api/merchant/ecommerce/webhooks |
| Ödeme yönetimi | POST /api/merchant/ecommerce/payments/checkout |
| Tema yönetimi | GET /api/merchant/themes |
Bu uçlar canlı temaya doğrudan verilmemelidir; satıcı paneli veya güvenilir backend app katmanı üzerinden çağrılmalıdır.
Storefront API
Canlı mağaza ve tema paketlerinin kullandığı public contract /api/store/* altındadır. Bu uçlar x-secret-key ile merchant bağlamını çözer.
| Alan | Örnek endpoint |
|---|---|
| Sayfa render | POST /api/store/render |
| Merchant bilgisi | GET /api/store/merchant-info |
| Ürün listesi | GET /api/store/ecommerce/products |
| Sepet doğrulama | POST /api/store/ecommerce/cart/validate |
| Checkout | POST /api/store/ecommerce/checkout |
| CMS canlı içerik | POST /api/store/cms/collections/:slug/items |
Tam liste için Public API Referansı sayfasını kullanın.
Webhook Olayları
Webhook yönetimi admin tarafında /api/merchant/ecommerce/webhooks uçlarıyla yapılır. Backend ve frontend tarafında senkron tutulan olay kataloğu şu event değerlerini içerir:
| Grup | Event |
|---|---|
| Sipariş | order.created, order.paid, order.updated, order.fulfilled, order.cancelled, order.refunded |
| Ürün | product.created, product.updated, product.deleted, inventory.low_stock |
| Müşteri | customer.created, customer.updated, customer.deleted |
| Değerlendirme | review.created, review.approved |
| Pazarlama | subscriber.created |
| CMS | cms.item.published |
| Genel | * |
cms.item.published, CMS item publish akışında fire-and-forget dispatch edilir. Düşük stok için backend eşik değeri LOW_STOCK_THRESHOLD = 5 olarak tanımlıdır.
Webhook Yönetim Endpointleri
| Metot | Endpoint | Açıklama |
|---|---|---|
GET |
/api/merchant/ecommerce/webhooks |
Webhook listesini getirir |
GET |
/api/merchant/ecommerce/webhooks/by/id/:id |
Tek webhook detayını getirir |
POST |
/api/merchant/ecommerce/webhooks |
Webhook oluşturur |
PUT |
/api/merchant/ecommerce/webhooks/:id |
Webhook günceller |
DELETE |
/api/merchant/ecommerce/webhooks/:id |
Webhook siler |
POST |
/api/merchant/ecommerce/webhooks/:id/test |
Test gönderimi yapar |
GET |
/api/merchant/ecommerce/webhooks/deliveries |
Teslimat geçmişini listeler |
POST |
/api/merchant/ecommerce/webhooks/deliveries/:id/redeliver |
Aynı payload ile tekrar gönderir |
App Marketplace Verisi
Backend'de StoreApp modeli uygulama kataloğu için name, description, developer, version, category, permissions, webhooks, settings, pricing, installUrl, webhookUrl ve sıralama alanlarını taşır.
Bu veri modeli uygulama vitrini ve entegrasyon tanımları için hazırdır; ancak canlı uygulama yükleme akışını dokümante ederken mevcut endpoint ve auth davranışı ayrıca doğrulanmalıdır.