Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
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:

Prompt para agentes

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:

  1. config poner entorno sandbox deja fijo en tu perfil el entorno de pruebas.
  2. login te pide la API Key sin mostrarla en pantalla y la guarda.
  3. doctor revisa la conexión, la API Key, tu IP y tu cupo. Si algo falla, te dice qué hacer.
  4. nuevo factura crea una factura de ejemplo. Abre el archivo, pon tu RUC y revisa los datos con la guía de Factura.
  5. 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      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#

No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

No se pudo conectar. Revisa tu conexión y vuelve a intentarlo.

La sesión ya no está disponible. Recarga la página para continuar.

La sesión está en pausa. Puedes reanudarla para continuar.

No se pudo reanudar la sesión. Vuelve a intentarlo o recarga la página.

Al recargar se perderán los cambios que no hayas guardado.