> ## Documentation Index
> Fetch the complete documentation index at: https://facturas-sdk.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuración

> Configurá credenciales, entorno, sesiones WSAA, logs, reintentos y límites de tiempo.

## 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`:

```ts theme={null}
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:

```ts theme={null}
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.

```ts theme={null}
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. 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, cifrar o apoyarse en almacenamiento cifrado,
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.

```ts theme={null}
const client = createArcaClient({
  logger: { level: "debug" },
});
```

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

```ts theme={null}
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.