@ramiidv/arca-padron 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## 0.4.0 (2026-11-01)
+
+### Breaking changes
+- Requiere `@ramiidv/arca-common` ^0.4.0. `ArcaPadronConfig` extiende `ArcaBaseConfig` (`cuit` acepta
+  `string | number`; se agregan `tokenTTLMinutes`, `loginErrorCooldownMs`, `fetch`, `legacyTls` y
+  `endpoints`, que se pasan al `WsaaClient` y a cada servicio).
+- Las CUIT se validan localmente con `validateCuit` (dígito verificador) y se envían normalizadas: una
+  CUIT inválida (también la representada de la config) lanza `ArcaValidationError` sin llamar a ARCA.
+- Los SOAP Faults de negocio conocidos (CUIT inexistente, clave INACTIVA, id inválido, token no
+  autorizado; textos de los manuales) se lanzan como `ArcaPadronServiceError` con `reason` tipado y el
+  `ArcaSoapError` original en `cause` (antes llegaban como `ArcaSoapError`).
+- Si `personaReturn` no trae `persona` (A4, A10, A13), la constancia no trae `datosGenerales` ni
+  `errorConstancia`, o A100 no trae `parameterCollection`, se lanza `ArcaPadronError` (antes se
+  devolvía una persona inventada `{ idPersona: '', tipoPersona: 'FISICA' }` o `[]`). También si falta el
+  id de un ítem (`idImpuesto`, `idActividad`, `idCategoria`, etc.): ya no se rellenan con `0` / `''`.
+- `status()` devuelve `PromiseSettledResult<ServerStatus>` por servicio (`Promise.allSettled`): un
+  servicio caído ya no hace fallar todo.
+- `ImpuestoId.BIENES_PERSONALES` es `180` (estaba como `31`, incorrecto); se quitó el alias
+  `ImpuestoId.MONOTRIBUTO_SOCIAL` (mismo valor que `MONOTRIBUTO`, rompía el mapeo inverso).
+- `condicionIvaDesdePadron`: el impuesto 30 en estado `NA` / `NO APORTANTE` ya no se interpreta como IVA
+  no alcanzado (`NA` es "NO APORTANTE" en la tabla TipoEstado); un impuesto 20 en baja ya no da
+  monotributista aunque haya categoría.
+- Tipos: `DomicilioA4` ya no tiene `estadoDomicilio` (no existe en el WSDL de A4) y, como
+  `DependenciaA4`/`DependenciaA10`, tiene sus campos opcionales (son `minOccurs="0"`);
+  `ImpuestoA4.estado` y `ParameterAttribute.value` son opcionales.
+- Se eliminaron los módulos internos `soap-client.ts` y `wsaa.ts` (re-exports puros): `WsaaClient`,
+  `ensureArray`, `parseXml` y `buildXml` se siguen exportando desde el índice.
+
+### Features
+- `getConstanciasInscripcion(cuits)` / `a5.getPersonaList`: `getPersonaList_v2`, hasta 250 CUITs; las
+  inexistentes vuelven con `errorConstancia`.
+- `getPersonaA13V2(cuit)` / `a13.getPersonaV2`: consulta de claves INACTIVAS (manual A13 v1.4).
+- `monotributo.componenteDeSociedad` en la constancia (tipo `relacion` del WSDL).
+- `CollectionName`: `AUTONOMO_MONOTRIBUTO`, `REGIMEN`, `TIPO_REGIMEN`, `CARACTERIZACION`,
+  `TIPO_ARCHIVO`, `ACTIVIDAD_RUBRO`, `RUBRO_ACTIVIDAD`, `ACTIVIDAD_OCUPACIONAL` (manual A100 v2.1).
+- `ImpuestoId`: `MONOTRIBUTO_AUTONOMO` (21), `AUTONOMOS` (308).
+- `getIdPersonaListByDocumento` acepta el documento con puntos/espacios y lo valida.
+- Se exportan `ArcaValidationError`, `DocTipo`, `PadronErrorReason`, `PadronStatus`, `PadronServicio`,
+  `ComponenteSociedadA5`, `PadronSoapOptions` y `MAX_PERSONA_LIST`.
+
+### Fixes
+- A4 y A10: los campos `xs:string` con contenido numérico (`codPostal`, `datoAdicional`, `localidad`,
+  `numeroInscripcion`) salían como `number`; ahora son `string`. A4 y A10 usan los helpers de
+  `mapping.ts` (sin bloques duplicados de dependencia, claves inactivas y domicilio).
+- A100: `id`, `description`, `name` y `value` se preservan tal cual (`"10.50"` ya no se convierte en
+  `10.5`, ni `"1E3"` en `1000`). Usa `parseNumbers: false` de arca-common en lugar de envolver `fetch`:
+  el A100 ya no desactiva el fallback TLS legacy (`legacyTls`) y respeta el `fetch` de la config.
+- Todos los servicios parsean las respuestas con `parseNumbers: false` y convierten explícitamente los
+  campos numéricos del WSDL: los `xs:string` con decimales, exponente o ceros a la izquierda
+  (`datoAdicional`, `piso`, `numeroDocumento`, etc.) llegan tal cual (`"1.50"` antes era `"1.5"`).
+- Los elementos `xsi:nil="true"` se tratan como ausentes (antes, por ejemplo, una caracterización nil
+  se mapeaba como `{ idCaracterizacion: 0 }`).
+- `condicionIvaDesdePadron`: reconoce los estados del manual A4 en palabras (`ACTIVO EN TRAMITE`,
+  `EXENTO`, `EXENTO EN TRAMITE`, `BAJA ...`) además de las abreviaturas; categorías 101 a 104
+  (proyectos productivos) como monotributo social; incluye `errorRegimenGeneral` / `errorMonotributo`
+  en el motivo y ya no afirma "No figura inscripto" cuando ARCA informó errores.
+- `ArcaPadronError` y `ArcaPadronServiceError` ahora se lanzan de verdad (la documentación enseñaba a
+  capturarlos pero el SDK nunca los usaba).
+
+### Deprecated
+- `TipoDocumento` (es `DocTipo` numérico de WSFEv1, no el `tipoDocumento` string del padrón): usar `DocTipo`.
+- `checkServiceErrors` desde este paquete (Padrón informa los errores como SOAP Fault).
+- `ImpuestoId.IVA_NO_INSCRIPTO` (33), sin respaldo en los manuales.
+
 ## 0.3.0 (2026-10-30)
 
 ### Breaking changes
