IQeSign.TicketBai 1.0.0

IQeSign.TicketBai

Cliente .NET para la API IQ eSign TicketBAI de InnoQubit Software. Permite integrar desde cualquier aplicación .NET la presentación de facturas electrónicas a las haciendas forales del País Vasco (Álava, Gipuzkoa y Bizkaia), gestionando certificados digitales, firma de peticiones y encadenamiento automático.

Sobre InnoQubit

InnoQubit Business Software es una empresa tecnológica con sede en Castellón (España), especializada en la digitalización y automatización de procesos empresariales para sistemas ERP.

Su producto insignia IQ eSign agrupa soluciones de facturación electrónica y firma digital que se integran con cualquier ERP (Microsoft Dynamics 365 Business Central, Navision y software a medida):

¿Qué es TicketBAI?

TicketBAI es el sistema de facturación electrónica obligatorio en el País Vasco, regulado por las haciendas forales de Álava, Gipuzkoa y Bizkaia. Garantiza la integridad de cada factura mediante encadenamiento de firmas digitales y su presentación en tiempo real a la hacienda foral correspondiente.

Este paquete encapsula toda la complejidad de la integración:

• Autenticación JWT automática con refresco de token
• Firma de peticiones con certificado digital (.pfx) almacenado en IQ Portal
• Encadenamiento automático de facturas (gestión de HuellaTbai)
• Soporte para facturas emitidas y recibidas
• Soporte para correcciones (Zuzendu) en Álava y Gipuzkoa
• Gestión de facturas simplificadas y rectificativas
• Reintentos de envío para documentos con fallos transitorios

Instalación

dotnet add package IQeSign.TicketBai

Para obtener una cuenta y el CredentialGuid necesarios para usar este paquete, contacta con el equipo comercial de InnoQubit en comercial@innoqubit.com.

Inicio rápido

1. Registro en el contenedor DI

// Program.cs
builder.Services.AddIQeSignTicketBai(options =>
{
    options.CredentialGuid = builder.Configuration["IQeSignTicketBai:CredentialGuid"]!;
    options.Environment = IQeSignEnvironment.Production; // o Staging para pruebas
    options.TimeoutSeconds = 30;
});

O bien usando una sección de appsettings.json:

{
  "IQeSignTicketBai": {
    "CredentialGuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "Environment": "Production"
  }
}

builder.Services.AddIQeSignTicketBai(
    builder.Configuration.GetSection(IQeSignOptions.SectionName));

2. Enviar una factura emitida

public class FacturacionService(ITicketBaiService ticketBai)
{
    public async Task<string> EnviarFacturaAsync(CancellationToken ct = default)
    {
        var response = await ticketBai.AddDocumentAsync(new AddDocumentRequest
        {
            CertificateId = "id-del-certificado-en-iqportal",
            CertificatePass = "contraseña-del-pfx",
            File = new TicketBaiDocumentFile
            {
                Issuer = new TicketBaiIssuerInfo
                {
                    Name = "Mi Empresa S.L.",
                    CifNif = "B12345678",
                    TaxCategory = "662"
                },
                Serial = "FAC",
                Number = "2024-001",
                Date = "2024-01-15",
                Name = "Cliente S.A.",
                Nif = "A98765432",
                Address = "Calle Mayor 1",
                ZipCode = "28001",
                Country = "ES",
                Simplified = false,
                OperationType = OperationTypeEmitted.SinInversion,
                Rectified = false,
                TotalInvoice = 1210.00m,
                Administration = Administration.Gipuzkoa,
                Lines =
                [
                    new InvoiceLine
                    {
                        Description = "Servicios de consultoría",
                        Quantity = 1,
                        UnitAmount = 1000.00m,
                        DiscountAmount = 0m,
                        Vat = 21m,
                        VatEc = 0m,
                        VatSubject = true,
                        VatCause = VatCause.E1,
                        TaxKey = TaxKey.RegimenGeneral
                    }
                ]
            },
            Metadata = new DocumentMetadata
            {
                Platform = "MiApp",
                Version = "1.0.0",
                User = "usuario@empresa.com",
                Email = "facturacion@empresa.com",
                Company = "Mi Empresa S.L.",
                Tenant = "tenant-001",
                Description = "Factura generada desde MiApp"
            }
        }, ct);

        if (!response.IsSuccess)
            throw new Exception($"Error TicketBAI [{response.ErrorCode}]: {response.ErrorMessage}");

        return response.Result!.Id!;
    }
}

3. Registrar una factura recibida

