API Dokümantasyonu

Connector credential doğrulaması yapar. Token üretmez; body veya header ile gönderilen mevcut key/token çiftini doğrular.

curl -X POST "$BASE_URL/auth/login" \
-H "Content-Type: application/json" \
-d '{"key":"<connector-key>","token":"<connector-token>"}'

Başarılı cevap:

{
  "success": true,
  "code": "AUTHENTICATED",
  "message": "Connector credentials verified.",
  "data": {
    "service": "simurgh-connector",
    "engine": "simurgh_marketplace",
    "tenant": "example-tenant",
    "version": "1.0.0.63",
    "auth": {"type":"headers","headers":["X-Connector-Key","X-Connector-Token"],"legacyHeaders":["X-Simurgh-Key","X-Simurgh-Token"]}
  },
  "meta": {"requestId":"uuid","timestamp":"ISO-8601"}
}

Uygulama ve veritabanı durumunu kontrol eder. Bu endpoint middleware arkasındadır.

curl -X GET "$BASE_URL/health" \
-H "X-Simurgh-Key: <connector-key>" \
-H "X-Simurgh-Token: <connector-token>"

{
  "success": true,
  "code": "HEALTHY",
  "message": "Connector is healthy.",
  "data": {
    "service": "simurgh-connector",
    "engine": "simurgh_marketplace",
    "tenant": "example-tenant",
    "version": "1.0.0.63",
    "checks": {"application":true,"database":true}
  },
  "meta": {"requestId":"uuid","timestamp":"ISO-8601"}
}

v1.0.0.28: Connector kurulumunu ve canlı ortam hazırlığını tek cevapta kontrol eder. Database, auth config, route kaydı, dokümantasyon sürümü, storage yazılabilirliği, Simurgh/Simurgh Pazaryeri tabloları, katalog varsayılanları ve sync job özetini döner.

curl -X GET "$BASE_URL/doctor" \
-H "X-Simurgh-Key: <connector-key>" \
-H "X-Simurgh-Token: <connector-token>"

Başarılı cevap HTTP 200 döner. Kritik hata varsa HTTP 503 döner; errors alanı deploy sonrası ilk bakılacak yerdir. Uyarılar warnings içinde kalır ve işlem bloklamaz.

{
  "success": true,
  "code": "CONNECTOR_DOCTOR_OK",
  "message": "Connector doktor kontrolü tamamlandı.",
  "data": {
    "service": "simurgh-connector",
    "engine": "simurgh_marketplace",
    "tenant": "example-tenant",
    "version": "1.0.0.63",
    "checks": {
      "database": {"ok":true},
      "routes": {"ok":true},
      "tables": {"ok":true},
      "catalog_defaults": {"ok":true}
    },
    "queue": {"enabled":true,"counts_by_status":{"pending":0}}
  },
  "meta": {"requestId":"uuid","timestamp":"ISO-8601"}
}

Ürünü oluşturur veya mapping üzerinden günceller. sku ya da barcode alanlarından en az biri zorunludur. Kategori ve marka için öncelikli alanlar simurgh_category_ids ve simurgh_brand_id değerleridir; bunlar tenant bazlı mapping tablolarından Simurgh Pazaryeri ID değerlerine çevrilir. Eski categories ve brand_id sayısal alanları geriye uyumluluk için kabul edilir.

{
  "simurgh_product_id":"prd_001",
  "sku":"TEST001",
  "barcode":"8690000000001",
  "name":"Test Ürün",
  "type":"simple",
  "price":149.90,
  "stock":12,
  "weight":1,
  "manage_stock":true,
  "status":true,
  "visible_individually":true,
  "simurgh_category_ids":["cat_001"],
  "simurgh_brand_id":"brand_001",
  "attribute_family_code":"default",
  "channel":"default",
  "channels":["default"],
  "inventory_source_code":"default",
  "locale":"tr"
}

{
  "success":true,
  "action":"created",
  "product_id":42,
  "simurgh_product_id":"prd_001",
  "category_ids":[7],
  "brand_option_id":12
}

v1.0.0.27: /products ile aynı payloadı yazmadan kontrol eder. Kategori/marka mapping, attribute family, inventory source, zorunlu attribute, configurable super attribute, duplicate varyant kombinasyonu ve option policy sonucu doğrulanır.

