UruFactura.Lite 1.0.0

UruFactura 🇺🇾

La vía rápida hacia la Facturación Electrónica en Uruguay

📖 Documentación completa: mathiasgonzalez.github.io/UruFactura

UruFactura SDK es una librería open-source .NET 10 C# de alto nivel diseñada para simplificar la integración de sistemas locales con el ecosistema de la DGI. Olvídate de lidiar con la complejidad manual de los sobres SOAP o la estructura rígida de los esquemas XML; esta herramienta actúa como un puente amigable entre tu lógica de negocio y los requisitos impositivos uruguayos.

🚀 Características Principales

📦 Estructura del Proyecto

UruFactura/
├── src/
│   ├── UruFactura/                  # Paquete completo (con PDF)
│   │   ├── Configuration/              # UruFacturaConfig
│   │   ├── Enums/                      # TipoCfe, TipoIva, FormaPago, Moneda, Ambiente, IndTraslado, TipoDocumentoReceptor
│   │   ├── Exceptions/                 # CaeException, CfeValidationException, DgiCommunicationException,
│   │   │                               # FirmaDigitalException, PdfGenerationException, UruFacturaException
│   │   ├── Models/                     # Cfe, Cae, Receptor, LineaDetalle, RefCfe,
│   │   │                               # RespuestaDgi, RespuestaReporteDiario, TotalesIva
│   │   ├── Formatting/                 # CfeFormat (formateadores internos de fecha y moneda)
│   │   ├── Xml/                        # CfeXmlBuilder / ICfeXmlBuilder (generación XML DGI)
│   │   ├── Signature/                  # CfeFirmante / ICfeFirmante (XAdES-BES)
│   │   ├── Soap/                       # DgiSoapClient / IDgiSoapClient (comunicación con DGI)
│   │   ├── Cae/                        # CaeManager / ICaeManager (gestión de CAE)
│   │   │                               # InMemoryCaeRepository / ICaeRepository (persistencia)
│   │   ├── Pdf/                        # CfePdfGenerator / ICfePdfGenerator (PDF A4 y térmico)
│   │   │                               # CfeQrGenerator / ICfeQrGenerator (código QR)
│   │   ├── IUruFacturaClient.cs        # Interfaz pública (para mocking en tests)
│   │   ├── UruFacturaClient.cs         # Fachada principal del SDK
│   │   ├── UruFacturaClientBuilder.cs  # Builder fluido con WithDefaults()
│   │   └── UruFacturaClientBuilderPdf.cs # Extensión del builder para PDF (solo paquete completo)
│   └── UruFactura.Lite/             # Paquete Lite (sin FluentReport/SkiaSharp/ZXing)
│       └── UruFacturaClient.cs         # Constructores de conveniencia (sin PDF por defecto)
└── tests/
    └── UruFactura.Tests/            # Tests unitarios xUnit

🛠️ Uso Rápido

1. Configurar el cliente

var config = new UruFacturaConfig
{
    // Obligatorios
    RutEmisor           = "210000000012",       // 12 dígitos, sin puntos ni guión
    RazonSocialEmisor   = "Mi Empresa S.A.",
    DomicilioFiscal     = "Av. 18 de Julio 1234",
    Ciudad              = "Montevideo",
    Departamento        = "Montevideo",
    Giro                = "Comercio al por mayor", // Actividad económica (opcional)
    Ambiente            = Ambiente.Homologacion,
    RutaCertificado     = "/ruta/al/certificado.p12",
    PasswordCertificado = Environment.GetEnvironmentVariable("CERT_PASSWORD")!,

    // Opcionales
    NombreComercialEmisor = "Mi Comercio",      // nombre de fantasía
    SoapTimeoutSegundos   = 60,                 // timeout SOAP (default: 30 s)
    OmitirValidacionSsl   = true,               // solo en Homologación con CA no confiable
};

// Constructor de conveniencia (paquete completo — incluye PDF)
using var client = new UruFacturaClient(config);

// O usando el builder fluido (recomendado para DI o tests):
using var client = UruFacturaClientBuilder.WithDefaults(config)
    .WithDefaultPdf()   // omitir si usás UruFactura.Lite
    .Build();

⚠️ Nunca almacenes PasswordCertificado en texto plano. Usá variables de entorno o un gestor de secretos.

2. Crear y enviar un e-Ticket

using UruFactura.Models; // Cae, LineaDetalle, Receptor, RefCfe

// Registrar CAE
client.Cae.RegistrarCae(new Cae
{
    NroSerie        = "CAE2025001",
    TipoCfe         = TipoCfe.ETicket,
    RangoDesde      = 1,
    RangoHasta      = 1000,
    FechaVencimiento = new DateOnly(2026, 12, 31),
});

