Sincronización de inventario

Mantén las existencias al día sin subir archivos a mano: StockAI lee tu base de datos (solo lectura), recibe lo que tu sistema le envía o toma el archivo que tu ERP deja en una carpeta SFTP o S3, siempre con vista previa y freno de seguridad.

Sincronización de inventario se abre desde el menú … de Inventario. Hay tres formas de alimentar el stock y las tres terminan en el mismo lugar:

• Una base de datos que StockAI lee cada cierto tiempo (tabla, vista, consulta o colección de MongoDB).
• Tu sistema envía los datos (push) a una dirección de la API.
• Una carpeta de archivos (SFTP o un bucket S3 o compatible) donde tu ERP deja un archivo de existencias.

Existencias: el estado de un vistazo

El panel de arriba aparece en cuanto tienes al menos una sincronización o una carpeta de existencias. Responde dos preguntas: ¿está al día el stock? y ¿hay algo esperando a una persona? Se actualiza solo cada minuto.

Existencias: al día

Todas las fuentes entregaron datos a tiempo.

Existencias: esperando datos

Las fuentes están configuradas pero todavía no llegó nada.

Existencias: requiere tu atención

Algo necesita una decisión. Tus existencias no cambian mientras tanto.

Existencias: detenida

Una sincronización está detenida y esa fuente no se actualiza.

datos al …

La fecha de los datos más recientes.

Debajo, una línea por asunto pendiente: Archivo en espera (con «Revisar archivo»), Detenida, Sin acceso, Atrasada o Filas rechazadas (con «Ver sincronización»). «Fuentes (N)» despliega cada fuente con su origen (Base de datos, Carpeta de archivos o Envío desde tu sistema), su estado, su última corrida (nuevas, actualizadas, rechazadas) y los archivos de los últimos 7 días.

Carpetas de archivos (SFTP y S3)

Tu equipo o tu ERP deja un archivo en una carpeta y StockAI lo lee solo. Antes de reemplazar tus datos compara el archivo con el anterior: si está vacío, cambió de columnas o trae muchas menos filas, lo deja en espera para que decidas. Solo lee y mueve archivos: los terminados pasan a la carpeta processed (los rechazados a rejected, con una nota del motivo). Un archivo se lee cuando terminó de subirse: dos revisiones seguidas deben ver el mismo tamaño y tener al menos un minuto. Puedes tener hasta 10 carpetas.

Agregar una carpeta de existencias

1. Pulsa «Agregar carpeta» (solo administrador).
2. Escribe un Nombre y elige el Tipo: SFTP o «S3 o compatible (MinIO, R2, GCS)».
3. Para SFTP: Servidor, Puerto (22), Usuario, Contraseña o Llave privada (opcional) (si la pegas, se usa en lugar de la contraseña) y Carpeta. Para S3: Bucket, Prefijo (carpeta dentro del bucket), Dirección del servicio (vacía para Amazon S3; para MinIO, R2 u otro, su dirección completa), Región, Clave de acceso y Clave secreta.
4. En «Qué alimenta» elige Existencias. (La otra opción, «Datos (ventas, catálogos)», reemplaza un archivo ya cargado en Archivos y conserva su mapeo.)
5. Nombres de archivo: con Existencias el patrón pasa a * (cualquier archivo de existencias que escriba tu ERP); puedes restringirlo, por ejemplo existencias_*.csv, y separar varios con comas.
6. Revisar cada (minutos): cada cuánto mira la carpeta (mínimo 5).
7. «Qué trae cada archivo»: Todo el inventario (cada archivo es la foto completa; un producto que falta no se pone en cero, se deja como estaba) o Solo lo que cambió (cada archivo trae algunos productos; los demás no se tocan).
8. «Cada cuánto llega un archivo»: cada hora, cada 4 horas, cada 12 horas, una vez al día o una vez a la semana. Si pasa el doble de ese tiempo sin archivo, StockAI avisa que las existencias están atrasadas.
9. Pulsa Guardar. Verás «Carpeta agregada. Pruébala…».

La carpeta en la lista

Cada carpeta muestra su tipo y servidor o bucket, el patrón, qué alimenta y el modo; para existencias, «Cada cuánto llega un archivo» (el administrador lo cambia ahí mismo) y si espera el primer archivo o tu confirmación. Después, el estado: Sin revisar, Al día, Con fallos o Detenida, si está en pausa, y la última revisión. Con SFTP, la llave del servidor fijada.

Revisar ahora

Mira la carpeta en ese momento: «Revisión lista: N aplicados, N en espera, N esperando a terminar de subirse». Un archivo recién dejado suele quedar «esperando» en la primera revisión y se lee en la siguiente.

Probar conexión

«Conexión correcta: N archivos a la vista, M coinciden con el nombre» y los permisos que necesita la cuenta, nada más. Con SFTP fija la llave del servidor la primera vez; si cambia después, la carpeta se detiene y aparece «Aceptar nueva llave» (confírmalo antes con quien administra el servidor).

Pausar / Reanudar

Deja de revisar la carpeta sin borrarla.

