Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
En esta página

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.

Importante

Ambiente de pruebas: sin validez fiscal. Los ejemplos que emiten usan el entorno sandbox.

Opciones globales#

Valen en cualquier comando.

Opción Descripción
-e, --entorno <entorno> sandbox, produccion u otro que hayas agregado con entorno agregar (Cambiar de ambiente o de URL).
-p, --perfil <perfil> Perfil de configuración. Por defecto, el activo.
-o, --salida <formato> tabla, json o csv. Por defecto, tabla en la terminal y JSON si rediriges la salida.
--campos <lista> Campos a mostrar, separados por coma. Admite rutas con punto (estado,claveAcceso).
-q, --silencioso Muestra solo el resultado y los errores.
--confirmar <entorno> Confirma sin preguntar una operación que escribe en producción. El valor es el nombre del entorno de producción: produccion o, en un entorno propio marcado con --produccion, su nombre.
--version Muestra la versión del CLI.
-h, --help Muestra la ayuda del comando.

Emisión#

ecuafact emitir#

Emite uno o varios comprobantes. Alias: emit.

ecuafact emitir <entradas...> [opciones]

El tipo (01 factura, 03 liquidación de compra, 04 nota de crédito, 05 nota de débito, 06 guía de remisión o 07 retención) elige la ruta de emisión y no se envía en el cuerpo. Sale de --tipo o de la forma del comprobante (en un XML, de su raíz), como se explica en Emitir con el CLI. Si no se puede decidir o hay contradicción, el comprobante se rechaza antes de enviarlo con código de salida 2.

Opción Descripción
<entradas...> Archivos .json (objeto o array), .jsonl, .xml (XML del SRI), .csv o .xlsx (con --plantilla), carpetas, o - para la entrada estándar.
-w, --esperar Espera el resultado del SRI. Por defecto, el valor de la clave esperar.
--espera-maxima <segundos> Tiempo máximo de espera, de 5 a 3600. Por defecto, 180.
--descargar <tipos> Descarga ride, xml o ride,xml al autorizarse. Implica --esperar.
-d, --destino <carpeta> Carpeta de las descargas. Por defecto, la clave carpetaDescargas (la carpeta actual).
--tipo <tipo> Tipo de los comprobantes: factura, liquidacion, nota-credito (nc), nota-debito (nd), guia, retencion, o 01, 03, 04, 05, 06, 07. Sin la opción se deduce de la forma del comprobante. Si el archivo trae infoTributaria.tipoDocumento, el CLI avisa y lo quita al enviar.
--plantilla <archivo> Plantilla para leer CSV o Excel (Emitir desde CSV o Excel).
--patron <patrones> En carpetas, archivos a leer separados por ;. Por defecto, *.json;*.jsonl;*.ndjson;*.xml. Para leer CSV o Excel de una carpeta, agrega *.csv o *.xlsx.
-r, --recursivo En carpetas, incluye las subcarpetas.
--validar-antes Antes de emitir, valida cada comprobante en la API (una petición más por comprobante). El que no cumple queda invalido y no se emite; las advertencias no bloquean. Por defecto, la clave validarAntes (false): sin esta opción se emite directo y la API responde 422 con los errores.
--dry-run, --simular Valida cada comprobante en la API con las reglas de la emisión (Validar sin emitir) y muestra lo que enviaría, sin emitir nada.
--continuar-con-errores Envía los válidos aunque otros tengan errores.
--reporte <archivo> Guarda el resultado de cada comprobante en un .csv o .json.
--mover-procesados <carpeta> Mueve ahí los archivos enviados bien.
--mover-errores <carpeta> Mueve ahí los archivos con errores, junto a su .error.json.
--concurrencia <n> Envíos simultáneos, de 1 a 10. Por defecto, la clave concurrencia (3).
--sin-verificar-cupo No compara el lote con el cupo antes de enviar.
ecuafact emitir factura.json --esperar --descargar ride --entorno sandbox
ecuafact emitir ./pendientes -r --reporte resultado.csv --entorno sandbox

ecuafact validar#

Valida comprobantes en la API sin emitirlos. Alias: validate.

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

