@ramiidv/arca-agro 0.1.0 → 0.3.0

package/README.md

@@ -1,10 +1,11 @@
 # @ramiidv/arca-agro
 
-SDK para los servicios web agropecuarios de ARCA (ex AFIP), Argentina. Integra tres servicios en un solo paquete:
+SDK para los servicios web agropecuarios de ARCA (ex AFIP), Argentina:
 
-- **WSCPE** - Carta de Porte Electrónica (transporte de granos por vía automotor)
-- **WSCTG** - Código de Trazabilidad de Granos (seguimiento del transporte)
-- **WSLPG** - Liquidación Primaria de Granos (liquidaciones y certificaciones)
+- **WSCPE**: Carta de Porte Electrónica (granos, automotor y ferroviaria). Reemplazó al CTG (RG 5017/2021).
+- **WSLPG**: Liquidación Primaria de Granos y certificación primaria.
+
+> **WSCTG ya no existe.** El Código de Trazabilidad de Granos fue derogado el 1/11/2021 y reemplazado por la Carta de Porte Electrónica; sus endpoints responden 404. Desde la versión 0.3.0 este paquete no lo incluye. El número de CTG ahora lo asigna WSCPE al autorizar la CPE (`cabecera.nroCTG`).
 
 ## Instalación
 
@@ -15,256 +16,287 @@ npm install @ramiidv/arca-agro @ramiidv/arca-common
 ## Requisitos
 
 - Node.js >= 18
-- Certificado digital y clave privada emitidos por ARCA
-- Autorización en los servicios `wscpe`, `wsctg` y/o `wslpg` en WSAA
+- Certificado digital y clave privada emitidos por ARCA, autorizados en WSAA para `wscpe` y/o `wslpg`.
 
 ## Inicio rápido
 
 ```ts
-import { ArcaAgro } from '@ramiidv/arca-agro';
 import fs from 'node:fs';
+import { FileTicketStorage } from '@ramiidv/arca-common';
+import { ArcaAgro, TIPO_CPE } from '@ramiidv/arca-agro';
 
 const agro = new ArcaAgro({
-  cuit: 20123456789,
+  cuit: '20-12345678-6', // CUIT representada (se valida el dígito verificador)
   cert: fs.readFileSync('cert.pem', 'utf-8'),
   key: fs.readFileSync('key.pem', 'utf-8'),
   production: false, // true para producción
+  ticketStorage: new FileTicketStorage('.arca-tickets'), // recomendado: persiste el TA entre reinicios
 });
 ```
 
-La autenticación WSAA se maneja automáticamente. Los tokens se cachean y renuevan según sea necesario.
+La autenticación WSAA es automática: el ticket se cachea y se renueva cuando vence.
 
-## WSCPE - Carta de Porte Electrónica
+Todos los métodos aceptan un último argumento opcional `{ signal }` (`AbortSignal`) para cancelar la llamada.
 
