<!-- source_url: https://docsapi.ecuafact.com/v1/guias/cli-csv-excel | last_updated: 2026-10-19 -->

# 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.

> [!IMPORTANT]
> 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:

```bash
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
```

1. `plantilla nueva factura` crea la plantilla `mapeo-factura.json` y un
   archivo `ejemplo-factura.csv` que la usa. Abre la plantilla, pon tu
   [RUC](/v1/guias/glosario#ruc) en `infoTributaria.ruc` y cambia los nombres
   de columna por los de tu archivo.
2. `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"`.
3. `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:

```json
{
  "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](/v1/guias/emision). 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](/v1/guias/cli-emision): entiende el estado de cada comprobante y reanuda lotes.
- [Vigilar una carpeta](/v1/guias/cli-vigilar): emite automáticamente los archivos que deja tu ERP.