curl -X POST "$BASE_URL/products/preflight" \
-H "Content-Type: application/json" \
-H "X-Simurgh-Key: <connector-key>" \
-H "X-Simurgh-Token: <connector-token>" \
-d '{
  "simurgh_product_id":"prd_parent_001",
  "type":"configurable",
  "sku":"TSHIRT-001",
  "attribute_family_code":"default",
  "attribute_option_policy":"create_if_allowed",
  "configurable_attributes":["color","size"],
  "variants":[
    {"sku":"TSHIRT-001-RED-M","price":349.90,"attributes":{"color":"Kırmızı","size":"M"}}
  ]
}'

Bu endpoint veritabanına ürün, varyant veya option yazmaz. create_if_allowed politikası bilinmeyen option için would_create raporu üretir; gerçek oluşturma sadece /products veya /products/full-sync sırasında yapılır.

{
  "success": true,
  "code": "PRODUCT_PREFLIGHT_OK",
  "can_sync": true,
  "data": {
    "product": {"operation":"create","type":"configurable"},
    "configurable": {"enabled":true,"variant_count":1},
    "attributes": {"options":{"resolved":[],"created":[],"would_create":[],"ignored":[]}}
  }
}

sku veya simurgh_product_id ile ürün bulur. Stok için ayrı payload hash kullanır; aynı veri tekrar gelirse action: unchanged dönebilir.

{ "simurgh_product_id":"prd_001", "stock":12, "manage_stock":true, "channel":"default", "locale":"tr" }

price, regular_price veya list_price alanlarından biriyle fiyat günceller. Özel fiyat ve tarih aralığı desteklenir.

{
  "simurgh_product_id":"prd_001",
  "price":149.90,
  "special_price":129.90,
  "cost_price":80,
  "special_price_from":"2026-07-11",
  "special_price_to":"2026-07-31"
}

simurgh_product_id öncelikli, SKU yedek yöntem olacak şekilde ürünü ortak mapping katmanından bulur. SEO payload hash değeri değişmediyse action: unchanged döner. url_key, meta_title, meta_keywords, meta_description, channel ve locale doğrulanır.

{ "simurgh_product_id":"prd_001", "url_key":"test-urun", "meta_title":"Test Ürün", "meta_keywords":"test,urun", "meta_description":"SEO açıklaması", "channel":"default", "locale":"tr" }

Ürünü ortak mapping katmanından bulur; simurgh_product_id önceliklidir. Görsel ve video URL alanları doğrulanır. Başarılı senkron sonrası mapping kaydına medya hash ve son medya senkron zamanı yazılır.

{ "simurgh_product_id":"prd_001", "main_image":"https://cdn.example.com/main.jpg", "images":["https://cdn.example.com/image.jpg"], "videos":[], "force":false }

simurgh_product_id öncelikli olacak şekilde ürünü ortak mapping katmanından bulur. Temel bilgi, kategori, marka, SEO ve görünürlük alanlarını tek akışta günceller. simurgh_category_ids ve simurgh_brand_id mevcut mapping tablolarından çözülür. Aynı bilgi payloadı tekrar gönderilirse action: unchanged döner.

{
  "simurgh_product_id":"prd_001",
  "name":"Güncel Ürün Adı",
  "short_description":"Kısa açıklama",
  "description":"Uzun açıklama",
  "simurgh_category_ids":["cat_001"],
  "simurgh_brand_id":"brand_001",
  "status":true,
  "visible_individually":true
}

Zorunlu kimlik: sku veya simurgh_product_id. Başarılı senkron sonrasında mapping kaydına last_info_hash ve last_info_sync_at yazılır.

Fiyat ve stoğu tek istekte iki ayrı servis üzerinden günceller. Ortak SKU üst seviyede veya nested payload içinde verilebilir.

{
  "sku":"TEST001",
  "price":{"price":1301,"special_price":null},
  "stock":{"stock":7}
}

Ürünü ortak mapping katmanından bulur. Aktiflik ve tekil görünürlük değerlerini günceller; aynı görünürlük hash değeri tekrar gönderilirse action: unchanged döner.

{ "simurgh_product_id":"prd_001", "status":true, "visible_individually":true, "channel":"default", "locale":"tr" }

Master import servisini syncMedia=true ve varsayılan operation=FULL_SYNC ile çalıştırır. Request doğrulaması /products ile aynıdır. Simurgh panel için response içinde panel, operation, simurgh_marketplace_product_id, errors ve warnings özetleri bulunur. Mevcut kategori, marka, ürün, fiyat, stok ve medya servisleri değiştirilmedi.