--tipo funciona igual que en emitir. validar siempre envía cada comprobante a la API, en la ruta de validación de su tipo, con todas las reglas de la emisión, como se explica en Validar sin emitir. Un comprobante que la API acepta queda en estado valido, con sus advertencias si las trae; uno que no cumple queda invalido con los errores de la API. No emite ni consume cupo. Localmente solo se comprueba que el archivo se pueda leer o convertir y que el tipo permita elegir la ruta.

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.

Comando Descripción
lote listar [--limite <n>] Lista los lotes, del más reciente al más antiguo. Por defecto, 20. Alias: ls.
lote estado <lote> Muestra el estado de cada comprobante del lote.
lote reanudar <lote> [--esperar] [--espera-maxima <segundos>] [--descargar <tipos>] [-d <carpeta>] Reenvía los pendientes sin duplicar. Se ejecuta en el entorno del lote; --descargar implica --esperar. Alias: resume.
lote borrar <lote> Borra el registro del lote. No afecta a los comprobantes.

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>
Opción Descripción
--plantilla, --patron Igual que en emitir. Con --plantilla, el patrón por defecto incluye también *.csv y *.xlsx.
--validar-antes Valida cada comprobante en la API antes de emitirlo; el que no cumple va a errores/. Por defecto, la clave validarAntes (false).
-w, --esperar Espera el resultado del SRI antes de mover el archivo.
--descargar <tipos>, -d, --destino <carpeta> Igual que en emitir; --descargar implica --esperar.
--intervalo <segundos> Cada cuánto revisa la carpeta, de 2 a 3600. Por defecto, 10.
--una-vez Revisa una vez y termina. El código de salida dice si algún archivo falló.
--nombre <nombre> Nombre del servicio (instalar, estado, desinstalar).
--usuario En Linux y macOS, usa un servicio de tu usuario, sin sudo. Va en instalar, estado y desinstalar.
--restringir-carpeta Al instalar, deja la carpeta solo para administradores y tu usuario.
--permitir-carpeta-compartida En primer plano o al instalar, acepta que otros usuarios con permiso de escritura en la carpeta puedan emitir con tu API Key.
--lineas <n> En estado, las últimas líneas del registro del servicio. Por defecto, 15.

Alias de los subcomandos: install, status y uninstall.

ecuafact plantilla#

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

Comando Descripción
plantilla nueva factura [-d <carpeta>] [--sobrescribir] Crea una plantilla y un CSV de ejemplo. Alias: new.
plantilla probar <archivo> --plantilla <archivo> [--limite <n>] [--tipo <tipo>] Muestra los comprobantes que saldrían del archivo, sin enviarlos. Por defecto, 3.

Consulta#

Comando Descripción
estado <idOperacion> Muestra el seguimiento de una operación (Seguimiento). Alias: status.
operaciones listar [opciones] Lista los comprobantes de un contribuyente y un período (Listado). Alias: ls.
descargar <claveAcceso...> [--tipo ride,xml] [-d <carpeta>] [--sobrescribir] Descarga el RIDE y el XML de comprobantes autorizados, como <claveAcceso>.pdf y <claveAcceso>.xml. Por defecto, solo el RIDE. Alias: download.
cuenta Muestra tu integración y sus contribuyentes. Alias: contexto.
consumo Muestra tu cupo de documentos. Cada comprobante autorizado o rechazado consume un documento y uno cancelado lo libera. Alias: cupo.
perfil-emisor ver Muestra los datos del emisor que salen en el RIDE (Perfil del emisor).
perfil-emisor editar [--nombre-comercial] [--direccion-matriz] [--correo] [--telefono] [--ciudad] [--provincia] Cambia solo los datos que indicas.
perfil-emisor logo <archivo> Cambia el logo del RIDE. Acepta PNG o JPEG de hasta 512 KB.

--ruc <ruc> elige el contribuyente en los comandos que lo admiten, como perfil-emisor; acepta la identificación completa que devuelve GET /v1/contexto, por ejemplo el RUC de 13 dígitos. Por defecto, usa el de tu perfil o el único habilitado.

ecuafact perfil-emisor editar --correo facturacion@ejemplo.com --telefono 042345678 --entorno sandbox
ecuafact descargar <claveAcceso> --tipo ride,xml -d ./octubre --entorno sandbox

ecuafact operaciones listar#

Lista los comprobantes de un contribuyente y un período, con paginación. Alias: ls.

ecuafact operaciones listar [--identificacion <identificacion>] [--desde <yyyy-MM-dd>]
  [--hasta <yyyy-MM-dd>] [--tipo <codigo>] [--buscar <texto>] [--pagina <n>]
  [--tamano <n>] [--json] [--csv]
