En esta página
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.
Para agentes#
Usa esta vía cuando quieras que un agente de programación haga esta tarea en tu entorno actual.
Pega este prompt en un agente de programación con acceso a la terminal:
Instala el CLI de Ecuafact y emite una factura de prueba desde esta terminal. Solo ambiente de pruebas: usa https://api-sandbox.mynexusapi.com y no emitas nada real. Si tienes la skill de Ecuafact, úsala; si no, puedes instalarla con npx skills add Ecuanexus/ecuafact-skill. Lee https://docs.mynexusapi.com/llms.txt y la guía en Markdown https://docs.mynexusapi.com/v1/guias/cli.md antes de escribir código; no inventes campos. Si ecuafact ya está instalado, reutilízalo; si no, instálalo con npm install -g @ecuafact/cli (o con Scoop o Homebrew si prefiero ese gestor). Fija el entorno con ecuafact config poner entorno sandbox. No pidas ni leas mi API Key: pídeme que ejecute yo mismo ecuafact login en mi terminal (la guarda sin mostrarla) o que defina ECUAFACT_API_KEY en mi entorno; nunca la pases como argumento de un comando, nunca la pegues en el chat ni la imprimas. Ejecuta ecuafact doctor y corrige lo que indique (clave, IP permitida, cupo); crea el comprobante con ecuafact nuevo factura --archivo factura.json, completa el RUC del emisor y los datos con los datos de prueba de la guía, valídalo con ecuafact validar factura.json y emítelo con ecuafact emitir factura.json --esperar. La respuesta 202 puede traer codEstado 1001 o 1002 (recibido) o ya un estado final: decide siempre por estado y codEstado (numérico), usa urlEstado tal cual (URL absoluta) y lee errores como arreglo. Ejecuta los comandos e informa solo el estado, el codEstado y la claveAcceso de la factura, y cualquier acción que yo deba hacer.
Instalación#
Instala el CLI con el gestor de paquetes que ya uses.
npm
npm install -g @ecuafact/cli
Windows (Scoop)
scoop bucket add ecuafact https://github.com/Ecuanexus/ecuafact-scoop
scoop install ecuafact/ecuafact
macOS y Linux (Homebrew)
brew install ecuanexus/ecuafact/ecuafact
Para actualizar, repite la instalación con npm o ejecuta
scoop update ecuafact o brew upgrade ecuafact, 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
o brew uninstall ecuafact.
Inicio rápido#
Necesitas una API Key de pruebas. Si todavía no tienes una, crea tu sandbox desde el Portal del Cliente. En sandbox no hay que registrar la IP de tu equipo; en producción 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 sandboxdeja fijo en tu perfil el entorno de pruebas.loginte pide la API Key sin mostrarla en pantalla y la guarda.doctorrevisa la conexión, la API Key, tu IP y tu cupo. Si algo falla, te dice qué hacer.nuevo facturacrea una factura de ejemplo. Abre el archivo, pon tu RUC y revisa los datos con la guía de Factura.emitirenví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 CODESTADO IDOPERACION CLAVEACCESO MENSAJE
factura.json autorizado 2001 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#
El CLI se autentica siempre con una API Key. ecuafact login la guarda 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
en sandbox y produccion:
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
- 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.
También puedes elegirlo con la variable ECUAFACT_ENTORNO, agregar entornos
propios con ecuafact entorno agregar o probar contra un servidor local con
ECUAFACT_API_URL; todo eso se explica en
Cambiar de ambiente o de URL.
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, XML del SRI, carpetas, CSV o Excel (Emitir con el CLI). |
estado, lote |
Seguir operaciones y reanudar lotes. |
descargar |
Descargar el RIDE y el XML. |
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 |
Hacer consultas al SRI. |
salud, estado-servicio, catalogos |
Comprobar que el servicio responde y consultar su estado público (sin API Key), y consultar los catálogos del 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. |
El tipo del comprobante (01 a 07) elige la ruta de emisión y no viaja en el
cuerpo. Lo indicas con --tipo, o el CLI lo deduce de la forma del comprobante (Emitir con el CLI).
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.