# Shopial — Agent-ready API

Human-readable docs: /gelistirici/api
OpenAPI 3.1 (canonical): /api/v1/openapi
Base path: /api/v1
Auth: Bearer vendor API key (create at /vendor/entegrasyonlar)

Integrators (Yengeç, Sopyo, Entegra, Shopial Bridge, custom ERP) connect without a formal Shopial partnership.
Native marketplace adapters are not required; use REST + outbound webhooks.

Scopes: PRODUCTS_READ, PRODUCTS_WRITE, INVENTORY_WRITE, ORDERS_READ, WEBHOOKS_MANAGE
Webhook events: order.paid
Signature header: X-Shopial-Signature (HMAC-SHA256)

Integrator REST (/api/v1, Bearer shp_…):
- GET /api/v1/health — Integrator API health check
- GET /api/v1/products — List vendor products
- POST /api/v1/products — Create product
- POST /api/v1/products/upsert — Create or update by matchBy
- POST /api/v1/products/bulk — Bulk import (create only)
- POST /api/v1/products/bulk-upsert — Bulk upsert (Idempotency-Key, max 200)
- GET /api/v1/products/lookup — Find by externalId, sku, or barcode
- GET /api/v1/products/{id} — Get product
- PATCH /api/v1/products/{id} — Update product
- DELETE /api/v1/products/{id} — Delete product
- GET /api/v1/offers — List vendor offers on catalog products
- POST /api/v1/offers — Create offer on catalog product
- GET /api/v1/offers/{id} — Get offer
- PATCH /api/v1/offers/{id} — Update offer
- DELETE /api/v1/offers/{id} — Archive offer
- PATCH /api/v1/inventory/{sku} — Update stock by SKU
- GET /api/v1/orders — List orders with vendor items
- GET /api/v1/orders/{id} — Get order
- GET /api/v1/categories — List active categories
- GET /api/v1/webhooks — List webhook endpoints
- POST /api/v1/webhooks — Register webhook endpoint
- DELETE /api/v1/webhooks/{id} — Delete webhook endpoint

Storefront JSON (public, rate-limited, no API key):
- GET /api/v1/vendors/{slug} — Vendor storefront payload
- GET /api/v1/vendors/{slug}/products — Vendor product list JSON

Product sync (bridge / PIM):
- POST /api/v1/products/upsert — matchBy: externalId | sku | barcode
- POST /api/v1/products/bulk-upsert — batch upsert (Idempotency-Key required, max 200)
- GET /api/v1/products/lookup?externalId=&externalSource= — resolve Shopial product id
- ProductInput supports options/variants, commerceFeed metadata, channel metadata, imageUrls, replaceImages
- Variant optionValues use "Option::Value" keys, for example "Renk::Siyah" or "Beden::M"
- metadata.integrator.externalId + metadata.integrator.source store connector mapping

Feeds:
- GET /api/feeds/google — Google Merchant RSS XML
- GET /api/feeds/meta — Meta/Facebook Catalog CSV
- GET /api/feeds/quality — JSON quality report
- GET /blog/rss.xml — Blog RSS (tr default; ?locale=en for English)

Storefront content map (public HTML):
- / — Homepage
- /urunler — All products PLP
- /{handle}-c-{shortId} — Category PLP (canonical)
- /kategori/{handle} — Category PLP (legacy redirect)
- /marka/{handle} — Brand PLP
- /koleksiyon/{handle} — Collection PLP
- /{vendorSlug} — Vendor store PLP
- /{handle}-p-{shortId} — Product PDP (canonical)
- /blog — Blog listing
- /blog/{category}/{postSlug}-{shortId} — Blog article
- /saticilar — Vendor directory
- /sitemap.xml — Sitemap index

MCP server card: GET /.well-known/mcp/server-card.json — use REST (/api/v1) and /.well-known/api-catalog for discovery.