Extensiones e integraciones personalizadas

1. 1

   Servicio de backend externo

   Lo mejor para ERP, tienda web, WMS, BI y sincronización similar. El token se queda en su servidor y los datos se mueven a través de API y webhooks.

2. 2

   Panel de iframe de gabinete

   Construir una página HTML/JavaScript regular utilizando cualquier marco. SelSup lo incorpora en un iframe; no ejecuta su código React dentro del gabinete.

3. 3

   Modulo de backend SelSup

   Requerido para una integración profunda del mercado o de entrega que participe en procesos compartidos de fondo SelSup.

Mantenga el token en un administrador de secretos y llame a SelSup solo desde su backend. Su aplicación de navegador debe hablar con su API y nunca recibir el token SelSup.

Separar el adaptador SelSup, la cola de trabajo y el modelo de dominio. Cambios de contrato API se mantienen aislados del resto de la aplicación.

Utilice una bandeja de entrada para eventos entrantes y una bandeya de salida para cambios salientes. Ambas revistas deben admitir la repetición y la auditoría.

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

Construir una página HTML/JavaScript regular utilizando cualquier marco. SelSup lo incorpora en un iframe; no ejecuta su código React dentro del gabinete.

Alojar el panel en un sitio HTTPS separado que no comparte un dominio de cookies con el gabinete. Abre integraciones → Mis extensiones → Agregar extensión y seleccione un nombre, icono, URL, sección de menú y posición. Guardar un panel privado sin permisos, luego habilitar solo los permisos que necesita. La publicación de la tienda requiere revisión SelSup.

Una integración de mercado normalmente cubre tokens, tarjetas, precios, acciones, pedidos y actualizaciones de estado de fondo.

Este módulo cambia el backend principal de SelSup y sigue su proceso de revisión, prueba, localización y liberación.

Convierta fallos externos de API en valores estables de ApplicationError y tokens externos revocados o inválidos en AccessException de acuerdo con las reglas del proyecto backend.

1. 1

   Crear una cuenta de prueba

   Separar los tokens de prueba, los almacenes, los productos y los pedidos de los datos de producción del cliente.

2. 2

   Añadir observabilidad

   Rastrear retraso en la cola, errores por código, recuentos de retemplajes y discrepancias de reconciliación.

3. 3

   Plan de migración por contrato

   Apoyar campos antiguos durante una transición y desplegar a los consumidores antes de desactivar el formato antiguo.

4. 4

   Desconexión de documentos

   Los usuarios deben saber cómo revocar un token, eliminar un webhook y detener la sincronización sin perder datos.

Seleccione una página de menú (MENU_PAGE), una pestaña de tarjeta de producto (PRODUCT_TAB) o una pestañe de pedidos (ORDER_TAB). La sección de menús y la posición se aplican solo a MENU_PAGE. Las pestañas requieren una entidad guardada con un ID.

Solo se comparten campos de contexto otorgados. USER proporciona user.id y user.locale; CLIENT proporciona client.id; ORGANIZATION proporciona el nombre y el identificador de la organización accesibles. PRODUCT otorga separadamente product.modelId en una tarjeta de producto; ORDER otorga order.id en un pedido. Se excluyen registros completos, contactos, contraseñas y tokens. Estos son identificadores de la página ya abierta, no prueba de acceso para su backend.

{
  "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
    }
  }
]

Verifique el evento.origine exacto, evento.source === window.parent, tipo de mensaje, versión y estructura. Envía listo en la conexión y el contexto de solicitud para actualizar. SelSup revisa el acceso y combina las solicitudes frecuentes. Nunca pase tokens en URL, panel localStorage o mensajes.

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');

El autor declara los métodos requeridos en las configuraciones de extensión. Cada cliente instalador otorga explícitamente métodos de esa declaración. API acceso por defecto a ninguno, incluidas las instalaciones existentes. Cambiar la lista solicitada requiere otra revisión; las copias instaladas nunca obtienen nuevos permisos automáticamente.

El host llama solo a los métodos siguientes a través de los servicios SelSupFront con los permisos de los empleados actuales. Los controles de acceso al servidor existentes todavía se aplican. el servicio cliente y el servicio autor están completamente prohibidos; todos los métodos fuera de esta lista también se niegan. Las aplicaciones no pueden proporcionar URL, encabezados, tokens o configuración arbitraria de Axios. El servidor verifica la instalación actual y sus concesiones en la solicitud real de API.

Las subvenciones API son independientes de los permisos de contexto. context.apiMethods enumera los métodos otorgados. Una subvención se aplica al método en todo el gabinete dentro del acceso del empleado, en lugar de solo la entidad en la pestaña actual. Los resultados contienen solo los campos documentados, nunca objetos o credenciales de Axios.

Una solicitud en vuelo y como máximo una salida por segundo. Las últimas 256 ID de solicitud están protegidas contra duplicados. Errores del host: ACCESS_DENIED, INVALID_REQUEST, ERATE_LIMITED, DUPLICATE_REQUEST, EREQUEST_FAILED. Errors de SDK también incluyen NOT_CONNECTED, DISCONNECTED y TIMEOUT (20 segundos). Nunca vuelva a intentar mutaciones automáticamente: una error, tiempo o cierre de iframe no significa que la operación se haya vuelto a hacer.

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);

La muestra se puede copiar en un repositorio GitHub independiente. Con Node.js 22+, prueba npm y pruebas de inicio npm, y un gabinete de simulación local sin claves API o datos reales. Configure config.js y despliegue cinco archivos estáticos en el alojamiento HTTPS. Descargue el archivo que se enlaza a continuación y copie su contenido en su repositoriu GitHub.

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

La sandbox bloquea los formularios, las ventanas emergentes, las descargas, la navegación superior y las API del navegador sensibles. El origen del panel se muestra por encima del iframe. Una extensión nunca debe solicitar una contraseña SelSup. Su sitio puede ver el IP del visitante y retener o reenviar los datos otorgados a él.

SelSup mismo autoriza llamadas de puente iframe; las cookies y tokens nunca llegan a la aplicación. Su propio backend todavía necesita su propia autenticación: el contexto no prueba la identidad. Solo mantenga tokens SelSup de larga duración en su servidor.