// Crear comprobante
var eticket = client.CrearETicket();
eticket.Numero = 1;
eticket.Detalle.Add(new LineaDetalle
{
    NroLinea       = 1,
    NombreItem     = "Servicio de consultoría",
    Cantidad       = 1,
    PrecioUnitario = 1000m,
    IndFactIva     = TipoIva.Basico,
    // Opcional: descuentos y recargos
    DescuentoMonto    = 50m,   // monto fijo sin IVA
    // DescuentoPorcentaje = 5m, // alternativa: porcentaje
    RecargoMonto      = 0m,
});

// Validar antes de enviar
var errores = eticket.Validar();
if (errores.Count > 0)
{
    foreach (var error in errores)
        Console.WriteLine($"❌ {error}");
    return;
}

// Generar XML, firmar y enviar
var xmlFirmado = client.GenerarYFirmar(eticket);
var respuesta  = await client.EnviarCfeAsync(eticket);

if (respuesta.Exitoso)
    Console.WriteLine($"✅ Aceptado: {respuesta.Mensaje}");

3. Generar PDF

// PDF A4
byte[] pdfA4 = client.GenerarPdfA4(eticket);
await File.WriteAllBytesAsync("eticket.pdf", pdfA4);

// PDF Térmico (ticket 80mm)
byte[] pdfTermico = client.GenerarPdfTermico(eticket);
await File.WriteAllBytesAsync("eticket_termico.pdf", pdfTermico);

4. Nota de crédito con referencia

var nc = client.CrearNotaCreditoETicket();
nc.Numero = 1;
nc.Referencias.Add(new RefCfe
{
    TipoCfe  = TipoCfe.ETicket,
    Serie    = "A",
    NroCfe   = 42,
    FechaCfe = new DateTime(2025, 6, 15),
    Razon    = "Devolución de mercadería",
});
nc.Detalle.Add(new LineaDetalle
{
    NroLinea       = 1,
    NombreItem     = "Devolución producto",
    Cantidad       = 1,
    PrecioUnitario = 500m,
    IndFactIva     = TipoIva.Basico,
});

5. Verificar estado de CAEs

// Registrar múltiples CAEs a la vez
client.Cae.RegistrarCaes(new[]
{
    new Cae { NroSerie = "CAE2025001", TipoCfe = TipoCfe.ETicket,  RangoDesde = 1, RangoHasta = 1000, FechaVencimiento = new DateOnly(2026, 12, 31) },
    new Cae { NroSerie = "CAE2025002", TipoCfe = TipoCfe.EFactura, RangoDesde = 1, RangoHasta = 500,  FechaVencimiento = new DateOnly(2026, 12, 31) },
});

// Obtener próximo número disponible (thread-safe)
var (cae, numero) = client.Cae.ObtenerProximoNumero(TipoCfe.ETicket);

// Obtener CAE activo para un tipo
var caeActivo = client.Cae.ObtenerCaeActivo(TipoCfe.ETicket);

// Ver advertencias (vencimiento próximo, rango casi agotado)
var advertencias = client.Cae.ObtenerAdvertencias(diasAlertaVencimiento: 7, porcentajeAlertaUso: 80m);
foreach (var advertencia in advertencias)
    Console.WriteLine(advertencia);

Console.WriteLine(client.Cae.ResumenEstado());

📄 Tipos de CFE soportados

💸 Tasas de IVA (TipoIva)

🧩 Interfaz IUruFacturaClient

El SDK expone la interfaz IUruFacturaClient para facilitar el mocking en tests de aplicaciones consumidoras:

// En tu aplicación
public class MiServicioFacturacion(IUruFacturaClient client) { ... }

// En tus tests
var mockClient = Substitute.For<IUruFacturaClient>(); // NSubstitute, Moq, etc.

Interfaces de dependencias

Todas las dependencias internas del cliente también tienen interfaces, lo que permite reemplazar cualquier componente sin subclasear UruFacturaClient:

UruFacturaClientBuilder

El builder fluido es la forma recomendada de construir el cliente, especialmente cuando se necesita inyectar dependencias personalizadas (p.ej. mocks en tests o transporte SOAP propio):

// Caso más habitual — todas las implementaciones predeterminadas:
using var client = UruFacturaClientBuilder.WithDefaults(config)
    .WithDefaultPdf()   // solo disponible en UruFactura (no en Lite)
    .Build();

// Reemplazar solo lo que necesitás:
using var client = UruFacturaClientBuilder.WithDefaults(config)
    .WithCaeManager(miCaeManager)
    .WithSoapClient(miSoapMock)
    .WithPdfGenerator(miGeneradorPdf)
    .WithSigner(miCfeFirmante)          // reemplaza la firma digital (ICfeFirmante)
    .WithXmlBuilder(miXmlBuilder)       // reemplaza el generador de XML (ICfeXmlBuilder)
    .Build();