@@ -37,6 +101,7 @@ deprecados; A5 sí (reemplazado por la constancia de inscripción).
 ## 0.2.0
 
 - Migración de WSAA/SOAP a `@ramiidv/arca-common`.
+- CI en Node 18/20/22, build standalone, workflow de release, `publishConfig` público y homepage.
 
 ## 0.1.0 (2026-03-31)
 

package/README.md

@@ -7,14 +7,14 @@ que pide la factura electronica (`CondicionIVAReceptorId`).
 
 ## Caracteristicas
 
-- Zero dependencias SOAP: construye los envelopes SOAP manualmente
-- Zero dependencias HTTP: usa `fetch` nativo (Node 18+)
-- Firma CMS/PKCS#7 con node-forge
+- Unica dependencia: `@ramiidv/arca-common` (WSAA, SOAP, validadores); usa `fetch` nativo (Node 18+)
 - ESM y CommonJS (funciona con `import` y con `require`, incluido TypeScript con `"module": "CommonJS"`)
 - TypeScript estricto con tipos completos
 - Cache automatico de tokens WSAA, con persistencia opcional (`ticketStorage`) y ajuste de reloj
 - Cancelacion con `AbortSignal` (global o por llamada)
-- Reintentos con backoff exponencial
+- Reintentos con backoff exponencial ante errores transitorios (nunca ante un SOAP Fault)
+- Errores de negocio tipados: `ArcaPadronServiceError` con `reason` (`inexistente`, `inactiva`, ...)
+- Validacion local de CUIT (digito verificador) antes de llamar a ARCA
 - Sistema de eventos para monitoreo
 
 ## Instalacion
@@ -32,23 +32,23 @@ import { ArcaPadron, FileTicketStorage } from '@ramiidv/arca-padron';
 const padron = new ArcaPadron({
   cert: readFileSync('./cert.pem', 'utf-8'),
   key: readFileSync('./key.pem', 'utf-8'),
-  cuit: '20123456789',
+  cuit: '20123456786',
   production: false, // false = homologacion
   ticketStorage: new FileTicketStorage('./.arca-tickets'), // recomendado
 });
 
 // Constancia de inscripcion (ex A5) + condicion frente al IVA para facturar
 import { condicionIvaDesdePadron } from '@ramiidv/arca-padron';
-const constancia = await padron.getConstanciaInscripcion('30712345674');
+const constancia = await padron.getConstanciaInscripcion('30712345671');
 const { condicionIva, motivo } = condicionIvaDesdePadron(constancia);
 // condicionIva: CondicionIva.RESPONSABLE_INSCRIPTO (1), motivo: "Inscripto en IVA (impuesto 30)."
 
 // Consulta completa (A4)
-const contribuyente = await padron.getPersona('20123456789');
+const contribuyente = await padron.getPersona('20-11111111-2'); // con o sin guiones
 console.log(contribuyente.tipoPersona, contribuyente.nombre);
 
 // Consulta basica (A10)
-const contribuyenteBasico = await padron.getPersonaBasic('20123456789');
+const contribuyenteBasico = await padron.getPersonaBasic('20111111112');
 console.log(contribuyenteBasico.domicilio?.[0]?.direccion);
 
 // Tablas de parametros (A100)
@@ -59,32 +59,30 @@ console.log(provincias.length, 'provincias');
 
 ## Configuracion
 
