Agent-ready

Shopial Integrator API

Satıcılar ve üçüncü taraf entegratörler (ERP, PIM, Yengeç, Sopyo, Entegra) bu REST API ile Shopial'e bağlanır. Resmi hub anlaşması gerekmez; API anahtarınızı vendor panelinden oluşturun.

OpenAPI YAML llms.txt API anahtarı oluştur →

Kimlik doğrulama

Tüm /api/v1 isteklerinde Bearer token (vendor API key).

Rate limit: 120 istek / dakika (API key + IP). 429 yanıtında retry bekleyin.

Authorization header

Authorization: Bearer shp_your_api_key_here

Scope'lar

Anahtar oluştururken en az bir scope seçin.

PRODUCTS_READ
PRODUCTS_WRITE
INVENTORY_WRITE
ORDERS_READ
WEBHOOKS_MANAGE

Uç noktalar

JSON gövde; hata formatı: code, message, details.

Metod	Yol	Scope
GET	/api/v1/products	PRODUCTS_READ
POST	/api/v1/products	PRODUCTS_WRITE
POST	/api/v1/products/upsert	PRODUCTS_WRITE
POST	/api/v1/products/bulk	PRODUCTS_WRITE
POST	/api/v1/products/bulk-upsert	PRODUCTS_WRITE
GET	/api/v1/products/lookup	PRODUCTS_READ
GET	/api/v1/products/{id}	PRODUCTS_READ
PATCH	/api/v1/products/{id}	PRODUCTS_WRITE
DELETE	/api/v1/products/{id}	PRODUCTS_WRITE
PATCH	/api/v1/inventory/{sku}	INVENTORY_WRITE
GET	/api/v1/orders	ORDERS_READ
GET	/api/v1/orders/{id}	ORDERS_READ
GET	/api/v1/categories	PRODUCTS_READ
GET	/api/v1/webhooks	WEBHOOKS_MANAGE
POST	/api/v1/webhooks	WEBHOOKS_MANAGE

Ürün senkronu (bridge / PIM)

Dış platformlardan tekrarlayan import için upsert ve lookup uç noktaları.

Shopial Bridge veya özel entegratör yazılımınız ürünleri externalId, sku veya barcode ile eşleştirip güncelleyebilir. Ürün çekirdeği category değil product-scoped'tur; primaryCategoryId yalnızca placement/template hint olarak kullanılır. POST /products/bulk yalnızca oluşturur; güncelleme için bulk-upsert kullanın.

matchBy: externalId (varsayılan), sku veya barcode — seçilen alanın dolu olması gerekir.
options + variants tek ürün graph'ını taşır; metadata.integrator.externalId + metadata.integrator.source eşleme anahtarıdır; metadata.schemaOrg ve metadata.gs1 GS1/schema.org identity alanlarını, googleMerchant / metaCatalog / ikas / trendyol / hepsiburada / shopify blokları ise kanal-özel SEO alanlarını taşır.
imageUrls (max 20) uzaktan indirilip S3'e yüklenir; replaceImages=true mevcut görselleri siler. Görsel ve varyant verisi kategoriye bağlı değildir.

Örnek istekler

Ürün listesi

curl -s "https://www.shopial.com/api/v1/products?page=1&limit=24" \
  -H "Authorization: Bearer shp_your_api_key_here"

Ürün oluştur

curl -s -X POST "https://www.shopial.com/api/v1/products" \
  -H "Authorization: Bearer shp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Örnek ürün",
    "price": 199.9,
    "vatRate": 0,
    "inventory": 10,
    "metadata": {
      "schemaOrg": {
        "brand": "Örnek Marka",
        "productType": "Giyim",
        "gtin": "869000000001",
        "mpn": "ORNEK-001"
      },
      "gs1": {
        "gtin13": "869000000001",
        "mpn": "ORNEK-001",
        "brand": "Örnek Marka",
        "productType": "Giyim"
      }
    }
  }'

Ürün upsert (senkron)

curl -s -X POST "https://www.shopial.com/api/v1/products/upsert" \
  -H "Authorization: Bearer shp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "matchBy": "externalId",
    "externalId": "TY-12345",
    "externalSource": "trendyol",
    "title": "Senkron ürün",
    "price": 299.9,
    "sku": "TY-12345",
    "inventory": 12,
    "primaryCategoryId": "cat_apparel",
    "options": [
      { "title": "Renk", "values": ["Siyah", "Beyaz"] },
      { "title": "Beden", "values": ["M", "L"] }
    ],
    "variants": [
      {
        "sku": "TY-12345-S-M",
        "barcode": "869000000001",
        "price": 299.9,
        "inventory": 5,
        "optionValues": ["Renk::Siyah", "Beden::M"],
        "isDefault": true
      },
      {
        "sku": "TY-12345-W-L",
        "barcode": "869000000002",
        "price": 299.9,
        "inventory": 7,
        "optionValues": ["Renk::Beyaz", "Beden::L"]
      }
    ],
    "imageUrls": ["https://cdn.example.com/img1.jpg"],
    "commerceFeed": {
      "brand": "Örnek Marka",
      "gtin": "869000000001",
      "mpn": "TY-12345",
      "condition": "new",
      "googleProductCategory": "Apparel & Accessories",
      "itemGroupId": "TY-12345",
      "color": "Siyah",
      "size": "M"
    },
    "metadata": {
      "integrator": { "externalId": "TY-12345", "source": "trendyol" },
      "schemaOrg": {
        "brand": "Örnek Marka",
        "productType": "Giyim > Üst Giyim",
        "category": "Giyim",
        "condition": "new",
        "gtin": "869000000001",
        "mpn": "TY-12345",
        "sku": "TY-12345",
        "color": "Siyah",
        "size": "M"
      },
      "gs1": {
        "gtin13": "869000000001",
        "mpn": "TY-12345",
        "sku": "TY-12345",
        "brand": "Örnek Marka",
        "productType": "Giyim > Üst Giyim",
        "category": "Giyim"
      },
      "trendyol": { "productMainId": "TY-12345" }
    }
  }'

Toplu upsert

curl -s -X POST "https://www.shopial.com/api/v1/products/bulk-upsert" \
  -H "Authorization: Bearer shp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sync-batch-2026-06-08" \
  -d '{"products":[{"matchBy":"sku","sku":"WP-001","title":"WP ürün","price":149}]}'

Ürün lookup

curl -s "https://www.shopial.com/api/v1/products/lookup?externalId=TY-12345&externalSource=trendyol" \
  -H "Authorization: Bearer shp_your_api_key_here"

Webhook kaydı

curl -s -X POST "https://www.shopial.com/api/v1/webhooks" \
  -H "Authorization: Bearer shp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://integrator.example/hooks/shopial","events":["order.paid"]}'

Outbound webhook

Shopial, kayıtlı URL'nize olay POST eder.

Desteklenen olaylar:

order.paid

Gövde HMAC-SHA256 ile imzalanır (endpoint secret veya SHOPIAL_WEBHOOK_SIGNING_SECRET).

Webhook header'ları

X-Shopial-Event: order.paid
X-Shopial-Signature: <hmac-sha256-hex>
X-Shopial-Delivery-Id: <delivery-id>

Hata yanıtı

Örnek JSON

{
  "code": "invalid_body",
  "message": "Invalid product payload",
  "details": { }
}

Hub / entegratör notu

Yengeç, Sopyo, Entegra ve benzeri platformlar kendi bağlantılarını bu API üzerinden kurar. Shopial, ürün oluşturmayı universal product core üzerinden standardize eder; kanal entegrasyonları metadata ve adapter katmanında çözülür.

Shopial Integrator API

Ara