{
  "simurgh_product_id":"prd_001",
  "sku":"TEST001",
  "name":"Tam Senkron Ürün",
  "price":1301,
  "stock":7,
  "simurgh_category_ids":["cat_001"],
  "simurgh_brand_id":"brand_001"
}

Panelin doğrudan okuyabileceği başarılı cevap özeti:

{
  "success": true,
  "code": "PRODUCT_FULL_SYNC_COMPLETED",
  "sku": "TEST001",
  "operation": "CREATE",
  "simurgh_marketplace_product_id": 42,
  "panel": {
    "tenant": "example-tenant",
    "source": "simurgh_panel",
    "result": "success",
    "next_action": "show_success",
    "operation": "CREATE",
    "sku": "TEST001",
    "product_id": 42,
    "price_synced": true,
    "stock_synced": true,
    "media_skipped": false,
    "failed_steps": [],
    "trace_id": "uuid",
    "endpoint": "products/panel-sync"
  },
  "panel_trace_id": "uuid",
  "errors": [],
  "warnings": []
}

v1.0.0.32: Simurgh panel için önerilen endpointtir. Aynı MasterProductImportService akışını kullanır, ancak panel isteği için ayrı controller metodundan geçer ve credential içermeyen audit izi üretir. /products/full-sync davranışını bozmaz.

POST /simurgh-connector/products/panel-sync
# Body: /products/full-sync ile aynı ürün payloadı

Başarılı/başarısız cevapta panel tarafı için panel.trace_id, panel.endpoint ve üst seviyede panel_trace_id döner. 1.0.0.33 ile aynı iz GET /products/panel-sync/audit?trace_id=... üzerinden de okunur. Sunucuda özet log:

/home/example-tenant/www/storage/logs/simurgh-panel-sync.jsonl

simurgh_category_id ile idempotent kategori upsert yapar. Aynı payload tekrar gönderildiğinde yeniden yazmak yerine action: unchanged dönebilir. external_id ve category_id geriye dönük alias olarak kabul edilir.

{
  "simurgh_category_id":"cat_001",
  "name":"Gümüş Kolye",
  "slug":"gumus-kolye",
  "parent_simurgh_category_id":"cat_root",
  "locale":"tr",
  "description":"Kategori açıklaması",
  "meta_title":"Gümüş Kolye",
  "meta_keywords":"gümüş,kolye",
  "meta_description":"Kategori SEO açıklaması",
  "position":10,
  "status":1,
  "display_mode":"products_only"
}

simurgh_brand_id ile Simurgh Pazaryeri brand attribute option kaydını oluşturur/günceller. external_id ve brand_id alias olarak kabul edilir.

{ "simurgh_brand_id":"brand_001", "name":"Example Store", "slug":"example-store", "locale":"tr", "sort_order":10 }

Siparişleri artan Simurgh Pazaryeri ID sırasıyla döndürür. after_id yeni cursor alanıdır; since_id geriye uyumluluk için desteklenir. limit 1–250 arasındadır. Her dönen sipariş mapping tablosunda pulled olarak işaretlenir.

curl "$BASE_URL/orders/pull?limit=50&after_id=120&updated_after=2026-07-11T00:00:00Z" \
-H "X-Simurgh-Key: <connector-key>" \
-H "X-Simurgh-Token: <connector-token>"

{
  "success": true,
  "code": "ORDERS_PULLED",
  "count": 2,
  "orders": [ ... ],
  "cursor": {
    "current": 120,
    "next": 122,
    "has_more": false,
    "limit": 50
  },
  "meta": { "requestId": "...", "timestamp": "..." }
}

order_id veya increment_id ile sipariş durumunu günceller. simurgh_order_id verilirse mapping kaydına bağlanır. async:true, ?async=1 veya Prefer: respond-async ile ORDER_STATUS işi kuyruğa alınabilir. Aynı status ve boş yorum tekrarında action: unchanged döner.

{
  "increment_id":"4",
  "simurgh_order_id":"sim-order-001",
  "status":"processing",
  "comment":"Simurgh tarafından işleme alındı.",
  "async":true
}

Simurgh Pazaryeri siparişinin Simurgh tarafında başarıyla oluşturulduğunu bildirir. simurgh_order_id zorunludur; mapping kaydı acknowledged durumuna alınır ve acknowledged_at yazılır.

{"increment_id":"1000001","simurgh_order_id":"sim-order-001","async":false}

