@ramiidv/arca-agro 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,119 @@
+# Changelog
+
+## 0.4.0
+
+### Minor Changes
+
+- 8c02c30: API uniforme entre los SDKs (los nombres anteriores siguen funcionando,
+  marcados `@deprecated`, hasta la próxima major):
+  
+  - arca-facturacion: la clase principal es `ArcaFacturacion` (`Arca` queda como
+    alias). Nuevo `status()` → `{ wsfe, wsfex }` con `ServiceStatus` y el
+    `ServerStatus` de arca-common (`appserver`/`dbserver`/`authserver`);
+    `serverStatus()`/`serverStatusExpo()` y su `ServerStatus` en mayúsculas
+    quedan deprecados.
+  - arca-agro: `status()` (antes `serverStatus()`).
+  - arca-fecred: el cliente de bajo nivel es `client` (antes `fecred`).
+  - arca-common: `ServiceStatus` y `statusOf()` para el estado de varios servicios.
+- bed68e8: Paquetes solo ESM y Node >= 20.19. `arca-common`, `arca-facturacion` y
+  `arca-padron` dejan de publicar un build CommonJS: desde CommonJS se cargan con
+  `require()` (require(esm), Node >= 20.19 / 22.12). Todos los paquetes pasan a
+  requerir Node >= 20.19.0 (Node 18 y 20 sin soporte). El código vive ahora en el
+  monorepo `arca-sdks`.
+- f8bd053: Las clases principales extienden `ArcaSdkBase` de arca-common, así que todos
+  los SDKs tienen la misma base: `wsaa`, `cuit`, `production`, `on()`/`off()`,
+  `clearAuthCache()`, `config.wsaa` (WsaaClient compartido) y `config.signal`
+  (signal global). arca-mtxca acepta `endpoints: { mtxca, wsaa }` (`endpoint` y
+  `wsaaEndpoint` quedan deprecados). Los `dummy`/`status` validan la respuesta con
+  `parseServerStatus`: si falta un campo lanzan `ArcaSoapError`.
+
+### Patch Changes
+
+- 20ecf7d: DSL de schemas, segunda versión:
+  
+  - Corrección: `dec()` redondea sobre el valor decimal escrito (`8.575` →
+    `8.58`; antes daba `8.57` por la representación binaria). Afecta los importes
+    que los SDKs envían redondeados.
+  - `must()` rechaza también el valor vacío; los elementos `xsi:nil` cuentan
+    como ausentes (en una lista, como lista vacía); `must()` en listas exige el
+    elemento; un objeto opcional vacío se omite y uno obligatorio valida sus hijos.
+  - Al decodificar se validan enteros (`int()`) y valores permitidos
+    (`str({ values })`).
+  - Nuevos: `siNo()` (S/N ↔ boolean), `double()`, `xml(nombre, campo)` (nombre
+    distinto en el XML), `custom(encode, decode)`, `roundHalfUp()` y
+    `decodeResponse(..., { emptyLists: 'omit' })`.
+- b86db00: Nuevo subpath `@ramiidv/arca-common/schema`: el DSL para describir los tipos
+  del XSD de un servicio y, con la misma descripción, validar y serializar
+  requests en el orden del XSD (`encodeRequest`) y decodificar respuestas con
+  tipos (`decodeResponse`). Nuevo error `ArcaResponseError` (respuesta con forma
+  inválida, con `uncertain`).
+  
+  arca-agro usa el DSL de common (`ArcaAgroResponseError` extiende
+  `ArcaResponseError`) y parsea las respuestas sin conversión numérica: los
+  `xs:string` con contenido numérico (ej: `"0012"`, `"10.50"`) ya no pierden ceros
+  ni decimales.
+- Updated dependencies [8c02c30]
+- Updated dependencies [f8bd053]
+- Updated dependencies [242fb5f]
+- Updated dependencies [fd438bc]
+- Updated dependencies [bed68e8]
+- Updated dependencies [20ecf7d]
+- Updated dependencies [b86db00]
+  - @ramiidv/arca-common@0.5.0
+
+## 0.3.0 (2026-11-01)
+
+Reescritura de los clientes contra los WSDL/XSD oficiales. La versión anterior no funcionaba contra ARCA en ningún servicio (endpoints, namespaces, elementos y campos incorrectos).
+
+### Breaking
+
+- **Se elimina WSCTG** (cliente `CtgClient`, `agro.ctg`, tipos, constantes `CTG_*`, `validateCTG`, servicio en `serverStatus`): el CTG fue derogado el 1/11/2021 (RG 5017/2021, reemplazado por la Carta de Porte Electrónica) y sus endpoints responden 404.
+- WSCPE: los requests ahora siguen el XSD (`cabecera`, `origen`, `datosCarga`, `destino`, `destinatario`, `transporte`, ...). Se renombran/reemplazan métodos: `confirmadoArriboCPE` → `confirmarArriboCPE`, `editarCPE` → `editarCPEAutomotor`, `consultarCPE` → `consultarCPEAutomotor`, `consultarConstanciaCPEPDF` eliminado (el PDF viene en `pdf` de las respuestas). `consultarUltNroOrden`/`siguienteNroOrden` reciben `(sucursal, tipoCPE)`.
+- WSLPG: `liquidacionAutorizar` recibe `{ liquidacion, deducciones?, retenciones?, percepciones? }` según `LpgLiquidacionBaseType`; `liquidacionConsultar` se reemplaza por `liquidacionXCoeConsultar` y `liquidacionXNroOrdenConsultar`; `liquidacionAnular(coe)`; `liquidacionAjustarUnificado({ ajusteBase, ajusteCredito?, ajusteDebito? })`; `certificacionAutorizar`/`certificacionAnular` → `cgAutorizar`, `cgSolicitarAnulacion`, `cgConfirmarAnulacion`; `consultarParametros(nombre)` → un método por paramétrica (`tipoGranoConsultar`, `puertoConsultar`, ...).
+- Respuestas tipadas según el XSD: `nroCTG` y `coe` son `string`; los `xs:string` (ej: `codigo` de paramétricas) son `string`. Se eliminan `AgroAuth`, `AgroError`, `raw` y las index signatures `[key: string]: unknown`.
+- Los errores de negocio se lanzan como `ArcaAgroServiceError` (extiende `ArcaServiceError`) en lugar de devolverse en `errores`.
+- `ArcaAgroConfig` extiende `ArcaBaseConfig`: `requestTimeoutMs` → `timeout`; `cuit` acepta `number | string` y se valida el dígito verificador.
+- `CpeClient`/`LpgClient` solo se obtienen desde `ArcaAgro` (se exportan como tipos); sus métodos reciben `opts?: { signal }` en lugar de `auth`.
+- `serverStatus()` devuelve `{ cpe, lpg }` con `{ ok: true, status } | { ok: false, error }`; `clearAuthCache()` es async.
+- `validateCPE`/`validateCTG` → `validateAutorizarCPEAutomotor`, `validateAutorizarCPEFerroviaria`, `validateLiquidacion`, `validateAjusteUnificado`.
+- Requiere `@ramiidv/arca-common` ^0.4.0.
+
+### Features
+
+- WSCPE, circuito automotor completo: `autorizarCPEAutomotor` (tipos 74 y 274), `consultarCPEAutomotor`, `editarCPEAutomotor`, `editarCPEConfirmadaAutomotor`, `confirmarArriboCPE`, `confirmacionDefinitivaCPEAutomotor`, `descargadoDestinoCPE`, `rechazoCPE`, `anularCPE`, `nuevoDestinoDestinatarioCPEAutomotor`, `regresoOrigenCPEAutomotor`, `desvioCPEAutomotor`, `informarContingencia`, `cerrarContingenciaCPE`.
+- WSCPE, circuito ferroviario: `autorizarCPEFerroviaria`, `consultarCPEFerroviaria`, `editarCPEFerroviaria`, `editarCPEConfirmadaFerroviaria`, `confirmacionDefinitivaCPEFerroviaria`, `nuevoDestinoDestinatarioCPEFerroviaria`, `regresoOrigenCPEFerroviaria`, `desvioCPEFerroviaria`, `consultaCPEFerroviariaPorNroOperativo`.
+- WSCPE, consultas y paramétricas: `consultarCPEPorDestino`, `consultarCPEPPendientesDeResolucion`, `consultarProvincias`, `consultarLocalidadesPorProvincia`, `consultarTiposGrano`, `consultarPlantas`, `consultarLocalidadesProductor`, `consultarCategoriasSemillas`, `consultarVariedadesSemillas`.
+- WSLPG: `liquidacionUltimoNroOrdenConsultar`, `cgConsultarUltimoNroOrden` y paramétricas (`provinciasConsultar`, `localidadXProvinciaConsultar`, `tipoOperacionXActividadConsultar`, `puertoConsultar`, `tipoActividadConsultar`, `tipoActividadRepresentadoConsultar`, `tipoCertificadoDepositoConsultar`, `tipoRetencionConsultar`, `tipoDeduccionConsultar`, `tipoGranoConsultar`, `codigoGradoReferenciaConsultar`, `codigoGradoEntregadoXTipoGranoConsultar`, `campaniasConsultar`).
+- Validación local completa contra el XSD (obligatorios, campos desconocidos, rangos, largos, CUIT con dígito verificador, números finitos, redondeo según `fractionDigits`, fechas) reportando todos los errores juntos.
+- Constantes `TIPO_CPE` y `ESTADOS_CPE`. Endpoints configurables (`endpoints: { cpe, lpg, wsaa }`).
+- Configuración de WSAA: `ticketStorage`, `clockOffsetMs`, `autoClockSkew`, `loginErrorCooldownMs`, `fetch`, `legacyTls`.
+- Todos los métodos aceptan `{ signal }`.
+
+### Fixes
+
+- WSCPE: endpoints de homologación (`cpea-ws-qaext.afip.gob.ar`) y producción (`cpea-ws.afip.gob.ar`), elementos `<Op>Req`/`<Op>Resp`, SOAPAction y auth `{ token, sign, cuitRepresentada }`.
+- WSLPG: namespace `http://serviciosjava.afip.gob.ar/wslpg/` (era `https`), elementos del WSDL (`liquidacionReq`, `liqConsXCoeReq`, ...) y auth `{ token, sign, cuit }`.
+- Los errores de negocio (`errores.error[]`, `erroresFormato.error[]`) ya no se pierden: siempre se lanzan.
+- Las consultas sin resultados devuelven `[]` (antes devolvían `[respuestaCompleta]`).
+- `consultarUltNroOrden` lanza si ARCA no devuelve `nroOrden` (antes devolvía 0 y `siguienteNroOrden` daba 1, un número ya usado).
+- Las emisiones (autorizar, anular, rechazar, confirmar, editar, contingencias, desvíos, liquidar, ajustar, certificar) nunca se reintentan y conservan `uncertain`.
+- `serverStatus()` usa `Promise.allSettled`; `clearAuthCache()` espera el borrado de los tickets.
+- Validación: `NaN` ya no pasa como número positivo; el CUIT se valida con dígito verificador.
+- Los ejemplos usaban `codTipoCartaPorte: 1` (inválido); ahora usan el tipo 74.
+
+## 0.2.0 (2026-06-03)
+
+### Chore
+- Build standalone para CI y workflow de release en GitHub Actions.
+- `homepage` apunta a arca-sdk.dev.
+
+## 0.1.0 (2026-03-31)
+
+### Features
+- Initial release
+- WSCPE (Carta de Porte Electronica) - Electronic bill of lading for grain transport
+- WSCTG (Codigo de Trazabilidad de Granos) - Grain traceability codes
+- WSLPG (Liquidacion Primaria de Granos) - Primary grain settlement/liquidation
+- Auto-handles WSAA authentication for all 3 services
+- Retry with exponential backoff on transient errors
+- Event system for logging/debugging

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,255 +16,310 @@ 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.
+
+Todos los métodos aceptan un último argumento opcional `{ signal }` (`AbortSignal`) para cancelar la llamada.
+
+## WSCPE: Carta de Porte Electrónica
 