+`ArcaPadronConfig` extiende `ArcaBaseConfig` de `@ramiidv/arca-common`:
+
 ```typescript
-interface ArcaPadronConfig {
-  /** Certificado X.509 en formato PEM */
-  cert: string;
-  /** Clave privada RSA en formato PEM */
-  key: string;
-  /** CUIT de la entidad representada */
-  cuit: string;
-  /** Usar endpoints de produccion (default: false) */
-  production?: boolean;
-  /** Cantidad de reintentos en errores 5xx/red (default: 1) */
-  retries?: number;
-  /** Delay base en ms para backoff exponencial (default: 1000) */
-  retryDelayMs?: number;
-  /** Callback de eventos para monitoreo */
+interface ArcaPadronConfig extends ArcaBaseConfig {
+  // De ArcaBaseConfig:
+  cert: string;                 // Certificado X.509 en formato PEM
+  key: string;                  // Clave privada en formato PEM
+  cuit: string | number;        // CUIT representada (se valida el digito verificador)
+  production?: boolean;         // default: false (homologacion)
+  timeout?: number;             // ms por request (default: 30000)
+  retries?: number;             // reintentos ante errores transitorios (default: 1)
+  retryDelayMs?: number;        // backoff exponencial (default: 1000)
+  tokenTTLMinutes?: number;     // vigencia pedida a WSAA (default: 720)
   onEvent?: (event: ArcaEvent) => void;
-  /** Persistencia de tickets WSAA entre reinicios (recomendado) */
-  ticketStorage?: TicketStorage;
-  /** Desfase relojARCA - relojLocal en ms (default: 0) */
-  clockOffsetMs?: number;
-  /** Ajustar el desfase si WSAA rechaza el login por reloj (default: true) */
-  autoClockSkew?: boolean;
-  /** Cancela todas las llamadas de la instancia */
-  signal?: AbortSignal;
-  /** WsaaClient compartido (ej: `arca.wsaa` de arca-facturacion con el mismo certificado) */
-  wsaa?: WsaaClient;
+  ticketStorage?: TicketStorage;     // persistencia de tickets WSAA (recomendado)
+  clockOffsetMs?: number;            // relojARCA - relojLocal en ms (default: 0)
+  autoClockSkew?: boolean;           // default: true
+  loginErrorCooldownMs?: number;     // default: 60000
+  fetch?: typeof fetch;              // fetch propio (proxy, mTLS, tests)
+  legacyTls?: 'auto' | 'never' | 'always';
+  // Propias de Padron:
+  signal?: AbortSignal;              // cancela todas las llamadas de la instancia
+  wsaa?: WsaaClient;                 // WsaaClient compartido (ej: arca.wsaa de arca-facturacion)
+  endpoints?: { wsaa?: string; a5?: string; a4?: string; a10?: string; a13?: string; a100?: string };
 }
 ```
 
@@ -97,71 +95,102 @@ Si usas tambien `@ramiidv/arca-facturacion` con el mismo certificado, comparti e
 
 ```typescript
 const arca = new Arca({ cuit, cert, key, ticketStorage });
-const padron = new ArcaPadron({ cuit: String(cuit), cert, key, wsaa: arca.wsaa });
+const padron = new ArcaPadron({ cuit, cert, key, wsaa: arca.wsaa });
 ```
 
-Todos los metodos aceptan un ultimo parametro opcional `{ signal }`.
+Todos los metodos aceptan un ultimo parametro opcional `{ signal }`. Las CUIT se aceptan con o sin
+guiones (`'20-11111111-2'`, `'20111111112'` o `20111111112`): se validan localmente (digito
+verificador) y se envian normalizadas; una CUIT invalida lanza `ArcaValidationError` sin llamar a ARCA.
+
+Todas las operaciones de Padron son consultas (no modifican nada en ARCA): se pueden reintentar sin
+riesgo.
 
 ## API
 
 ### Metodos de alto nivel
 
-#### `getConstanciaInscripcion(cuit: string): Promise<PersonaA5>`
+#### `getConstanciaInscripcion(cuit): Promise<PersonaA5>`
 
 Constancia de inscripcion via `ws_sr_constancia_inscripcion` (metodo `getPersona_v2`). Reemplaza a
 Padron A5 (`ws_sr_padron_a5`), deprecado por ARCA. Incluye datos generales, domicilio fiscal,
 caracterizaciones, regimen general (impuestos, actividades, regimenes), monotributo (categoria,
-impuestos, actividad) y, si ARCA no puede emitir la constancia, `errorConstancia`.
+impuestos, actividad, `componenteDeSociedad`) y, si ARCA no puede emitir la constancia (o una parte),
+`errorConstancia` / `errorRegimenGeneral` / `errorMonotributo`: esos casos se devuelven, no se lanzan.
 
 ```typescript
-const constancia = await padron.getConstanciaInscripcion('30712345674');
+const constancia = await padron.getConstanciaInscripcion('30712345671');
 constancia.domicilioFiscal;        // { direccion, localidad, codPostal, idProvincia, ... }
 constancia.impuestos;              // impuestos de ambos regimenes
 constancia.monotributo?.categoria; // { idCategoria, descripcionCategoria, ... }
 ```
 