Simurgh Pazaryeri RefundRepository üzerinden iade oluşturur. items verilmezse kalan iade edilebilir kalemlerin tamamı kullanılır. shipping, adjustment_refund ve adjustment_fee desteklenir. Bu işlem Simurgh Pazaryeri iade ve stok iade akışını çalıştırır; harici ödeme sağlayıcısına otomatik para iadesi garantisi vermez.

{"increment_id":"1000001","items":{"42":1},"shipping":0,"adjustment_refund":0,"adjustment_fee":0,"async":false}

Siparişin faturalanabilir kalemleri için Simurgh Pazaryeri InvoiceRepository üzerinden fatura oluşturur. items verilmezse kalan tüm miktar faturalanır.

{"increment_id":"1000001","items":{"42":1},"async":false}

Simurgh Pazaryeri ShipmentRepository üzerinden gönderi oluşturur, stok hareketini ve sipariş durumunu Simurgh Pazaryeri kurallarıyla işler. Inventory source kodu veya ID kabul edilir.

{"increment_id":"1000001","inventory_source":"default","carrier_title":"Yurtiçi Kargo","tracking_number":"123456789","items":{"42":1}}

OrderRepository iptal akışını kullanır; stok iadesi, kalem miktarları ve sipariş durumu Simurgh Pazaryeri tarafından güncellenir. force yalnız yönetici override ihtiyacında kullanılmalıdır.

{"increment_id":"1000001","force":false}

Kategori, marka, ürün, fiyat, stok, SEO ve medya aktarımını tek servis akışında yürütür. Controller henüz FormRequest ve ortak response standardına taşınmamıştır.

{
  "product": {
    "simurgh_product_id":"prd_001",
    "sku":"MASTER001",
    "name":"Master Test Ürün",
    "description":"Ürün açıklaması",
    "price":199.90,
    "stock":7,
    "weight":1,
    "manage_stock":true,
    "status":"ACTIVE",
    "category":{"name":"Gümüş Kolye","slug":"gumus-kolye","parent_id":1},
    "brand":{"name":"Example Store"},
    "seo":{"url_key":"master-test-urun","meta_title":"Master Test Ürün"},
    "media":{"images":["https://cdn.example.com/product.jpg"]}
  }
}

/system/reindex endpointi mevcut route dosyasında yoktur. Gerektiğinde container içinde CLI kullanılır.

docker exec -it example-tenant-php php artisan indexer:index

php artisan simurgh:sync-work --tenant=example-tenant --once
php artisan simurgh:sync-work --tenant=example-tenant --types=PRODUCT_PRICE --types=PRODUCT_STOCK
php artisan simurgh:sync-work --tenant=example-tenant --sleep=5 --max-jobs=100

Desteklenen job tiplerini görmek için:

php artisan simurgh:sync-types

Desteklenen çekirdek tipler: CATEGORY_UPSERT, BRAND_UPSERT, PRODUCT_CREATE, PRODUCT_UPDATE, PRODUCT_UPSERT, PRODUCT_FULL_SYNC, PRODUCT_PRICE, PRODUCT_STOCK, PRODUCT_MEDIA, PRODUCT_SEO, PRODUCT_VISIBILITY, PRODUCT_INFO.

Son panel sync audit kayıtlarını listeler. trace_id verilirse tek ürün gönderiminin started/completed kayıtları destek ekranında hızlı bulunur.

curl -X GET "$BASE_URL/products/panel-sync/audit?limit=20" \
-H "X-Simurgh-Key: <connector-key>" \
-H "X-Simurgh-Token: <connector-token>"

curl -X GET "$BASE_URL/products/panel-sync/audit?trace_id=<panel_trace_id>" \
-H "X-Simurgh-Key: <connector-key>" \
-H "X-Simurgh-Token: <connector-token>"

curl -X GET "$BASE_URL/products/panel-sync/audit?endpoint=products/full-sync" \
-H "X-Simurgh-Key: <connector-key>" \
-H "X-Simurgh-Token: <connector-token>"

{
  "success": true,
  "code": "PANEL_SYNC_AUDIT_LISTED",
  "message": "Panel sync audit kayıtları listelendi.",
  "data": {
    "tenant": "example-tenant",
    "log_exists": true,
    "path": "storage/logs/simurgh-panel-sync.jsonl",
    "entries_count": 2,
    "entries": [
      {"event":"completed","trace_id":"uuid","success":true,"sku":"TEST001"},
      {"event":"started","trace_id":"uuid","summary":{"sku":"TEST001"}}
    ]
  },
  "meta": {"requestId":"uuid","timestamp":"ISO-8601"}
}