-## WSCPE - Carta de Porte Electrónica
+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
 
 ```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',
+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,
+  },
 });
 
-// Confirmar arribo
-await agro.cpe.confirmadoArriboCPE({
-  nroCTG: resultado.nroCTG!,
-  nroCartaPorte: resultado.nroCartaPorte!,
-  cuitDestino: 30111222333,
-  pesoNeto: 29800,
-  fechaArribo: '2026-04-01',
-});
+cpe.cabecera.nroCTG; // '010100012345' (string)
+cpe.cabecera.estado; // 'AC'
+cpe.pdf; // constancia en base64
+```
+
+> **`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.
+
+### Circuito automotor
 
-// Consultar CPEs
-const cpes = await agro.cpe.consultarCPE({
-  fechaDesde: '2026-03-01',
-  fechaHasta: '2026-03-31',
-  codGrano: 23,
+```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' });
 
-// Rechazar / Anular
-await agro.cpe.rechazoCPE({ nroCTG: 12345, nroCartaPorte: 67890, codMotivo: 1 });
-await agro.cpe.anularCPE({ nroCTG: 12345, nroCartaPorte: 67890, codMotivo: 2 });
+const detalle = await agro.cpe.consultarCPEAutomotor({ nroCTG: '010100012345' }); // o { cartaPorte }
+```
 
-// Obtener constancia PDF (base64)
-const pdfBase64 = await agro.cpe.consultarConstanciaCPEPDF(12345);
+Las operaciones que modifican una CPE devuelven `CPEResultado` (`{ cabecera?, pdf?, metadata? }`).
 
-// Obtener siguiente número de orden
-const nroOrden = await agro.cpe.siguienteNroOrden(1);
+### Circuito ferroviario
 
-// Estado del servicio
-const status = await agro.cpe.dummy();
-```
+`autorizarCPEFerroviaria`, `consultarCPEFerroviaria`, `editarCPEFerroviaria`, `editarCPEConfirmadaFerroviaria`, `confirmacionDefinitivaCPEFerroviaria`, `nuevoDestinoDestinatarioCPEFerroviaria`, `regresoOrigenCPEFerroviaria`, `desvioCPEFerroviaria` y `consultaCPEFerroviariaPorNroOperativo`.
 