-```ts
-// Autorizar una carta de porte
-const resultado = await agro.cpe.autorizarCPEAutomotor({
-  cuitTitularCartaPorte: 20123456789,
-  sucursal: 1,
-  nroOrden: 1,
-  codTipoCartaPorte: 1,
-  codGrano: 23, // soja
-  codLocalidadProcedencia: 10001,
-  codProvProcedencia: 1,
-  codLocalidadDestino: 20001,
-  codProvDestino: 12,
-  cuitDestino: 30111222333,
-  plantaDestino: 1,
-  pesoNeto: 30000,
-  pesoBruto: 32000,
-  pesoTara: 2000,
-  patente: 'ABC123',
-  cuitTransportista: 20999888777,
-  fechaEmision: '2026-03-31',
-});
+## WSCPE: Carta de Porte Electrónica
 
-// Confirmar arribo
-await agro.cpe.confirmadoArriboCPE({
-  nroCTG: resultado.nroCTG!,
-  nroCartaPorte: resultado.nroCartaPorte!,
-  cuitDestino: 30111222333,
-  pesoNeto: 29800,
-  fechaArribo: '2026-04-01',
-});
+Los requests siguen el XSD oficial de WSCPE (mismos nombres y anidamiento). El SDK arma el XML en el orden del XSD, valida los datos antes de enviarlos y devuelve objetos tipados.
+
+Tipos de carta de porte (`TIPO_CPE`): `74` automotor, `75` ferroviaria, `274` automotor flete corto.
+
+### Autorizar una CPE automotor
 
-// Consultar CPEs
-const cpes = await agro.cpe.consultarCPE({
-  fechaDesde: '2026-03-01',
-  fechaHasta: '2026-03-31',
-  codGrano: 23,
+```ts
+const sucursal = 1;
+const nroOrden = await agro.cpe.siguienteNroOrden(sucursal, TIPO_CPE.AUTOMOTOR);
+
+const cpe = await agro.cpe.autorizarCPEAutomotor({
+  cabecera: { tipoCP: TIPO_CPE.AUTOMOTOR, cuitSolicitante: '20123456786', sucursal, nroOrden },
+  origen: { productor: { codProvincia: 1, codLocalidad: 10270 } }, // o { operador: { codProvincia, codLocalidad, planta } }
+  correspondeRetiroProductor: false,
+  esSolicitanteCampo: true,
+  datosCarga: { codGrano: 23, cosecha: 2526, pesoBruto: 42000, pesoTara: 12000 },
+  destino: { cuit: '30500011129', esDestinoCampo: false, codProvincia: 12, codLocalidad: 5244, planta: 1938 },
+  destinatario: { cuit: '30500011129' },
+  transporte: {
+    cuitTransportista: '20999888772',
+    dominio: ['AB123CD'],
+    fechaHoraPartida: new Date('2026-11-02T08:00:00-03:00'),
+    kmRecorrer: 250,
+    cuitChofer: '27300000008',
+    tarifa: 1500.5,
+    cuitPagadorFlete: '30712345671',
+    mercaderiaFumigada: false,
+  },
 });
 
-// Rechazar / Anular
-await agro.cpe.rechazoCPE({ nroCTG: 12345, nroCartaPorte: 67890, codMotivo: 1 });
-await agro.cpe.anularCPE({ nroCTG: 12345, nroCartaPorte: 67890, codMotivo: 2 });
+cpe.cabecera.nroCTG; // '010100012345' (string)
+cpe.cabecera.estado; // 'AC'
+cpe.pdf;             // constancia en base64
+```
 
-// Obtener constancia PDF (base64)
-const pdfBase64 = await agro.cpe.consultarConstanciaCPEPDF(12345);
+> **`siguienteNroOrden` no es atómico.** Hace `consultarUltNroOrden + 1`: dos procesos que lo llamen a la vez obtienen el mismo número y ARCA rechaza la segunda autorización. Si emitís en paralelo para la misma sucursal y tipo, serializá las emisiones o llevá tu propio contador.
 
-// Obtener siguiente número de orden
-const nroOrden = await agro.cpe.siguienteNroOrden(1);
+### Circuito automotor
 
-// Estado del servicio
-const status = await agro.cpe.dummy();
+```ts
+const cartaPorte = { tipoCPE: TIPO_CPE.AUTOMOTOR, sucursal: 1, nroOrden: 15 };
+
+await agro.cpe.confirmarArriboCPE({ cuitSolicitante, cartaPorte });
+await agro.cpe.confirmacionDefinitivaCPEAutomotor({ cuitSolicitante, cartaPorte, pesoBrutoDescarga: 41900, pesoTaraDescarga: 12000 });
+await agro.cpe.descargadoDestinoCPE({ cuitSolicitante, cartaPorte });
+await agro.cpe.rechazoCPE({ cuitSolicitante, cartaPorte, rechazoMotivo: 2, rechazoObservaciones: 'Humedad' });
+await agro.cpe.anularCPE({ cartaPorte, anulacionMotivo: 3, anulacionObservaciones: 'Error de carga' });
+await agro.cpe.editarCPEAutomotor({ nroCTG, cuitDestinatario, cuitChofer, cuitTransportista, destino, pesoBruto, codGrano });
+await agro.cpe.editarCPEConfirmadaAutomotor({ nroCTG, intervinientes: { cuitCorredorVentaPrimaria } });
+await agro.cpe.nuevoDestinoDestinatarioCPEAutomotor({ cartaPorte, destino, transporte: { fechaHoraPartida, kmRecorrer } });
+await agro.cpe.regresoOrigenCPEAutomotor({ cartaPorte, transporte: { fechaHoraPartida, kmRecorrer } });
+await agro.cpe.desvioCPEAutomotor({ cuitSolicitante, cartaPorte, destino, transporte });
+await agro.cpe.informarContingencia({ cartaPorte, contingencia: { concepto: 'C', descripcion: 'Desperfecto mecánico' } });
+await agro.cpe.cerrarContingenciaCPE({ cartaPorte, concepto: 'A' });
+
+const detalle = await agro.cpe.consultarCPEAutomotor({ nroCTG: '010100012345' }); // o { cartaPorte }
 ```
 
-## WSCTG - Código de Trazabilidad de Granos
+Las operaciones que modifican una CPE devuelven `CPEResultado` (`{ cabecera?, pdf?, metadata? }`).
 
-```ts
-// Solicitar un CTG
-const ctg = await agro.ctg.solicitarCTGInicial({
-  nroCartaPorte: 67890,
-  codEspecie: 23,
-  cuitDestino: 30111222333,
-  cuitDestinatario: 30111222333,
-  codLocalidadOrigen: 10001,
-  codLocalidadDestino: 20001,
-  codCosecha: 2526,
-  pesoNeto: 30000,
-});
+### Circuito ferroviario
 