+#### `getConstanciasInscripcion(cuits): Promise<PersonaA5[]>`
+
+Hasta 250 CUITs en una llamada (`getPersonaList_v2`). Las CUITs inexistentes no hacen fallar la
+consulta: vuelven como una persona con `errorConstancia.error = ['No existe persona con ese Id']`.
+
+```typescript
+const constancias = await padron.getConstanciasInscripcion(['20224107030', '27015942210']);
+for (const c of constancias) {
+  if (c.errorConstancia) console.warn(c.idPersona, c.errorConstancia.error);
+}
+```
+
 #### `condicionIvaDesdePadron(persona): { condicionIva: CondicionIva | null; motivo: string }`
 
 Funcion pura (no consulta ARCA). Acepta una constancia (`PersonaA5`) o una persona de A4:
 
 | Padron | `condicionIva` |
 | --- | --- |
-| Monotributo activo (impuesto 20 o categoria) | `MONOTRIBUTISTA` (6) |
-| Monotributo social (categorias 61, 99, 100) | `MONOTRIBUTO_SOCIAL` (13) |
-| Trabajador independiente promovido | `MONOTRIBUTO_INDEPENDIENTE_PROMOVIDO` (16) |
-| IVA activo (impuesto 30) | `RESPONSABLE_INSCRIPTO` (1) |
-| IVA exento (impuesto 32) | `EXENTO` (4) |
-| IVA no alcanzado (impuesto 34) | `IVA_NO_ALCANZADO` (15) |
-| Ninguno de los anteriores, o constancia no emitida | `null` (con el motivo) |
+| Monotributo activo (impuesto 20 activo; si no figura el 20, la categoria) | `MONOTRIBUTISTA` (6) |
+| Monotributo social (categorias 61, 99, 100 y proyectos productivos 101-104) | `MONOTRIBUTO_SOCIAL` (13) |
+| Trabajador independiente promovido (por la descripcion de la categoria) | `MONOTRIBUTO_INDEPENDIENTE_PROMOVIDO` (16) |
+| IVA (impuesto 30) `ACTIVO` / `ACTIVO EN TRAMITE` / `AC` | `RESPONSABLE_INSCRIPTO` (1) |
+| IVA (impuesto 30) `EXENTO` / `EXENTO EN TRAMITE` / `EX`, o impuesto 32 | `EXENTO` (4) |
+| Impuesto 34 (IVA no alcanzado) | `IVA_NO_ALCANZADO` (15) |
+| Ninguno de los anteriores, constancia no emitida o con errores | `null` (con el motivo) |
+
+Los impuestos en `BAJA PROVISORIA`, `BAJA DEFINITIVA` o `NO APORTANTE` no cuentan (un impuesto 20
+en baja no se considera monotributo aunque haya categoria). Si el padron no alcanza, devuelve `null`
+en lugar de asumir consumidor final: decidilo segun la operacion. Si ARCA informo
+`errorRegimenGeneral` / `errorMonotributo`, el motivo los incluye.
+
+Fuentes: manual de `ws_sr_constancia_inscripcion` v4.1 (impuestos 20 y 30, estado `AC`, categorias
+de monotributo del anexo 5.3) y manual de `ws_sr_padron_a4` v1.3 §5.3 (TipoEstado). Los impuestos 32
+y 34 no figuran en los manuales: se reconocen por id o por su descripcion. La categoria 98
+(`B ASOCIADO COOPERATIVA`) se trata como monotributo comun.
 
-Si el padron no alcanza, devuelve `null` en lugar de asumir consumidor final: decidilo segun la
-operacion. Fuente: manual de `ws_sr_constancia_inscripcion` v4.1 (impuestos 20 y 30, estado `AC`,
-categorias de monotributo social). Los impuestos 32 y 34 se reconocen tambien por su descripcion.
+#### `getPersonaA13(cuit): Promise<PersonaA13>` y `getPersonaA13V2(cuit)`
 
-#### `getPersonaA13(cuit: string): Promise<PersonaA13>`
+Datos basicos via `ws_sr_padron_a13`. `getPersona` falla con `reason: 'inactiva'` si la clave esta
+inactiva; `getPersonaV2` (manual A13 v1.4) devuelve los datos igual (con `estadoClave: 'INACTIVO'`).
 
-Datos basicos via `ws_sr_padron_a13`. Tambien `getIdPersonaListByDocumento(dni)` devuelve los
-CUIT/CUIL asociados a un documento.
+#### `getIdPersonaListByDocumento(documento): Promise<string[]>`
 
-#### `getPersona(cuit: string): Promise<PersonaA4>`
+CUIT/CUIL asociados a un numero de documento (A13). Acepta puntos y espacios (`'11.709.676'`).
+Devuelve `[]` si ARCA no informa claves.
+
+#### `getPersona(cuit): Promise<PersonaA4>`
 
 Obtiene los datos completos de un contribuyente via ws_sr_padron_a4. Autentica automaticamente con WSAA.
 
 ```typescript
-const contribuyente = await padron.getPersona('20123456789');
+const contribuyente = await padron.getPersona('20111111112');
 ```
 
-#### `getPersonaBasic(cuit: string): Promise<PersonaA10>`
+#### `getPersonaBasic(cuit): Promise<PersonaA10>`
 
 Obtiene los datos basicos de un contribuyente via ws_sr_padron_a10.
 
 ```typescript
-const contribuyenteBasico = await padron.getPersonaBasic('20123456789');
+const contribuyenteBasico = await padron.getPersonaBasic('20111111112');
 ```
 
 #### `getParametros(collection: string): Promise<ParameterRecord[]>`
 
