Cosmos.Types.IdentificacionesLegales 1.1.1

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 });

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.