Inicio rápido

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:

npx facturas init --cuit 20123456786 --env test

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á

pnpm add facturas

npm install facturas

Requiere Node.js 22 o superior y módulos ESM.

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.

import { createArcaClient } from "facturas";

const arca = createArcaClient();

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:

npx facturas check

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 Comandos del 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:

const factura = await arca.issue({
  issuer: "monotributo",
  salesPoint: 3,
  to: { condition: "consumidor_final" },
  items: [{ amount: 150_000 }], // ARS 1.500,00 en centavos
});

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 Emitir 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 request enviado no aparecen por defecto. Podés pedirlos con include: { rawResponse: true, request: 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. 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á:

import { createArcaClient, createPostgresStore } from "facturas";
import { Pool } from "pg";

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

const arca = createArcaClient({
  store: createPostgresStore({ query: (text, params) => pool.query(text, params) }),
});

const factura = await arca.issue(input, { idempotencyKey: venta.id });

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. Antes del primer comprobante real, repasá la lista y la prueba de ARS 1 según la clase del comprobante en Pasar a producción.

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:

if (factura.kind === "authorized") {
  const nota = await arca.issueCreditNote(
    {
      for: factura.voucher,
      items: [{ amount: 50 }], // ARS 0,50 de una factura de ARS 1,00.
    },
    { idempotencyKey: `nc:${venta.id}` },
  );
  console.log(nota); // También debe tratarse cada resultado de la nota.
}

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.

Empezar

Guías

Referencia

1. Habilitá ARCA

2. Instalá

3. Configurá el cliente

4. Emití la primera factura

5. Tratá todos los resultados

6. Evitá duplicados al reintentar

7. Pasá a producción

8. Emití una nota de crédito

​1. Habilitá ARCA

​2. Instalá

​3. Configurá el cliente

​4. Emití la primera factura

​5. Tratá todos los resultados

​6. Evitá duplicados al reintentar

​7. Pasá a producción

​8. Emití una nota de crédito

1. Habilitá ARCA

2. Instalá

3. Configurá el cliente

4. Emití la primera factura

5. Tratá todos los resultados

6. Evitá duplicados al reintentar

7. Pasá a producción

8. Emití una nota de crédito