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

CLI de Ecuafact

Emite, sigue y descarga comprobantes electrónicos desde la terminal con el CLI ecuafact, sin escribir código.

Si necesitas hacer revisiones rápidas o conectar nuestros servicios de facturación a un proceso automatizado, puedes usar nuestro CLI ecuafact. Con él creas un comprobante de ejemplo, lo validas, lo emites, esperas la respuesta del SRI y descargas el RIDE con un par de comandos, sin programar las llamadas HTTP. Te sirve tanto para probar la API por primera vez como para emitir desde los archivos que genera tu ERP.

En esta página instalas el CLI, lo conectas con tu API Key de pruebas y emites tu primera factura. Al final encontrarás la lista de comandos, agrupados por tarea, con enlaces a las guías y a la referencia donde se explica cada uno.

Importante

Ambiente de pruebas: sin validez fiscal. Los ejemplos de esta página usan el entorno sandbox.

Instalación#

Instala el CLI con el gestor de paquetes que ya uses.

npm

npm install -g @ecuafact/cli@preview

Windows (Scoop)

scoop bucket add ecuafact https://github.com/Ecuanexus/ecuafact-scoop
scoop install ecuafact/ecuafact-preview

macOS y Linux (Homebrew)

brew install ecuanexus/ecuafact/ecuafact-preview

Para actualizar, repite la instalación con npm o ejecuta scoop update ecuafact-preview o brew upgrade ecuafact-preview, según el gestor. Para comprobar qué versión tienes, ejecuta ecuafact --version. Si no muestra la versión que acabas de instalar, tienes otra instalación antes en el PATH: desinstala la que no uses.

Para desinstalar el CLI, quita primero los servicios de vigilancia de carpetas que hayas instalado, con ecuafact vigilar desinstalar --nombre <nombre>, y luego desinstálalo con el mismo gestor: npm uninstall -g @ecuafact/cli, scoop uninstall ecuafact-preview o brew uninstall ecuafact-preview.

Inicio rápido#

Necesitas una API Key de pruebas. Si todavía no tienes una, crea tu sandbox desde el Portal del Cliente. Además, la IP de tu equipo debe estar registrada en el portal, en Cuenta > IP permitidas.

ecuafact config poner entorno sandbox
ecuafact login
ecuafact doctor
ecuafact nuevo factura --archivo factura.json
ecuafact emitir factura.json --esperar --descargar ride

Estos comandos hacen lo siguiente, en orden:

config poner entorno sandbox deja fijo en tu perfil el entorno de pruebas.
login te pide la API Key sin mostrarla en pantalla y la guarda.
doctor revisa la conexión, la API Key, tu IP y tu cupo. Si algo falla, te dice qué hacer.
nuevo factura crea una factura de ejemplo. Abre el archivo, pon tu RUC y revisa los datos con la guía de Factura.
emitir envía la factura, espera la autorización del SRI y descarga el RIDE.

Si todo funcionó, el último comando muestra el comprobante con el estado autorizado:

ORIGEN        ESTADO      IDOPERACION                           CLAVEACCESO                                        MENSAJE
factura.json  autorizado  3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f  0710202601012345678900110010010000001231234567811  Autorizado por el SRI.

El CLI guarda el RIDE en la carpeta actual, con la clave de acceso como nombre de archivo (<claveAcceso>.pdf).

Autenticación#

ecuafact login guarda la API Key para el perfil y el entorno que estás usando. Para ver cuál está activa, ejecuta ecuafact sesion; para borrarla, ecuafact logout.

En un servidor o en un proceso de integración continua, define la API Key en la variable de entorno ECUAFACT_API_KEY. El CLI la usa en lugar de la guardada:

export ECUAFACT_API_KEY="..."
ecuafact --entorno sandbox consumo

Atención

No pases la API Key como argumento de un comando, porque queda guardada en el historial de la terminal.

En scripts y CI#

Puedes usar el CLI en un servidor, una tarea programada o un pipeline de integración continua, porque ahí no te pregunta nada. Escribe el resultado en JSON por la salida estándar, los mensajes y los errores por la salida de errores, y termina con un código de salida que tu script puede comprobar para saber si todo salió bien.

