Contrato de Datos MVP · NDA

Sección 01

Tesis del contrato

FARO Connect no puede operar sin datos. Pero el costo de pedirle todo a una empresa al inicio mata el piloto. El contrato MVP resuelve esa tensión.

Tres principios que sostienen el contrato:

Mínimo viable real. Solo 21 campos obligatorios distribuidos en 3 archivos. Cualquier empresa con un ERP básico los tiene.
Tolerancia a la realidad. Alias amplios (cliente_id puede llegar como customer_id, id_cliente, cod_cliente...). FARO normaliza al importar.
Trazabilidad inmutable. El dato crudo (RAW) nunca se modifica. Todo lo que FARO calcula queda versionado con linaje completo.

El contrato es la frontera entre la empresa cliente y FARO. Bien definido, el piloto arranca en una semana. Mal definido, se vuelve un proyecto de integración eterno.

Sección 02

Tres dominios MVP

Los tres mínimos para que FARO pueda detectar la tensión TNS-001 (Crecimiento no rentable, alias "Crecimiento no rentable") — la tensión más común y la que valida la tesis de pipeline determinístico.

01 CRÍTICO

📈 Ventas

Movimientos comerciales con cliente, producto, sucursal, importe, descuentos y costo. Habilita ~140 KPIs del bloque comercial/margen.

17 columnas 9 obligatorias

02 CRÍTICO

📦 Stock

Foto de inventario por SKU y sucursal con valor, rotación, días de cobertura. Habilita ~80 KPIs del bloque stock/abastecimiento.

13 columnas 6 obligatorias

03 CRÍTICO

💰 Cobranza

Facturación pendiente y cobrada con vencimientos, saldos y estado. Habilita ~60 KPIs del bloque cobranza/caja/crédito.

14 columnas 6 obligatorias

Con solo estos 3 dominios, FARO Connect cubre los espacios donde más decisiones ejecutivas se toman semanalmente. El resto (compras, RRHH, gastos, proyectos) entra en versiones siguientes y no es bloqueante para arrancar.

Sección 03

Pipeline de ingreso

Qué le pasa a un archivo cuando entra a FARO. 7 estaciones desde el upload hasta que dispara una tensión.

UPLOAD

xlsx/csv

RAW

inmutable

VALIDA

reglas + alias

STAGING

normalizado

MAESTROS

clientes / productos

FACTS

KPIs calculados

TENSIONES

detectadas

El paso RAW inmutable es la columna vertebral de la auditoría. Si una tensión se dispara, podemos volver al archivo original byte por byte y demostrar de dónde salió el dato. Sin este eslabón, FARO no es defendible ante CFO/auditor.

Sección 04 · Dominio 1

📈 Ventas — estructura

17 columnas. 9 obligatorias para que FARO pueda calcular margen, conversión, ticket promedio, mix de productos.

Campo	Obligatorio	Tipo	Descripción
fecha	OBLIG	YYYY-MM-DD	Fecha de la venta
factura_id	OBLIG	string único	Identificador único de factura
cliente_id	OBLIG	string	ID interno del cliente
cliente_nombre	opc	string	Razón social (ayuda a normalizar)
producto_id	OBLIG	string	SKU o ID del producto
producto_nombre	opc	string	Descripción
sucursal_id	OBLIG	string	Sucursal donde se realizó la venta
vendedor_id	opc	string	ID del vendedor
cantidad	OBLIG	numérico	Unidades vendidas
precio_unitario	OBLIG	numérico	Precio antes de descuentos
descuento_pct	opc	0-100	Porcentaje de descuento aplicado
importe_bruto	OBLIG	numérico	cantidad × precio_unitario
importe_neto	OBLIG	numérico	Después de descuento
costo_unitario	OBLIG	numérico	Costo al momento de la venta. Sin esto no hay margen ni TNS-001.
moneda	opc	ISO 4217	Default ARS
canal	opc	string	Físico, e-commerce, mayorista...
condicion_pago	opc	string	Contado, 30, 60, financiado