-Obtiene una tabla de parametros via ws_sr_padron_a100.
+Obtiene una tabla de parametros via ws_sr_padron_a100. `id`, `descripcion` y los `value` de los
+atributos se devuelven tal cual los envia ARCA (`"10.50"` sigue siendo `"10.50"`). Lanza
+`ArcaPadronError` si la respuesta no trae `parameterCollection`; una coleccion vacia devuelve `[]`.
 
 ```typescript
 import { CollectionName } from '@ramiidv/arca-padron';
@@ -171,15 +200,19 @@ const tiposDocumento = await padron.getParametros(CollectionName.TIPO_DOCUMENTO)
 const tiposRelacion = await padron.getParametros(CollectionName.TIPO_RELACION);
 ```
 
-Colecciones disponibles (enum `CollectionName`, valores SUPA.\* prefijados): `PROVINCIA`, `TIPO_DOCUMENTO`, `TIPO_DOMICILIO`, `TIPO_CLAVE`, `TIPO_EMPRESA_JURIDICA`, `TIPO_EMPRESA_JURIDICA_SUBGRUPO`, `TIPO_RELACION`, `TIPO_SUBTIPO_RELACION`, `TIPO_COMPONENTE_SOCIEDAD`, `TIPO_RELACION_COMPONENTE_SOC`, `TIPO_EMAIL`, `TIPO_TELEFONO`, `TIPO_RESIDENCIA`, `TIPO_DATO_ADICIONAL_DOMICILIO`, `ORGANISMO_INFORMANTE`, `ORGANISMO_CONTROL`, `PROVINCIA_SOCIEDAD_ORG`, `SEXO`, `CALLE`, `LOCALIDAD`.
+Colecciones disponibles (enum `CollectionName`, manual A100 v2.1 anexo 5.1): `PROVINCIA`, `TIPO_DOCUMENTO`, `TIPO_DOMICILIO`, `TIPO_CLAVE`, `TIPO_EMPRESA_JURIDICA`, `TIPO_EMPRESA_JURIDICA_SUBGRUPO`, `TIPO_RELACION`, `TIPO_SUBTIPO_RELACION`, `TIPO_COMPONENTE_SOCIEDAD`, `TIPO_RELACION_COMPONENTE_SOC`, `TIPO_EMAIL`, `TIPO_TELEFONO`, `TIPO_RESIDENCIA`, `TIPO_DATO_ADICIONAL_DOMICILIO`, `ORGANISMO_INFORMANTE`, `ORGANISMO_CONTROL`, `PROVINCIA_SOCIEDAD_ORG`, `SEXO`, `CALLE`, `LOCALIDAD`, `AUTONOMO_MONOTRIBUTO`, `REGIMEN`, `TIPO_REGIMEN`, `CARACTERIZACION`, `TIPO_ARCHIVO`, `ACTIVIDAD_RUBRO`, `RUBRO_ACTIVIDAD`, `ACTIVIDAD_OCUPACIONAL`.
+La coleccion de categorias de monotributo no se incluye porque su nombre aparece cortado en el manual.
 
-#### `status(): Promise<{ a5, a4, a10, a13, a100 }>`
+#### `status(): Promise<PadronStatus>`
 
-Verifica el estado de los servicios (no requiere autenticacion).
+Verifica el estado de los servicios (`dummy`, no requiere autenticacion). Consulta los cinco en
+paralelo con `Promise.allSettled`: cada uno es un `PromiseSettledResult<ServerStatus>`, asi que un
+servicio caido no oculta el estado de los demas.
 
 ```typescript
-const estadoServicios = await padron.status();
-console.log(estadoServicios.a4.appserver); // "OK"
+const estado = await padron.status();
+if (estado.a4.status === 'fulfilled') console.log(estado.a4.value.appserver); // "OK"
+else console.error('A4 caido:', estado.a4.reason);
 ```
 
 ### Acceso a clientes de bajo nivel
@@ -195,11 +228,12 @@ const ticket = await padron.wsaa.getAccessTicket('ws_sr_padron_a4');
 const credenciales = {
   Token: ticket.token,
   Sign: ticket.sign,
-  CuitRepresentada: '20123456789',
+  CuitRepresentada: '20123456786',
 };
 
 // Llamar directamente al servicio
-const contribuyente = await padron.a4.getPersona(credenciales, '20123456789');
+const contribuyente = await padron.a4.getPersona(credenciales, '20111111112');
+// Tambien: padron.a5.getPersona / getPersonaList, padron.a13.getPersonaV2, padron.a100.getParameterCollectionByName
 ```
 
 Clientes disponibles: `padron.wsaa`, `padron.a5` (constancia), `padron.a4`, `padron.a10`,
@@ -207,6 +241,10 @@ Clientes disponibles: `padron.wsaa`, `padron.a5` (constancia), `padron.a4`, `pad
 
 ## Tipos de respuesta
 
