نقطة النهاية ومرجع الاستجابة
POST/api/shop/sessionإنشاء الجلسة باستخدام سر Bearer
DELETE/api/shop/session/:tokenإبطال - سر حامل (Bearer)
يأتي الاستدعاءان من خادمك الخلفي: يصادق باستخدام mint secret الخاص بعميلك (المُنشأ في لوحة إدارة ADITUS) كرمز Bearer. جلسة واحدة لكل تسجيل دخول هي النمط المعتاد؛ ولا يرى المتصفح إلا الرمز الناتج. المواقع بلا خادم خلفي لا تستخدم نقاط النهاية هذه: ينشئ العنصر جلسة المتصفح بنفسه عبر POST /api/shop/embed-session المقيّد بالنطاق (public-key مع cart-scope="tab").
يمكنك تجربة هذا التدفق الدقيق باستخدام بيانات الاعتماد الخاصة بك فياختبار التكامل. أنشئ الجلسة وركّب المتجر ثم اتبع مسار الشراء.
إنشاء جلسة: الطلب
رأسقيمةمعنى
AuthorizationBearer <mint-secret>mint secret الخاص بعميلك، والذي تم إنشاؤه في وحدة تحكم المشرف الخاصة بـ ADITUS. من جانب الخادم فقط - يجب ألا يتم شحنه مطلقًا إلى متصفح أو حزمة تطبيقات.
Content-Typeapplication/jsonالجسم هو كائن JSON.
Idempotency-Keystring · 8–200 visible ASCII chars · required with redeemVoucherOnMintمطلوب عند ضبط redeemVoucherOnMint على true، ويتكون من 8–200 حرف ASCII ظاهر. احفظ مفتاحًا ثابتًا لمحاولة استرداد واحدة على خادمك واستخدمه مع الطلب نفسه عند إعادة المحاولة. تؤدي إعادة استعماله بمدخلات مختلفة إلى 409 idempotency_conflict. لا ترسل هذا المفتاح أو سرّ إصدار الجلسة من المتصفح.
مجال الجسميكتبمعنى
sharedCartKeystring · optionalتشارك الجلسات المحددة الصادرة بين الخوادم عادةً عبر الهوية الموثوقة. للسلات المجهولة المشتركة يجب على خادمك إصدار الجلسة مع sharedCartKey: مرجع زائر مبهم وثابت مستمد من جلسة الزائر الموثوقة لديه، وليس بريدًا إلكترونيًا. هذا حقل إصدار للخادم فقط، لا تهيئة متصفح ولا سمة HTML. لا تقبل بريدًا أو هوية أو sharedCartKey اعتباطيًا من المتصفح. الإصدار التلقائي من المتصفح وحده لا يتيح مشاركة آمنة؛ يعيد shared دون هوية موثوقة خطأ صريحًا بعدم الدعم، حتى عند حذف النطاق. لا يحتاج العزل الصريح 'tab' إلى sharedCartKey؛ ولا يوجد تراجع صامت.
publicKeystring · requiredالمفتاح القابل للنشر الذي أُنشئت الجلسة من أجله. يجب أن يكون هو نفس المفتاح الذي يتم تركيب الواجهة الأمامية الصغيرة به - يتم التحقق من كل مكالمة متجر لاحقة (403 عند عدم التطابق). يجب أن ينتمي سر حامل هذا المفتاح إلى عميل هذا المفتاح. (Bearer)
emailstring · optionalمستخدم المتجر الذي تعمل فيه الجلسة. يمكنك الحصول عليها من جلسة خادمك المصادق عليها (تسجيل الدخول/ملف تعريف الارتباط SSO أو JWT) - وليس من طلب المتصفح أبدًا، وإلا يمكن للزائر الحصول على جلسة شخص آخر. قم بحذفها لإنشاء جلسة مجهولة: يمكن للزائر تصفح عربة التسوق وملؤها، لكن الواجهة الأمامية الصغيرة تحظر الخطوة التي تلي عربة التسوق حتى يوفر رد الاتصال onUserRequired جلسة مرتبطة بالمستخدم (راجع تدفق المستخدم الاختياري). لا يزال يتم رفض البريد الإلكتروني الحالي ولكن المشوه (400).
externalUserIdstring · optionalمرجع مستخدم ثابت من جلسة خادمك المصادق عليها. يُحفظ مع الجلسة ويُستخدم لنطاق الهوية عند وجوده؛ لا تغيّره عند التجديد ولا تقبله من إدخال متصفح اعتباطي. ليس مصادقة بحد ذاته.
ttlSecondsnumber · optionalمدة الجلسة بالثواني. الافتراضي 20 دقيقة، بحد أقصى 24 ساعة. عند انتهاء صلاحيتها، تُرجع مكالمات المتجر 401 session_expired. عندها أصدر رمزًا جديدًا؛ ومع refreshSession في الإعدادات تطلبه الواجهة المصغّرة تلقائيًا.
eventSlugstring · optionalFixes the journey's entry point server-side: set, the micro-frontend starts directly on this event's article selection; omitted, it starts on the event overview. Because it is part of the session created by your server, the browser cannot manipulate it. Invalid characters yield 400 invalid_event_slug; session creation fails closed for a slug that matches no live event (404 event_not_found) or an event that is closed / not on sale (409 event_not_sellable). No session is issued and there is no fallback to the event overview.
startMode"articles" طريقة بدء الرحلة. يفتح "articles" (الافتراضي) اختيار المقالات؛ ويفتح "home" صفحة بداية الفعالية مع إجراءات الدخول (التذاكر، القسيمة، التشكيلات المتاحة)؛ ويفتح "voucher" نموذج رمز القسيمة أو التذكرة أولًا. يعمل نموذج القسيمة كما هو موضح في «استرداد قسيمة / تسجيل تذكرة». بدون eventSlug يظهر اختيار الفعالية أولًا ويُطبَّق الوضع على الفعالية التي يختارها المشتري.
assortmentstring · optionalRestricts the article start to one assortment of the pinned event (requires eventSlug; ignored for startMode "voucher"). Give the assortment id or its exact name (case-insensitive); hidden assortments are allowed. A selector that matches nothing shows an explicit error in the micro-frontend instead of silently falling back to the full list. Max. 200 characters, else 400 invalid_assortment.
voucherCodestring · optionalرمز قسيمة/تذكرة يسلّمه خادمك مع الجلسة، ويسترده التطبيق افتراضيًا في رحلة جديدة (بعد اختيار الفعالية إذا لم تكن محددة). يظهر الرفض في النموذج أو في إشعار السلة الأولى. مع redeemVoucherOnMint: true يُحجز الرمز على الخادم قبل نجاح إصدار الجلسة، لفعالية محددة ومستخدم معروف. طوله من 1 إلى 100 حرف دون فراغات أو فواصل URL، وإلا 400 invalid_voucher_code.
redeemVoucherOnMintboolean · optional (default false)اضبطه على true فقط عند إنشاء الجلسة من خادم إلى خادم مع voucherCode وeventSlug محدد وبريد إلكتروني لمستخدم معروف وIdempotency-Key. ينشئ الخادم سلة للمستخدم ويحجز القسيمة قبل إصدار الجلسة؛ وتستخدم الواجهة السلة نفسها دون إعادة إنشاء أو حجز. يدعم كلا وضعي البدء ورموز القسائم/التذاكر فقط، ولا يدعم PromotionCode. من دون هذا الخيار يُطبَّق التسليم العادي لـ voucherCode. التسجيل والشراء لازمان لاحقًا.
إنشاء جلسة: الرد (200)
مجاليكتبمعنى
sessionTokenstringرمز غير شفاف (sess_...). قم بتسليمها إلى المتصفح وتمريرها إلى mount() كـ sessionToken؛ ترسلها الواجهة الأمامية الصغيرة كجلسة X-Aditus في كل مكالمة متجر. لا يحتوي على بيانات المستخدم ولا يمكن فك تشفيره.
expiresAtnumberانتهاء الصلاحية كطابع زمني لنظام Unix بالمللي ثانية. معلوماتية بحتة لجدولتك الخاصة - تتفاعل الواجهة الأمامية الصغيرة مع 401 من تلقاء نفسها.
voucherRedeemedboolean · only with redeemVoucherOnMintتكون القيمة true عند نجاح إنشاء جلسة بقسيمة محجوزة. تمتلك الجلسة سلة فيها الحجز وتستخدمها الواجهة المضمّنة؛ لم يكتمل تسجيل التذكرة بعد.
إلغاء الجلسة
DELETE /api/shop/session/:token بنفس سر الحامل - يجب أن ينتمي السر إلى العميل الذي أُنشئت الجلسة من أجله. قم باستدعائه عند تسجيل الخروج حتى يموت الرمز المميز مع جلستك الخاصة. الاستجابة: { "تم إبطاله": صحيح } (أو خطأ إذا كانت الجلسة قد انتهت بالفعل). الإلغاء أمر غير فعال وآمن للحرق والنسيان. (Bearer)
Server-to-server reads
A backend that drives the micro-frontend (a kiosk shell, an onsite shop) usually needs tenant facts before it creates a session: which events exist and are on sale, which languages the shop speaks, which lookup lists and branding apply. Four read endpoints answer that with the same credentials as session creation (Bearer mint secret + X-Aditus-Public-Key header, same rate limit, Cache-Control: no-store). They are whitelisted projections of the Shop API, never a raw passthrough; ?language= (or Accept-Language, default de) picks the language of names. Errors: 400 invalid_public_key, 401 unauthorized, 503 shop_api_not_configured, 502 upstream_error.
EndpointReturns
GET /api/shop/events?language=deEvery event of the tenant: id, slug, name, year, start/end, location, saleState (open · registration_only · closed), the raw flags, showInOverview, languages, icon/logo URLs. Pick the slug for the session from here.
GET /api/shop/configurationTenant facts: mandator, the lookup list names (salutations, countries, titles, cookie consent) and websiteMetricTracking. Login-provider credentials of the tenant are deliberately never included.
GET /api/shop/languagessystemLanguage بالإضافة إلى قائمة لغات المتجر ({ code, name }). هذه هي القيم التي تقبلها سمة culture في الواجهة المصغّرة.
GET /api/shop/branding?images=ONSITE_SHOP_LOGO,…The tenant's Shop theme: styles as a flat key → value map, the theme images with URLs, and (for up to 40 image keys you name (A–Z, 0–9, _ , -)) whether each key exists, its public URL and content type. Image URLs need no auth and can be used directly in your shell. Add &eventSlug=<slug> or &event=<GUID> to scope theme and keys to one event (event-level overrides, event-only keys such as ONSITE_SHOP_HEADER / ONSITE_SHOP_ATTRACT_*); the answer then names the resolved event. Unknown slug → 404 event_not_found, non-GUID → 400 invalid_event, Shop API down → 503 event_unavailable.
الأخطاء واضحة
حالةشفرةمعنى
503session_not_configuredجلسات التضمين غير مهيأة لهذا العميل.
401unauthorizedقيمة mint secret المستخدمة لإنشاء الجلسة غير صالحة أو مفقودة.
400invalid_public_keyقيمة public key المقدمة غير صالحة.
400invalid_emailعنوان البريد الإلكتروني المقدم غير صالح.
400invalid_tokenقيمة session token المقدمة غير صالحة.
429rate_limitedعدد الطلبات كبير جداً. حاولوا مجدداً بعد قليل.
403public_key_invalidتنسيق public key المقدمة غير صالح.
403public_key_unknownلم يتم التعرف على public key المقدمة.
403public_key_origin_unresolvedتعذر تحديد مصدر هذا الطلب.
403public_key_domain_not_allowedالنطاق الذي صدر منه هذا الطلب غير مسموح له باستخدام public key هذه.
401invalid_sessionالجلسة المقدمة غير صالحة.
401session_expiredانتهت صلاحية الجلسة المقدمة.
403session_requires_public_keyتتطلب هذه الجلسة public key.
403session_key_mismatchلا تتطابق public key مع الجلسة.
403anonymous_sessionهذه العملية غير متاحة لجلسة مجهولة الهوية.