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

Emitir con el CLI

Emite uno o muchos comprobantes desde archivos JSON con ecuafact emitir y sigue cada uno hasta que el SRI responde.

Con ecuafact emitir puedes emitir un comprobante, un lote de comprobantes o una carpeta entera, y ver el resultado de cada uno. Cada archivo lleva la misma estructura de comprobante que recibe la API, que se explica en Emisión de comprobantes, así que puedes reutilizar los JSON que ya genera tu sistema.

En esta página verás cómo emitir y validar antes de enviar, qué significa cada estado que muestra el CLI, cómo reanudar un lote que se cortó y cómo consultar y descargar lo que ya emitiste.

Importante

Ambiente de pruebas: sin validez fiscal. Los ejemplos usan el entorno sandbox configurado en tu perfil, como se explica en el inicio rápido del CLI.

Emitir#

ecuafact emitir factura.json --entorno sandbox
ecuafact emitir lote.json ventas.jsonl --entorno sandbox
ecuafact emitir ./pendientes -r --entorno sandbox
ecuafact emitir factura.json --entorno sandbox --esperar --descargar ride,xml
mi-erp exportar | ecuafact emitir - --entorno sandbox

emitir acepta archivos .json con un comprobante o con un array de comprobantes, archivos .jsonl, archivos .xml con un comprobante del SRI, carpetas y la entrada estándar si escribes -. En un XML, el tipo sale del elemento raíz del comprobante. Si tus datos están en un CSV o un Excel, sigue la guía Emitir desde CSV o Excel.

El tipo de comprobante elige la ruta de emisión (/facturas, /liquidaciones-compra, /notas-credito, /notas-debito, /guias-remision o /retenciones) y no viaja en el cuerpo de la petición. El CLI lo toma de estas fuentes, en este orden:

  1. La opción --tipo: factura, liquidacion, nota-credito (o nc), nota-debito (o nd), guia, retencion, o el código 01, 03, 04, 05, 06 o 07.
  2. La forma del comprobante, cuando solo puede ser un tipo: motivos es una nota de débito (05), destinatarios una guía de remisión (06), docsSustento una retención (07); con detalles, codDocModificado o valorModificacion indican una nota de crédito (04), razonSocialProveedor o identificacionProveedor una liquidación de compra (03), y un comprador con pagos e importeTotal una factura (01).

Por eso los comprobantes de ejemplo de la documentación se validan y se emiten sin indicar nada más. Si el CLI no puede decidir el tipo, o --tipo contradice a la forma del comprobante, rechaza el comprobante antes de enviarlo (código de salida 2) y el mensaje te pide indicar --tipo.

El cuerpo que se envía es exactamente el esquema de ese tipo: el contrato tiene un esquema por tipo de comprobante y ninguno incluye infoTributaria.tipoDocumento. Si tu archivo trae ese campo, el CLI avisa, lo quita antes de enviar y sigue adelante; quítalo de tus archivos.

ecuafact emitir liquidacion.json --tipo liquidacion --entorno sandbox

Al reanudar un lote con ecuafact lote reanudar no necesitas indicar el tipo de nuevo.

Cuando un archivo del lote no se puede leer o convertir (JSON mal formado, XML que no es un comprobante del SRI, fila de CSV que no cumple la plantilla) o no permite elegir la ruta (falta el RUC o el tipo), el CLI no envía ningún comprobante del lote. Corrige el archivo y vuelve a ejecutar el comando, o agrega --continuar-con-errores si prefieres enviar los demás. Las reglas del comprobante (campos requeridos, formatos, catálogos, topes y totales) las aplica solo la API: emitir envía el comprobante directo y, si no cumple, muestra el 422 con su codEstado 3002 y la lista de errores.

Puedes reenviar el mismo comprobante sin duplicarlo mientras conserve su origenReferencia y su referenciaExterna. Por eso, cuando quieras emitir un comprobante nuevo o una versión corregida de uno rechazado, dale otra referenciaExterna. Un XML con exactamente el mismo contenido tampoco se duplica.

Antes de emitir puedes revisar el comprobante sin emitir nada. validar 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; si la API lo acepta, el estado es valido, y las advertencias que devuelve se muestran sin bloquear. Localmente solo se comprueba que el archivo se pueda leer o convertir y que el tipo permita elegir la ruta. emitir --dry-run hace la misma validación y muestra lo que enviaría. Ninguno de los dos emite ni consume cupo.

