Cosmos.Types.IdentificacionesLegales 1.2.0

Cosmos.Types.IdentificacionesLegales

IdentificacionLegal — Value Object de identificación legal para el ERP Cosmos: tipo de documento (país-scoped, catálogo embebido de 46 tipos), número y dígito de verificación. Implementa el módulo-11 DIAN para el NIT colombiano. Viaja dentro de eventos event-sourced (JSONB) aguas abajo, por lo que su forma serializada es un contrato estable.

Instalación

dotnet add package Cosmos.Types.IdentificacionesLegales

Construcción

Dos tipos, dos puertas distintas:

• TipoDocumento es un VO de catálogo país-scoped: se obtiene con TipoDocumento.Obtener(pais, codigo), que lanza ArgumentException si el código no existe/activo para ese país. Su Crear es internal.
• IdentificacionLegal es un VO compuesto: su factory pública Crear(...) : Result<IdentificacionLegal> valida sin lanzar (EsExitoso / .Valor / .Errores).

using Cosmos.Types.IdentificacionesLegales;
using Cosmos.Types.Paises;

var colombia = Pais.Obtener("CO");
var nit = TipoDocumento.Obtener(colombia, "NIT");   // VO de catálogo: Obtener (lanza)

var resultado = IdentificacionLegal.Crear(           // VO compuesto: Crear (Result)
    tipo: nit,
    numero: "900123456");                            // el DV se calcula (módulo-11 DIAN)

if (resultado.EsExitoso)
    UsarIdentificacion(resultado.Valor);             // resultado.Valor.DigitoVerificacion == "8"
else
    foreach (var error in resultado.Errores)
        Console.WriteLine(error.Codigo);   // V02 (tipo), V03 (número), V06 (DV)

Crear recibe el TipoDocumento tipado y deriva el país de él (un tipo de documento existe "para un país"): no se pasa el país por separado. Para tipos con DV (NIT) el dígito se calcula (módulo-11 DIAN); si lo proveés (digitoVerificacion: "8") la politica controla el desajuste: Rechazo falla con V06, Advertencia lo degrada. Ver el algoritmo en docs/algoritmos-dv.md.

Forma serializada

{
  "tipoDocumento": "NIT",
  "numero": "900123456",
  "pais": { "codigo": "CO" },
  "digitoVerificacion": "8"
}

Las claves son camelCase ancladas con [JsonPropertyName]. Notá la asimetría deliberada: el tipo de documento se aplana a un string ("tipoDocumento": "NIT", no un objeto), mientras que el pais se anida como objeto ({ "codigo": "CO" }). Un consumidor que mapee a mano necesita saberlo. La ClaveCanonica es un accessor derivado [JsonIgnore]: no viaja.

Rehidratación (deserialización)

No requiere setup: ni JsonConverter ni JsonSerializerContext registrados; basta el STJ por defecto. Al deserializar un evento histórico el VO se rehidrata crudo ([JsonConstructor]), sin validar — un tipo que ya no figura en el catálogo igual se rehidrata.

Listado

Para poblar un selector de tipos de documento de un país (frontends) usá TipoDocumento.ListarPorPais(pais) — devuelve los mismos TipoDocumento que consume la escritura. El backend proyecta su propio DTO de API:

var tiposDto = TipoDocumento.ListarPorPais(colombia)
    .Select(tipo => new { tipo.Codigo, tipo.Nombre, tipo.AplicaA, tipo.CapturaDv });

Superficie derivada de TipoDocumento (para armar el formulario)

Además de Nombre, TipoDocumento expone dos accessors derivados del catálogo para que un consumidor arme el formulario de captura sin conocer vocabularios del catálogo (nombres de algoritmo, strings de naturaleza):

• AplicaA (Naturaleza?) — enum tipado { PersonaNatural, PersonaJuridica, Ambos }. Sirve para parear tipo ↔ naturaleza (ofrecer solo los tipos que aplican al sujeto).
• CapturaDv (CapturaDigitoVerificacion?) — record (bool Requiere, int? Longitud): la decisión de mostrar/ocultar el campo de DV y su longitud, no el nombre del algoritmo. NIT (CO) → { true, 1 }; RUC-PA/NT-PA → { true, 2 }; DV embebido (cédula/RNC de DO) o sin algoritmo → { false, null }.

Ambos son [JsonIgnore]: no viajan al wire (la forma serializada de TipoDocumento sigue siendo { pais, codigo }). Como son datos de display/decisión, es responsabilidad del backend consumidor proyectar su propio DTO (ver el ejemplo de ListarPorPais arriba) antes de exponerlos a un frontend JS. En un TipoDocumento rehidratado cuyo código ya no figura en el catálogo (poison), ambos devuelven null sin lanzar (igual que Nombre).

La forma del DV que expone CapturaDv sale de la misma fuente única que gobierna qué algoritmo de cálculo aplica IdentificacionLegal.Crear: no hay un segundo mapeo que pueda diverger.

Dependencias

• Cosmos.Types.Abstractions (kernel: Result<T>)
• Cosmos.Types.Paises (validación del país)

Requiere net10.0. Solo está implementado el módulo-11 DIAN (NIT colombiano); otros algoritmos de DV quedan diferidos.

Documentación

• Convenciones de los nuggets
• Algoritmos de dígito de verificación

Licencia

Uso interno del ERP Cosmos.