Store apps
Hosted Shopify, Salla and Zid apps: OAuth install, webhooks, embedded admin.
5 نقاط وصول. أسماء نقاط الوصول وأوصافها مأخوذة من ملف OpenAPI، لذلك تظهر بالإنجليزية.
GET /v1/connectors/{platform}/installGET /v1/connectors/{platform}/oauth/callbackPOST /v1/connectors/{platform}/webhooksPOST /v1/connectors/{platform}/sessionGET /v1/connectors/{platform}/storefront
/v1/connectors/{platform}/installStart the app install: redirect to the platform's OAuth consent page
المعاملات
| الاسم | الموضع | النوع | إلزامي | الوصف |
|---|---|---|---|---|
platform | path | "shopify" | "salla" | "zid" | نعم | |
shop | query | string | null | لا | Shopify: <name>.myshopify.com · max length 255 |
الردود
- 302Redirect to the platform (install) or to the embedded admin (callback)
/v1/connectors/{platform}/oauth/callbackOAuth callback: check state + signature, store tokens, create or link the tenant
المعاملات
| الاسم | الموضع | النوع | إلزامي | الوصف |
|---|---|---|---|---|
platform | path | "shopify" | "salla" | "zid" | نعم |
الردود
- 302Redirect to the platform (install) or to the embedded admin (callback)
/v1/connectors/{platform}/webhooksPlatform webhooks: products, app uninstalled, Shopify GDPR topics (signature checked)
Shopify sends the topic in `X-Shopify-Topic`: products/create|update|delete, app/uninstalled, customers/data_request, customers/redact, shop/redact (mandatory GDPR webhooks). SeekGist stores no shopper personal data, so the customer topics are answered 200 and logged; shop/redact deletes the tenant's data (same job as POST /v1/data/requests kind=delete). Answer within 5 s; do the work in a job.
المعاملات
| الاسم | الموضع | النوع | إلزامي | الوصف |
|---|---|---|---|---|
platform | path | "shopify" | "salla" | "zid" | نعم |
الردود
- 200Successful Response
WebhookAck
/v1/connectors/{platform}/sessionEmbedded admin: exchange the platform session token for a SeekGist session
Sets the `sg_session` cookie (SameSite=None; Secure, because the admin runs inside the platform's iframe) for the store's tenant, with role owner, valid 1 hour. CSRF works as for the dashboard.
المعاملات
| الاسم | الموضع | النوع | إلزامي | الوصف |
|---|---|---|---|---|
platform | path | "shopify" | "salla" | "zid" | نعم |
جسم الطلب application/json StoreAppSessionRequest
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
token | string | نعم | Shopify: App Bridge session token (JWT, HS256, signed with the app secret). Salla / Zid: the token their embedded page gives the app.min length 20 · max length 4000 |
الردود
- 200Successful Response
LoginResult
/v1/connectors/{platform}/storefrontStorefront script config: the shop's public key and on/off switch
Called by the store-app storefront script (theme app extension / app snippet) before it starts the widget. Returns only public data: the public key is meant for browsers and is locked to the shop's origins. Unknown or switched-off shops get `enabled: false`. Cached (`Cache-Control: public, max-age=30`).
المعاملات
| الاسم | الموضع | النوع | إلزامي | الوصف |
|---|---|---|---|---|
platform | path | "shopify" | "salla" | "zid" | نعم | |
shop | query | string | نعم | Shopify: <name>.myshopify.com; Salla / Zid: store id · min length 1 · max length 255 |
الردود
- 200Successful Response
StorefrontConfig
أشكال البيانات في هذه الصفحة
WebhookAck
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
ok | boolean | لا | default true |
StoreAppSessionRequest
Embedded admin: trade the platform's short-lived session token for a SeekGist dashboard session.
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
token | string | نعم | Shopify: App Bridge session token (JWT, HS256, signed with the app secret). Salla / Zid: the token their embedded page gives the app.min length 20 · max length 4000 |
LoginResult
On success the API sets the `sg_session` cookie (HttpOnly, Secure, SameSite=Lax) and returns the CSRF token, which the web app sends back as `X-CSRF-Token` on every write.
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
status | "ok" | "mfa_required" | "email_sent" | نعم | |
user | UserOut | null | لا | |
csrf_token | string | null | لا | |
weak_password | boolean | لا | Password sign-in only: the password is on the breached-password list or no longer meets the rules. Sign-in still works; ask the user to change it (POST /v1/auth/password/change).default false |
UserOut
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
id | string | نعم | |
email | string | نعم | |
name | string | null | نعم | |
locale | "en" | "ar" | نعم | |
email_verified | boolean | نعم | |
totp_enabled | boolean | نعم | |
is_superadmin | boolean | نعم | |
memberships | MembershipOut[] | نعم |
MembershipOut
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
id | string | نعم | |
tenant_id | string | نعم | |
tenant_name | string | نعم | |
tenant_slug | string | نعم | |
role | "owner" | "admin" | "editor" | "viewer" | نعم |
StorefrontConfig
What the store-app storefront script needs to start the widget. `enabled: false` (unknown shop, app uninstalled or switched off in the embedded admin) means: leave the store's own search alone.
| الاسم | النوع | إلزامي | الوصف |
|---|---|---|---|
enabled | boolean | نعم | |
key | string | null | لا | The store's public key (sg_pub_...), safe in a browser. |
locale | string | لا | default "en" |
suggest | boolean | لا | default true |
search | boolean | لا | default true |
assistant | boolean | لا | default false |