# Shopial — Agent-ready API

Human-readable docs: /gelistirici/api
OpenAPI 3.1: /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)

Product sync (bridge / PIM):
- POST /api/v1/products/upsert — create or update by 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 first-class options/variants, commerceFeed metadata (Google Merchant + Meta Catalog), channel metadata, externalId, externalSource, imageUrls (import to S3), replaceImages
- Variant optionValues use "Option::Value" keys, for example "Renk::Siyah" or "Beden::M"
- metadata.integrator.externalId + metadata.integrator.source store connector mapping
- Channel keys in metadata: commerceFeed, googleMerchant, metaCatalog, ikas, trendyol, shopify, hepsiburada

Feeds:
- GET /api/feeds/google — Google Merchant RSS XML
- GET /api/feeds/meta — Meta/Facebook Catalog CSV
- GET /api/feeds/quality — JSON quality report for missing identifiers, images, brand, condition, and variant grouping