Actualizado: 2026-10-19 Markdown Abrir en Claude Abrir en ChatGPT

Emitir desde CSV o Excel

Emite comprobantes desde las filas de un CSV o de un Excel (.xlsx) con una plantilla que indica de qué columna sale cada campo.

Si tu sistema exporta las ventas a una hoja de cálculo, puedes emitirlas desde ahí sin convertirlas a JSON. Escribes una vez una plantilla de mapeo, un archivo JSON que dice de qué columna sale cada campo del comprobante, y el CLI arma los comprobantes a partir de las filas de tu archivo cada vez que emites.

En esta página creas una plantilla de ejemplo, la pruebas sin enviar nada y emites desde un CSV. Después encontrarás cómo se escriben las expresiones, las rutas de los campos y las líneas del comprobante, y qué hacer ante los errores más comunes.

Importante

Ambiente de pruebas: sin validez fiscal. Los ejemplos usan el entorno sandbox.

Inicio rápido#

Estos tres comandos crean una plantilla de ejemplo, la prueban y emiten en el ambiente de pruebas:

ecuafact plantilla nueva factura
ecuafact plantilla probar ejemplo-factura.csv --plantilla mapeo-factura.json
ecuafact --entorno sandbox emitir ejemplo-factura.csv --plantilla mapeo-factura.json --esperar --reporte resultado.csv

plantilla nueva factura crea la plantilla mapeo-factura.json y un archivo ejemplo-factura.csv que la usa. Abre la plantilla, pon tu RUC en infoTributaria.ruc y cambia los nombres de columna por los de tu archivo.
plantilla probar muestra el JSON de cada comprobante que saldría del archivo, sin enviarlo. Si la plantilla está bien, cada uno dice "validacionLocal": "sin errores".
emitir envía los comprobantes y guarda el resultado de cada uno en resultado.csv.

Plantilla#

La plantilla es un archivo JSON. Dentro de documento, cada clave es un campo del comprobante y cada valor dice de qué columna sale ese campo o qué valor fijo lleva. Este es un ejemplo para una factura:

{
  "version": 1,
  "agruparPor": "numero",
  "documento": {
    "origenReferencia": "mi-erp",
    "referenciaExterna": "FAC-{numero}",
    "infoTributaria.ruc": "0123456789001",
    "infoTributaria.codDoc": "01",
    "infoTributaria.estab": "{establecimiento:digitos3}",
    "info.fechaEmision": "{fecha:fecha}",
    "info.importeTotal": "{importe_total:numero}"
  },
  "lineas": {
    "coleccion": "detalles",
    "campos": {
      "codigoPrincipal": "{codigo}",
      "cantidad": "{cantidad:numero}",
      "impuestos[0].codigo": "2"
    }
  }
}

Clave	Descripción
`agruparPor`	Columna que identifica al comprobante: las filas con el mismo valor forman uno. Sin `agruparPor`, cada fila es un comprobante.
`separador`	Solo CSV: `","`, `";"` o `"tab"`. Por defecto se detecta.
`hoja`	Solo Excel: nombre de la hoja. Por defecto, la primera.
`documento`	Campos del comprobante. Se toman de la primera fila del grupo.
`lineas`	Líneas del comprobante, una por fila del grupo.

Los campos de cada tipo de comprobante están en Emisión de comprobantes. El CLI no calcula los totales, así que tu archivo debe traerlos ya calculados.

Expresiones#

El valor de cada campo es una expresión. Entre llaves va el nombre de la columna y, si hace falta, el tipo al que se convierte la celda.

Expresión	Resultado	Ejemplo
`"{columna}"`	Texto de la celda.	`Av. Principal` → `"Av. Principal"`
`"{columna:numero}"`	Número. Acepta coma o punto decimal.	`1.234,56` → `1234.56`
`"{columna:entero}"`	Número entero.	`3` → `3`
`"{columna:fecha}"`	Fecha `dd/MM/yyyy`. Acepta `yyyy-MM-dd`, `dd/MM/yyyy` y fechas de Excel.	`2026-10-16` → `"16/10/2026"`
`"{columna:digitos3}"`	Dígitos con ceros a la izquierda (`digitos1` a `digitos20`), para códigos como `estab` o `formaPago`.	`1` → `"001"`
`"texto"`, `0`, `true`	Valor fijo.	`"DOLAR"`
`"FAC-{numero}"`	Texto fijo con columnas.	`000123` → `"FAC-000123"`

Si la celda está vacía, el campo no se incluye en el comprobante.

Rutas#

La clave de cada campo es su ruta dentro del JSON del comprobante. Los niveles se separan con un punto y los elementos de una lista se indican con su índice entre corchetes, empezando en cero. Por ejemplo, info.pagos[0].formaPago es la forma de pago del primer pago y info.totalConImpuestos[1].valor es el valor del segundo total de impuestos.

Líneas#

El bloque lineas arma la lista de líneas del comprobante, con una línea por cada fila del grupo.

Clave	Descripción
`coleccion`	`detalles` (factura, liquidación de compra, nota de crédito), `motivos` (nota de débito), `destinatarios` (guía de remisión) o `docsSustento` (retención).
`campos`	Campos de cada línea, con rutas relativas a la línea.

Errores frecuentes#

Cada error indica la fila del archivo donde está el problema.

Columna inexistente#

El mensaje Columnas de la plantilla que no estan en ventas.csv: ... indica que la plantilla nombra una columna que no existe en el archivo. Corrige el nombre de la columna en la plantilla o en la primera fila del archivo.

Valor no numérico#

El mensaje La columna 'cantidad' debe ser numerica; tiene 'dos'. indica que una celda que debía tener un número tiene texto. Corrige la celda.

Fecha inválida#

El mensaje La columna 'fecha' debe ser una fecha ... indica que la celda no tiene un formato de fecha que el CLI reconozca. Escribe la fecha como dd/MM/yyyy o yyyy-MM-dd.

Hoja inexistente#

El mensaje No existe la hoja 'Ventas'. Hojas: Hoja1, Hoja2. indica que la hoja de la clave hoja no está en el Excel; el mensaje lista las que sí existen. Corrige el nombre o quita la clave para que el CLI use la primera hoja.

Siguientes pasos#

Emitir con el CLI: entiende el estado de cada comprobante y reanuda lotes.
Vigilar una carpeta: emite automáticamente los archivos que deja tu ERP.