@ramiidv/arca-empleados 0.2.0 → 0.3.0

package/README.md

@@ -1,379 +1,171 @@
-# @ramiidv/arca-empleados-sdk
+# @ramiidv/arca-empleados
 
-SDK de TypeScript para la gestion de empleados con ARCA (ex AFIP). Genera archivos F935 para el sistema "Mi Simplificacion - Ingreso Masivo de Datos v2.0".
+SDK de TypeScript que genera el archivo TXT de **"Ingreso masivo de datos – Relaciones laborales"** del
+servicio **Simplificación Registral** de ARCA (ex AFIP): altas, bajas y modificaciones de relaciones
+laborales en registros de ancho fijo de 130 posiciones.
 
-## Importante
+- No hace llamadas a servicios web: ARCA no expone un web service para esto. El archivo se sube a mano
+  en Simplificación Registral → Relaciones laborales → Carga Masiva → Nuevo → Cargar Archivo → Enviar.
+- Fuente del formato: [Manual de Ayuda de Simplificación Registral (ARCA, feb. 2025), pág. 24](https://www.arca.gob.ar/simplificacionregistral/ayuda/documentos/SR_Manual-de-Ayuda_20250218_definitivo.pdf).
 
-Este SDK **no realiza llamadas a servicios web ni APIs**. ARCA no expone una API publica para la gestion de empleados. En cambio, los empleadores utilizan la interfaz web de "Mi Simplificacion" o la aplicacion de escritorio "Ingreso Masivo de Datos" que procesa archivos de datos estructurados.
+> **¿Y el F.935?** Las versiones 0.1/0.2 de este paquete hablaban de "archivos F935" con registros
+> `00`–`05` separados por `|`. Ese formato no existe: el F.935 era el archivo encriptado que generaba
+> el viejo aplicativo "Mi Simplificación – Ingreso Masivo de Datos v2.0", que ya no se usa. El formato
+> vigente es el TXT de ancho fijo que describe el manual, y es el que genera la versión 0.3.0.
 
-Este SDK genera esos archivos de datos (formato F935) con tipado fuerte y validacion completa.
-
-## Instalacion
+## Instalación
 
 ```bash
-npm install @ramiidv/arca-empleados-sdk
-```
-
-## Inicio rapido
-
-```ts
-import { writeFileSync } from 'node:fs';
-import {
-  ArcaEmpleados,
-  ModalidadContratacion,
-  Provincia,
-} from '@ramiidv/arca-empleados-sdk';
-
-const empleados = new ArcaEmpleados({
-  cuitEmpleador: '30-71234567-1',
-  razonSocial: 'Mi Empresa S.A.',
-});
-
-empleados.alta({
-  cuil: '20-12345678-6',
-  fechaInicio: new Date(2024, 2, 1),
-  modalidadContratacion: ModalidadContratacion.TIEMPO_COMPLETO_INDETERMINADO,
-  obraSocial: '100100',
-  actividadEconomica: '620100',
-  domicilioExplotacion: {
-    calle: 'Av. Corrientes',
-    numero: '1234',
-    localidad: 'CABA',
-    codigoPostal: '1043',
-    provincia: Provincia.CAPITAL_FEDERAL,
-  },
-});
-
-const resultado = empleados.generar();
-writeFileSync('F935.txt', resultado.contenido, 'utf-8');
-console.log(resultado.resumen);
-```
-
-## Tipos de registro
-
-El archivo F935 comunica 5 tipos de registro:
-
-### 1. Relaciones Laborales (Alta / Baja / Modificacion)
-
-**Alta** - Registro de un nuevo empleado. Segun RG 5508/2024, requiere 7 campos obligatorios:
-
-```ts
-empleados.alta({
-  cuil: '20-12345678-6',
-  fechaInicio: new Date(2024, 2, 1),
-  modalidadContratacion: ModalidadContratacion.TIEMPO_COMPLETO_INDETERMINADO,
-  obraSocial: '100100',
-  actividadEconomica: '620100',
-  trabajadorAgropecuario: false, // default: false
-  domicilioExplotacion: { /* ... */ },
-  fechaFin: undefined, // solo para plazo fijo, eventual, aprendizaje, pasantia
-});
-```
-
-**Baja** - Desvinculacion de un empleado (debe informarse dentro de 5 dias habiles):
-
-```ts
-empleados.baja({
-  cuil: '20-12345678-6',
-  fechaBaja: new Date(2024, 5, 15),
-  motivoBaja: MotivoBaja.RENUNCIA,
-});
-```
-
-**Modificacion** - Cambios en una relacion laboral existente:
-
-```ts
-empleados.modificacion({
-  cuil: '20-12345678-6',
-  fechaInicio: new Date(2024, 2, 1),
-  obraSocial: '100200', // nuevo valor
-});
+npm install @ramiidv/arca-empleados
 ```
 
-### 2. Datos Complementarios del Trabajador
-
-Datos adicionales que deben completarse antes de la primera liquidacion:
-
-```ts
-empleados.datosComplementarios({
-  cuil: '20-12345678-6',
-  fechaInicio: new Date(2024, 2, 1),
-  situacionRevista: SituacionRevista.ACTIVO,
-  nivelEducacion: NivelEducacion.UNIVERSITARIO_COMPLETO,
-  modalidadLiquidacion: ModalidadLiquidacion.MENSUAL,
-  remuneracion: 350000,
-  // ... mas campos opcionales
-});
-```
+Requiere Node.js 18 o superior. ESM.
 
-### 3. CBU (Datos Bancarios)
+## Uso
 
 ```ts
-empleados.cbu({
-  cuil: '20-12345678-6',
-  fechaInicio: new Date(2024, 2, 1),
-  cbu: '0110599100000054489273',
-  tipoCuenta: TipoCuenta.CAJA_AHORRO,
-});
-```
+import { writeFileSync } from 'node:fs';
+import { ArcaEmpleados } from '@ramiidv/arca-empleados';
 
-### 4. Relaciones Familiares
+const sr = new ArcaEmpleados();
 
-```ts
-empleados.relacionFamiliar({
+sr.alta({
   cuil: '20-12345678-6',
-  fechaInicio: new Date(2024, 2, 1),
-  tipoRelacion: TipoRelacionFamiliar.HIJO,
-  nombreFamiliar: 'Juan',
-  apellidoFamiliar: 'Perez',
-  fechaNacimiento: new Date(2015, 5, 10),
-});
-```
-
-### 5. Domicilios de Explotacion
+  fechaInicio: '2026-11-02',
+  modalidadContrato: 8,
+  obraSocial: '126205',
+  sucursal: 1,
+  retribucion: 850000.5,
+  cct: '9999/99',
+})
+  .baja({ cuil: '27-11111111-7', fechaInicio: '2024-03-01', fechaFin: '2026-10-31' })
+  .modificacion({ cuil: '20-34567890-6', retribucion: 1200000 });
+
+const { buffer, contenido, lineas, resumen } = sr.generar();
+writeFileSync('relaciones-laborales.txt', buffer); // ISO-8859-1 + CRLF
+```
+
+Los códigos (modalidad de contrato, obra social, situación de revista, sucursal, actividad, puesto,
+convenio, categoría, tipo de servicio, modalidad de liquidación) se obtienen en el propio servicio con
+**"Ver tablas informativas de códigos"**. ARCA no publica esas tablas en un documento público, así que el
+SDK no las trae: valida solo que cada código sea numérico/alfanumérico y entre en su campo.
+
+### API
+
+| Método | Movimiento | Descripción |
+| --- | --- | --- |
+| `alta(datos)` | `AT` | Alta de relación laboral |
+| `baja(datos)` | `BT` | Baja (la fecha de baja va en `fechaFin`) |
+| `modificacion(datos)` | `MR` | Modificación |
+| `novedad({ movimiento, ...datos })` | `AT`/`BT`/`MR`/`NA`/`NB` | Cualquier código; única vía para `NA` y `NB` |
+| `altasMasivas([...])`, `bajasMasivas([...])`, `modificacionesMasivas([...])`, `novedadesMasivas([...])` | | **Atómicas**: validan todo y, si algo falla, no agregan nada |
+| `generar()` | | `{ contenido, lineas, encoding, buffer, resumen }` |
+| `registros` | | Copia de los registros agregados (modificarla no afecta al builder) |
+| `cantidad`, `resumen()`, `limpiar()` | | |
+
+Cada registro se valida y se serializa **al agregarlo**: si falla, se lanza el error y no se agrega.
+
+Funciones sueltas (uso avanzado): `serializarRegistro`, `serializarArchivo`, `codificarArchivo`,
+`formatFechaSR` (fecha → `AAAA/MM/DD`; distinto del `formatDate` de common, que da `AAAAMMDD`),
+`validateRegistro`, `validateCuilTrabajador`, `DISENO_REGISTRO`, `CAMPOS_OBLIGATORIOS`.
+
+### Configuración
 
 ```ts
