SER.FactElectronica 0.14.2

SER.FactElectronica

Biblioteca para integración con el sistema de Factura Electrónica de FACTURA1. Esta biblioteca facilita la comunicación con los servicios de facturación electrónica proporcionados por FACTURA1, permitiendo la creación y gestión de documentos electrónicos requeridos por la DIAN en Colombia.

Características

• Generación de facturas electrónicas
• Generación de notas crédito
• Generación de documentos soporte
• Asociación de rangos de numeración
• Carga y validación de representación gráfica (PDF)
• Obtención de Attached Document
• Registro y habilitación de empresas
• Gestión de autenticación con los servicios de FACTURA1

Instalación

dotnet add package SER.FactElectronica

Requisitos

• .NET 6.0 o superior
• Credenciales válidas de FACTURA1

Uso

Configuración

Uso

Configuración del Servicio

Para utilizar esta biblioteca, es necesario configurar las credenciales de acceso a los servicios de FACTURA1 y registrar la implementación del servicio en el contenedor de dependencias.

// En Startup.cs o Program.cs
services.AddTransient<IFactElectronica>(provider =>
{
    var logger = provider.GetService<ILoggerFactory>();
    var config = provider.GetService<IConfiguration>();
    var options = provider.GetService<IOptionsMonitor<FacturaOptions>>();
    return new Factura1(logger, config, options);
});

// En appsettings.json
{
  "Factura1": {
    "username": "su_usuario",
    "password": "su_contraseña",
    "SandBox": true  // true para ambiente de pruebas, false para producción
  }
}

Autenticación

La biblioteca maneja automáticamente la autenticación con los servicios de FACTURA1, pero también puedes solicitar un token manualmente:

// Obtener token de autenticación
var token = await _factura.LoginAsync();

Creación de Facturas Electrónicas

// Inyectar la dependencia
private readonly IFactElectronica _factura;

public MiController(IFactElectronica factura)
{
    _factura = factura;
}

// Crear factura electrónica
public async Task<IActionResult> CrearFactura()
{
    try
    {
        // Crear el encabezado de la factura
        var encabezado = Encabezado.Basic(
            nitemisor: 900000000,
            mailContactoEmisor: "emisor@ejemplo.com",
            tiporeceptor: TipoPersona.PersonaJuridica,
            tipoDocRec: TipoIdentificadorFiscal.NIT,
            nitreceptor: "800000000",
            digitoverificacion: "1",
            obligacionesfiscalesreceptor: ObligacionesFiscales.IVARegComun,
            procvendedor: Procedencia.Residente,
            tributoreceptor: TributosReceptorVendedor.ZZ,
            regimenreceptor: TipoRegimen.SimpleTributacion,
            nombrereceptor: "EMPRESA CLIENTE S.A.S.",
            segnombrereceptor: "",
            apellidosreceptor: "",
            codigodepartamento: "11",
            departamentoreceptor: "Bogotá",
            codigociudadreceptor: "11001",
            ciudadreceptor: "Bogotá D.C.",
            direccionreceptor: "Calle 123 # 45-67",
            telefonoreceptor: "6017654321",
            telefonomovilreceptor: "3001234567",
            mailreceptor: "cliente@empresa.com",
            mailreceptorcontacto: "contacto@empresa.com",
            nombrecontactoreceptor: "Contacto Cliente",
            tipoComprobante: TiposDocumentos.FacturaVenta,
            numResolucion: "18760000001",
            prefijoFact: "SETP",
            numeroFactura: "1000",
            fechaFactura: DateTime.Now,
            subtotal: 1000000,
            medioPago: MediosPago.Efectivo,
            fechaPagoFact: DateTime.Now.AddDays(30),
            baseImpuesto: 1000000,
            totalSinDescuento: 1000000,
            totalDescuentos: 0,
            totalImpuestos: 190000,
            totalImpuestosRetenidos: 0,
            total: 1190000
        );

        // Crear los detalles de la factura
        var detalles = new List<Det>
        {
            new Det(
                idConcepto: 1,
                cantidad: 1,
                impuesto: 0.19,
                precioUnitario: 1000000,
                identificacionproducto: "SERV-001",
                nombreProducto: "Servicio de implementación"
            )
        };

        // Crear la factura
        var factura = new Factura
        {
            Encabezado = encabezado,
            Detalle = detalles
        };

        // Enviar la factura
        var resultado = await _factura.CreateInvoice(factura);

        if (resultado?.Dian != null && resultado.Dian.Any(d => d.StatusCode == "200"))
        {
            return Ok(new
            {
                CUFE = resultado.Cufe,
                QRData = resultado.Qrdata,
                XML = resultado.Xml
            });
        }

        return BadRequest(new { Error = resultado?.Error, Detalles = resultado?.Dian });
    }
    catch (Exception ex)
    {
        return StatusCode(500, $"Error al crear factura: {ex.Message}");
    }
}

### Obtención de Attached Document