Sección 05 · Dominio 2

📦 Stock — estructura

13 columnas. 6 obligatorias. Foto de inventario que permite calcular rotación, cobertura, sobrestock, quiebres.

Campo	Obligatorio	Tipo	Descripción
fecha_corte	OBLIG	YYYY-MM-DD	Fecha de la foto de inventario
producto_id	OBLIG	string	SKU del producto
producto_nombre	opc	string	Descripción
sucursal_id	OBLIG	string	Sucursal o depósito
stock_unidades	OBLIG	numérico	Unidades disponibles a esa fecha
stock_valor	OBLIG	numérico	Valor monetario (unidades × costo)
costo_unitario	OBLIG	numérico	Costo unitario vigente
categoria_abc	opc	A / B / C	Clasificación ABC del producto
rotacion_anual	opc	numérico	Vueltas/año (FARO lo calcula si falta)
dias_cobertura	opc	numérico	Días de cobertura al ritmo actual
stock_minimo	opc	numérico	Punto de reposición
stock_maximo	opc	numérico	Tope superior
observaciones	opc	string	Notas (quiebre, vencimiento próximo, etc)

Sección 06 · Dominio 3

💰 Cobranza — estructura

14 columnas. 6 obligatorias. Cuentas a cobrar con vencimientos y estado, alimenta tensiones de mora, riesgo crediticio y caja.

Campo	Obligatorio	Tipo	Descripción
factura_id	OBLIG	string	ID factura (matchea con Ventas)
cliente_id	OBLIG	string	ID del cliente
cliente_nombre	opc	string	Razón social
fecha_emision	OBLIG	YYYY-MM-DD	Fecha de emisión
fecha_vencimiento	OBLIG	YYYY-MM-DD	Fecha de vencimiento
fecha_pago	opc	YYYY-MM-DD	Fecha real de pago (vacío si pendiente)
importe_factura	OBLIG	numérico	Importe total
importe_pagado	OBLIG	numérico	Importe efectivamente cobrado
saldo	OBLIG	numérico	importe_factura - importe_pagado
dias_vencido	opc	numérico	Días vencidos si saldo > 0
estado	OBLIG	enum	Pagada / Pendiente / Vencida / Incobrable
medio_pago	opc	string	Efectivo, transferencia, cheque, tarjeta
moneda	opc	ISO 4217	Default ARS
observaciones	opc	string	Notas

Sección 07

Reglas de validación

Qué chequea FARO al importar. Errores duros (rechazo) vs. warnings (importa pero advierte).

IDs únicos por dominio

RECHAZO

No se permite cliente_id, producto_id o factura_id duplicados. Si aparecen, la fila se rechaza y queda log con motivo.

Fechas en formato YYYY-MM-DD

RECHAZO

Sin excepciones. Las fechas en formato local (DD/MM/YYYY) deben convertirse antes de subir. FARO no adivina formato.

Montos sin separadores de miles

RECHAZO

Usar punto decimal. 1234.56 ✅ · 1.234,56 ❌. El locale argentino confunde el parser.

Coherencia bruto/descuento/neto

WARNING

FARO valida que importe_neto ≈ importe_bruto × (1 - descuento_pct/100) con tolerancia ±1%. Si no cuadra, recalcula y deja advertencia.

Costo unitario null

WARNING

Importa la fila pero deshabilita los KPIs de margen. Aparece banner: "No se puede calcular margen sin costo_unitario".

Importe pagado > importe factura

RECHAZO

Inconsistencia contable. Frecuente en sistemas que mal-mapean retenciones. FARO no la deja pasar.

Sección 08

Alias soportados

FARO reconoce nombres de columna comunes y los mapea al canónico. No requiere que el ERP del cliente cambie nada.

cliente_id

cliente, customer_id, id_cliente, cod_cliente, ClienteID, cust_id

cliente_nombre