-## WSCTG - Código de Trazabilidad de Granos
+### Consultas y paramétricas
 
 ```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,
+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();
+```
 
-// Confirmar arribo
-await agro.ctg.confirmarArribo({
-  nroCTG: ctg.nroCTG!,
-  nroCartaPorte: 67890,
-  cuitDestino: 30111222333,
-  pesoNeto: 29800,
-  fechaArribo: '2026-04-01',
-});
+Las listas sin resultados devuelven `[]`; si ARCA devuelve errores, se lanza `ArcaAgroServiceError` (nunca una lista vacía).
 
-// Consultar CTGs
-const ctgs = await agro.ctg.consultarCTG({
-  fechaDesde: '2026-03-01',
-  fechaHasta: '2026-03-31',
-});
+### No soportado en WSCPE
 
-// Exportar a Excel (base64)
-const excelBase64 = await agro.ctg.consultarCTGExcel({
-  fechaDesde: '2026-03-01',
-  fechaHasta: '2026-03-31',
-});
+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.
 
-// Rechazar / Anular
-await agro.ctg.rechazarCTG({ nroCTG: 123, nroCartaPorte: 456, codMotivo: 1 });
-await agro.ctg.anularCTG({ nroCTG: 123, nroCartaPorte: 456, codMotivo: 2 });
+## WSLPG: Liquidación Primaria de Granos
 
