Қосымшалар және жекешелендіру

1. 1

   Сыртқы бакинд қызметі

   ERP, веб-дүкен, WMS, BI және ұқсас синхрондастыру үшін жақсы. Токен серверде қалып, деректер API және веб-хок арқылы өтеді.

2. 2

   Қапшықтың iframe панелі

   Кез келген кадрды пайдалана отырып, әдеттегі HTML/JavaScript беттерін құру. SelSup оны iframe-ге енгізеді; ол сіздің React кодын шкафтың ішінде орындамайды.

3. 3

   SelSup бакинд модулі

   SelSup ортақ фоновый процестерде қатысу үшін терең нарық немесе жеткізу интеграциясы үшін қажет.

Токенді құпия менеджерінде сақтаңыз және SelSup-ге тек сіздің артындағы желіңізден хабарласыңыз. Сіздің браузерлік қолданбаңыз API-пен сөйлесуі және SelSup токенін ешқашан қабылдамауы керек.

SelSup адаптері, жұмыс кезегі және домен моделі бөлектірілсін. API келісімшарт өзгерістері кейін қосымшаның қалған бөлігінен оқшауланады.

Келесі оқиғалар үшін кіріс қорапты және шығыс өзгерістер үшін шығыс қорын қолданыңыз.

SelSup webhook → inbox → domain worker → ERP/WMS
ERP/WMS change → outbox → SelSup API → reconciliation

Кез келген кадрды пайдалана отырып, әдеттегі HTML/JavaScript беттерін құру. SelSup оны iframe-ге енгізеді; ол сіздің React кодын шкафтың ішінде орындамайды.

Панельді Kabinetке cookie доменін бөліспейтін бөлек HTTPS сайтында орналастырыңыз. Ашыңыз Интеграциялар → Менің кеңейтулер → Қосымшаны қосыңыз және атау, таңбаша, URL, мәзір бөлімін және орналасуын таңдаңыз. Әдеттегі панельге рұқсаттары жоқ сақтаңыз, содан кейін оған қажетті рұқсаттарды ғана қосу.

Базардағы интеграция әдетте токендер, карталар, бағалар, қорлар, тапсырыстар және фоновой жай-күйді жаңартуды қамтиды.

Бұл модуль SelSup негізгі аясын өзгертеді және оның тексеру, сынау, жергіліктіकरण және босату процесін орындайды.

API сыртқы қателерін тұрақты ApplicationError мәндеріне және жойылған немесе жарамсыз сыртқы белгілерді AccessException-ке айналдыру.

1. 1

   Сынақ тіркелгісін құру

   Клиенттің өндіріс деректері бойынша сынақ белгілерін, қоймаларды, өнімдерді және тапсырыстарды бөлектеу.

2. 2

   Байқауға қабілеттілікті қосу

   Кезекті кешіктіруді, код бойынша қателерді, қайта сынақтан өткізуді және келісудің қайшылықтарын бақылау.

3. 3

   Шартты көші-қонды жоспарлау

   Өткiрiс кезiнде ескі өрістерді қолдау және ескі форматты өшіруден бұрын тұтынушыларды орналастыру.

4. 4

   Құжаттарды ажырату

   Пайдаланушылар токенді қайтарып алуды, веб-таспаны алып тастауды және деректерді жоғалтпайтын синхрондықты тоқтатуды білуі керек.

Меню бетін (MENU_PAGE), өнім картасы парағын (PRODUCT_TAB) немесе тапсырыс парағын таңдаңыз (ORDER_TAB). Меню бөлімдері мен орналасуы тек MENU_PAGE үшін қолданылады. Парақтарда ID-сі бар сақталған субъекті қажет.

Тек берілген контекст өрістері бөлінеді. USER user.id және user.locale береді; CLIENT client.id береді; ORGANIZATION қолжетімді ұйым ID мен есімін береді. PRODUCT product.modelId-ді өнім картасында бөлек береді; ОРДЕР тапсырыс бойынша order.id-ді береді. Толық жазбалар, байланыс, парольдер және белгілер алынып тасталады. Бұл - сіздің артта тұрған парақтың идентификаторы, бірақ қолжетімнің дәлелі емес.

{
  "type": "selsup.extension.context",
  "version": 1,
  "context": {
    "version": 1,
    "extensionId": "example-extension-id",
    "placement": "MENU_PAGE",
    "user": {"id": 101, "locale": "ru"},
    "client": {"id": 202},
    "organizations": [{"id": 303, "name": "Demo"}]
  }
}

[
  {
    "version": 1,
    "extensionId": "example",
    "placement": "PRODUCT_TAB",
    "apiMethods": [],
    "product": {
      "modelId": 404
    }
  },
  {
    "version": 1,
    "extensionId": "example",
    "placement": "ORDER_TAB",
    "apiMethods": [],
    "order": {
      "id": 505
    }
  }
]

Шешімнің нақты event.origin, event.source === window.parent, хабарлама түрі, нұсқасы және құрылымы. Жаңаландыру үшін қосылым және сұрау-контексті дайын жіберу. SelSup қатынасты қайта тексереді және жиі сұрауларды біріктіреді. URL-терде, localStorage панеліне немесе хабарламаларға ешқашан белгілер жібермейді.