Entrega la API Key con la variable ECUAFACT_API_KEY, que es lo más simple en un pipeline. Si prefieres guardarla una vez en el equipo, pásala por la entrada estándar con login --desde-stdin, para que no quede en el historial ni en la lista de procesos:

echo "$ECUAFACT_KEY_SANDBOX" | ecuafact login --desde-stdin --entorno sandbox

En produccion, los comandos que emiten o cambian datos se detienen si no agregas --confirmar produccion, porque en un script nadie puede responder la confirmación. Este es un paso de GitHub Actions que emite una carpeta en pruebas, espera el resultado y guarda un reporte:

- run: npm install -g @ecuafact/cli@preview
- run: ecuafact --entorno sandbox emitir ./salida -r --esperar --reporte resultado.json
  env:
    ECUAFACT_API_KEY: ${{ secrets.ECUAFACT_API_KEY_SANDBOX }}

Revisa el código de salida y, si es distinto de 0, el reporte: ahí está el estado de cada comprobante.

Entornos#

Puedes trabajar con dos entornos, uno por cada ambiente de la API.

Entorno	Para qué
`sandbox`	Pruebas, sin validez fiscal.
`produccion`	Comprobantes reales. Es el entorno por defecto.

Como un perfil nuevo trabaja en produccion, elige el entorno antes de empezar a probar. Puedes indicarlo en cada comando con --entorno sandbox o dejarlo fijo en tu perfil con ecuafact config poner entorno sandbox. Cada entorno usa su propia API Key, así que ejecuta login una vez en cada uno.

En produccion, los comandos que emiten o cambian datos te piden confirmación antes de seguir. Si los ejecutas desde un script, donde nadie puede responder, agrega --confirmar produccion.

Configuración#

Con config guardas valores por defecto para no repetirlos en cada comando, y con perfil separas la configuración y las API Keys de cada integración, por ejemplo si trabajas para varias empresas.

ecuafact config poner ruc 0123456789001
ecuafact config ver
ecuafact perfil usar empresa-b

Puedes guardar el entorno, el RUC, el establecimiento, el punto de emisión y el formato de salida, entre otros. Todas las claves están en la referencia.

Si trabajas en un proyecto, puedes fijar su configuración en un archivo ecuafact.json dentro del repositorio, sin la API Key. Ese archivo tiene prioridad sobre tu perfil; el orden completo está en Precedencia y ecuafact.json.

Comandos#

Los comandos se agrupan por tarea. Cada grupo enlaza a la guía que lo explica con ejemplos, y la referencia tiene todas sus opciones.

Comando	Para qué
`emitir`, `validar`, `nuevo`	Crear, validar y emitir comprobantes desde JSON, JSONL, carpetas, CSV o Excel (Emitir con el CLI).
`estado`, `comprobantes listar`, `lote`	Seguir operaciones, listar emitidos y reanudar lotes.
`descargar`, `correo reenviar`	Descargar el RIDE y el XML, y reenviar el correo.
`vigilar`	Emitir lo que tu ERP deja en una carpeta (Vigilar una carpeta).
`plantilla`	Mapear las columnas de un CSV o Excel (Emitir desde CSV o Excel).
`cuenta`, `consumo`, `perfil-emisor`	Ver tu integración, tu cupo y los datos del emisor.
`ruc`, `identificacion`, `clave`, `establecimientos`, `catalogos`	Hacer consultas al SRI.
`webhooks`	Probar tu endpoint de webhooks.
`login`, `config`, `perfil`, `entorno`, `doctor`	Gestionar credenciales y configuración, y diagnosticar problemas.
`api`, `schema`	Llamar a cualquier ruta del API y describir el CLI en JSON.

Si necesitas ayuda en la terminal, ecuafact <comando> --help muestra la ayuda de cada comando y ecuafact ayuda lista guías breves que funcionan sin conexión.

Siguientes pasos#

Emitir con el CLI: emite lotes y carpetas, sigue cada comprobante y descarga sus archivos.
Emitir desde CSV o Excel: emite desde las filas de tu archivo sin escribir JSON.
Referencia de comandos: consulta todas las opciones y los códigos de salida.