-// CTGs activos
-const activos = await agro.ctg.obtenerCTGActivos();
+`liquidacion` sigue `LpgLiquidacionBaseType` del XSD; `deducciones`, `retenciones` y `percepciones` van como hermanos (arrays).
 
-// Constancia PDF (base64)
-const pdf = await agro.ctg.consultarConstanciaCTGPDF(12345);
+```ts
+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 }],
+});
 
-// Estado del servicio
-const status = await agro.ctg.dummy();
+autorizacion.coe; // '330100012345' (string)
+autorizacion.totalNetoAPagar; // number
 ```
 
-## WSLPG - Liquidación Primaria de Granos
+Los códigos de actividad, operación, puerto, grano, deducción y retención salen de las paramétricas.
 
 ```ts
-// Autorizar una liquidación
-const liq = await agro.lpg.liquidacionAutorizar({
-  cuitComprador: 30111222333,
-  cuitVendedor: 20123456789,
-  codGrano: 23,
-  pesoNeto: 30000,
-  precioRefTn: 350000,
+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({
+  ajusteBase: { ptoEmision, nroOrden, coeAjustado: coe, codLocalidad: 3, codProv: 1 },
+  ajusteDebito: { diferenciaPesoNeto: 0, diferenciaPrecioOperacion: 1000, diferenciaPrecioFleteTn: 0 },
 });
 
-// Consultar liquidaciones
-const liquidaciones = await agro.lpg.liquidacionConsultar({
-  fechaDesde: '2026-03-01',
-  fechaHasta: '2026-03-31',
-});
+// 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 liquidación
-await agro.lpg.liquidacionAnular(1, 100);
+### No soportado en WSLPG
 
-// Ajuste unificado
-await agro.lpg.liquidacionAjustarUnificado({
-  nroOrdenOriginal: 100,
-  ptoEmisionOriginal: 1,
-  tipoAjuste: 'credito',
-  liquidacion: { pesoNeto: 29500 },
-});
+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`).
 