Eliminar

StockAI deja de revisarla. Los datos ya cargados y los archivos de tu servidor no se tocan.

El primer archivo: confirmar qué significa

El primer archivo de una carpeta de existencias solo propone: queda en espera con lo que StockAI entendió, y nada cambia hasta que lo confirmes. En Archivos recientes aparece «En espera — Primer archivo: confirma qué columna es cada dato antes de cargarlo» con el botón «Revisar y confirmar».

1. Pulsa «Revisar y confirmar». Arriba ves el archivo, cuántas filas, el formato (CSV, codificación, separador u hoja de Excel) y cuántas bodegas trae.
2. Lee los avisos: columnas obligatorias que faltan, columnas dudosas, punto ambiguo, guiones en la existencia, códigos convertidos a notación científica por Excel, filas repetidas o con existencia negativa (se rechazarán) y filas sin código (se ignoran).
3. Revisa a qué columna corresponde cada dato. Código (SKU) y Existencia son obligatorios; los demás (Bodega, Existencia mínima, Costo unitario, Precio de venta, Proveedor, Días de entrega, Categoría, Marca, Unidad de medida, Código de barras, Nombre) son opcionales: elige «— No está en el archivo —» si no vienen. «Lo dedujimos por el contenido: confírmalo» marca una columna adivinada por sus valores. Una misma columna no puede significar dos datos.
4. Si los números traen un punto ambiguo, responde «¿Qué significa el punto en los números?»: «Es decimal (1.250 = uno coma veinticinco)» o «Separa miles (1.250 = mil doscientos cincuenta)». Sin respuesta no se puede confirmar.
5. Si algunas existencias son un guion, decide con «Un guion en la existencia significa cero».
6. Si el archivo no trae columna de bodega, escribe la «Bodega para todas las filas» o déjala vacía para usar la principal.
7. Revisa «Así leímos las primeras filas» y pulsa «Confirmar y cargar existencias».

Al confirmar verás «Listo: se cargaron las existencias de …. Los siguientes archivos entran solos.». La confirmación crea una sincronización con el nombre de la carpeta (aparece en Sincronizaciones) con ese mapeo; desde ahí cada archivo nuevo pasa por el freno de seguridad sin preguntar. Como la alimenta la carpeta y no una base de datos, esa sincronización se muestra como «Recibe datos por envío (push)» y no tiene vista previa, doctor ni «Sincronizar ahora»: para traer un archivo nuevo usa Revisar ahora en la carpeta.

Archivos en espera, frenados o rechazados

Cada archivo de Archivos recientes tiene su estado: Aplicando, Aplicado, En espera, Rechazado o Falló, con el motivo. «No se pudo mover a processed» avisa que la cuenta no tiene permiso de mover (el archivo no se vuelve a aplicar igual). Los motivos más comunes de una espera:

Faltan columnas que la sincronización usa

Tu ERP renombró columnas. «Revisar y confirmar» abre «Las columnas del archivo cambiaron»: indica cuáles son ahora y pulsa «Guardar columnas y aplicar». Se conserva el formato de números confirmado. Tus existencias no se tocaron.

El freno de seguridad lo detuvo

El archivo cambiaría demasiado de golpe (muchos productos desaparecen, muchas menos filas, muchas filas rechazadas o saltos enormes de cantidad).

Los números cambiaron de formato decimal

Los archivos anteriores usaban otra convención.

Es más antiguo que el último archivo aplicado

Aplicarlo volvería atrás las existencias.

La sincronización de este archivo está apagada / en pausa

Enciéndela en Sincronizaciones.

Para un archivo en espera sin análisis, los botones son «Aplicar igual» y Rechazar (lo rechaza una persona y queda registrado). Para uno con análisis, «Revisar y confirmar» y Rechazar.

Sincronizaciones

La lista de sincronizaciones muestra cada una con su nombre, qué lee (o «Recibe datos por envío (push)»), el último éxito y su estado: Al día, Sincronizando…, Detenida por el freno, Sin éxito reciente, Falló la última vez, Apagada, En pausa o Bloqueada. Sin ninguna base de datos conectada verás «Primero conecta una base de datos» con el enlace «Ir a mis fuentes de datos» (Archivos y fuentes); igual puedes usar las carpetas de archivos.

El detalle de una sincronización

Último éxito / Próxima ejecución

Cuándo terminó bien por última vez y cuándo vuelve a correr («Sin programar (apagada)» si está apagada).

Campos que manda la fuente

Los datos que esta sincronización trae. Regla de conflictos: manda la fuente. Si alguien edita uno de esos campos a mano en StockAI, la próxima sincronización lo reemplaza y se avisa en la actividad.

Salud

Sin ejecutar, Sana, Con problemas, En pausa o Bloqueada, con el motivo y «Qué hacer:». «Revisar conexión» abre el doctor y «Copiar diagnóstico» copia un resumen sin contraseñas para soporte.

Vista previa (sin escribir)

Lee la fuente y dice qué se crearía, actualizaría, quedaría igual, se rechazaría o se excluiría por filtro, y si el freno la detendría. No escribe nada.

