Regira.Invoicing 6.6.1

Regira Invoicing

Regira Invoicing covers electronic invoice creation, UBL/Peppol conversion, and document transmission via an AP gateway.

Projects

Installation

<PackageReference Include="Regira.Invoicing.Billit"       Version="6.*" />
<PackageReference Include="Regira.Invoicing.UblSharp"     Version="6.*" />
<PackageReference Include="Regira.Invoicing.ViaAdValvas"  Version="6.*" />

Billit

BillitConfig

DI Registration

using Regira.Invoicing.Billit.Config;                // BillitConfig
using Regira.Invoicing.Billit.DependencyInjection;   // AddBillit

services.AddBillit(sp => new BillitConfig
{
    PartyId = configuration["Billit:PartyId"],
    Api     = new() { BaseUrl = configuration["Billit:Api:Url"], Key = configuration["Billit:Api:Key"] }
});
// Registers: IInvoiceManager, IFileManager, IPartyManager, IPeppolManager (transient).
// IInvoiceManager extends IInvoiceService, which AddBillit registers too (an IInvoiceService of your own wins).
// The managers also need an ISerializer (package Regira.Serializing.Newtonsoft), which AddBillit does not register:
services.AddSingleton<Regira.Serializing.Abstractions.ISerializer, Regira.Serializing.Newtonsoft.Json.JsonSerializer>();

IInvoiceManager

Task<ICreateInvoiceResult> Create(IInvoice item);
Task<ISendInvoiceResult>   Send(params string[] ids);    // send by IDs
Task<ISendInvoiceResult>   Send(IInvoice input);          // creates the invoice, then sends it

UblSharp — UBL Conversion

IUblConverter

XDocument Convert(UblDocumentInput input);

Produces a UBL 2.1 Invoice document.

IInvoice invoice = new Invoice
{
    Code = "INV-001",
    IssueDate = DateTime.Today,
    Supplier = new InvoiceParty
    {
        Code = "BE0123456789",                                                         // VAT number
        Title = "Fleet Services",
        Identifiers = [new PartyIdentifier { Scheme = "0208", Value = "0123456789" }],   // Peppol participant ID
        Address = new PartyAddress { Street = "Stationsstraat 1", PostalCode = "9000", City = "Gent", CountryCode = "BE" }
    },
    Customer = new InvoiceParty
    {
        Code = "BE0987654321",
        Title = "Transport Co",
        Identifiers = [new PartyIdentifier { Scheme = "0208", Value = "0987654321" }],
        Address = new PartyAddress { Street = "Kaai 12", PostalCode = "2000", City = "Antwerpen", CountryCode = "BE" }
    },
    InvoiceLines = [new InvoiceLine { Title = "Brake service", Quantity = 1, UnitPriceExcl = 100, VatPercentage = 21 }]
};

var converter = new UblConverter();
XDocument ubl = converter.Convert(new UblDocumentInput
{
    Invoice  = invoice,            // required
    Supplier = invoice.Supplier    // the seller: read from here only, never from Invoice
});

UblDocumentInput takes the Invoice (required), the Supplier and optional PaymentConditions, written as the payment terms note. The converter writes AccountingSupplierParty from Supplier alone, so a document converted without it has no seller, which Peppol validation refuses (EN 16931 rule BR-06).

How the model maps to UBL

VAT is computed per rate: the sum of the rate's rounded line amounts times the rate, rounded once, half away from zero (BR-CO-17). The VAT total, TaxInclusiveAmount and PayableAmount follow from those subtotals, so compute a printed invoice's totals the same way.

What the converter writes

Some fields are fixed rather than taken from the invoice:

• Customization ID and Profile ID from UblConstants: Peppol BIS Billing 3.0
• Invoice type code 380, a commercial invoice, for every document. IInvoice.InvoiceType is not read, so the converter writes no credit notes
• Currency EUR
• Payment means 1 (not defined), with RemittanceInfo as the payment ID
• Tax category S (standard rate) on every line. Peppol refuses S with a 0 % rate (BR-S-05), so an exempt, zero-rated or reverse-charge line needs its category changed in the returned XDocument

Not written: IInvoiceLine.Code, IInvoiceLine.EndDate and a payee bank account.

ViaAdValvas — Peppol Transmission

GatewaySettings

PeppolService

var service = new PeppolService(gatewaySettings, new Regira.Serializing.Newtonsoft.Json.JsonSerializer());   // reads the gateway's answer

try
{
    // returns only once the gateway accepted the document, so result.Success is always true here
    UblDocumentResponse result = await service.Send(ublDocument);
    Console.WriteLine($"Sent. Reference: {result.Reference}");
}
catch (PeppolRequestException ex)    // the gateway answered with a non-2xx status
{
    Console.WriteLine($"Rejected ({ex.ServiceStatusCode}): {ex.ResponseContent}");
}
catch (PeppolResponseException ex)   // it answered, but did not accept the document
{
    Console.WriteLine($"Not sent: {ex.SerializedResponse}");
}

The request always goes out with the declared (PascalCase) property names the gateway expects, nulls included, whatever ISerializer the service is given: that serializer only reads the gateway's answer, so the camelCase Regira.Serializing.Newtonsoft.Json.JsonSerializer works as well as any other.

Every instance sends through a connection pool the package shares, so it can be registered with any lifetime. Never repeat a Send that may have reached the gateway: the document would go out twice.

PeppolRequestException and PeppolResponseException are in Regira.Invoicing.ViaAdValvas.Models.

Requests are sealed with SealUtility.Generate() — an MD5 digest over the token, sender ID, reference ID, date, and the secret key: a plain hash with the secret appended, not an HMAC.

Typical end-to-end flow

// 1. Build the invoice domain model
IInvoice invoice = BuildInvoice(order);

// 2. Convert to UBL XML
XDocument ubl = new UblConverter().Convert(new UblDocumentInput { Invoice = invoice, Supplier = invoice.Supplier });

// 3. Transmit via Peppol
var result = await peppolService.Send(ubl);

// 4. (Optional) also record it in Billit for accounting: Create only. Both Billit sends deliver over Peppol,
//    Send(ids) for an invoice created before and Send(invoice), which creates it first, so either would
//    deliver the invoice a second time
var created = await invoiceManager.Create(invoice);

License

Apache License 2.0 — this package contains no license validation and no runtime limits. See LICENSE. A few companion packages are commercially licensed with a free tier; see the licensing overview.