UruFacturaSDK.Lite 1.0.0

UruFacturaSDK 🇺🇾

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

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

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

UruFacturaSDK/
├── src/
│   ├── UruFacturaSDK/                  # Paquete completo (con PDF)
│   │   ├── Configuration/              # UruFacturaConfig
│   │   ├── Enums/                      # TipoCfe, TipoIva, FormaPago, Moneda, Ambiente, 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)
│   │   ├── 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)
│   └── UruFacturaSDK.Lite/             # Paquete Lite (sin QuestPDF/SkiaSharp/ZXing)
│       └── UruFacturaClient.cs         # Constructores de conveniencia (sin PDF por defecto)
└── tests/
    └── UruFacturaSDK.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 UruFacturaSDK.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 UruFacturaSDK.Models; // Cae, LineaDetalle, Receptor, RefCfe

// Registrar CAE
client.Cae.RegistrarCae(new Cae
{
    NroSerie        = "CAE2025001",
    TipoCfe         = TipoCfe.ETicket,
    RangoDesde      = 1,
    RangoHasta      = 1000,
    FechaVencimiento = new DateTime(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 DateTime(2026, 12, 31) },
    new Cae { NroSerie = "CAE2025002", TipoCfe = TipoCfe.EFactura, RangoDesde = 1, RangoHasta = 500,  FechaVencimiento = new DateTime(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 UruFacturaSDK (no en Lite)
    .Build();

// Reemplazar solo lo que necesitás:
using var client = UruFacturaClientBuilder.WithDefaults(config)
    .WithCaeManager(miCaeManager)
    .WithSoapClient(miSoapMock)
    .WithPdfGenerator(miGeneradorPdf)
    .Build();

⚠️ Excepciones tipadas

🔧 Requisitos

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

📚 Documentación adicional

📦 Paquetes NuGet

# Paquete completo
dotnet add package UruFacturaSDK

# Paquete Lite (sin QuestPDF / SkiaSharp / ZXing)
dotnet add package UruFacturaSDK.Lite

🧪 Tests

dotnet test tests/UruFacturaSDK.Tests/

📝 Licencia

MIT — ver LICENSE