+Los campos `xs:string` de los WSDL (codigos postales, datos adicionales, numeros de inscripcion,
+documentos) y los `xs:long` (CUIT, actividades, telefonos) se devuelven siempre como `string`, aunque
+sean numericos. Los elementos `xsi:nil` se tratan como ausentes.
+
 ### PersonaA4 (datos completos)
 
 ```typescript
@@ -284,50 +322,62 @@ interface ParameterRecord {
 
 interface ParameterAttribute {
   name: string;
-  value: string;
+  value?: string; // tal cual lo envia ARCA (xs:string)
 }
 ```
 
 ## Manejo de errores
 
-El SDK usa una jerarquia de errores de 4 clases:
-
 ```
 Error
   └── ArcaError (base, de @ramiidv/arca-common)
-        ├── ArcaPadronError
+        ├── ArcaPadronError (respuesta de ARCA sin un dato obligatorio, ej: personaReturn sin persona)
         ├── ArcaAuthError (errores de WSAA)
         │     └── ArcaTicketVigenteError (TA vigente que no esta en memoria ni en el storage)
+        ├── ArcaValidationError (CUIT o documento invalido: no se llamo a ARCA)
         ├── ArcaServiceError
-        │     └── ArcaPadronServiceError (errores de negocio)
-        └── ArcaSoapError (errores HTTP/transporte, SOAP Faults)
+        │     └── ArcaPadronServiceError (errores de negocio: reason + errors + cause)
+        └── ArcaSoapError (HTTP/red/timeout y SOAP Faults no reconocidos)
 ```
 
 Todos tienen un `code` estable y `instanceof` funciona aunque haya mas de una copia del paquete
-cargada. ARCA informa "persona inexistente" y similares como SOAP Fault (`ArcaSoapError` con
-`faultString`).
+cargada. ARCA informa los errores de negocio como SOAP Fault; el SDK reconoce los textos de los
+manuales y los convierte en `ArcaPadronServiceError` con un `reason` tipado (el `ArcaSoapError`
+original queda en `cause`). No se reintentan.
+
+| `reason` | Mensaje de ARCA |
+| --- | --- |
+| `inexistente` | "La Clave (CUIT/CUIL) consultada es inexistente", "No existe persona con ese Id" |
+| `inactiva` | "La clave (CUIT/CUIL) consultada se encuentra INACTIVA" (A13: usar `getPersonaA13V2`) |
+| `id_invalido` | "El Id de la persona no es valido" |
+| `no_autorizado` | "No autorizado, par token/sign invalido.", "Falta token y/o sign.", "Debe enviar la CUIT representada", "Este token no le permite actuar en representacion de la CUIT ..." |
+
+Un SOAP Fault con otro texto queda como `ArcaSoapError` (con `faultString`). En la constancia de
+inscripcion, los motivos por los que ARCA no emite la constancia (CUIT limitada, domicilio
+incompleto, etc.) no son excepciones: vienen en `errorConstancia`, `errorRegimenGeneral` y
+`errorMonotributo`.
 
 ```typescript
 import {
   ArcaAuthError,
   ArcaPadronServiceError,
   ArcaSoapError,
+  ArcaValidationError,
 } from '@ramiidv/arca-padron';
 
 try {
-  await padron.getPersona('20123456789');
+  await padron.getPersona('20111111112');
 } catch (error) {
-  if (error instanceof ArcaAuthError) {
-    // Certificado vencido, servicio no autorizado, WSAA caido
-    console.error('Error de autenticacion:', error.message);
+  if (error instanceof ArcaValidationError) {
+    console.error('CUIT invalida:', error.message);
   } else if (error instanceof ArcaPadronServiceError) {
-    // Errores de negocio (CUIT no encontrada, etc.)
-    for (const detalle of error.errors) {
-      console.error(`[${detalle.code}] ${detalle.msg}`);
-    }
+    if (error.reason === 'inexistente') console.error('La CUIT no existe');
+    else if (error.reason === 'inactiva') console.error('La CUIT esta inactiva');
+    else console.error(error.errors[0]?.msg);
+  } else if (error instanceof ArcaAuthError) {
+    console.error('Error de autenticacion:', error.message);
   } else if (error instanceof ArcaSoapError) {
-    // Errores HTTP/red
-    console.error('Error HTTP:', error.statusCode, error.message);
+    console.error('Error HTTP/red:', error.statusCode, error.message);
   }
 }
 ```