Opción Descripción
--identificacion <identificacion> Identificación del contribuyente, la misma de GET /v1/contexto. Si la omites, el comando usa el único contribuyente habilitado; con varios, se detiene y te pide esta opción, sin elegir uno.
--desde <yyyy-MM-dd>, --hasta <yyyy-MM-dd> Fechas del período. Sin ninguna de las dos, la API usa los últimos 30 días. El rango máximo es de 366 días.
--tipo <codigo> 01 factura, 03 liquidación de compra, 04 nota de crédito, 05 nota de débito, 06 guía de remisión o 07 retención.
--buscar <texto> Texto libre de hasta 100 caracteres.
--pagina <n> Página desde 1. Por defecto, 1.
--tamano <n> Comprobantes por página, de 1 a 100. Por defecto, 20.
--json Equivale a --salida json; devuelve la página completa, con comprobantes, pagina, tamanoPagina y hayMas.
--csv Equivale a --salida csv; escribe una fila por comprobante.

La tabla muestra el número, el tipo, la fecha, el estado, el codEstado, el total, la identificación de la contraparte y la clave de acceso. Si la respuesta trae hayMas en true, repite el comando con --pagina una unidad mayor; el mensaje de resumen te indica cuál. --json y --csv no se pueden combinar en la misma llamada.

ecuafact operaciones listar --desde 2026-11-01 --hasta 2026-11-10 --tipo 01 --entorno sandbox
ecuafact operaciones listar --identificacion 0123456789001 --buscar FAC --pagina 2 --tamano 50 --json
ecuafact operaciones listar --desde 2026-11-01 --hasta 2026-11-10 --csv > emitidos.csv

Consultas al SRI#

Comando Descripción
ruc consultar <identificacion> [--fusionar <true\|false>] [--fuente <fuente>] Muestra los datos de un contribuyente. --fusionar combina las fuentes (por defecto, true) y --fuente acepta Todas (por defecto) o SriCatastro.
ruc buscar --apellidos <texto> [--nombres <texto>] [--clase <clase>] [--max <n>] Busca contribuyentes por nombre. --clase acepta PersonaNatural (por defecto), Sociedad o SociedadPublica; --max, de 1 a 30 (por defecto, 10).
identificacion validar <numero> Valida una cédula, un RUC o un pasaporte. Alias del grupo: cedula.
clave decodificar <claveAcceso> Descompone una clave de acceso.
establecimientos <ruc> [--filtro <filtro>] Lista los establecimientos de un RUC. --filtro acepta Todos (por defecto), SoloActivos, SoloCerrados, SoloMatriz o SoloSucursales.

Estado del servicio y catálogos#

salud y estado-servicio no requieren API Key ni sesión: consultan GET /salud y GET /estado. catalogos consulta GET /v1/catalogos y GET /v1/catalogos/{nombre} con la API Key del perfil y el entorno actuales.

Comando Descripción
salud Comprueba que el servicio responde (GET /salud, sin API Key).
estado-servicio Muestra el estado público del servicio: el estado general, la disponibilidad de los últimos 90 días, el estado de cada componente y los incidentes. Alias: servicio. Con --salida json devuelve la respuesta completa.
catalogos [nombre] Sin nombre, lista los catálogos del SRI con su clave y descripción. Con el nombre de un catálogo (por ejemplo tarifas-iva), muestra sus filas: código, descripción, valor y vigencia. En JSON conserva también fuente y los atributos de cada fila. Alias: catalogo.
ecuafact estado-servicio
ecuafact estado-servicio --salida json --campos estado,disponibilidad90Dias
ecuafact catalogos
ecuafact catalogos tarifas-iva
ecuafact catalogos tarifas-iva --salida json --campos items

Si el nombre del catálogo no existe, el comando termina con el código de salida 8. Si catalogos se ejecuta sin API Key, termina con el código 3.

Webhooks#

El grupo webhooks destinos administra los destinos por API con la API Key del perfil y el entorno actuales. webhooks probar y webhooks verificar trabajan con tu endpoint 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 destinos#

Administra los destinos de webhooks. Las operaciones que escriben piden confirmación en producción, como el resto de comandos del CLI.