🏭 APIs de alto tráfico: usá .WithHttpClient(httpClient) para inyectar un HttpClient gestionado por IHttpClientFactory y evitar el agotamiento de sockets (socket exhaustion) que ocurre cuando se crean y descartan instancias de HttpClient por cada request. Al hacerlo, el SDK no configura el handler interno (certificado de cliente ni OmitirValidacionSsl), así que es responsabilidad del caller configurarlos en el handler del HttpClient inyectado.

// Ejemplo en Program.cs (ASP.NET Core)
builder.Services.AddHttpClient("DGI");
builder.Services.AddSingleton(sp =>
    UruFacturaClientBuilder
        .WithDefaults(config)
        .WithHttpClient(sp.GetRequiredService<IHttpClientFactory>().CreateClient("DGI"))
        .Build());

💾 Persistencia de CAEs

En producción, el estado de los CAEs —especialmente UltimoNroUsado— debe sobrevivir reinicios de la aplicación. Si la app arranca con el contador en cero, volvería a emitir números ya usados, lo que la DGI rechazaría por duplicado.

El SDK separa la gestión en memoria (ICaeManager) de la persistencia (ICaeRepository):

Al iniciar la app:   repo.CargarTodosAsync() → manager.RegistrarCaes()
Al emitir un CFE:    manager.ObtenerProximoNumero() → repo.ActualizarUltimoNroUsadoAsync()

Uso con la implementación en memoria (tests / desarrollo)

// InMemoryCaeRepository: los datos se pierden al reiniciar (solo para tests/dev)
var repo = new InMemoryCaeRepository();
await repo.GuardarCaeAsync(new Cae
{
    NroSerie         = "CAE2025001",
    TipoCfe          = TipoCfe.ETicket,
    RangoDesde       = 1,
    RangoHasta       = 1000,
    FechaVencimiento = new DateOnly(2026, 12, 31),
});

// Al iniciar: cargar y registrar en el manager
client.Cae.RegistrarCaes(await repo.CargarTodosAsync());

// Al emitir: obtener número y persistir inmediatamente
var (cae, numero) = client.Cae.ObtenerProximoNumero(TipoCfe.ETicket);
await repo.ActualizarUltimoNroUsadoAsync(cae.NroSerie, cae.UltimoNroUsado);

Implementar persistencia real (producción)

Implementá ICaeRepository con tu mecanismo de almacenamiento:

public class MiCaeRepository : ICaeRepository
{
    public ValueTask<IEnumerable<Cae>> CargarTodosAsync()
    {
        // Leer de base de datos / archivo / Redis / etc.
        throw new NotImplementedException();
    }

    public ValueTask GuardarCaeAsync(Cae cae)
    {
        // INSERT o UPDATE en tu store
        throw new NotImplementedException();
    }

    public ValueTask ActualizarUltimoNroUsadoAsync(string nroSerie, long ultimoNroUsado)
    {
        // UPDATE ultimo_nro_usado WHERE nro_serie = nroSerie
        // ¡Llamar en cada emisión exitosa antes de considerar la operación completa!
        throw new NotImplementedException();
    }
}

⚠️ ActualizarUltimoNroUsadoAsync debe ejecutarse antes de considerar la emisión finalizada. Si la app cae entre la emisión y la persistencia, el siguiente arranque repetirá ese número. En escenarios críticos, usá transacciones de base de datos o idempotencia en el endpoint de la DGI.

⚠️ Excepciones tipadas

🔧 Requisitos

• .NET 10 SDK
• Certificado digital DGI (.p12 / .pfx)
• CAE vigente emitido por la DGI

☁️ Despliegue en Cloudflare

El ecosistema UruFactura incluye una solución completa para Cloudflare:

cloudflare/
├── worker.js              → Worker multi-tenant (router)
├── wrangler.toml          → Config de Containers + Secrets
└── email-worker/          → Worker de envío de emails
     ├── worker.js
     └── wrangler.toml

admin/                     → Web de administración (Cloudflare Pages)
├── src/                   → SPA React + Vite
├── functions/auth/        → Pages Functions (auth backend)
└── wrangler.toml          → Config KV + Secrets

src/UruFactura.CloudflareApi/ → API .NET (Container)
src/UruFactura.TestApi/       → API local con Scalar UI

Workflows CI/CD

Desarrollo local

# API (con Scalar UI)
cd src/UruFactura.TestApi && dotnet run

# Admin + auth (Pages Functions con KV local)
cd admin && npx wrangler pages dev --kv AUTH_CODES --kv AUTH_SESSIONS --kv TENANTS -- npm run dev

📖 Documentación completa: docs/ARQUITECTURA_CLOUDFLARE.md y admin/README.md

📚 Documentación adicional

📦 Paquetes NuGet

# Paquete completo
dotnet add package UruFactura

# Paquete Lite (sin FluentReport / SkiaSharp / ZXing)
dotnet add package UruFactura.Lite

🧪 Tests

dotnet test tests/UruFactura.Tests/

📝 Licencia

MIT — ver LICENSE