-empleados.domicilioExplotacion({
-  cuil: '20-12345678-6',
-  calle: 'Av. Corrientes',
-  numero: '1234',
-  localidad: 'CABA',
-  codigoPostal: '1043',
-  provincia: Provincia.CAPITAL_FEDERAL,
+new ArcaEmpleados({
+  strict: true, // default
+  serializacion: {
+    eol: '\r\n',              // o '\n'
+    eolFinal: true,           // fin de línea después del último registro
+    encoding: 'latin1',       // o 'ascii'
+    noRepresentables: 'error', // o 'transliterar' (quita diacríticos: Ñ→N, Ú→U)
+    numericoVacio: 'ceros',   // o 'espacios'
+  },
 });
 ```
 
-## API
-
-### `ArcaEmpleados`
-
-Constructor:
-
-```ts
-new ArcaEmpleados(config: ArcaEmpleadosConfig)
-```
-
-| Opcion | Tipo | Default | Descripcion |
-|--------|------|---------|-------------|
-| `cuitEmpleador` | `string` | (requerido) | CUIT del empleador |
-| `razonSocial` | `string` | - | Razon social del empleador |
-| `strict` | `boolean` | `true` | Valida campos al agregar registros |
-
-Metodos:
-
-| Metodo | Retorno | Descripcion |
-|--------|---------|-------------|
-| `alta(data)` | `this` | Agrega un alta |
-| `baja(data)` | `this` | Agrega una baja |
-| `modificacion(data)` | `this` | Agrega una modificacion |
-| `datosComplementarios(data)` | `this` | Agrega datos complementarios |
-| `cbu(data)` | `this` | Agrega datos de CBU |
-| `relacionFamiliar(data)` | `this` | Agrega relacion familiar |
-| `domicilioExplotacion(data)` | `this` | Agrega domicilio de explotacion |
-| `altasMasivas(data[])` | `this` | Agrega multiples altas |
-| `bajasMasivas(data[])` | `this` | Agrega multiples bajas |
-| `generar()` | `F935Output` | Genera el archivo |
-| `resumen()` | `F935Resumen` | Resumen sin generar |
-| `limpiar()` | `this` | Limpia registros |
-| `registros` | `F935Registro[]` | Registros almacenados (lectura) |
-
-### `F935Output`
-
-```ts
-interface F935Output {
-  contenido: string;      // Contenido del archivo
-  archivo: F935Archivo;    // Metadata
-  resumen: F935Resumen;    // Resumen de registros
-}
-```
-
-### `F935Resumen`
-
-```ts
-interface F935Resumen {
-  totalRegistros: number;
-  altas: number;
-  bajas: number;
-  modificaciones: number;
-  datosComplementarios: number;
-  cbus: number;
-  familiares: number;
-  domicilios: number;
-}
-```
-
-## Enums y constantes
-
-### Modalidad de Contratacion (`ModalidadContratacion`)
-
-Codigos oficiales SICOSS (tabla T03). Se muestran los mas utilizados:
-
-| Codigo | Enum | Descripcion |
-|--------|------|-------------|
-| `0` | `PROMOVIDA_REDUCCION_0` | Contrato Modalidad Promovida. Reduccion 0% |
-| `1` | `TIEMPO_PARCIAL_INDETERMINADO` | A tiempo parcial: Indeterminado/permanente |
-| `3` | `APRENDIZAJE` | De aprendizaje Ley 25.013 |
-| `8` | `TIEMPO_COMPLETO_INDETERMINADO` | A Tiempo completo indeterminado / Trabajo permanente |
-| `11` | `TEMPORADA` | Trabajo de temporada |
-| `12` | `EVENTUAL` | Trabajo eventual |
-| `21` | `TIEMPO_PARCIAL_PLAZO_FIJO` | A tiempo parcial determinado (plazo fijo) |
-| `22` | `TIEMPO_COMPLETO_PLAZO_FIJO` | A Tiempo completo determinado (plazo fijo) |
-| `24` | `CONSTRUCCION` | Personal de la Construccion Ley 22.250 |
-| `27` | `PASANTIA_CON_OS` | Pasantias Ley 26.427 -con obra social- |
-| `32` | `PERIODO_PRUEBA` | Periodo de Prueba Art. 6 Ley 25.877 |
-| `110` | `AGRARIO_PERMANENTE` | Trabajo permanente Ley 26.727 (agrario) |
-| `111` | `AGRARIO_TEMPORARIO` | Trabajo temporario Ley 26.727 (agrario) |
-| `112` | `AGRARIO_PERMANENTE_DISCONTINUO` | Trabajo permanente discontinuo Ley 26.727 |
-
-> Hay 35 codigos en total. Consultar el enum `ModalidadContratacion` para la lista completa.
-
-### Motivo de Baja (`MotivoBaja`)
-
-Codigos oficiales de Simplificacion Registral. Se muestran los mas utilizados:
-
-| Codigo | Enum | Descripcion |
-|--------|------|-------------|
-| `0` | `FALLECIMIENTO` | Baja por fallecimiento |
-| `7` | `DESPIDO` | Baja por despido |
-| `21` | `RENUNCIA` | Renuncia del trabajador (Art.240 LCT) |
-| `22` | `MUTUO_ACUERDO` | Voluntad concurrente de las partes (Art.241 LCT) |
-| `26` | `DESPIDO_SIN_CAUSA` | Despido sin causa (Art.245 LCT) |
-| `30` | `VENCIMIENTO_PLAZO` | Vencimiento de plazo (Art.250 LCT) |
-| `33` | `JUBILACION` | Jubilacion (Art.252 LCT) |
-| `34` | `INCAPACIDAD` | Incapacidad del trabajador (Art.254 LCT) |
-| `38` | `FIN_APRENDIZAJE_PASANTIA` | Fin contrato de aprendizaje y pasantias |
-| `99` | `VENCIMIENTO_PLAZO_FIJO` | Vencimiento contrato a plazo fijo o determinado |
-
-> Hay 34 codigos en total. Consultar el enum `MotivoBaja` para la lista completa.
-
-### Situacion de Revista (`SituacionRevista`)
-
-Codigos oficiales de Simplificacion Registral. Se muestran los mas utilizados:
-
-| Codigo | Enum | Descripcion |
-|--------|------|-------------|
-| `1` | `ACTIVO` | Activo |
-| `5` | `LICENCIA_MATERNIDAD` | Licencia por maternidad |
-| `6` | `SUSPENSION_OTRAS_CAUSALES` | Suspensiones otras causales |
-| `9` | `SUSPENSION_223_BIS` | Suspendido Art. 223 Bis |
-| `13` | `LICENCIA_SIN_GOCE` | Licencia sin goce de haberes |
-| `14` | `RESERVA_PUESTO` | Reserva de puesto |
-| `32` | `LICENCIA_PATERNIDAD` | Licencia por paternidad |
-| `44` | `CONSERVACION_EMPLEO` | Conservacion del empleo |
-
-> Hay 23 codigos en total. Consultar el enum `SituacionRevista` para la lista completa.
-
-### Provincias (`Provincia`)
-
-Codigos 0-23: CABA (0), Buenos Aires (1), Catamarca (2), Cordoba (3), Corrientes (4), Entre Rios (5), Jujuy (6), Mendoza (7), La Rioja (8), Salta (9), San Juan (10), San Luis (11), Santa Fe (12), Santiago del Estero (13), Tucuman (14), Chaco (15), Chubut (16), Formosa (17), Misiones (18), Neuquen (19), La Pampa (20), Rio Negro (21), Santa Cruz (22), Tierra del Fuego (23).
-
-### Otros enums
-
-- `NivelEducacion` (0-10): Sin instruccion hasta Posgrado completo
-- `EstadoCivil` (1-6): Soltero, Casado, Divorciado, Viudo, Separado, Union convivencial
-- `TipoRelacionFamiliar` (1-7): Conyuge, Hijo, Hijo discapacitado, Hijastro, Menor en guarda, Prenatal, Conviviente
-- `TipoServicio` (1-2): Con/sin aporte PAMI
-- `ModalidadLiquidacion` (1-8): Mensual, Quincenal, Semanal, Diaria, Por hora, Por pieza, A comision, Jornal
-- `TipoCuenta` (1-2): Caja de ahorro, Cuenta corriente
-- `Escolaridad` (0-5): No escolar hasta Universitaria
-
-### Mapas de descripciones
-
-Cada enum tiene un mapa de descripciones exportado:
-
-```ts
-import { MOTIVO_BAJA_DESCRIPCION, MotivoBaja } from '@ramiidv/arca-empleados-sdk';
-
-console.log(MOTIVO_BAJA_DESCRIPCION[MotivoBaja.RENUNCIA]); // "Renuncia del trabajador (Art.240 LCT)"
-```
-
-Mapas disponibles: `MODALIDAD_CONTRATACION_DESCRIPCION`, `MOTIVO_BAJA_DESCRIPCION`, `SITUACION_REVISTA_DESCRIPCION`, `NIVEL_EDUCACION_DESCRIPCION`, `ESTADO_CIVIL_DESCRIPCION`, `TIPO_RELACION_FAMILIAR_DESCRIPCION`, `PROVINCIA_DESCRIPCION`, `MODALIDAD_LIQUIDACION_DESCRIPCION`, `TIPO_CUENTA_DESCRIPCION`, `ESCOLARIDAD_DESCRIPCION`, `TIPO_SERVICIO_DESCRIPCION`.
-
-## Validacion
-
-El SDK valida automaticamente los datos cuando `strict: true` (default):
-
-### CUIL
-
-- Formato: 11 digitos (acepta `XX-XXXXXXXX-X` o `XXXXXXXXXXX`)
-- Prefijos validos: 20, 23, 24, 27, 30, 33, 34
-- Digito verificador: algoritmo de modulo 11 con pesos [5,4,3,2,7,6,5,4,3,2]
-
-### CBU
-
-- Formato: 22 digitos
-- Bloque 1 (8 digitos): banco + sucursal + digito verificador
-- Bloque 2 (14 digitos): cuenta + digito verificador
-- Ambos digitos verificadores se validan con algoritmo de pesos alternados
-
-### Fechas
-
-- Deben ser objetos `Date` validos
-- `fechaFin` debe ser posterior a `fechaInicio`
-- `fechaFin` es obligatoria para contratos a plazo fijo, eventuales, aprendizaje y pasantia
-
-### Domicilios
-
-- Calle, numero, localidad y codigo postal son requeridos
-- Provincia debe ser un valor entre 0 y 23
-
-## Manejo de errores
-
-```ts
-import {
-  ArcaEmpleadosError,     // Base (catch-all)
-  ArcaValidationError,     // Datos invalidos
-  ArcaSerializationError,  // Fallo al serializar
-} from '@ramiidv/arca-empleados-sdk';
-
-try {
-  empleados.alta({ /* ... */ });
-} catch (error) {
-  if (error instanceof ArcaValidationError) {
-    console.error('Campo:', error.field);
-    for (const detalle of error.errors) {
-      console.error(`  ${detalle.field}: ${detalle.message}`);
-    }
-  }
-}
-```
-
-## Utilidades de CUIL/CBU
-
-```ts
-import {
-  validateCuil,   // Valida y retorna CUIL normalizado (11 digitos)
-  validateCBU,     // Valida y retorna CBU (22 digitos)
-  normalizeCuil,   // Quita guiones: "20-12345678-6" -> "20123456786"
-  formatCuil,      // Agrega guiones: "20123456789" -> "20-12345678-6"
-} from '@ramiidv/arca-empleados-sdk';
-```
-
-## Formato del archivo
-
-El archivo generado usa formato delimitado por pipes (`|`). Cada linea representa un registro:
-
-```text
-00|CUIT_EMPLEADOR|RAZON_SOCIAL|FECHA_GENERACION|CANTIDAD_REGISTROS|
-01|CUIT_EMPLEADOR|TIPO_OP|CUIL|...campos...|
-02|CUIT_EMPLEADOR|CUIL|...campos...|
-03|CUIT_EMPLEADOR|CUIL|...campos...|
-04|CUIT_EMPLEADOR|CUIL|...campos...|
-05|CUIT_EMPLEADOR|CUIL|...campos...|
-```
-
-- `00`: Header
-- `01`: Relacion laboral (alta=0, baja=1, modificacion=2)
-- `02`: Datos complementarios
-- `03`: CBU
-- `04`: Relacion familiar
-- `05`: Domicilio de explotacion
-
-Las fechas se formatean como DDMMYYYY. Los booleanos como 'S'/'N'.
-
-## Nota sobre codigos SICOSS
-
-Los codigos de modalidad de contratacion, situacion de revista, motivos de baja y otros estan basados en las tablas SICOSS oficiales. Es recomendable verificar los valores contra las tablas vigentes publicadas por ARCA, ya que pueden actualizarse periodicamente.
+- `strict: true`: formato + reglas de negocio (CUIL con prefijo de persona física 20/23/24/27 y dígito
+  verificador, campos obligatorios por movimiento, rectificación `00`–`05`, marca `0`–`9`,
+  `fechaFin ≥ fechaInicio`). Todos los errores se informan juntos en `ArcaValidationError.details`.
+- `strict: false`: solo formato (que el registro entre en las 130 posiciones). Datos que no son un
+  objeto o un movimiento inválido dan `ArcaValidationError`; un valor que no entra en su campo da
+  `ArcaSerializationError` con `field`, `desde`, `hasta` y `value`.
+
+## Diseño de registro (oficial)
+
+Un único tipo de registro, `01`, de 130 posiciones. Tabla transcripta del manual (pág. 24):
+
+| Pos. | Campo (propiedad) | Tipo | Long. | Formato |
+| --- | --- | --- | --- | --- |
+| 1-2 | Tipo de registro | N | 2 | `01` |
+| 3-4 | Código de movimiento (`movimiento`) | A | 2 | `AT`, `BT`, `MR`, `NA`, `NB` |
+| 5-15 | CUIL del empleado (`cuil`) | N | 11 | |
+| 16 | Marca de trabajador agropecuario (`trabajadorAgropecuario`) | A | 1 | |
+| 17-19 | Modalidad de contrato (`modalidadContrato`) | N | 3 | |
+| 20-29 | Fecha de inicio de rel. laboral (`fechaInicio`) | A | 10 | `AAAA/MM/DD` |
+| 30-39 | Fecha de fin de rel. laboral (`fechaFin`) | A | 10 | `AAAA/MM/DD` |
+| 40-45 | Código obra social (`obraSocial`) | N | 6 | |
+| 46-47 | Situación de revista (`situacionRevista`) | N | 2 | |
+| 48-57 | Fecha recepción telegrama de renuncia (`fechaTelegramaRenuncia`) | A | 10 | `AAAA/MM/DD` |
+| 58-72 | Retribución pactada (`retribucion`) | N | 15 | |
+| 73 | Modalidad de liquidación (`modalidadLiquidacion`) | N | 1 | |
+| 74-78 | Sucursal – domicilio de desempeño (`sucursal`) | N | 5 | |
+| 79-84 | Actividad en el domicilio de desempeño (`actividad`) | N | 6 | |
+| 85-88 | Puesto desempeñado (`puesto`) | A | 4 | |
+| 89-90 | Rectificación (`rectificacion`) | N | 2 | `00`–`05` |
+| 91-100 | Convenio colectivo de trabajo (`cct`) | A | 10 | |
+| 101-106 | Categoría profesional (`categoriaProfesional`) | N | 6 | |
+| 107-109 | Tipo de servicio (`tipoServicio`) | N | 3 | |
+| 110-119 | Fecha de suspensión servicios temporarios (`fechaSuspensionServiciosTemporarios`) | A | 10 | `AAAA/MM/DD` |
+| 120-129 | Número formulario agropecuario (`numeroFormularioAgropecuario`) | N | 10 | |
+| 130 | Marca licencia COVID / tipo de contrato CCG (`marcaCovidTipoContratoCCG`) | N | 1 | `0`–`9` |
+
+### Qué es oficial y qué es convención
+
+**Oficial (manual):** las posiciones, largos y tipos de la tabla; el formato `AAAA/MM/DD` de las fechas;
+los códigos `AT,BT,MR,NA,NB`; rectificación `00`–`05`; la marca de la posición 130 (`0`–`9`, default
+`0`); que la retribución se informa "con indicación de centavos"; que el CCT `9999/99` es "excluido de
+convenio"; los datos mínimos del alta (RG 5508/2024): CUIL, domicilio de desempeño, fecha de inicio,
+modalidad de contratación, obra social y fecha de fin si el contrato es a plazo fijo.
+
+**Convención no documentada por ARCA** (la habitual en los diseños de registro de ARCA; configurable
+donde se indica):
+
+| Tema | Lo que hace el SDK | Configurable |
+| --- | --- | --- |
+| Numéricos | Ceros a la izquierda | — |
+| Numérico no informado | Ceros (salvo rectificación y marca 130, siempre `0`) | `numericoVacio: 'espacios'` |
+| Alfanuméricos | Espacios a la derecha; sin cambiar mayúsculas | — |
+| Fecha no informada | 10 espacios | — |
+| Retribución | 2 decimales implícitos, sin separador: `1500.5` → `000000000150050`. Más de 2 decimales es error (no se redondea) | — |
+| Codificación | ISO-8859-1 (`Buffer` en latin1, 1 byte por caracter) | `encoding: 'ascii'` |
+| Caracteres no representables | Error | `noRepresentables: 'transliterar'` |
+| Fin de línea | CRLF, también después del último registro | `eol`, `eolFinal` |
+| Fechas `Date` | Se toma la fecha calendario de Argentina (`America/Argentina/Buenos_Aires`) | Pasá un string `AAAA-MM-DD` para fijarla literal |
+| Marca de trabajador agropecuario | Se escribe el caracter que pases (el manual no dice cuál) | — |
+
+**No verificado / no documentado:**
+
+- El significado de `NA` y `NB`. El manual los lista sin describirlos (`AT`, `BT` y `MR` = alta, baja y
+  modificación coinciden con la RG 3399/2012). Se pueden usar con `novedad()`; el SDK solo exige el CUIL.
+- El significado de cada valor de "Rectificación" y de la marca de la posición 130.
+- Qué campos exige ARCA para `BT`, `MR`, `NA` y `NB`. El SDK exige: `AT` → `cuil`, `fechaInicio`,
+  `modalidadContrato`, `obraSocial`, `sucursal`; `BT` → `cuil`, `fechaFin`; el resto → `cuil`
+  (`CAMPOS_OBLIGATORIOS`). La fecha de fin obligatoria para contratos a plazo fijo no se puede chequear
+  sin la tabla de modalidades. El servicio de ARCA hace su propia validación al importar el archivo y
+  muestra los rechazos en el listado de novedades.
+
+Nada se trunca en silencio: un valor que no entra en su campo, `NaN`, un número negativo o con decimales
+en un campo de código, un tipo incorrecto, una fecha inexistente, un salto de línea o un caracter no
+representable lanzan `ArcaSerializationError`.
+
+## Errores
+
+| Clase | Cuándo |
+| --- | --- |
+| `ArcaValidationError` (de common) | Reglas de negocio, datos que no son un objeto, movimiento inválido, `generar()` sin registros. `details[]` por campo; en las operaciones masivas el campo es `"[i].campo"` y `cause` es el error original (o un `AggregateError` con uno por registro). |
+| `ArcaSerializationError` | Un valor no se puede escribir en el formato. `field`, `desde`, `hasta`, `value`, `indice` (en `serializarArchivo`), `cause`. |
+| `ArcaEmpleadosError` | Base de los errores propios (acepta `{ cause }`). |
 
 ## Licencia