Comando Descripción
destinos listar Lista los destinos que puede ver la API Key (GET /v1/webhooks/destinos). Alias: ls.
destinos crear --url <url> [--eventos <lista>] [--ruc <ruc>] [--mostrar-secreto] Crea un destino (POST /v1/webhooks/destinos). --url exige HTTPS en el puerto 443, sin credenciales ni fragmento. --eventos acepta una lista separada por coma; por defecto, los cuatro eventos. --ruc limita el destino a ese contribuyente.
destinos ver <id> Muestra un destino (GET /v1/webhooks/destinos/{id}). Alias: obtener.
destinos eventos <id> --eventos <lista> Reemplaza los eventos suscritos del destino (PUT .../eventos). Alias: actualizar.
destinos probar-destino <id> Pide a la plataforma que envíe un evento de prueba firmado al destino registrado (POST .../probar). Para probar cualquier URL desde tu equipo usa webhooks probar.
destinos pausar <id> Pausa las entregas nuevas (POST /v1/webhooks/destinos/{id}/pausar).
destinos reanudar <id> Reactiva un destino pausado (POST .../reanudar).
destinos rotar <id> [--mostrar-secreto] Genera un secreto nuevo y lo devuelve una vez (POST .../rotar-secreto).
destinos entregas <id> Lista las últimas 50 entregas (GET .../entregas).
destinos intentos <id> <entregaId> Lista los intentos de una entrega (GET .../entregas/{entregaId}/intentos). entregaId es el campo publicId de la entrega.
destinos reintentar <id> <eventoId> Reenvía un evento ahora (POST .../entregas/{eventoId}/reintentar). eventoId es el campo eventId de la entrega.
destinos deshabilitar <id> Da de baja el destino; no se puede reactivar (POST .../deshabilitar).

<id> es el publicId del destino. crear y rotar devuelven el secreto una sola vez: en la salida de tabla se muestra, y con --salida json o --salida csv solo aparece si agregas --mostrar-secreto. El CLI no guarda el secreto en ningún archivo ni lo escribe en un mensaje, así que cópialo y guárdalo en tu servidor en ese momento.

ecuafact webhooks destinos listar --entorno sandbox
ecuafact webhooks destinos crear --url https://erp.ejemplo.com/webhooks/ecuafact --entorno sandbox
ecuafact webhooks destinos crear --url https://erp.ejemplo.com/webhooks/ecuafact \
  --eventos document.authorized,document.failed --ruc 0123456789001 --entorno sandbox
ecuafact webhooks destinos pausar <idDestino> --entorno sandbox
ecuafact webhooks destinos rotar <idDestino> --entorno sandbox
ecuafact webhooks destinos entregas <idDestino> --entorno sandbox
ecuafact webhooks destinos reintentar <idDestino> <eventoId> --entorno sandbox
ecuafact webhooks destinos deshabilitar <idDestino> --entorno sandbox

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.

Opción Descripción
--a <url> URL de tu endpoint. Exige HTTPS, sin credenciales ni fragmento; HTTP solo se acepta en localhost. Si tu endpoint no responde con un código de éxito, el comando termina con el código de salida 1.
--evento <evento> document.authorized (por defecto), document.rejected, document.failed u operation.requires_attention.
--cod-estado <codEstado> codEstado del cuerpo, un número de 4 dígitos. Solo admite las combinaciones que puede traer un evento real, que se detallan después de esta tabla. El estado, el msgError y errores del cuerpo se ajustan al código.
--clave-acceso <clave> Clave de acceso del cuerpo. Por defecto, una de ejemplo.
--id-operacion <id> idOperacion del cuerpo. Por defecto, uno nuevo en cada envío.
--firma-invalida Envía una firma incorrecta, para comprobar que tu endpoint la rechaza con un 401.
--secreto-desde-stdin Lee el secreto de la entrada estándar.

Cada evento admite solo los códigos con los que te llega en una entrega real. document.authorized lleva siempre 2001. Con document.rejected puedes usar 3001, el rechazo del SRI, que es el valor por defecto y llega con un mensaje del SRI de ejemplo en errores, o 4002, la firma electrónica no válida. Con document.failed puedes usar 3002, 4001, 4002, 4003, 4004, 5001, 5006, que es el valor por defecto, o 5007. Con operation.requires_attention, si no indicas --cod-estado recibes el evento de prueba del portal, con probe en "true". Si indicas 1001, o 1002 para que traiga claveAcceso, recibes el aviso de que el comprobante sigue recibido sin un resultado confirmado, con el motivo en errores. No hay opción para 6001, porque un comprobante cancelado no genera evento. Si pides una combinación que no existe, el comando termina con el código de salida 2 y no envía nada. Qué significa cada código se explica en Códigos de resultado de una operación.