public class FacturasRecibidasService(ITicketBaiReceivedService received)
{
    public async Task<string> RegistrarAsync(CancellationToken ct = default)
    {
        var response = await received.AddReceivedAsync(new AddReceivedRequest
        {
            CertificateId = "id-del-certificado",
            CertificatePass = "contraseña",
            File = new ReceivedDocumentFile
            {
                Issuer = new ReceivedIssuerInfo
                {
                    Name = "Proveedor S.L.",
                    CifNif = "B87654321",
                    Country = "ES",
                    IdentifierType = IdentifierType.NifIva
                },
                OperationType = ReceivedOperationType.AdquisicionBienesServicios,
                InvoiceType = ReceivedInvoiceType.FacturaConDestinatario,
                Serial = "PRV",
                Number = "2024-100",
                Exercise = 2024,
                ReceivedDate = "2024-01-20",
                InvoiceDate = "2024-01-18",
                SalesVatQuote = 0m,
                Name = "Mi Empresa S.L.",
                Nif = "B12345678",
                Description = "Servicios de consultoría recibidos",
                Rectified = false,
                TaxBase = 500.00m,
                TotalInvoice = 605.00m
            }
        }, ct);

        if (!response.IsSuccess)
            throw new Exception($"[{response.ErrorCode}] {response.ErrorMessage}");

        return response.Result!.Id!;
    }
}

4. Gestión de certificados

public class CertificadoService(ICertificateService certs)
{
    public async Task<string> SubirCertificadoAsync(byte[] pfxBytes, string nombre)
    {
        var resp = await certs.AddAsync(new AddCertificateRequest
        {
            Name = nombre,
            File = Convert.ToBase64String(pfxBytes)
        });
        return resp.Result!.Id;
    }
}

Servicios disponibles

ITicketBaiService — Facturas emitidas

ITicketBaiReceivedService — Facturas recibidas

ICertificateService — Certificados digitales

Listas de referencia TicketBAI

// Administración hacienda foral
Administration.Alava       // "Álava"
Administration.Gipuzkoa    // "Gipuzkoa"
Administration.Bizkaia     // "Bizkaia" (solo facturas emitidas, no Zuzendu)

// Clave fiscal / régimen (L9)
TaxKey.RegimenGeneral      // "01"
TaxKey.Exportacion         // "02"

// Causa de exención (L10)
VatCause.Articulo20        // "E1"
VatCause.NoSujetoArticulo7 // "OT"

// Tipo de operación emitida (L11)
OperationTypeEmitted.SinInversion  // "S1"
OperationTypeEmitted.ConInversion  // "S2"

// Tipo de factura recibida (L18)
ReceivedInvoiceType.FacturaConDestinatario     // "F1"
ReceivedInvoiceType.FacturaSinDestinatario     // "F2"

// Código de rectificación (L7)
RectificationCode.R1  // "R1" — Error fundado en derecho
RectificationCode.R5  // "R5" — Facturas simplificadas

// Tipo de compra (L19)
PurchaseType.ComprasBienes   // "C"
PurchaseType.Gastos          // "G"
PurchaseType.BienesInversion // "I"

// Inversión del sujeto pasivo (L20)
ReverseCharge.Si  // "S"
ReverseCharge.No  // "N"

Documentos con envío fallido (Processed = false)

Si el envío a la hacienda foral falla por un error transitorio, la API devuelve el Id del documento pero con Processed = false. Usa RetryDocumentAsync para reintentarlo:

var doc = await ticketBai.GetDocumentByIdAsync(id, ct);
if (!doc.Result!.Processed)
{
    var retry = await ticketBai.RetryDocumentAsync(id, ct);
    if (!retry.IsSuccess)
        Console.WriteLine($"Reintento fallido: {retry.ErrorMessage}");
}

Si existe un documento pendiente con Processed = false, la API devuelve el aviso "00001" al intentar enviar uno nuevo. Resuelve primero el documento pendiente con RetryDocumentAsync.

Control de errores

var response = await ticketBai.AddDocumentAsync(request, ct);

if (!response.IsSuccess)
{
    // ErrorCode "0"  → éxito
    // ErrorCode "8"  → validación incorrecta (datos, ID no encontrado, plataforma rechaza)
    // ErrorCode "9"  → error no controlado (ver ErrorMessage)
    // Otros valores  → error de negocio controlado (ver ErrorMessage)
    Console.WriteLine($"[{response.ErrorCode}] {response.ErrorMessage}");
}

// Avisos de la plataforma (no impiden el registro)
foreach (var w in response.Result?.Warning ?? [])
    Console.WriteLine($"Aviso [{w.Code}]: {w.Message} / {w.Azalpena}");

Las excepciones se lanzan únicamente ante fallos de comunicación:

Entornos

Requisitos

• .NET 8.0 o .NET Standard 2.1 (compatible con .NET 6+, .NET 7+)
• Cuenta activa en IQ Portal con la solución IQ eSign TicketBAI contratada
• Certificado digital .pfx válido para firma de facturas (FNMT, ACA, etc.)

Documentación adicional

• Documentación técnica de la API IQ eSign TicketBAI (PDF)
• IQ Portal — gestión de credenciales y certificados
• Swagger de la API (producción)

Licencia

MIT © InnoQubit Software