@@ -377,10 +427,15 @@ import {
 
 // Verificar si el contribuyente esta inscripto en IVA (mejor: condicionIvaDesdePadron)
 const tieneIva = contribuyente.impuesto?.some(
-  (imp) => imp.idImpuesto === ImpuestoId.IVA_RESPONSABLE_INSCRIPTO && imp.estado === 'ACTIVO'
+  (imp) => imp.idImpuesto === ImpuestoId.IVA_RESPONSABLE_INSCRIPTO && imp.estado?.startsWith('ACTIVO')
 );
 
-// ImpuestoId.MONOTRIBUTO = 20 (antes figuraba como 21, que era incorrecto)
+// ImpuestoId.MONOTRIBUTO = 20, IVA_RESPONSABLE_INSCRIPTO = 30, BIENES_PERSONALES = 180,
+// EMPLEADOR = 301, AUTONOMOS = 308 (manuales de ARCA). IVA_EXENTO (32) e IVA_NO_ALCANZADO (34)
+// no figuran en los manuales del padron.
+//
+// `TipoDocumento` esta deprecado: es `DocTipo` (codigos numericos de WSFEv1), no el
+// `tipoDocumento` string del padron ("DNI", "LC"...).
 ```
 
 ## Requisitos

package/dist/cjs/arca-padron.d.ts

@@ -5,7 +5,7 @@ import { PadronA5Client } from './padron-a5.js';
 import { PadronA10Client } from './padron-a10.js';
 import { PadronA13Client } from './padron-a13.js';
 import { PadronA100Client } from './padron-a100.js';
-import type { ArcaPadronConfig, ParameterRecord, PersonaA4, PersonaA5, PersonaA10, PersonaA13, ServerStatus } from './types.js';
+import type { ArcaPadronConfig, PadronStatus, ParameterRecord, PersonaA4, PersonaA5, PersonaA10, PersonaA13 } from './types.js';
 /**
  * Main orchestrator class for ARCA Padrón web services.
  *
@@ -47,51 +47,64 @@ export declare class ArcaPadron {
     private readonly signal?;
     constructor(config: ArcaPadronConfig);
     /**
-     * Constancia de inscripción (ws_sr_constancia_inscripcion, ex Padrón A5):
-     * datos generales, domicilio fiscal, impuestos del régimen general y
-     * monotributo. Combinar con `condicionIvaDesdePadron` para facturar.
-     * @param cuit - CUIT of the taxpayer to query
+     * Constancia de inscripción (ws_sr_constancia_inscripcion, ex Padrón A5,
+     * `getPersona_v2`): datos generales, domicilio fiscal, impuestos del régimen
+     * general y monotributo. Combinar con `condicionIvaDesdePadron` para facturar.
+     * @param cuit - CUIT a consultar (con o sin guiones)
+     * @throws ArcaValidationError si la CUIT es inválida (dígito verificador)
+     * @throws ArcaPadronServiceError si ARCA informa la CUIT inexistente, inactiva, etc.
      */
-    getConstanciaInscripcion(cuit: string, call?: CallOptions): Promise<PersonaA5>;
+    getConstanciaInscripcion(cuit: string | number, call?: CallOptions): Promise<PersonaA5>;
     /**
-     * Get full taxpayer data (Padrón A4) for a given CUIT.
-     * Authenticates automatically via WSAA.
-     * @param cuit - CUIT of the taxpayer to query
+     * Constancias de inscripción de hasta 250 CUITs en una llamada
+     * (`getPersonaList_v2`). Las CUITs inexistentes vuelven con `errorConstancia`
+     * ("No existe persona con ese Id") en lugar de hacer fallar la consulta.
      */
-    getPersona(cuit: string, call?: CallOptions): Promise<PersonaA4>;
+    getConstanciasInscripcion(cuits: Array<string | number>, call?: CallOptions): Promise<PersonaA5[]>;
     /**
-     * Get basic taxpayer data (Padrón A10) for a given CUIT.
-     * Authenticates automatically via WSAA.
-     * @param cuit - CUIT of the taxpayer to query
+     * Datos completos de un contribuyente (Padrón A4).
+     * @param cuit - CUIT/CUIL a consultar (con o sin guiones)
      */
-    getPersonaBasic(cuit: string, call?: CallOptions): Promise<PersonaA10>;
+    getPersona(cuit: string | number, call?: CallOptions): Promise<PersonaA4>;
     /**
-     * Get basic taxpayer data (Padrón A13) for a given CUIT.
-     * @param cuit - CUIT of the taxpayer to query
+     * Datos básicos de un contribuyente (Padrón A10).
+     * @param cuit - CUIT/CUIL a consultar (con o sin guiones)
      */
-    getPersonaA13(cuit: string, call?: CallOptions): Promise<PersonaA13>;
+    getPersonaBasic(cuit: string | number, call?: CallOptions): Promise<PersonaA10>;
+    /**
+     * Datos básicos de un contribuyente (Padrón A13, `getPersona`). Con la clave
+     * inactiva ARCA responde con error (`reason: 'inactiva'`): ver `getPersonaA13V2`.
+     * @param cuit - CUIT/CUIL a consultar (con o sin guiones)
+     */
+    getPersonaA13(cuit: string | number, call?: CallOptions): Promise<PersonaA13>;
+    /**
+     * Datos básicos de un contribuyente (Padrón A13, `getPersonaV2`): responde
+     * también si la clave está INACTIVA (manual A13 v1.4).
+     */
+    getPersonaA13V2(cuit: string | number, call?: CallOptions): Promise<PersonaA13>;
     /**
      * CUITs/CUILs asociados a un número de documento (Padrón A13).
-     * @param documento - Número de documento (DNI)
+     * @param documento - Número de documento (DNI); se aceptan puntos y espacios
      */
-    getIdPersonaListByDocumento(documento: string, call?: CallOptions): Promise<string[]>;
+    getIdPersonaListByDocumento(documento: string | number, call?: CallOptions): Promise<string[]>;
     /**
-     * Get a parameter table (Padrón A100) by collection name.
-     * Authenticates automatically via WSAA.
-     * @param collection - Name of the collection (e.g. CollectionName.PROVINCIA, CollectionName.TIPO_DOCUMENTO)
+     * Tabla de parámetros (Padrón A100) por nombre de colección.
+     * @param collection - Nombre de la colección (ej: CollectionName.PROVINCIA)
      */
     getParametros(collection: string, call?: CallOptions): Promise<ParameterRecord[]>;
     /**
-     * Health check for the Padrón services.
-     * Does not require authentication.
+     * Estado de los servicios de Padrón (`dummy`, sin autenticación). Consulta
+     * todos en paralelo y devuelve el resultado de cada uno por separado: un
+     * servicio caído no oculta el estado de los demás.
+     *
+     * @example
+     * ```ts
+     * const s = await padron.status();
+     * if (s.a4.status === 'fulfilled') console.log(s.a4.value.appserver);
+     * else console.error(s.a4.reason);
+     * ```
      */
-    status(call?: CallOptions): Promise<{
-        a5: ServerStatus;
-        a4: ServerStatus;
-        a10: ServerStatus;
-        a13: ServerStatus;
-        a100: ServerStatus;
-    }>;
+    status(call?: CallOptions): Promise<PadronStatus>;
     private opts;
     private getAuth;
 }

package/dist/cjs/arca-padron.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"arca-padron.d.ts","sourceRoot":"","sources":["../../src/arca-padron.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAa,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAa,WAAW,EAAmB,MAAM,sBAAsB,CAAC;AAEpF,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,SAAS,EACT,UAAU,EACV,UAAU,EACV,YAAY,EAEb,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,UAAU;IACrB,wFAAwF;IACxF,SAAgB,IAAI,EAAE,UAAU,CAAC;IACjC,gEAAgE;IAChE,SAAgB,EAAE,EAAE,cAAc,CAAC;IACnC,mDAAmD;IACnD,SAAgB,EAAE,EAAE,cAAc,CAAC;IACnC,oDAAoD;IACpD,SAAgB,GAAG,EAAE,eAAe,CAAC;IACrC,oDAAoD;IACpD,SAAgB,GAAG,EAAE,eAAe,CAAC;IACrC,qDAAqD;IACrD,SAAgB,IAAI,EAAE,gBAAgB,CAAC;IAEvC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAc;gBAE1B,MAAM,EAAE,gBAAgB;IA0CpC;;;;;OAKG;IACG,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC;IAMpF;;;;OAIG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC;IAMtE;;;;OAIG;IACG,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAM5E;;;OAGG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAM1E;;;OAGG;IACG,2BAA2B,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAM3F;;;;OAIG;IACG,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAMvF;;;OAGG;IACG,MAAM,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;QACxC,EAAE,EAAE,YAAY,CAAC;QACjB,EAAE,EAAE,YAAY,CAAC;QACjB,GAAG,EAAE,YAAY,CAAC;QAClB,GAAG,EAAE,YAAY,CAAC;QAClB,IAAI,EAAE,YAAY,CAAC;KACpB,CAAC;IAgBF,OAAO,CAAC,IAAI;YAIE,OAAO;CAQtB"}
+{"version":3,"file":"arca-padron.d.ts","sourceRoot":"","sources":["../../src/arca-padron.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA2B,MAAM,sBAAsB,CAAC;AAC3E,OAAO,KAAK,EAAa,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGnE,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EACV,gBAAgB,EAEhB,YAAY,EACZ,eAAe,EACf,SAAS,EACT,SAAS,EACT,UAAU,EACV,UAAU,EAEX,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,UAAU;IACrB,wFAAwF;IACxF,SAAgB,IAAI,EAAE,UAAU,CAAC;IACjC,gEAAgE;IAChE,SAAgB,EAAE,EAAE,cAAc,CAAC;IACnC,mDAAmD;IACnD,SAAgB,EAAE,EAAE,cAAc,CAAC;IACnC,oDAAoD;IACpD,SAAgB,GAAG,EAAE,eAAe,CAAC;IACrC,oDAAoD;IACpD,SAAgB,GAAG,EAAE,eAAe,CAAC;IACrC,qDAAqD;IACrD,SAAgB,IAAI,EAAE,gBAAgB,CAAC;IAEvC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAc;gBAE1B,MAAM,EAAE,gBAAgB;IAiDpC;;;;;;;OAOG;IACG,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC;IAM7F;;;;OAIG;IACG,yBAAyB,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAMxG;;;OAGG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC;IAM/E;;;OAGG;IACG,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAMrF;;;;OAIG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAMnF;;;OAGG;IACG,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAMrF;;;OAGG;IACG,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAMpG;;;OAGG;IACG,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAMvF;;;;;;;;;;;OAWG;IACG,MAAM,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAgBvD,OAAO,CAAC,IAAI;YAIE,OAAO;CAQtB"}