ecuafact webhooks probar --a http://localhost:5000/webhooks
ecuafact webhooks probar --a http://localhost:5000/webhooks --evento document.failed --cod-estado 4002
ecuafact webhooks probar --a http://localhost:5000/webhooks --evento operation.requires_attention --cod-estado 1001

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

Opción Descripción
--firma <valor> Valor de la cabecera Ecuafact-Signature (t=...,v1=...).
--webhook-id <id> Valor de la cabecera webhook-id.
--webhook-timestamp <segundos> Valor de la cabecera webhook-timestamp.
--webhook-signature <firma> Valor de la cabecera webhook-signature (v1,...).
--cuerpo <@archivo> Cuerpo crudo, desde un archivo o - para la entrada estándar.
--tolerancia <segundos> Diferencia admitida con la marca de tiempo. Por defecto, 300.
--ahora <segundos> Instante de comparación en segundos Unix, para revisar un evento antiguo. Por defecto, ahora.
--secreto-desde-stdin Lee el secreto de la entrada estándar.
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

El resultado trae valida, esquema, motivo, detalle, marca (la marca de tiempo de la firma) y edadSegundos. Si la firma es válida, motivo es null y el comando termina con 0. Si no lo es, termina con 4 y motivo te dice la causa, mientras detalle la explica:

motivo Qué pasó Qué hacer
cabecera_invalida La cabecera no trae t y v1, o faltan webhook-id o webhook-timestamp válidos. Copia las cabeceras completas de la entrega.
secreto_invalido El secreto no tiene el formato esperado para Standard Webhooks. Copia el secreto completo desde el portal, con o sin el prefijo whsec_.
firma_no_coincide La firma no corresponde a ese secreto y ese cuerpo. Revisa que uses el secreto del destino correcto y el cuerpo exactamente como llegó, sin reformatearlo ni cambiar los fines de línea.
fuera_de_tolerancia La firma es correcta, pero la marca de tiempo está fuera de la tolerancia. Para revisar un evento antiguo, pasa --ahora con su marca de tiempo.

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]
Opción Descripción
--desde-stdin Lee la API Key de la entrada estándar, para scripts.
--sin-verificar Guarda la API Key sin probarla contra la API.
ecuafact login --entorno sandbox
echo "$ECUAFACT_KEY_SANDBOX" | ecuafact login --desde-stdin --entorno sandbox

Otros comandos de configuración#

Comando Descripción
logout Borra la API Key guardada del perfil y el entorno.
sesion Muestra el perfil, el entorno, la URL de la API y de dónde sale la API Key, sin mostrarla. Termina con el código 3 si no hay API Key. Alias: whoami.
config ver Muestra la configuración efectiva, la URL de la API en uso y de dónde sale cada valor.
config obtener <clave>, poner <clave> <valor>, quitar <clave> Lee, guarda o borra una clave del perfil. Alias: get, set, unset.
config claves Lista las claves, su variable de entorno y su valor por defecto.
config ruta Muestra dónde está el archivo de configuración de tu usuario.
perfil usar <nombre>, listar, borrar <nombre> Activa (o crea), lista o borra perfiles. Alias de listar: ls.
entorno listar, agregar <nombre> --api <url> [--produccion], quitar <nombre> Lista los entornos y cuál está en uso, y agrega o quita entornos propios. --produccion hace que el entorno pida confirmación al escribir, como produccion. Alias de listar: ls.
doctor [--sin-ip-publica] Revisa la versión, la configuración, el entorno (y de dónde sale), la conexión, el reloj, la API Key, la IP, el cupo y los contribuyentes. Termina con el código 1 si alguna revisión falla. Si la autenticación falla, consulta tu IP pública en api.ipify.org; --sin-ip-publica evita esa consulta.

Cambiar de ambiente o de URL#

