npx facturas. Si es tu primera vez, empezá por el
recorrido del CLI, que cuenta en orden qué hace cada
comando y qué guarda en tu máquina.
Ayuda
npx facturas --help lista los cuatro comandos y las opciones globales, nada
más. Las opciones de cada comando están en su propia ayuda, con dos o tres
ejemplos y una nota corta de qué escribe y qué guarda:
-h y -v son alias de --help y --version. --help sale con código 0 y
nunca toca la red ni pregunta nada, aunque el resto de la línea esté mal.
init
Genera una clave privada RSA 2048 en PKCS#8 sin cifrar y el CSR que se sube en
ARCA. El subject es el que pide el instructivo oficial:
C=AR, O=<organización>, CN=<alias>, serialNumber=CUIT <cuit>, con un espacio
literal después de CUIT.
20-12345678-6 o 20 12345678 6. El CSR lleva solo los dígitos. Un
CUIT equivocado se nombra como equivocado, con lo que recibió y por qué:
--cuit y en ARCA_TAX_ID para check e
issue.
Escribe
arca-<entorno>.key con permisos 0600 y arca-<entorno>.csr. Si ya
existe alguno, se niega y sale con código 1. --force los pisa. Si hay un
.gitignore en el directorio, le agrega arca-*.key y arca-*.crt una sola
vez y te lo dice. En Windows los permisos 0600 no se aplican: guardá la clave
fuera del repositorio.
Sin terminal, por ejemplo en CI o scripts, --cuit y --env son obligatorios.
Si faltan, sale con código 2.
En homologación, además, copia el CSR al portapapeles antes de imprimir nada,
para que el paso 3 sea una sola pegada. En producción no lo copia: ahí ARCA
pide el archivo, no el texto.
Después imprime los pasos exactos en ARCA, en una sola lista para el entorno
que elegiste: init ya sabe si es homologación o producción, así que no
imprime los dos caminos. Los nombres de página, campo y botón están
verificados contra las referencias oficiales que lista
Habilitación en ARCA.
Para --env test:
xclip ni xsel, la línea del paso 3 cambia y el CSR sale impreso
ahí mismo, para copiarlo de la terminal:
--no-clipboard. El CSR no es secreto: es la clave pública
más el subject, y se sube a una página de ARCA.
En homologación no hay descarga: el certificado aparece en el cuadro de
resultado del propio WSASS, en PEM. Por eso init lo pide ahí mismo, mientras
la pestaña sigue abierta. Pegás el bloque entero y termina solo al ver la línea
-----END CERTIFICATE-----:
init verifica dos cosas. Si alguna falla, no guarda el
archivo y sale con código 1:
Ctrl-C, con --no-paste o sin terminal (CI, scripts)
no pregunta nada y te deja la instrucción de siempre, con código 0:
Solicitud de certificado en formato PKCS10.
Para --env production:
Representante al crear la relación con el servicio.
Las páginas, en una tabla, para tenerlas juntas:
El punto de venta no está en la salida de
init: check es el que informa
cuáles tenés habilitados. Su sistema depende de tu condición: RECE para aplicativo y Web Services para responsable inscripto, y las opciones
Factura Electrónica – Monotributo – Web Services o
Factura Electrónica – Exento en IVA – Web Services para monotributo y exento.
Comprobantes en línea es otro sistema y no sirve para web services.
No hay ningún export que copiar: check encuentra el par de archivos en el
directorio. Las variables de entorno son para tu aplicación, no para el CLI, y
están en Inicio rápido.
cert
cert toma el certificado que te dio ARCA, pegado, y lo guarda al lado de la clave.
Es lo mismo que init pregunta al final: cert está para cuando lo dejaste
para después, saliste con Ctrl-C o corriste init --no-paste.
arca-<entorno>.key con las mismas reglas que check: un solo par en el
directorio, o en --dir, gana y el entorno sale del nombre del archivo. Si
están los dos, no adivina y te pide --env. El CUIT sale del
arca-<entorno>.csr que escribió init, si sigue ahí. Si no está, no hay con
qué comparar y esa verificación se saltea.
Antes de escribir,
cert verifica que el certificado y la clave tengan el mismo
módulo RSA y que pertenezcan al mismo CUIT. Si no, no guarda nada:
0 si guardó el certificado o si saliste con Ctrl-C
sin pegar nada. Es 1 si no encontró la clave, si están los dos entornos, si ya
existe el .crt y no pasaste --force, si el certificado no corresponde o si
tres pegadas seguidas no fueron un PEM. Es 2 si --env no es uno de los dos.
Sin terminal también funciona, para scripts: npx facturas cert < cert.pem
lee de la entrada estándar, sin prompt.
check
check prueba las capas en orden y para en la primera que falla. Después de init,
con el certificado guardado al lado de la clave, no necesita nada más:
De dónde sale cada valor
check e issue buscan en este orden, y el primero que responde gana:
Los archivos son los que escribe
init, con el nombre que muestra el comando.
La búsqueda es en el directorio actual o en --dir. Reglas:
- Si está un solo par completo, ese se usa, y el entorno sale del nombre
del archivo:
arca-test.crtes homologación. - Si están los dos pares, el CLI no adivina: sale con código 1 y te pide
--env testo--env production. - Si está medio par, te dice cuál falta. Entre
inity la respuesta de ARCA vas a verEstá arca-test.key pero falta arca-test.crt. - El CUIT sale del
serialNumberdel certificado, donde ARCA lo escribe comoCUIT <11 dígitos>. Si el certificado no lo trae y tampoco lo pasaste, el CLI te pide--cuit. Si pasaste uno y el certificado dice otro, el CLI se detiene. Es un certificado de otro contribuyente, y falla la capacertificado y clavecon los dos números a la vista.
createArcaClient() no mira el
disco: sigue leyendo variables de entorno, como explica
Configuración.
Las capas, en orden:
Hay dos advertencias que no son fallas y mantienen el código de salida 0: un
certificado que vence en menos de 30 días, y una lista de puntos de venta vacía
en homologación, donde ARCA muchas veces no los informa aunque funcionen. En
ese caso un
--sales-point que no figura en la lista sale como
3 (no informado) y issue puede seguir.
En producción no hay excepción: si ARCA no informa ningún punto de venta, no
hay comprobante que puedas emitir, así que la capa falla y check sale con
código 1.
Diagnósticos
Cada falla que el CLI sabe nombrar tiene exactamente una fila. Es la tabla completa:
Cualquier otro error sale con el mensaje seguro del SDK y su código estable.
Las clases de error están en Errores.
--json
check e issue aceptan --json. check imprime un solo objeto. Las capas a
las que no llegó no aparecen.
issue --json imprime el resultado tal como lo devuelve issue() del SDK, sin
evidencia cruda. Si ARCA falla entre la consulta del número y la autorización,
sale un objeto con la misma forma que el de check, con el
mensaje seguro y el código estable del SDK:
issue
Emite una factura de ARS 1 en homologación, para probar el circuito
completo. Se niega si ARCA_ENVIRONMENT no es test. Corre antes las capas de
check y no sigue si alguna falla.
check, incluidos --dir y --no-cache, más --issuer, con las
cuatro condiciones de emisor: monotributo, responsable_inscripto, exento y no_alcanzado. En
una terminal pregunta el punto de venta y el emisor si no los pasaste.
Emite sin store y sin idempotencyKey: es el inicio rápido en un comando. En
tu aplicación real, configurá los dos, como explica
Inicio rápido.
Los otros tres resultados salen con código 1: rejected lista los errores de
ARCA uno por línea, e indeterminate y conflict muestran el número y la
evidencia con el consejo de
Inicio rápido.
Si ARCA se cae después de que pasaron las capas, la emisión falla como una capa
más. Muestra ✗ emisión, el mensaje seguro del SDK y sale con código 1.
Nunca sale una traza ni un PEM.
Códigos de salida
Colores
El CLI usa ANSI solo cuando la salida es una terminal. Se apaga con--no-color o con la variable NO_COLOR, y se enciende sin terminal con
FORCE_COLOR (FORCE_COLOR=0 lo apaga). En los reportes el color va
únicamente en las marcas ✓, ✗ y !. En la ayuda, aparece en los títulos de sección
(atenuados), los nombres de comando (negrita) y los ejemplos (cian, con el $
atenuado). Sin color, el texto es exactamente el mismo menos los escapes.