ecuafact validar factura.json
ecuafact emitir factura.json --entorno sandbox --dry-run

La validación previa a la emisión es opcional y está apagada por defecto, para que cada emisión haga una sola petición. Si quieres que emitir valide cada comprobante antes de enviarlo, agrega --validar-antes o guarda validarAntes en true en la configuración. Con ella, el comprobante que la API declara inválido queda en estado invalido y no se emite, las advertencias se muestran sin bloquear, y cada comprobante cuesta dos peticiones.

ecuafact emitir factura.json --validar-antes --entorno sandbox

Todas las opciones de emitir están en la referencia.

Resultado de cada comprobante#

Al terminar, el CLI muestra una fila por comprobante con su estado. Esta tabla dice qué significa cada uno y qué hacer.

Estado Qué hacer
autorizado No hagas nada. En produccion tiene validez fiscal.
recibido La API lo aceptó y todavía no tiene resultado final. Usa --esperar o consulta con ecuafact estado <idOperacion>, y no lo emitas con otra referenciaExterna, porque lo duplicarías.
rechazado No se autorizó por su contenido. Si codEstado es 3001 (rechazo_sri), lo rechazó el SRI: corrígelo según el mensaje y emítelo con una referenciaExterna nueva y un secuencial nuevo. Si es 3002 (comprobante_invalido), corrígelo y emítelo de nuevo con una referenciaExterna nueva; puedes conservar el número.
rechazo_configuracion No se emitió porque falta o está mal una configuración del emisor, como la firma electrónica, la suscripción o el cupo. Corrige lo que indica codEstado, de 4001 a 4004, y emítelo de nuevo con una referenciaExterna nueva.
error No se pudo emitir. Si codEstado es 5006 (entrega_no_posible), emítelo de nuevo con una referenciaExterna nueva; si es 5007 (resultado_no_confirmado) o 5001 (error_interno), no lo emitas de nuevo y escribe a soporte con el idOperacion.
simulado Con emitir --dry-run: la API validó el comprobante y no se emitió nada.
valido Con validar: la API validó el comprobante con las reglas de la emisión. Si trae advertencias, no impiden emitir.
invalido No se envió: el archivo no se pudo leer o convertir, no permite elegir la ruta, o la API lo declaró inválido en la validación (validar o --validar-antes). Corrígelo según el mensaje. Si el mensaje pide --tipo, indica el tipo de comprobante.
no_enviado No se envió porque otro comprobante del lote no se pudo leer o no pasó la validación.
pendiente No se confirmó el envío. Reanuda el lote.
cancelado La plataforma canceló el envío y no se emitió. Emítelo con una referenciaExterna nueva.

Cada comprobante autorizado o rechazado consume un documento de tu cupo, y uno cancelado lo libera. Revisa lo que te queda con ecuafact consumo.

Cada codEstado y qué hacer ante él se explican en Códigos de resultado de una operación.

Si necesitas conservar el resultado, agrega --reporte resultado.csv (o .json). El CLI guarda una fila por comprobante, con su idOperacion y su clave de acceso.

Lotes#

Cada ejecución de emitir queda registrada como un lote, así que si se corta a la mitad, por ejemplo porque se cayó la conexión, puedes reanudarlo en el mismo entorno en el que lo empezaste sin duplicar los comprobantes que ya se enviaron.

ecuafact lote listar
ecuafact lote estado 20261017-093012-0a66
ecuafact lote reanudar 20261017-093012-0a66 --esperar

Seguimiento#

Para saber en qué quedó una emisión, consulta su operación con estado.

ecuafact estado 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f

Descargar#

descargar baja el RIDE y el XML de los comprobantes autorizados. Indica una o más claves de acceso.

ecuafact descargar 0710202601012345678900110010010000001231234567811 --tipo ride,xml --entorno sandbox

Errores frecuentes#

Mensaje Qué hacer
Credenciales inválidas. Ejecuta ecuafact doctor y revisa la API Key del entorno y, en producción, que tu IP esté registrada.
Contribuyente, tipo o suscripción no habilitados. Usa uno de tus contribuyentes, que puedes ver con ecuafact cuenta, y revisa el entorno.
Cupo insuficiente: ... Revisa tu cupo con ecuafact consumo.
Operacion en PRODUCCION sin confirmar En un script, agrega --confirmar produccion.
El lote es del entorno '...' Reanuda el lote con el mismo --entorno con el que lo emitiste.

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.