Integración bilateral
de inventario
Espejo de inventario en tiempo real entre SEO (ERP: facturación electrónica, contabilidad, inventario, centro de costos, POS) y NodoTech (POS + bandeja de entrada con agente de IA autónomo). Un solo stock, dos sistemas, cero descuadres.
Un inventario, espejado en ambos sistemas
SEO administra el inventario como fuente de verdad para el negocio piloto. NodoTech lo espeja y opera ventas autónomas. Toda venta —ocurra donde ocurra— descuenta en ambos lados, sin doble alimentación.
- Inventario y bodegas
- Contabilidad y centro de costos
- Facturación electrónica
- POS propio
- Agente de IA que cotiza
- Bandeja de entrada autónoma
- POS y ventas por chat
- Espejo del stock de SEO
Regla de oro
Ante cualquier duda, el nivel de stock de SEO es el autoritativo y NodoTech converge a él. Nunca dos deducciones independientes sobre el mismo hecho.
Cómo aislamos cada negocio
NodoTech es multi-tenant: cada negocio es un tenant lógico aislado, identificado por un businessId (UUID). La integración con SEO se ata a ese identificador.
Base única, aislamiento por fila
Una sola base de datos multi-esquema por dominio (inventario/ERP, POS, CRM…). No hay una DB por cliente: toda lectura y escritura se filtra por businessId.
Scope validado en cada petición
El identificador del negocio viaja en cada petición autenticada. Una capa de control valida que la credencial solo pueda tocar los negocios habilitados para ella.
Sedes = bodegas
Dentro de un negocio, cada sede física mapea a una bodega. El stock vive por (producto, bodega), lo que permite sincronizar por sede si SEO lo requiere.
Implicación para SEO
La integración se activa por negocio. La credencial que reciba SEO solo verá el negocio piloto; ampliar a otro negocio es emitir otra credencial.
La API key es el validador de autenticación
El acceso estándar a NodoTech usa sesión de usuario (JWT). Para la integración con SEO habilitamos una superficie dedicada, autenticada y estable, con una API key de servicio por negocio como validador de cada llamada.
- API key máquina-a-máquina por negocio. Una credencial de servicio (no un usuario), con alcance (scopes) acotado a
inventoryysales. Rotable y revocable de forma independiente. - Una API pública y estable para partners. SEO trabaja contra la superficie
/partners/v1, diseñada para integraciones y con contrato estable. La API key fija automáticamente el negocio y aplica el control de acceso, sin acoplar la integración a la mecánica interna de la plataforma. - Webhooks firmados (HMAC). Lo que NodoTech envía a SEO va firmado con un secreto compartido; cada lado verifica la firma antes de aceptar. Impide suplantación y payloads manipulados.
- HTTPS, rate limiting y bitácora. Toda llamada queda auditada (dirección, estado, latencia, error), con límites de tasa por credencial. Patrón ya en producción en nuestros conectores externos.
Cómo se mueve el stock en NodoTech
Stock por producto y bodega
El nivel real vive por (variante de producto, bodega). Un agregado por producto se deriva de la suma de bodegas. Sin columnas de "reservado": es stock físico simple.
Transaccional, con bloqueo de fila
Cada venta descuenta dentro de una transacción con bloqueo pesimista y validación de no-negativo. Resultado: nunca hay sobreventa ni condiciones de carrera entre ventas simultáneas.
Kardex de cada movimiento
Entradas, salidas, ventas, ajustes, devoluciones y transferencias quedan registradas con stock previo y nuevo. Toda variación es auditable.
Fijar stock desde un externo
Existe ya la capacidad de que un sistema externo fije el nivel absoluto de stock de forma idempotente. Este es el gancho natural para que SEO empuje inventario a NodoTech.
Identificación de producto
Cada producto se identifica por SKU y código de barras, únicos por negocio. El SKU será la clave natural para mapear productos entre SEO y NodoTech.
De dónde viene el descuadre (y cómo lo eliminamos)
El riesgo real no es el modelo de stock: es la repetición de eventos (reintentos de red, doble entrega de un webhook). La forma del mensaje decide si eso descuadra o no.
evento: −3 → 9
evento repetido: −3 → 6 ✕ descuadre
Un mismo hecho aplicado dos veces resta de más. Requiere de-duplicación perfecta para ser seguro.
evento: stock=9 → 9
evento repetido: stock=9 → 9 ✓ converge
Reaplicar el mismo valor no hace daño. El sistema converge al nivel autoritativo de SEO.
Decisión de diseño
El intercambio primario es por cantidad absoluta autoritativa: SEO envía el nuevo onHand y NodoTech lo fija. Además, cada mensaje lleva idempotencyKey + occurredAt para descartar duplicados y resolver orden. Doble alimentación: imposible por construcción.
Webhooks bidireccionales + REST idempotente
Reutilizamos un patrón de integración bilateral que ya opera en producción en NodoTech (conectores de marketplace): credenciales cifradas por negocio, tabla de mapeo de productos y bitácora de sincronización. No partimos de cero.
Flujo A · SEO → NodoTech
SEO vende o ajusta stock → llama POST /inventory/sync con el onHand nuevo (o nos notifica por webhook). NodoTech fija el nivel absoluto. Idempotente.
Flujo B · NodoTech → SEO
Venta autónoma (POS o Inbox IA) → evento interno tras confirmar la venta → webhook firmado a SEO → SEO descuenta y (opcional) nos devuelve el nuevo onHand, y convergemos.
Red de seguridad: reconciliación periódica
Un proceso programado compara catálogos y niveles de ambos lados y corrige cualquier deriva, con SEO como autoritativo. Si un webhook se pierde, la reconciliación lo repara sin intervención.
Las dos vías de integración, comparadas
| Opción | Bilateralidad | Esfuerzo | Tiempo | Riesgo descuadre | Veredicto |
|---|---|---|---|---|---|
| A. NodoTech consume la API de SEO | Parcial | Medio (solo nuestro lado) | Corto | Medio | Insuficiente sola |
| B. Web service / eventos webhooks bidireccionales + REST idempotente |
Completa | Medio (reutilizamos patrón) | Corto-medio | Bajo | Recomendada |
Recomendación: Opción B
La opción A por sí sola no cierra el ciclo: cubriría el sentido SEO → NodoTech (con polling), pero no basta para reflejar nuestras ventas del lado de SEO. La opción B es estándar REST + webhooks firmados sobre cantidad absoluta idempotente: cubre ambos sentidos, es de bajo riesgo de descuadre y reutiliza infraestructura ya probada en ambos lados.
Lo que NodoTech expone a SEO
Borrador para evaluación de sus desarrolladores. Autenticación por API key de negocio: Authorization: ApiKey <key>. Scopes: inventory:write, sales:write.
idempotencyKey. Es la vía preferida.{ "idempotencyKey": "seo-evt-8f3a1c92", "occurredAt": "2026-07-22T15:04:05Z", "items": [ { "sku": "CAM-ROJ-M", "warehouseCode": "PRINCIPAL", "onHand": 12 } ] } // 200 → { "applied": 1, "skippedDuplicate": false }
onHand resultante.{ "idempotencyKey": "seo-sale-0012", "occurredAt": "2026-07-22T15:05:00Z", "externalSaleId": "SEO-0012", "warehouseCode": "PRINCIPAL", "lines": [ { "sku": "CAM-ROJ-M", "quantity": 2 } ] }
Lo que NodoTech envía a SEO
Cuando ocurre una venta autónoma en NodoTech, emitimos un webhook firmado hacia el endpoint que SEO nos indique. Reintentos con backoff; SEO responde 2xx como acuse.
Headers X-Nodo-Event: sale.completed X-Nodo-Signature: sha256=<hmac(body, secreto)> { "event": "sale.completed", "idempotencyKey": "nodo-sale-4b7e", "occurredAt": "2026-07-22T15:06:10Z", "businessId": "019df35a-...", "sale": { "id": "POS-3391", "warehouseCode": "PRINCIPAL", "lines": [ { "sku": "CAM-ROJ-M", "quantity": 1, "unitPrice": 45000 } ] } } // también: event "inventory.changed" con el onHand resultante
El equivalente que necesitamos de SEO
- Un endpoint para recibir nuestras ventas o un webhook que nos notifique las suyas (con el
onHandresultante). - Un secreto compartido para firmar/verificar HMAC en ambas direcciones.
- Acuse idempotente: respetar
idempotencyKeypara no doble-procesar reintentos.
Correlacionar los catálogos
Clave: el SKU
Preferimos SKU idéntico como clave natural producto↔producto. Si difieren, mantenemos una tabla de mapeo por negocio (código interno ↔ código externo).
Bodega compartida
Un warehouseCode acordado (p. ej. PRINCIPAL) alinea sedes y bodegas entre ambos sistemas.
Carga inicial
SEO nos envía un snapshot de productos + onHand. Poblamos el mapeo y nivelamos el stock de partida en un solo paso.
Reconciliación continua
Un proceso programado compara onHand de ambos lados y corrige la deriva (SEO autoritativo). Cada sincronización queda en bitácora —dirección, estado, latencia, error— para auditoría y soporte.
Cómo lo ejecutamos
Handshake técnico
Intercambio de documentación y sandbox, definición de SKU y warehouseCode compartidos, secreto HMAC y decisión de opción.
Inbound absoluto · SEO → NodoTech
Emitimos la API key M2M, publicamos POST /inventory/sync y hacemos el bootstrap de catálogo. SEO ya espeja stock en NodoTech.
Outbound firmado · NodoTech → SEO
Webhook sale.completed firmado hacia SEO en cada venta autónoma. Ciclo bilateral completo.
Reconciliación y monitoreo
Proceso de reconciliación contra deriva, bitácora de sincronización y alertas. Operación en régimen.
Qué necesitamos de SEO para arrancar
- Documentación de su API o web service (autenticación, endpoints de inventario y ventas).
- Ambiente de pruebas con credenciales, para integrar sin tocar producción.
- Decisión sobre la opción — recomendamos la B (webhooks bidireccionales + REST idempotente).
Llévate este informe
Descarga esta propuesta completa —diagnóstico de arquitectura y contrato de API— para revisarla con tu equipo de desarrollo en el formato que prefieras.
NodoTech · Grupo HayPlan — web@grupohayplan.com