Configuración

Variables de entorno

createArcaClient() descubre los campos que faltan con las mismas reglas que createArcaClientConfigFromEnv(). Los campos explícitos tienen prioridad y process.env no se modifica.

Variable	Obligatoria	Notas
`ARCA_TAX_ID`	Sí	CUIT de 11 dígitos
`ARCA_CERTIFICATE_PEM`	Sí	Certificado PEM
`ARCA_PRIVATE_KEY_PEM`	Sí	Clave privada PEM
`ARCA_ENVIRONMENT`	Sí	`test` o `production`. No hay valor por defecto

Para loguear sin tocar el código, definí ARCA_LOG_LEVEL en debug, info, warn o error.

Opciones de `createArcaClient()`

Pasale un objeto de configuración a createArcaClient:

import { createArcaClient } from "facturas";

const client = createArcaClient({
  timeout: 30_000,
  retries: 2,
  retryDelay: 500,
  logger: { level: "debug" },
  // Si hay varios procesos, podés compartir los tickets de WSAA.
  // wsaaSessionStore,
});

Campo	Por defecto	Descripción
`taxId`	`ARCA_TAX_ID`	CUIT de 11 dígitos
`certificatePem`	`ARCA_CERTIFICATE_PEM`	Certificado PEM
`privateKeyPem`	`ARCA_PRIVATE_KEY_PEM`	Clave privada PEM
`environment`	`ARCA_ENVIRONMENT`	`test` o `production`. Sin valor por defecto: si falta en ambos lados, `createArcaClient()` lanza `ArcaConfigurationError`
`timeout`	`30000`	Límite de cada pedido HTTP en milisegundos
`retries`	`0`	Intentos extra, solo ante fallas de transporte
`retryDelay`	`500`	Espera entre reintentos de transporte en milisegundos
`logger`	No aplica	Configuración opcional del logger estructurado
`store`	No aplica	Tickets y reservas persistentes unificados
`wsaaSessionStore`	No aplica	Store opcional de tickets WSAA para despliegues con varios procesos

Stores de sesión WSAA

Por defecto, los tickets de login de WSAA se guardan solo en el proceso actual. Eso mantiene los scripts y las apps de un solo proceso sin configuración:

const client = createArcaClient();

Un store configurado provee tickets WSAA persistentes de forma automática. Un wsaaSessionStore explícito sigue soportado y tiene prioridad, solo para los tickets.

import {
  type ArcaAuthCredentials,
  type ArcaWsaaSessionKey,
  createArcaClient,
} from "facturas";

const wsaaSessionStore = {
  async get(key: ArcaWsaaSessionKey): Promise<ArcaAuthCredentials | null> {
    // Leé desde Postgres, Redis u otro store compartido.
    return null;
  },
  async set(
    key: ArcaWsaaSessionKey,
    credentials: ArcaAuthCredentials
  ): Promise<void> {
    // Guardá token, sign y expiresAt para esta clave.
  },
  async withLock<T>(
    key: ArcaWsaaSessionKey,
    fn: () => Promise<T>
  ): Promise<T> {
    // Conviene serializar las renovaciones simultáneas.
    return await fn();
  },
};

const client = createArcaClient({
  wsaaSessionStore,
});

La clave del store está alcanzada por entorno, servicio WSAA y huella del certificado. Con store, el SDK cifra cada ticket antes de guardarlo, con AES-256-GCM y una clave derivada de tu clave privada, así que ningún adaptador, incluido el tuyo, ve el ticket en claro. No hace falta configurar ningún secreto más: quien tiene la clave privada ya puede iniciar sesión por su cuenta. Un wsaaSessionStore propio recibe las credenciales en claro y el cifrado en reposo queda de tu lado. Las lecturas del store igual se controlan con el margen de seguridad de expiración del SDK. Un store de producción tendría que compartir los datos entre todos los procesos, hacer cumplir la expiración en la lectura e implementar un bloqueo con advisory locks de Postgres, bloqueos de Redis o un mecanismo equivalente. Para pruebas y coordinación local a través de un objeto compartido, el paquete también exporta createMemoryWsaaSessionStore().

Logs

El nivel mínimo por defecto es warn. En debug, el SDK loguea los requests SOAP, los tiempos de respuesta, el origen del login WSAA (cached o fresh) y los reintentos.

const client = createArcaClient({
  logger: { level: "debug" },
});

Los callbacks de un logger propio reciben (level, message, ...args):

const client = createArcaClient({
  logger: {
    level: "info",
    log(level, message, ...args) {
      // Enviá el evento a tu logger.
    },
  },
});

Desactivá los logs por completo con logger: { disabled: true }.

Reintentos y límites de tiempo

Los reintentos de transporte configurados se aplican solo a ArcaTransportError: límites de tiempo, fallas de conexión y respuestas HTTP de error que no son XML. Las respuestas XML, incluidos los errores SOAP con HTTP 500, se parsean y se exponen como errores de SOAP o de servicio en vez de reintentarse a ciegas. Aparte, las operaciones autenticadas de conveniencia de WSFE y WSMTXCA pueden hacer un reintento con refresco forzado, solo después de un ArcaAuthenticationError. Los límites de tiempo, la pérdida de conexión, el SOAP inválido, la evidencia incompleta, la evidencia contradictoria y los rechazos genéricos de servicio nunca habilitan ese camino de recuperación. wsfe.issue() y wsmtxca.issue() siempre hacen un único intento de autorización, y cada intento SOAP de autorización va con los reintentos de transporte en cero.

Selección avanzada del servicio de emisión

createArcaClient() no detecta ni configura el servicio de emisión. Los métodos de la fachada usan WSFE por defecto. Solo cuando el contribuyente o el punto de venta opere a través de WSMTXCA, pasá { service: "wsmtxca" } en la llamada. El SDK no cambia de servicio solo. Revisá WSMTXCA para casos requeridos.

Empezar

Guías

Referencia

Variables de entorno

Opciones de `createArcaClient()`

Stores de sesión WSAA

Logs

Reintentos y límites de tiempo

Selección avanzada del servicio de emisión

​Variables de entorno

​Opciones de createArcaClient()

​Stores de sesión WSAA

​Logs

​Reintentos y límites de tiempo

​Selección avanzada del servicio de emisión

Variables de entorno

Opciones de `createArcaClient()`

Stores de sesión WSAA

Logs

Reintentos y límites de tiempo

Selección avanzada del servicio de emisión