-// Confirmar arribo
-await agro.ctg.confirmarArribo({
-  nroCTG: ctg.nroCTG!,
-  nroCartaPorte: 67890,
-  cuitDestino: 30111222333,
-  pesoNeto: 29800,
-  fechaArribo: '2026-04-01',
-});
+`autorizarCPEFerroviaria`, `consultarCPEFerroviaria`, `editarCPEFerroviaria`, `editarCPEConfirmadaFerroviaria`, `confirmacionDefinitivaCPEFerroviaria`, `nuevoDestinoDestinatarioCPEFerroviaria`, `regresoOrigenCPEFerroviaria`, `desvioCPEFerroviaria` y `consultaCPEFerroviariaPorNroOperativo`.
 
-// Consultar CTGs
-const ctgs = await agro.ctg.consultarCTG({
-  fechaDesde: '2026-03-01',
-  fechaHasta: '2026-03-31',
-});
+### Consultas y paramétricas
 
-// Exportar a Excel (base64)
-const excelBase64 = await agro.ctg.consultarCTGExcel({
-  fechaDesde: '2026-03-01',
-  fechaHasta: '2026-03-31',
-});
+```ts
+await agro.cpe.consultarUltNroOrden(1, TIPO_CPE.AUTOMOTOR);  // número; si ARCA no lo devuelve, lanza
+await agro.cpe.consultarCPEPorDestino({ planta: 1938, fechaPartidaDesde: '2026-11-01', fechaPartidaHasta: '2026-11-07' });
+await agro.cpe.consultarCPEPPendientesDeResolucion({ perfil: 'D', planta: 1938 });
+await agro.cpe.consultarProvincias();
+await agro.cpe.consultarLocalidadesPorProvincia(12);
+await agro.cpe.consultarTiposGrano();
+await agro.cpe.consultarPlantas('30500011129');
+await agro.cpe.consultarLocalidadesProductor('20123456786');
+await agro.cpe.consultarCategoriasSemillas();
+await agro.cpe.consultarVariedadesSemillas(23);
+await agro.cpe.dummy();
+```
 
-// Rechazar / Anular
-await agro.ctg.rechazarCTG({ nroCTG: 123, nroCartaPorte: 456, codMotivo: 1 });
-await agro.ctg.anularCTG({ nroCTG: 123, nroCartaPorte: 456, codMotivo: 2 });
+Las listas sin resultados devuelven `[]`; si ARCA devuelve errores, se lanza `ArcaAgroServiceError` (nunca una lista vacía).
 
-// CTGs activos
-const activos = await agro.ctg.obtenerCTGActivos();
+### No soportado en WSCPE
 
