Referencia de comandos del CLI

Consulta cada comando del CLI ecuafact con sus opciones, las variables de entorno que acepta y los códigos de salida para tus scripts.

Opciones globales#

Valen en cualquier comando.

Emisión#

ecuafact emitir#

Emite uno o varios comprobantes. Alias: emit.

ecuafact emitir <entradas...> [opciones]

ecuafact emitir factura.json --esperar --descargar ride --entorno sandbox
ecuafact emitir ./pendientes -r --reporte resultado.csv --entorno sandbox

ecuafact validar#

Valida comprobantes sin enviarlos. Alias: validate.

ecuafact validar <entradas...> [--en-linea] [--plantilla <archivo>] [--patron <patrones>] [-r]

--en-linea comprueba además con la API que tu RUC y el tipo de comprobante estén habilitados.

ecuafact nuevo#

Crea un comprobante de ejemplo. Alias: new.

ecuafact nuevo <tipo> [-f, --archivo <archivo>] [--sobrescribir]

<tipo> acepta factura, liquidacion, nota-credito (o nc), nota-debito (o nd), guia, retencion o el código, de 01 a 07.

ecuafact lote#

Consulta y reanuda las emisiones anteriores. Alias: batch.

ecuafact vigilar#

Emite cada archivo que aparece en una carpeta. Alias: watch. Guía: Vigilar una carpeta.

ecuafact vigilar <carpeta> [opciones]
ecuafact vigilar instalar <carpeta> --nombre <nombre> [opciones]
ecuafact vigilar estado --nombre <nombre> [--lineas <n>]
ecuafact vigilar desinstalar --nombre <nombre>

Alias de los subcomandos: install, status y uninstall.

ecuafact plantilla#

Plantillas para emitir desde CSV o Excel. Alias: template.

Consulta#

--ruc <ruc> elige el contribuyente en comprobantes, descargar y perfil-emisor; acepta el RUC de 13 dígitos o la identificación de 10. Por defecto, el de tu perfil o el único habilitado.

ecuafact perfil-emisor editar --correo facturacion@ejemplo.com --telefono 042345678 --entorno sandbox
ecuafact descargar --desde 2026-10-01 --hasta 2026-10-31 --tipo ride,xml -d ./octubre --entorno sandbox

Consultas al SRI#

Webhooks#

Estos comandos prueban tu endpoint de webhooks y no llaman a la API. Los dos leen el secreto del destino de la variable ECUAFACT_WEBHOOK_SECRET, o de la entrada estándar con --secreto-desde-stdin.

ecuafact webhooks probar#

Envía a tu endpoint un evento de ejemplo firmado y muestra lo que respondió. Alias: test. El evento lleva las mismas cabeceras de firma que una entrega real, Ecuafact-Signature y las de Standard Webhooks, así que sirve para probar tu endpoint con cualquiera de los dos esquemas.

ecuafact webhooks probar --a http://localhost:5000/webhooks
ecuafact webhooks probar --a http://localhost:5000/webhooks --evento document.failed --motivo plan_agotado

ecuafact webhooks verificar#

Comprueba la firma de un webhook que ya recibiste. Alias: verify. Verifica la cabecera Ecuafact-Signature con --firma, o las tres cabeceras de Standard Webhooks con --webhook-id, --webhook-timestamp y --webhook-signature juntas; no se pueden combinar los dos esquemas en la misma llamada. El resultado indica en esquema cuál verificó.

ecuafact webhooks verificar --firma "t=1791385446,v1=a1ae..." --cuerpo @evento.json --ahora 1791385446
ecuafact webhooks verificar --webhook-id 9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b --webhook-timestamp 1791385446 --webhook-signature "v1,6Ygt..." --cuerpo @evento.json --ahora 1791385446

Configuración#

ecuafact login#

Guarda la API Key del perfil y el entorno actuales. Sin opciones, la pide sin mostrarla.

ecuafact login [--desde-stdin] [--sin-verificar]

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

Otros comandos de configuración#

Claves y variables de entorno#

Además, ECUAFACT_API_KEY define la API Key y tiene prioridad sobre la guardada, y ECUAFACT_PERFIL elige el perfil.

Precedencia y ecuafact.json#

Cada valor sale del primero que lo defina, en este orden:

1. La opción del comando (--entorno, --salida, --perfil).
2. La variable de entorno ECUAFACT_*.
3. Un archivo ecuafact.json en la carpeta actual o en una superior.
4. Tu perfil (config poner).
5. El valor por defecto.

ecuafact.json fija la configuración de un proyecto y se puede guardar en tu repositorio, porque nunca lleva la API Key. Como tiene prioridad sobre tu perfil, si config poner parece no tener efecto, revisa si hay uno con ecuafact config ver.

{
  "perfil": "empresa-b",
  "entorno": "sandbox",
  "ruc": "0123456789001",
  "salida": "json"
}

Otros comandos#

Códigos de salida#

En los comandos que procesan varios elementos, el código resume el lote. En emitir y lote reanudar es 0 si ningún comprobante falló, 7 si unos salieron bien y otros no, y el código del primer fallo si ninguno salió bien (por ejemplo, 5 si el SRI rechazó todos). El 0 incluye los comprobantes en enviado o en_proceso, que todavía no tienen el resultado del SRI, así que no los des por autorizados: usa --esperar o revisa el estado de cada uno con --reporte. vigilar --una-vez sigue el mismo criterio con los archivos de la carpeta, y descargar devuelve 7 si solo fallaron algunas descargas.

Cuando el CLI no se ejecuta en una terminal, por ejemplo desde un script, escribe el resultado en JSON por la salida estándar y los errores, también en JSON, por la salida de errores. Un error de la API se ve así:

{
  "error": "Credenciales invalidas.",
  "estadoHttp": 401,
  "codigo": "101",
  "idCorrelacion": "0HN7A2B3C4D5E:00000001",
  "codigoSalida": 3,
  "sugerencia": "Revisa la API Key ('ecuafact sesion') y que la IP publica de este equipo este registrada en el portal (Cuenta > IP permitidas). 'ecuafact doctor' muestra la IP detectada."
}

Siguientes pasos#

• CLI de Ecuafact: instala el CLI y emite tu primera factura.
• Emitir con el CLI: emite lotes y carpetas y descarga sus archivos.