1. Habilitá ARCA
Necesitás CUIT, certificado y clave privada, la relación del certificado con
el servicio Facturación Electrónica, y un punto de venta habilitado para
web services. Homologación y producción tienen certificados y puntos de venta
propios. El SDK no hace estas habilitaciones por vos, pero el CLI te acompaña:
El comando genera la clave privada y el CSR que se sube en ARCA. En homologación,
te deja el CSR en el portapapeles. Después imprime qué página abrir, qué botón
usar y qué servicio autorizar. Cuando ARCA te dé el certificado, pegalo en el
prompt final. El CLI lo guarda en ese mismo directorio como arca-test.crt.
Si saliste antes, npx facturas cert lo toma después. El
paso a paso completo y las referencias oficiales están en
Habilitación en ARCA. Los comandos están en
CLI.
2. Instalá
Requiere Node.js 20 o superior y módulos ESM. Si usás Vercel Postgres,
instalá también el cliente @vercel/postgres de tu aplicación.
3. Configurá el cliente
Definí ARCA_TAX_ID, ARCA_CERTIFICATE_PEM, ARCA_PRIVATE_KEY_PEM y
ARCA_ENVIRONMENT=test. Los PEM deben contener el certificado y la clave
completos. No los subas al repositorio. No hay entorno predeterminado: test
apunta a homologación y production a los servidores reales.
Los campos explícitos de createArcaClient() tienen prioridad.
Con eso alcanza para emitir: el cliente lee las variables de entorno y guarda
el ticket WSAA en memoria. No necesitás base de datos ni ningún servicio
externo. El resto de las opciones está en Configuración.
Antes de escribir código, confirmá las habilitaciones:
El comando prueba la configuración, el certificado, WSAA, WSFE y los puntos de
venta en ese orden. Si algo falla, nombra el paso y muestra dónde corregirlo en
ARCA. No
hace falta exportar nada para correrlo: si arca-test.crt y arca-test.key
están en el directorio, los usa, y saca de ahí el entorno y el CUIT. No
escribe nada en ARCA. Guarda el ticket WSAA en el directorio temporal para
poder repetirse. La tabla completa de diagnósticos está en
CLI.
4. Emití la primera factura
Elegí tu condición real de emisor y tu punto de venta habilitado. Este bloque
es examples/primera-factura.ts:
El importe se expresa en centavos. Para responsables inscriptos usá
issuer: "responsable_inscripto" e ítems como { gross: 12_100, vat: 21 }.
Si preferís probar el circuito antes de escribir código,
npx facturas issue --sales-point 3 --issuer monotributo emite una factura de
ARS 1 en homologación y te imprime la llamada que hizo.
ARCA valida la habilitación fiscal. El SDK no infiere tu condición. Todos los
campos del input están en Facturas.
Antes de emitir podés revisar lo que el SDK va a enviar con
arca.preview(input): es sincrónico, no hace ninguna llamada y devuelve la
clase, el tipo de comprobante, los amounts y el request exacto. Compará
preview(input).amounts.sentTotal con el total de tu venta y recién entonces
llamá a issue().
5. Tratá todos los resultados
authorized: guardá factura.voucher y su CAE.rejected: revisá los errores que devolvió ARCA.indeterminate: conservá el número y la evidencia. Conciliá o repetí el mismo input con su clave, como explica el paso 6.conflict: hay otro comprobante en ese número. Detené el flujo e investigá.
La evidencia SOAP y el input exacto no aparecen por defecto. Podés pedirlos
con include: { raw: true, exactInput: true }. La secuencia de llamadas está en
Qué hace issue() al emitir.
Cuando una llamada falla, mirá Errores.
6. Evitá duplicados al reintentar
ARCA no acepta una clave de idempotencia como Stripe. Si se corta la respuesta,
tu aplicación no sabe si ARCA emitió el comprobante. facturas facilita un
mecanismo de deduplicación: guardá el intento en un store y pasá el ID estable
de la venta como idempotencyKey. Al reintentar, el SDK consulta el número
reservado antes de decidir si tiene que emitir.
Creá una vez la tabla Postgres y usá:
Un solo store guarda tickets WSAA y reservas de comprobantes. También hay
adaptadores para Redis, archivos y memoria. La memoria sirve para pruebas y no
sobrevive al reinicio del proceso. Comparalos en
Evitar comprobantes duplicados.
Usá de 1 a 255 caracteres, sin CUIT, DNI ni otros datos personales. No generes
una clave nueva por intento. Una clave con un input diferente produce
ARCA_INPUT_IDEMPOTENCY_MISMATCH. No borres ni hagas vencer las reservas:
guardan el número fiscal que el reintento debe consultar.
7. Pasá a producción
Habilitá el certificado y punto de venta de producción y cambiá
ARCA_ENVIRONMENT=production. Una prueba de ARS 1 usa items: [{ amount: 100 }].
Una factura de prueba en producción es un documento fiscal real y queda registrada en ARCA.
8. Emití una nota de crédito
ARCA no anula comprobantes: una corrección es una nota de crédito, que también
es un documento real. Lo habitual es la nota parcial, que acredita las líneas
que elegís:
Con all: true en lugar de items acreditás el total del original. El modo es
explícito y obligatorio: sin items ni all: true, el SDK falla antes de
cualquier llamada, así un campo olvidado nunca acredita la factura entera.
La nota es una segunda operación. Si falla, la factura sigue pendiente. La
clase, el receptor, la moneda, el concepto y las fechas de servicio salen del
original. Vos aportás las líneas y, como mucho, el punto de venta y la fecha de
la nota. issueDebitNote() emite notas de débito y associatedPeriod permite
emitir notas por período. Está todo
en Notas de crédito. Si además necesitás detalle de
ítems, el comprobante va por WSMTXCA.