Encender / Apagar

Una sincronización nueva o editada queda apagada hasta revisar su vista previa.

Sincronizar ahora

Corre una vez ya. El resultado aparece en el historial.

Editar / Eliminar

Eliminar borra la sincronización y su historial; tu inventario queda exactamente como está.

Si el freno de seguridad detuvo la última corrida verás «El freno de seguridad detuvo la última sincronización» con el motivo: no se cambió nada. Si el cambio es real (cerraste una bodega, depuraste el catálogo), «Aplicar de todos modos, una vez» corre una sola vez sin freno y queda registrado quién lo hizo.

Historial de ejecuciones y detalle

Cada corrida con Inicio (y qué la disparó), Resultado (Bien, Falló, Frenada, En curso), Leídas, Creadas, Actualizadas, Sin cambios, Rechazadas y Duración; debajo, ediciones manuales reemplazadas y productos que ya no están en la fuente. Un clic en la fecha abre el «Detalle de la ejecución»: el motivo de una falla con qué hacer y si se reintenta sola, avisos, las filas rechazadas con su motivo y «Descargar filas rechazadas (CSV)».

El doctor de conexión

«Revisar conexión» prueba paso por paso (red, acceso, permisos, lectura, captura de cambios) y dice en qué paso falla, con qué hacer. Termina en «Todo en orden (N ms)» o «Falla en el paso: …». «Copiar diagnóstico» y «Copiar JSON» dan algo que puedes mandar a soporte: no incluye contraseñas ni datos de tus productos.

Nueva sincronización desde una base de datos

Necesitas una base de datos conectada en Archivos › fuentes de datos (ver Fuentes SQL). Pulsa «Nueva sincronización» y sigue cuatro pasos:

1. Base de datos

Nombre y Base de datos. Si no está conectada, la pantalla lo dice.

2. Qué leer

Una tabla o vista (con las que más parecen tener existencias marcadas arriba), Una consulta (solo lectura), Una colección o Una agregación (MongoDB), o Tu sistema envía los datos (push). Las recetas de ERP rellenan una consulta probada para tu sistema. Con consulta o colección, «Leer columnas».

3. Columnas

Proponemos qué columna es cada dato con una confianza (alta, media, baja) y ejemplos de valores: tú confirmas. Cada campo tiene Transformaciones: Multiplicar por (cajas de 12 → 12), cómo leer números escritos como texto, mayúsculas, valor si viene vacío y traducir valores (01=Norte). Filtros: solo se sincronizan las filas que los cumplen.

Bodegas y proveedores de tu sistema

Qué hacer si una fila trae una bodega que StockAI no tiene (crearla, rechazar la fila o asignarla a la bodega por defecto) y, opcionalmente, una tabla maestra de bodegas y otra de proveedores. Nunca se borra una bodega.

4. Frecuencia y reglas

Cómo se calcula la existencia (Foto, Suma de varias filas o Libro de movimientos), Qué tan al día (Programada, Continua o Solo a pedido), Cómo detectar cambios, Prioridad, Clave para la API, Cómo leer (todo o incremental), Cada cuántos minutos, qué hacer si un producto desaparece (no hacer nada, recomendado; marcarlo como faltante; o ponerlo en 0), existencias negativas, repetidos, Bodega si la fila no la dice, Crear bodegas nuevas y el Freno de seguridad (máx. % de productos que pueden desaparecer, mín. filas vs. la última vez, máx. % de filas rechazadas, salto máximo de cantidad).

1. Completa los cuatro pasos.
2. Pulsa «Vista previa (sin escribir)» para ver qué pasaría.
3. Pulsa «Guardar y ver vista previa». Guardar no sincroniza nada: queda apagada.
4. Revisa la vista previa de lo guardado y pulsa Encender.

Para desarrolladores

Panel plegable (analista o administrador) con cuatro pestañas:

Recetas

Permisos de solo lectura listos para copiar por motor, una vista de ejemplo, consultas para ERP conocidos y ejemplos de envío (push) desde otros sistemas, con las direcciones IP desde las que se conecta StockAI.

Probar transformaciones

Elige un campo, escribe un valor (por ejemplo 1.250) y prueba el multiplicador, el formato decimal, las mayúsculas y la traducción de valores sin tocar nada.

Perfil como código

El JSON de la sincronización seleccionada: Validar, probar sin aplicar, Aplicar, copiar y ver el esquema.

Referencia

Explicación de modos, frescura, modelos, libro de movimientos, freno, conflictos, idempotencia, transformaciones, envío y límites.

Límites conocidos

Al final, «Límites conocidos» lista lo que la sincronización no hace a propósito y qué usar en su lugar; por ejemplo: no lee el log de replicación de PostgreSQL ni el binlog de MySQL (usa el envío con Debezium), no lee con NOLOCK en SQL Server, una réplica atrasada devuelve stock viejo, las estrategias incrementales no ven filas borradas hasta la siguiente conciliación completa y las existencias nunca quedan negativas.