const allowedOrigins = new Set(['https://your-cabinet.example.com']);
window.addEventListener('message', (event) => {
  if (event.source !== window.parent || !allowedOrigins.has(event.origin)) return;
  const message = event.data;
  if (!message || message.type !== 'selsup.extension.context' || message.version !== 1) return;
  const context = message.context;
  if (!context || context.version !== 1 || !['MENU_PAGE', 'PRODUCT_TAB', 'ORDER_TAB'].includes(context.placement)) return;
  // The complete sample also validates fields and strips unknown properties.
  document.querySelector('#context').textContent = JSON.stringify(context, null, 2);
});
for (const origin of allowedOrigins) {
  window.parent.postMessage({type: 'selsup.extension.ready', version: 1}, origin);
}
// Refresh after connecting: use the validated origin, never "*".
window.parent.postMessage({type: 'selsup.extension.request-context', version: 1},
  'https://your-cabinet.example.com');

Автор кеңейту параметрлерінде қажетті әдістерді жариялайды. Әрбір орнатушы клиент бұл декларациядан әдістерге айқын түрде рұқсат береді. API қатынасы қолданыстағы қондырғыларды қоса алғанда, ешқайсысына де әдетті түрде рұқсат етілмейді. Сұралған тізімді өзгерту тағы бір тексеруді талап етеді; орнатылған көшірмелер ешқашан автоматты түрде жаңа рұқсаттарды алмайды.

Веб-сайт сервері қолданыстағы серверге қол жеткізуді бақылауға алады. ClientService және authService толық тыйым салынған; осы тізімнен тыс барлық әдістер де бас тартылады. Қолданбалар URL-тер, басушылар, токендер немесе еркін Axios конфигурациясын бере алмайды. Сервер ағымдағы орнатуды және оның API сұрауы бойынша берілетін гранттарын тексереді.

API гранттары контекст рұқсаттарынан тәуелсіз. context.apiMethods берілген әдістерді тізбелейді. Грант қызметкердің қолжетімділігі ішінде барлық кабинеттегі әдіске қолданылады, тек ағымдағы қойындыдағы субъектіге емес. Нәтижелер тек құжатталған өрістерді, ешқашан Axios объектілері немесе сенімхаттарды қамтиды.

Ұшу кезінде бір сұрау және ең көп дегенде бір старт секунд. Соңғы 256 сұрау ID-лері дубликаттардан қорғалады. Ұстаз қателері: ACCESS_DENIED, INVALID_REQUEST, ERATE_LIMITED, DUPLICATE_REQUEST, REQUEST_FAILED. SDK қателері NOT_CONNECTED, DISCONNECTED және TIMEOUT (20 секунд) кіреді.

tagService.findTags              {query?, page?, limit?}   => {rows: [{id, name}]}
tagService.createTag             {name}                   => {id, name}
tagService.updateTag             {id, name}               => {id, name}
tagService.deleteTag             {id}                     => null
productService.updateFavourite   {id, favourite}          => null

id: positive safe integer; updateFavourite.id = product.modelId
favourite: boolean
name: 1..100 characters (trimmed); query: 0..100 characters
page: 1..10000, default 1; limit: 1..100, default 30

{
  "type": "selsup.extension.api-request",
  "version": 1,
  "requestId": "request-1",
  "method": "tagService.createTag",
  "params": {
    "name": "Demo"
  }
}

{
  "type": "selsup.extension.api-response",
  "version": 1,
  "requestId": "request-1",
  "ok": true,
  "result": {
    "id": 1,
    "name": "Demo"
  }
}

// connection = connectExtension(...) from selsup-extension.js
// Run from a button click after receiving context.apiMethods.
const tag = await connection.callApi('tagService.createTag', {name: 'Demo'});
console.log(tag.id, tag.name);

Үлгі GitHub-тың дербес қоймасына көшірілуі мүмкін. Node.js 22+, npm тест және npm старт тесті және API кілттері немесе нақты деректерсіз жергілікті мокей шкафпен. Config.js-ті баптау және HTTPS хостингке бес статикалық файлды орналастыру. Төмендегі сілтемеленген мұрағатты жүктеңіз және оның мазмұнын GitHub қоймасына көшiртеңіз.

cd selsup-extension-example
npm test
npm start
# Mock host: http://localhost:4174/
# Panel: http://127.0.0.1:4173/

Content-Security-Policy: default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'none'; form-action 'none'; base-uri 'none'; frame-ancestors https://your-cabinet.example.com
Referrer-Policy: no-referrer
X-Content-Type-Options: nosniff

https://api.selsup.ru/assets/examples/selsup-extension-example.zip

Құмдықтар нысандарды, қосқыштарды, жүктеулерді, жоғары навигацияны және сезікті браузерлік API-лерді блоктайды. Панельдің шығу тегі iframe-нің үстінде көрсетіледі. Қосымшасы ешқашан SelSup паролін сұрауға тиіс. Оның сайты әлі де келушінің IP-ін көре алады және оған берілген деректерді сақтай алады немесе қайтарады. Тексеру сыртқы URL-де көрсетілетін кодты тоңазыта алмайды. Тек қажетті рұқсаттарды береді.

SelSup өзі iframe bridge шақыруларына рұқсат береді; cookie-тер мен токендер қолданбаға ешқашан жемейді. Сіздің жеке арттағы аяныңыз әлі де өздерінің куәлігін қажет етеді: контекст жеке басын дәлелдемейді. Тек серверде ұзақ өмір сүретін SelSup токендерін сақтаңыз. Толық тапсырыс/product жазбалары мен инлайн карталар блоктарын қолдамайды.