cliente, razon_social, customer_name, nombre_cliente

producto_id

producto, sku, item_id, codigo, cod_producto, ProductoID

producto_nombre

producto, descripcion, item_name, articulo, nombre_producto

fecha

date, fecha_factura, fec, fechaventa, fecha_operacion

cantidad

qty, units, cant, q

precio_unitario

precio, price, pu, precio_unit, valor_unit

importe_neto

neto, total, monto, importe, total_factura

costo_unitario

costo, cost, cu, costo_unit, valor_costo

sucursal_id

sucursal, branch, deposito, store_id, local

vendedor_id

vendedor, seller_id, user_id, asesor, vend_id

factura_id

factura, invoice_id, comprobante, nro_factura, FacturaNro

Sección 09

Dataset demo — Empresa Demo

Las plantillas vienen con 110 filas sintéticas que dispararán automáticamente las tensiones MVP cuando se importen.

Prototipo · datos sintéticos

Qué dispara el dataset demo

Empresa Demo: distribuidora de materiales de construcción, 3 sucursales, ~65 empleados, facturación anual USD 2.4M.

TNS-001 · Crecimiento no rentable — ventas crecen +12% MoM pero el margen baja -8 puntos por descuentos crecientes (alias: "Crecimiento no rentable")
TNS-002 · Concentración de cartera — top 3 clientes = 51% facturación últimos 60 días
TNS-051 · Stock fuera de ritmo — SKUs A (P001/P002) con rotación 1.5-2.2 vs objetivo 3.5 vueltas/año
TNS-XXX · Riesgo de quiebre — P005 alta rotación en 0 unidades, sin pedido pendiente
TNS-XXX · Cobranza vencida elevada — 8/30 facturas vencidas, 2 en categoría incobrable (>90 días)

El motor está diseñado para procesar este dataset y disparar las 5 tensiones de extremo a extremo. Tiempos exactos a confirmar en pilotos.

Sección 10

Contrato de salida hacia el motor

Una vez normalizado, FARO emite eventos estructurados al motor de tensiones + IA explicativa.

Evento canónico de venta

POST /faro/events/sales
{
  "company_id": "uuid-empresa-demo",
  "event_id": "uuid-evento",
  "source": {
    "raw_import_id": "uuid-raw",
    "row_hash": "sha256:..."      // trazabilidad inmutable
  },
  "venta": {
    "factura_id": "FAC-2026-1042",
    "fecha": "2026-05-15",
    "cliente_id": "C002",
    "producto_id": "P001",
    "sucursal_id": "S001",
    "cantidad": 24,
    "importe_neto": 183600.00,
    "costo_total": 163200.00,
    "margen_pct": 11.1                // calculado
  },
  "linaje": {
    "ingested_at": "2026-05-28T10:32:14Z",
    "normalized_by": "faro-etl-v1.0",
    "validations_passed": ["unique_id", "date_format", "bruto_neto_match"]
  }
}

Sección 11

Reglas para la IA explicativa

Qué puede y qué NO puede hacer la IA cuando explica una tensión. Regla maestra: si el dato no está en el payload, la IA no lo inventa.

Permitido

Resumir patrones detectables sobre los datos que están en RAW/Staging.
Sugerir hipótesis explicativas marcadas como hipótesis, no como hechos.
Recomendar acciones del catálogo ACT-001..300 cuando hay match con tensión activa.
Citar fuentes con linaje (ej. raw_import_id: uuid).

Prohibido

Inventar valores que no están en el payload (ej. estimar costos si no hay costo_unitario).
Atribuir causalidad a datos externos al sistema sin marcarlo.
Recomendar acciones fuera del catálogo canónico.
Citar tensiones, KPIs o acciones con códigos que no existen en la biblioteca.

Toda invocación a la IA se audita en ai_requests + ai_responses con el modelo usado, los tokens, el costo y la latencia. Costo controlado y auditoría completa de cada invocación.

Sección 12