Instalaciones locales y cloud

Administración desde IstmoAdmin

Configuración → Tienda online permite crear integraciones, rotar/revocar claves, buscar y publicar productos y consultar/rechazar solicitudes recibidas por el POS. La clave recién creada sólo se muestra una vez; no se guarda en el navegador.

Para guardar un puente desde la pantalla, el operador configura COMMERCE_BRIDGE_ENCRYPTION_KEY (64 caracteres hexadecimales aleatorios) y COMMERCE_GATEWAY_ALLOWED_ORIGINS (orígenes HTTPS separados por coma) en el servidor. Las credenciales se cifran con AES-256-GCM y contexto de empresa/sucursal/integración. Respaldar la llave junto con la BD.

Guardar no confirma conectividad. El diagnóstico indica último intento, último ciclo correcto y error. Una pausa sólo queda confirmada tras recibir respuesta del gateway. Los vínculos de COMMERCE_CONNECTORS tienen prioridad y se administran desde el entorno.

Configuración y revocación del puente

Un error de autorización local intenta retirar el catálogo del gateway. Sin conexión, esa actualización puede tardar: la revocación cloud debe hacerse también en el gateway. HTTP 503 indica catálogo aún no sincronizado o servicio pausado. Los rechazos por producto retirado antes de importar no generan pedido POS; posOrderId queda null.

La cola conserva pedidos tras reiniciar. El gateway vuelve a ofrecer pendientes después de 30 segundos para recuperar confirmaciones perdidas y propagar rechazos. Mantener reloj sincronizado, respaldos, política de retención y límites en el proxy HTTPS.

• El operador crea la integración local con los tres scopes y obtiene installationId de GET /api/v1/empresa/connection-identity con sesión autorizada.
• Aprovisionar el servicio Commerce gateway por HTTPS y una base PostgreSQL exclusiva de comercio; no reutilizar la base de licencias.
• COMMERCE_GATEWAY_STORES configura UUID de tienda, binding con installationId/integrationId, siteKey, connectorKey, scopes y enabled. Conservar el binding: no se puede reasignar una tienda existente.
• COMMERCE_CONNECTORS en el entorno POS configura gatewayUrl, el mismo binding, connectorKey y localKey. El conector hace consultas salientes cada 15 segundos y recupera hasta 10 pedidos por ciclo. Requiere reiniciar el proceso.
• Guardar siteKey sólo en el backend de tienda; localKey sólo en POS y connectorKey sólo en gateway/POS. No publicar estos secretos.
• Para revocar inmediatamente, enabled=false en gateway y reiniciar todas sus réplicas. Rotar siteKey actualiza gateway/Vercel; rotar connectorKey actualiza gateway/POS. Configuración → Tienda online permite administrar la integración y guardar el vínculo cifrado; las claves del gateway siguen bajo control del operador.

POS alojado en cloud

La tienda llama por HTTPS al servidor operativo actualizado. La credencial queda restringida a empresa, sucursal, almacén y scopes. La BD de licencias permanece separada de los datos operativos.

Se requiere desplegar pos-server con Commerce, aplicar su migración y aprovisionar la integración. Una página de documentación accesible no demuestra que esos pasos se hayan completado.

POS instalado en el negocio

El servidor local ofrece el mismo contrato dentro de su red después de actualizarlo. Para recibir solicitudes desde una web alojada en Vercel hace falta un gateway de comercio y un conector que establezca conexiones salientes desde el negocio.

El puente está implementado y requiere aprovisionar gateway HTTPS, base dedicada y credenciales de conector. No abrir PostgreSQL, exponer directamente el puerto del POS ni configurar Vercel contra localhost o una IP privada como solución.

Puente saliente: despliegue requerido

El gateway ofrece las mismas cinco operaciones públicas de catálogo, pedidos y checkout-commands, con x-istmo-commerce-key; los endpoints /admin permanecen en el POS. Webhooks firmados opcionales: ver la guía Webhooks. El operador configura el gateway y el conector antes de conectar Vercel.

• Vinculación autorizada entre tienda, empresa e instalación, con credenciales independientes.
• Catálogo completo con bajas explícitas, observedAt y lastSyncAt; durante desconexión puede estar desactualizado.
• Cola durable en gateway y descarga saliente con confirmación de recepción, reintentos e idempotencia.
• Distinguir recibido_gateway de pendiente_confirmacion: sólo el segundo tiene un recibo POS. El id público permanece estable; posOrderId identifica el recibo local.
• Durante desconexión: solicitudes pendientes sin cobro ni promesa de stock. Las ventas físicas siguen funcionando.