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:
- La opción
--tipo:factura,liquidacion,nota-credito(onc),nota-debito(ond),guia,retencion, o el código01,03,04,05,06o07. - La forma del comprobante, cuando solo puede ser un tipo:
motivoses una nota de débito (05),destinatariosuna guía de remisión (06),docsSustentouna retención (07); condetalles,codDocModificadoovalorModificacionindican una nota de crédito (04),razonSocialProveedoroidentificacionProveedoruna liquidación de compra (03), y un comprador conpagoseimporteTotaluna 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#
- Emitir desde CSV o Excel: emite desde las filas de tu archivo sin escribir JSON.
- Vigilar una carpeta: emite automáticamente los archivos que deja tu ERP.
- Referencia de comandos: consulta todas las opciones y los códigos de salida.