Para elegir el ambiente, usa --entorno sandbox o --entorno produccion en un comando, define la variable ECUAFACT_ENTORNO o déjalo fijo en tu perfil con ecuafact config poner entorno <nombre>. Si necesitas apuntar a otro servidor, agrega un entorno propio con ecuafact entorno agregar <nombre> --api <url>. La URL debe usar HTTPS, salvo localhost, y sandbox y produccion no se pueden redefinir. Con --produccion, el entorno propio pide confirmación al escribir y, en un script, se confirma con --confirmar <nombre>.

Cada entorno guarda su propia API Key: ejecuta login en cada uno, y el CLI solo envía la API Key guardada al entorno con el que la guardaste. Si cambias la URL de un entorno propio con entorno agregar, el CLI borra las API Key guardadas para ese entorno y debes ejecutar login de nuevo.

Cuando prefieres no guardar la API Key, defínela en la variable ECUAFACT_API_KEY. Como la entregas tú de forma explícita, el CLI la usa con cualquier URL (sandbox, produccion, un entorno propio o una URL definida con ECUAFACT_API_URL) y tiene prioridad sobre la guardada. Por eso conviene definirla solo en el proceso que la necesita y comprobar a qué URL apunta con ecuafact sesion, que muestra el entorno, la URL y el prefijo de la clave.

La variable ECUAFACT_API_URL reemplaza la URL del entorno actual y sirve para apuntar a otro servidor, por ejemplo uno local. El entorno conserva su nombre y su comportamiento, así que con produccion sigue pidiendo confirmación. Con ECUAFACT_API_URL el CLI no usa la API Key guardada, porque ya no apunta al entorno con el que la guardaste: si no defines ECUAFACT_API_KEY, el comando termina con el código de salida 3 y te indica que la definas.

Quieres usar Qué API Key envía el CLI
sandbox o produccion La de ECUAFACT_API_KEY; si no existe, la guardada con login en ese entorno.
Un entorno propio (entorno agregar) La de ECUAFACT_API_KEY; si no existe, la guardada con login --entorno <nombre>.
Cualquier entorno con ECUAFACT_API_URL Solo la de ECUAFACT_API_KEY.
ecuafact entorno agregar pruebas --api https://api.ejemplo.com
ecuafact entorno listar
echo "$API_KEY" | ecuafact --entorno pruebas login --desde-stdin
ecuafact --entorno pruebas consumo

export ECUAFACT_API_URL=http://localhost:5000
export ECUAFACT_API_KEY="..."
ecuafact --entorno sandbox consumo

Claves y variables de entorno#

Clave Variable de entorno Descripción
entorno ECUAFACT_ENTORNO Entorno por defecto: sandbox, produccion o uno propio. Por defecto, produccion.
ruc ECUAFACT_RUC Identificación completa del contribuyente por defecto, como la devuelve GET /v1/contexto (por ejemplo, el RUC de 13 dígitos).
establecimiento ECUAFACT_ESTABLECIMIENTO Establecimiento por defecto.
puntoEmision ECUAFACT_PUNTO_EMISION Punto de emisión por defecto.
salida ECUAFACT_SALIDA Formato de salida: auto (por defecto: tabla en la terminal y JSON si rediriges), tabla, json o csv.
concurrencia ECUAFACT_CONCURRENCIA Envíos simultáneos. Por defecto, 3.
carpetaDescargas ECUAFACT_CARPETA_DESCARGAS Carpeta de las descargas.
esperar ECUAFACT_ESPERAR Con true, todos los emitir esperan el resultado del SRI.
descargar ECUAFACT_DESCARGAR Archivos a descargar al autorizarse en todos los emitir; también activa la espera.
validarAntes ECUAFACT_VALIDAR_ANTES Con true, todos los emitir y vigilar validan cada comprobante en la API antes de emitirlo. Por defecto, false.

Además, ECUAFACT_API_KEY define la API Key y tiene prioridad sobre la guardada, ECUAFACT_API_URL cambia la URL de la API (Cambiar de ambiente o de URL) y ECUAFACT_PERFIL elige el perfil. ECUAFACT_MAX_RESPUESTA_BYTES cambia el tamaño máximo, en bytes, de una respuesta de la API (por defecto, 64 MiB); 0 quita el tope. Si una respuesta lo supera, el comando termina con un error que lo indica.

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, hasta la raíz Git más próxima o tu carpeta de usuario. Sin ninguno de esos límites, solo se consulta la carpeta actual.
  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.