-// Autorizar certificación
-const cert = await agro.lpg.certificacionAutorizar({
-  tipoCertificacion: 1,
-  cuitDepositante: 20123456789,
-  codGrano: 23,
-  pesoNeto: 30000,
-});
+## Errores
 
-// Anular certificación
-await agro.lpg.certificacionAnular(1, cert.nroCertificacion!);
+| 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.                                                                                                                                                                                                                                          |
 
-// Consultar parámetros (tipos de grano, grados, puertos, etc.)
-const granos = await agro.lpg.consultarParametros('tipoGranoConsultar');
+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.
 
-// Estado del servicio
-const status = await agro.lpg.dummy();
-```
+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`.
 
-## Verificar todos los servicios
+## Emisiones y reintentos
 
-```ts
-const status = await agro.serverStatus();
-// { cpe: { appserver, dbserver, authserver }, ctg: { ... }, lpg: { ... } }
-```
+Las operaciones que crean o modifican algo en ARCA **nunca se reintentan**:
 
-## Clientes de bajo nivel
+- WSCPE: `autorizarCPEAutomotor`, `autorizarCPEFerroviaria`, `confirmarArriboCPE`, `confirmacionDefinitivaCPE*`, `descargadoDestinoCPE`, `rechazoCPE`, `anularCPE`, `editarCPE*`, `nuevoDestinoDestinatarioCPE*`, `regresoOrigenCPE*`, `desvioCPE*`, `informarContingencia`, `cerrarContingenciaCPE`.
+- WSLPG: `liquidacionAutorizar`, `liquidacionAnular`, `liquidacionAjustarUnificado`, `cgAutorizar`, `cgSolicitarAnulacion`, `cgConfirmarAnulacion`.
 
-Para control total sobre la autenticación, se pueden usar los clientes individuales directamente:
+Las consultas se reintentan ante errores transitorios (`retries`, default 1).
 
-```ts
-import { CpeClient, CtgClient, LpgClient } from '@ramiidv/arca-agro';
-import { WsaaClient } from '@ramiidv/arca-common';
+### Recuperar una emisión incierta
 
-const wsaa = new WsaaClient({ cert, key, production: false });
-const cpeClient = new CpeClient(false, { timeoutMs: 60000 });
+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.
 
-const ticket = await wsaa.getAccessTicket('wscpe');
-const auth = { Token: ticket.token, Sign: ticket.sign, Cuit: 20123456789 };
+- **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)`.
 
-const resultado = await cpeClient.autorizarCPEAutomotor(auth, { ... });
+```ts
+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ó
+}
 ```
 
-## Eventos
+## Estado de los servicios
 
 ```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}`));
+const estado = await agro.status();
+// { cpe: { ok: true, status: { appserver, dbserver, authserver } }, lpg: { ok: false, error } }
 ```
 
-## Manejo de errores
+Usa `Promise.allSettled`: la caída de un servicio no oculta el estado del otro.
 
-```ts
-import {
-  ArcaAuthError,
-  ArcaSoapError,
-  ArcaServiceError,
-} from '@ramiidv/arca-agro';
+## Eventos
 
-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);
-  }
-}
+```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
 
-| 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 |
-| `retryDelayMs` | `number` | `1000` | Delay base entre reintentos (ms) |
-| `onEvent` | `function` | `undefined` | Callback para eventos del SDK |
+`ArcaAgroConfig` extiende `ArcaBaseConfig` de `@ramiidv/arca-common`.
+
+| Opción                            | Tipo                            | Default       | Descripción                                                 |
+| --------------------------------- | ------------------------------- | ------------- | ----------------------------------------------------------- |
+| `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)                            |
+| `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` |
-| WSLPG | `https://fwshomo.afip.gov.ar/wslpg/LpgService` | `https://serviciosjava.afip.gob.ar/wslpg/LpgService` |
+| Servicio | Homologación                                            | Producción                                           |
+| -------- | ------------------------------------------------------- | ---------------------------------------------------- |
+| 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