-// Constancia PDF (base64)
-const pdf = await agro.ctg.consultarConstanciaCTGPDF(12345);
+El circuito de **derivados granarios** (CPE DG, tipos 284-287: `autorizarCPEAutomotorDG`, `autorizarCPEFerroviariaDG`, `autorizarCPEDuctosDG`, `autorizarCPEEmisionDestinoDG`, etc.), `consultarCPEDuctos`, `consultarRenspa`, `consultarDomiciliosPorCUIT` y las paramétricas de DG (`consultarTiposEmbalaje`, `consultarUnidadesMedida`, `consultarDerivadosGranarios`, `consultarPlantasDG`) todavía no están implementados.
 
-// Estado del servicio
-const status = await agro.ctg.dummy();
-```
+## WSLPG: Liquidación Primaria de Granos
 
-## WSLPG - Liquidación Primaria de Granos
+`liquidacion` sigue `LpgLiquidacionBaseType` del XSD; `deducciones`, `retenciones` y `percepciones` van como hermanos (arrays).
 
 ```ts
-// Autorizar una liquidación
-const liq = await agro.lpg.liquidacionAutorizar({
-  cuitComprador: 30111222333,
-  cuitVendedor: 20123456789,
-  codGrano: 23,
-  pesoNeto: 30000,
-  precioRefTn: 350000,
+const ptoEmision = 1;
+const nroOrden = (await agro.lpg.liquidacionUltimoNroOrdenConsultar(ptoEmision)) + 1;
+
+const { autorizacion, eventos } = await agro.lpg.liquidacionAutorizar({
+  liquidacion: {
+    ptoEmision,
+    nroOrden,
+    cuitComprador: '20123456786',
+    nroActComprador: 40,
+    nroIngBrutoComprador: 901234567,
+    codTipoOperacion: '1',
+    codPuerto: 14,
+    codGrano: 31,
+    cuitVendedor: '30712345671',
+    nroIngBrutoVendedor: 900123,
+    liquidaCorredor: 'N',
+    fechaPrecioOperacion: '2026-10-30',
+    precioRefTn: 250000,
+    precioFleteTn: 0,
+    campaniaPPal: 2526,
+    codLocalidadProcedencia: 3,
+    codProvProcedencia: 1,
+    pesoNetoSinCertificado: 30000,
+  },
+  deducciones: [{ codigoConcepto: 'CO', comisionGastosAdm: 1.5, alicuotaIva: 21 }],
+  retenciones: [{ codigoConcepto: 'RG', baseCalculo: 7500000, alicuota: 2 }],
 });
 
-// Consultar liquidaciones
-const liquidaciones = await agro.lpg.liquidacionConsultar({
-  fechaDesde: '2026-03-01',
-  fechaHasta: '2026-03-31',
-});
+autorizacion.coe;             // '330100012345' (string)
+autorizacion.totalNetoAPagar; // number
+```
 
-// Anular liquidación
-await agro.lpg.liquidacionAnular(1, 100);
+Los códigos de actividad, operación, puerto, grano, deducción y retención salen de las paramétricas.
 
-// Ajuste unificado
+```ts
+await agro.lpg.liquidacionXCoeConsultar(coe, { pdf: true }); // { liquidacion, autorizacion, pdf, eventos }
+await agro.lpg.liquidacionXNroOrdenConsultar(ptoEmision, nroOrden);
+await agro.lpg.liquidacionAnular(coe);                         // { coe, resultado, pdf?, eventos }
 await agro.lpg.liquidacionAjustarUnificado({
-  nroOrdenOriginal: 100,
-  ptoEmisionOriginal: 1,
-  tipoAjuste: 'credito',
-  liquidacion: { pesoNeto: 29500 },
+  ajusteBase: { ptoEmision, nroOrden, coeAjustado: coe, codLocalidad: 3, codProv: 1 },
+  ajusteDebito: { diferenciaPesoNeto: 0, diferenciaPrecioOperacion: 1000, diferenciaPrecioFleteTn: 0 },
 });
 
-// Autorizar certificación
-const cert = await agro.lpg.certificacionAutorizar({
-  tipoCertificacion: 1,
-  cuitDepositante: 20123456789,
-  codGrano: 23,
-  pesoNeto: 30000,
-});
+// Certificación primaria
+await agro.lpg.cgConsultarUltimoNroOrden(ptoEmision);
+await agro.lpg.cgAutorizar({ cabecera: { ... }, primaria: { ... } }); // o retiroTransferencia / preexistente
+await agro.lpg.cgSolicitarAnulacion(coe);
+await agro.lpg.cgConfirmarAnulacion(coe, { pdf: true });
+
+// Paramétricas
+await agro.lpg.tipoGranoConsultar();
+await agro.lpg.puertoConsultar();
+await agro.lpg.provinciasConsultar();
+await agro.lpg.localidadXProvinciaConsultar(1);
+await agro.lpg.tipoActividadConsultar();
+await agro.lpg.tipoActividadRepresentadoConsultar();
+await agro.lpg.tipoOperacionXActividadConsultar(40);
+await agro.lpg.tipoDeduccionConsultar();
+await agro.lpg.tipoRetencionConsultar();
+await agro.lpg.tipoCertificadoDepositoConsultar();
+await agro.lpg.codigoGradoReferenciaConsultar();
+await agro.lpg.codigoGradoEntregadoXTipoGranoConsultar(2);
+await agro.lpg.campaniasConsultar();
+await agro.lpg.dummy();
+```
 
-// Anular certificación
-await agro.lpg.certificacionAnular(1, cert.nroCertificacion!);
+### No soportado en WSLPG
 
-// Consultar parámetros (tipos de grano, grados, puertos, etc.)
-const granos = await agro.lpg.consultarParametros('tipoGranoConsultar');
+Liquidación secundaria (`lsg*`), anticipos (`lpgAutorizarAnticipo`, `lpgCancelarAnticipo`), anulación contra documento, ajuste por contrato (`liquidacionAjustarContrato`, `asociarLiquidacionAContrato`, `*PorContratoConsultar`, `ajusteXCoeConsultar`, `ajusteXNroOrdenConsultar`) y el resto de las operaciones de certificación (`cgBuscarCtg`, `cgBuscarCertConSaldoDisponible`, `cgConsultarXCoe`, `cgConsultarXNroOrden`, `cgInformarCalidad`).
 
-// Estado del servicio
-const status = await agro.lpg.dummy();
-```
+## Errores
 
-## Verificar todos los servicios
+| Error | Cuándo |
+|-------|--------|
+| `ArcaValidationError` | Datos inválidos, antes de llamar a ARCA: campo obligatorio faltante, campo desconocido, CUIT con dígito verificador incorrecto, `NaN`/`Infinity`, rangos y largos del XSD, fechas. `details[]` trae cada campo con su ruta (ej: `transporte.dominio[0]`). |
+| `ArcaAgroServiceError` (extiende `ArcaServiceError`) | ARCA rechazó la operación: `errores.error[]` (y en WSLPG también `erroresFormato.error[]`). `errors[]`, `service`, `method` y `response` (el nodo completo devuelto). |
+| `ArcaSoapError` | Red, timeout, HTTP o SOAP Fault. `uncertain` indica si ARCA pudo haber procesado el request. |
+| `ArcaAgroResponseError` | La respuesta no trae un dato imprescindible (ej: `nroCTG` al autorizar, `coe` al liquidar, `nroOrden` al consultar el último). `uncertain` es `true` en emisiones. |
+| `ArcaAuthError` / `ArcaTicketVigenteError` | Errores de WSAA. |
 
-```ts
-const status = await agro.serverStatus();
-// { cpe: { appserver, dbserver, authserver }, ctg: { ... }, lpg: { ... } }
-```
+Los montos se redondean a los decimales del XSD (`fractionDigits`). Las fechas `xsd:date` aceptan `Date` o `AAAAMMDD`/`AAAA-MM-DD`; las `xsd:dateTime` aceptan `Date` (se envía en hora de Argentina, `-03:00`) o un string ISO-8601.
 
-## Clientes de bajo nivel
+En las respuestas, los campos `xs:string` (ej: `codigo` de las paramétricas) son `string`, los IDs largos (`nroCTG`, `coe`) son `string`, los CUIT y montos son `number`.
 
-Para control total sobre la autenticación, se pueden usar los clientes individuales directamente:
+## Emisiones y reintentos
 
-```ts
-import { CpeClient, CtgClient, LpgClient } from '@ramiidv/arca-agro';
-import { WsaaClient } from '@ramiidv/arca-common';
+Las operaciones que crean o modifican algo en ARCA **nunca se reintentan**:
 
-const wsaa = new WsaaClient({ cert, key, production: false });
-const cpeClient = new CpeClient(false, { timeoutMs: 60000 });
+- WSCPE: `autorizarCPEAutomotor`, `autorizarCPEFerroviaria`, `confirmarArriboCPE`, `confirmacionDefinitivaCPE*`, `descargadoDestinoCPE`, `rechazoCPE`, `anularCPE`, `editarCPE*`, `nuevoDestinoDestinatarioCPE*`, `regresoOrigenCPE*`, `desvioCPE*`, `informarContingencia`, `cerrarContingenciaCPE`.
+- WSLPG: `liquidacionAutorizar`, `liquidacionAnular`, `liquidacionAjustarUnificado`, `cgAutorizar`, `cgSolicitarAnulacion`, `cgConfirmarAnulacion`.
 
-const ticket = await wsaa.getAccessTicket('wscpe');
-const auth = { Token: ticket.token, Sign: ticket.sign, Cuit: 20123456789 };
+Las consultas se reintentan ante errores transitorios (`retries`, default 1).
 
-const resultado = await cpeClient.autorizarCPEAutomotor(auth, { ... });
-```
+### Recuperar una emisión incierta
 
-## Eventos
+Si una emisión falla con `error.uncertain === true` (timeout, conexión cortada, HTTP 5xx, SOAP Fault, respuesta incompleta), ARCA pudo haberla procesado. **No reintentes a ciegas**: consultá primero.
+
+- **CPE** (manual WSCPE §1.3): `consultarUltNroOrden(sucursal, tipoCPE)`. Si es `>=` al `nroOrden` que enviaste, la CPE se autorizó: obtenela con `consultarCPEAutomotor({ cartaPorte: { tipoCPE, sucursal, nroOrden } })` (o `consultarCPEFerroviaria`). Si no, reintentá con el mismo `nroOrden`. Para las demás operaciones, consultá la CPE y mirá `cabecera.estado`.
+- **Liquidación**: `liquidacionUltimoNroOrdenConsultar(ptoEmision)` y `liquidacionXNroOrdenConsultar(ptoEmision, nroOrden)`. Para anulaciones y ajustes, `liquidacionXCoeConsultar(coe)` y mirá `autorizacion.estado`.
+- **Certificación**: `cgConsultarUltimoNroOrden(ptoEmision)`.
 
 ```ts
-agro.on('auth:login', (e) => console.log(`Login ${e.service} en ${e.durationMs}ms`));
-agro.on('request:end', (e) => console.log(`${e.method} completado en ${e.durationMs}ms`));
-agro.on('request:retry', (e) => console.warn(`Reintento #${e.attempt}: ${e.error}`));
-agro.on('request:error', (e) => console.error(`Error en ${e.method}: ${e.error}`));
+try {
+  return await agro.cpe.autorizarCPEAutomotor(params);
+} catch (e) {
+  if (!((e instanceof ArcaSoapError || e instanceof ArcaAgroResponseError) && e.uncertain)) throw e;
+  const { tipoCP, sucursal, nroOrden } = params.cabecera;
+  if ((await agro.cpe.consultarUltNroOrden(sucursal, tipoCP)) >= nroOrden) {
+    return agro.cpe.consultarCPEAutomotor({ cartaPorte: { tipoCPE: tipoCP, sucursal, nroOrden } });
+  }
+  return agro.cpe.autorizarCPEAutomotor(params); // no se emitió
+}
 ```
 
-## Manejo de errores
+## Estado de los servicios
 
 ```ts
-import {
-  ArcaAuthError,
-  ArcaSoapError,
-  ArcaServiceError,
-} from '@ramiidv/arca-agro';
+const estado = await agro.serverStatus();
+// { cpe: { ok: true, status: { appserver, dbserver, authserver } }, lpg: { ok: false, error } }
+```
 
-try {
-  await agro.cpe.autorizarCPEAutomotor({ ... });
-} catch (error) {
-  if (error instanceof ArcaServiceError) {
-    // Errores de negocio (datos inválidos, CPE rechazada, etc.)
-    console.error('Errores:', error.errors);
-  } else if (error instanceof ArcaSoapError) {
-    // Error de comunicación SOAP / HTTP
-    console.error('Error SOAP:', error.message, error.statusCode);
-  } else if (error instanceof ArcaAuthError) {
-    // Error de autenticación WSAA
-    console.error('Error auth:', error.message);
-  }
-}
+Usa `Promise.allSettled`: la caída de un servicio no oculta el estado del otro.
+
+## Eventos
+
+```ts
+agro.on('auth:login', (e) => console.log(`Login ${e.service}`));
+agro.on('request:end', (e) => console.log(`${e.method} en ${e.durationMs}ms`));
+agro.on('request:retry', (e) => console.warn(`Reintento #${e.attempt}`));
+agro.on('request:error', (e) => console.error(`Error en ${e.method}`));
 ```
 
+También se puede pasar `onEvent` en la configuración. Los errores de los handlers se ignoran.
+
 ## Configuración
 
+`ArcaAgroConfig` extiende `ArcaBaseConfig` de `@ramiidv/arca-common`.
+
 | Opción | Tipo | Default | Descripción |
 |--------|------|---------|-------------|
-| `cuit` | `number` | **requerido** | CUIT del contribuyente |
-| `cert` | `string` | **requerido** | Certificado X.509 en formato PEM |
-| `key` | `string` | **requerido** | Clave privada en formato PEM |
-| `production` | `boolean` | `false` | Usar entorno de producción |
-| `tokenTTLMinutes` | `number` | `720` | Tiempo de vida del token WSAA (minutos) |
-| `requestTimeoutMs` | `number` | `30000` | Timeout para requests HTTP (ms) |
-| `retries` | `number` | `1` | Reintentos en errores transitorios |
+| `cuit` | `number \| string` | **requerido** | CUIT representada (con o sin guiones) |
+| `cert` / `key` | `string` | **requerido** | Certificado y clave privada PEM |
+| `production` | `boolean` | `false` | Entorno de producción |
+| `timeout` | `number` | `30000` | Timeout HTTP (ms) |
+| `retries` | `number` | `1` | Reintentos de consultas (las emisiones nunca se reintentan) |
 | `retryDelayMs` | `number` | `1000` | Delay base entre reintentos (ms) |
-| `onEvent` | `function` | `undefined` | Callback para eventos del SDK |
+| `tokenTTLMinutes` | `number` | `720` | Vida del ticket WSAA |
+| `ticketStorage` | `TicketStorage` | memoria | Persistencia del ticket WSAA (recomendado en producción) |
+| `clockOffsetMs` / `autoClockSkew` | | `0` / `true` | Desfase de reloj con ARCA |
+| `loginErrorCooldownMs` | `number` | `60000` | Espera tras un login WSAA fallido |
+| `fetch` | `typeof fetch` | global | `fetch` propio (proxy, tests) |
+| `legacyTls` | `'auto' \| 'never' \| 'always'` | `'auto'` | Transporte TLS legacy |
+| `endpoints` | `{ cpe?, lpg?, wsaa? }` | oficiales | Endpoints propios |
+| `onEvent` | `function` | | Callback de eventos |
+
+`clearAuthCache()` (async) invalida los tickets de WSCPE y WSLPG.
 
 ## Endpoints
 
 | Servicio | Homologación | Producción |
 |----------|-------------|------------|
-| WSCPE | `https://fwshomo.afip.gov.ar/wscpe/services/soap` | `https://serviciosjava.afip.gob.ar/wscpe/services/soap` |
-| WSCTG | `https://fwshomo.afip.gov.ar/wsctg/services/CTGService_v4.0` | `https://serviciosjava.afip.gob.ar/wsctg/services/CTGService_v4.0` |
+| WSCPE | `https://cpea-ws-qaext.afip.gob.ar/wscpe/services/soap` | `https://cpea-ws.afip.gob.ar/wscpe/services/soap` |
 | WSLPG | `https://fwshomo.afip.gov.ar/wslpg/LpgService` | `https://serviciosjava.afip.gob.ar/wslpg/LpgService` |
 
+Namespaces: WSCPE `https://serviciosjava.afip.gob.ar/wscpe/`, WSLPG `http://serviciosjava.afip.gob.ar/wslpg/`.
+
 ## Licencia
 
 MIT