```csharp
// Obtener Attached Document
public async Task<IActionResult> ObtenerAttachedDocument(string xmlDian, string apDian)
{
    try
    {
        // El método acepta XML en formato string o codificado en base64
        var resultado = await _factura.GetAttachedDocumentAsync(xmlDian, apDian);
        
        if (resultado != null && !string.IsNullOrEmpty(resultado.AttachedDocument))
        {
            return Ok(new
            {
                AttachedDocument = resultado.AttachedDocument,
                Url = resultado.Url
            });
        }
        
        return BadRequest("No se pudo generar el Attached Document");
    }
    catch (Exception ex)
    {
        return StatusCode(500, $"Error al generar el Attached Document: {ex.Message}");
    }
}

Verificación y Descarga de PDF

// Verificar si existe el PDF de una factura
public async Task<IActionResult> VerificarPDF(string cufe)
{
    try
    {
        var resultado = await _factura.CheckPdfFromInvoice(cufe);
        
        if (resultado != null && !string.IsNullOrEmpty(resultado.Basepdf))
        {
            // Convertir base64 a archivo PDF
            byte[] pdfBytes = Convert.FromBase64String(resultado.Basepdf);
            return File(pdfBytes, "application/pdf", $"factura-{cufe}.pdf");
        }
        
        return NotFound("No se encontró el PDF de la factura");
    }
    catch (Exception ex)
    {
        return StatusCode(500, $"Error al verificar PDF: {ex.Message}");
    }
}

// Subir un PDF asociado a una factura
public async Task<IActionResult> SubirPDF(string cufe, IFormFile pdfFile)
{
    try
    {
        using (var ms = new MemoryStream())
        {
            await pdfFile.CopyToAsync(ms);
            byte[] fileBytes = ms.ToArray();
            string base64Pdf = Convert.ToBase64String(fileBytes);
            
            var uploadRequest = new UploadPdf
            {
                Cufe = cufe,
                Basepdf = base64Pdf
            };
            
            var resultado = await _factura.UploadPdfAsync(uploadRequest);
            
            if (resultado != null && string.IsNullOrEmpty(resultado.Error))
            {
                return Ok(new { Message = "PDF subido correctamente", CUFE = resultado.Cufe });
            }
            
            return BadRequest(new { Error = resultado?.Error });
        }
    }
    catch (Exception ex)
    {
        return StatusCode(500, $"Error al subir PDF: {ex.Message}");
    }
}

Registro de Empresas

// Registrar una nueva empresa con Factura1
public async Task<IActionResult> RegistrarEmpresa()
{
    try
    {
        var request = new CompanyRegisterRequest
        {
            Nit = "900000000",
            DV = "1",
            RazonSocial = "MI EMPRESA S.A.S.",
            Email = "contacto@miempresa.com",
            Telefono = "6017654321",
            Celular = "3001234567",
            PrimerNombre = "Juan",
            PrimerApellido = "Pérez",
            Ciudad = "Bogotá",
            Direccion = "Calle 123 # 45-67",
            TypeDocument = "31", // NIT
            TipoRegimen = "48", // Responsable de IVA
            ObFiscales = "R-99-PN", // No aplica - Otros
            SetID = "...", // Obtenido al registrarse con Factura1
            Servicio = "1" // Factura Electrónica
        };
        
        var resultado = await _factura.CreateCompanyAsync(request);
        
        if (resultado != null && resultado.Valido == "true")
        {
            return Ok(new { Message = resultado.Msg });
        }
        
        return BadRequest(new { Error = resultado?.Msg });
    }
    catch (Exception ex)
    {
        return StatusCode(500, $"Error al registrar empresa: {ex.Message}");
    }
}

Especificaciones de los Servicios

Servicio AttachedDocument

Request

{
  "xmlDian": "XML del documento timbrado a la DIAN (Invoice) en formato base 64",
  "apDian": "XML respuesta del documento timbrado a la DIAN (Application Response) en formato base 64"
}

Response

{
  "AttachedDocument": "Attached document del comprobante en formato base 64",
  "URL": "URL en la cual se puede identificar el attached document (XML)"
}

Manejo de Errores

La biblioteca proporciona respuestas estandarizadas en caso de error:

// Ejemplo de respuesta de error
new InvoiceRes
{
    Error = "Error comunicacion DIAN / proveedor tecnológico",
    Dian = new Dian[]
    {
        new() {
            StatusCode = "666", // Código de error interno
        }
    }
};

Gestión de Versiones

La biblioteca usa versionado semántico. La versión actual es 0.12.1.

Entorno de Pruebas vs Producción

La biblioteca permite configurar el entorno de ejecución mediante la propiedad SandBox:

• true: Utiliza el entorno de pruebas (QA) de FACTURA1
• false: Utiliza el entorno de producción de FACTURA1

Asegúrese de probar completamente en el entorno de pruebas antes de pasar a producción.

Licencia

Este proyecto es propiedad de SER y SIRIO Dev.

Contribuir

Para contribuir a este proyecto, consulta nuestro archivo CONTRIBUTING.md.

Response

{
  "AttachedDocument": "Attached document del comprobante en formato base 64",
  "URL": "URL en la cual se puede identificar el attached document (XML)"
}

Licencia

Este proyecto es propiedad de SER y SIRIO Dev.