واجهة برمجة المتاجر
يوفّر كل متجر ShopKollect الواجهة البرمجية العامة نفسها بصيغة JSON. يستخدمها تطبيق ShopKollect، ويمكنك استخدامها لتطبيقاتك أو تكاملاتك.
العنوان
عنوان المتجر (نطاق فرعي أو نطاق التاجر) متبوعًا بـ /api/v1. مثال:
https://demo.shopkollect.com/api/v1/productsاللغة
ترويسة Accept-Language (fr, en, es, ar)؛ وإلا فلغة المتجر.
الأسعار
بالسنتيمات شاملة الضريبة، مع نسخة منسّقة. يعيد الخادم دائمًا التحقق من الأسعار والمخزون والمواعيد والتركيبات.
المصادقة
الكتالوج والطلب دون حساب. حساب العميل: رمز شخصي «Authorization: Bearer …» يُحصل عليه عند تسجيل الدخول، خاص بالمتجر.
الأخطاء والحدود
الأخطاء {"message", "errors"} (422 تحقق، 401 رمز، 404، 429 طلبات كثيرة). معدل محدود لكل عنوان IP.
OpenAPI
Discovery and shop
GET
/.well-known/shopkollect.json
Shop card: name, logo, colours, languages, currency, modules, API base URL.
GET
/api/v1/shop
Contact details, open / closed state and message, pages (terms, legal notice…).
GET
/api/v1/pickup-slots
Today's pickup times (HH:MM); "required" tells whether a time must be chosen.
Catalogue
GET
/api/v1/categories
Visible categories, with the number of products for sale.
GET
/api/v1/products
Products for sale: prices incl. tax in cents, sale price, images (320 / 640 / 1024 px), stock, "composable".
category category id or slugq search (2 characters min.)sort position, new, price_asc, price_desc, name
GET
/api/v1/products/{slug}
Full product: description, allergens, product page URL.
GET
/api/v1/products/{slug}/composition
Smart Kiosk journey of the product (pages, options, prices, min / max rules): same definition as the kiosk.
Cart and orders
POST
/api/v1/cart/quote
The cart lives in the app: the server returns priced lines (compositions included), the total and per-line errors.
lines [{product: id or slug, quantity, selection?: {page_id: {option_id: quantity}}}]
POST
/api/v1/orders
Places the order (pay on site) → number and tracking token. Same checks as the website: opening hours, stock, pickup time.
lines [{product: id or slug, quantity, selection?: {page_id: {option_id: quantity}}}]name stringphone stringemail stringnote stringpickup_time HH:MM, from /pickup-slotsaccept terms accepted (required)
GET
/api/v1/orders/{number}
Tracking: status (new, preparing, ready, collected, cancelled), pickup time, lines. With the tracking token or the customer token.
token order tracking token
POST
/api/v1/devices
Registers a phone (Firebase token) for "order ready" / "cancelled" notifications, linked to the tracked orders.
token stringplatform android | ioslocale stringorders [{number, token}]
DELETE
/api/v1/devices
Unregisters a phone.
token string
Customer account (per shop)
POST
/api/v1/auth/register
Creates the account → personal token (one per device). A customer who already ordered as a guest keeps their history.
name stringemail stringphone stringpassword stringnewsletter booleandevice_name string
POST
/api/v1/auth/login
Login → personal token. 5 attempts per minute.
email stringpassword stringdevice_name string
POST
/api/v1/auth/password
Forgotten password: sends the same e-mail as the website.
email string
DELETE
/api/v1/auth/token رمز
Logout: revokes the token used.
GET
/api/v1/me رمز
Customer profile.
PUT
/api/v1/me رمز
Updates name, e-mail, phone, newsletter, language, password.
GET
/api/v1/me/orders رمز
Last 50 orders.
GET
/api/v1/me/export رمز
Data export (GDPR), JSON.
DELETE
/api/v1/me رمز
Deletes the account (confirm=true); orders stay with the shop, unlinked from the customer.
confirm boolean