Usa solo una configuración de proyecto de confianza. Antes de ejecutar comandos en un repositorio clonado, revisa su archivo de configuración y los valores efectivos. carpetaDescargas puede indicar una carpeta fuera del repositorio; el límite de búsqueda del archivo no restringe el destino de las descargas. Para elegir otra carpeta en un comando usa --destino. --salida cambia el formato de presentación, no la carpeta.

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

Otros comandos#

Comando Descripción
api <metodo> <ruta> [--datos @archivo] [--idempotency-key <clave>] [--archivo-salida <archivo>] Llama a cualquier ruta de la API con tu API Key y muestra la respuesta tal cual. <metodo> acepta GET, POST o PUT. Para emitir, pasa una --idempotency-key estable (auto genera una nueva en cada llamada). --archivo-salida es necesario para PDF y XML.
schema [comando] Describe el CLI en JSON, para scripts y agentes de IA.
docs [tema] [--imprimir] Abre esta documentación en el navegador; con --imprimir, solo muestra la URL.
ayuda [tema] Muestra guías breves que funcionan sin conexión.

Códigos de salida#

Código Significado
0 El comando terminó bien.
1 Error general, de red o del servidor, o el comprobante quedó en error.
2 Uso incorrecto del comando.
3 Falló la autenticación, la IP o el permiso, o el comprobante quedó en rechazo_configuracion por la firma, la configuración del emisor o la suscripción.
4 Error de validación, o el comprobante quedó rechazado por su contenido, con el codEstado 3002 (comprobante_invalido).
5 El SRI rechazó el comprobante: quedó rechazado con el codEstado 3001 (rechazo_sri).
6 Se superó el límite de solicitudes o no hay cupo, ya sea porque la API respondió 429 o porque el comprobante quedó en rechazo_configuracion con el codEstado 4004 (cupo_agotado).
7 Resultado parcial: unos elementos salieron bien y otros no.
8 No encontrado o en conflicto, o el comprobante quedó cancelado, con el codEstado 6001 (operacion_cancelada).

Cuando el código viene del resultado de un comprobante, depende de su estado y de su codEstado:

estado codEstado Código de salida
autorizado o recibido 2001, 1001 o 1002 0
rechazado 3001 (rechazo_sri) 5
rechazado 3002 (comprobante_invalido) 4
rechazo_configuracion 4001 (emisor_no_configurado), 4002 (firma_no_valida) o 4003 (suscripcion_inactiva) 3
rechazo_configuracion 4004 (cupo_agotado) 6
error 5006 (entrega_no_posible), 5007 (resultado_no_confirmado) o 5001 (error_interno) 1
cancelado 6001 (operacion_cancelada) 8

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 recibido, que todavía no tienen un resultado final, 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.

Si la API no responde, o responde 500, 502, 503 o 504, o 429 con el codEstado 5005 (limite_solicitudes), el CLI repite la petición por su cuenta hasta tres veces, con una espera entre intentos y respetando la cabecera Retry-After cuando viene. Al emitir, cada reintento lleva la misma Idempotency-Key, así que no duplica el comprobante: si la primera solicitud se aceptó, recibes el mismo idOperacion. Si el error persiste después de los reintentos, el comando termina con su código de salida, 1 para los errores del servidor y 6 para el límite de solicitudes, y puedes reanudar el lote más tarde con ecuafact lote reanudar. Un 429 con el codEstado 4004 (cupo_agotado) no se reintenta, porque esperar no devuelve cupo.

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 inválidas.",
  "estadoHttp": 401,
  "estado": "rechazado",
  "codEstado": 3009,
  "idCorrelacion": "0HN7A2B3C4D5E:00000001",
  "codigoSalida": 3,
  "sugerencia": "Revisa la API Key ('ecuafact sesion') y, en produccion, que la IP publica de este equipo este registrada en el portal (Cuenta > IP permitidas). 'ecuafact doctor' muestra la IP detectada."
}
Campo Descripción
error Mensaje del error.
codigoSalida El mismo código con el que termina el comando.
sugerencia Qué hacer, cuando el CLI lo sabe.
estadoHttp, estado, codEstado Solo si el error vino de la API: el estado HTTP, el estado y el codEstado del cuerpo de error.
errores Solo si la API devolvió detalle de validación.
idCorrelacion Solo si el error vino de la API. Inclúyelo si escribes a soporte.

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.