ADDEV Framework - Service Peppol Billit

Ce document décrit l'utilisation du service Peppol Billit intégré dans le framework ADDEV pour l'envoi et la gestion de documents électroniques.

Vue d'ensemble

Le service Billit permet l'intégration avec l'API Peppol de Billit pour :

• L'envoi de factures électroniques avec pièces jointes PDF
• La confirmation d'envoi des factures
• La récupération du statut des commandes
• La gestion complète du cycle de vie des documents Peppol

Configuration

Variables d'environnement requises

# Endpoint API Billit (sandbox ou production)
BILLIT_API_ENDPOINT=https://api.sandbox.billit.be

# Clé API Billit
BILLIT_API_KEY=votre-cle-api

# ID de l'entreprise Billit
BILLIT_COMPANY_ID=votre-company-id

Utilisation de base

Envoi d'une facture

using ADDEV.Framework.Backend.Services.Peppol;

// Création d'une facture
var invoice = new BillitOrder
{
    OrderNumber = "INV-2025-001",
    OrderDate = DateTime.UtcNow,
    ExpiryDate = DateTime.UtcNow.AddDays(30),
    Customer = new BillitCustomer
    {
        Name = "Client SA",
        VATNumber = "BE0123456789",
        Addresses = new List<BillitAddress>
        {
            new BillitAddress
            {
                AddressType = BillitAddressType.InvoiceAddress,
                Street = "Rue de la Clientèle",
                StreetNumber = "123",
                Zipcode = "1000",
                City = "Bruxelles",
                CountryCode = "BE"
            }
        }
    },
    Orderlines = new List<BillitOrderLine>
    {
        new BillitOrderLine
        {
            Description = "Service de consultation",
            Quantity = 1,
            UnitPriceExcl = 500.00m,
            VATPercentage = 21.0m
        }
    },
    OrderPDF = new BillitOrderPDF
    {
        FileName = "facture-2025-001.pdf",
        FileContent = Convert.ToBase64String(pdfBytes)
    }
};

// Envoi de la facture
var response = await BillitService.SendInvoice(invoice);
Console.WriteLine($"Facture envoyée avec l'ID: {response.OrderId}");

Confirmation d'envoi

// Confirmation d'envoi (passage du statut "ToSend" à "Sent")
bool confirmed = await BillitService.ConfirmSendInvoice(response.OrderId);
if (confirmed)
{
    Console.WriteLine("Facture confirmée pour envoi");
}

Récupération du statut

// Récupération des détails complets de la commande
var details = await BillitService.GetOrderStatus(response.OrderId);
Console.WriteLine($"Statut actuel: {details.Status}");

Classes principales

BillitOrder

Représente une commande/facture à envoyer.

Propriétés principales :

• OrderNumber : Numéro de commande (requis)
• OrderDate : Date de commande (requis)
• ExpiryDate : Date d'échéance (requis)
• Customer : Informations client (requis)
• Orderlines : Lignes de commande (au moins une requise)
• OrderPDF : Pièce jointe PDF (optionnel)

BillitCustomer

Informations sur le client destinataire.

Propriétés principales :

• Name : Nom du client (requis)
• VATNumber : Numéro TVA (requis)
• Addresses : Liste d'adresses (au moins une requise)

BillitOrderLine

Représente une ligne de commande.

Propriétés principales :

• Description : Description de l'article (requis)
• Quantity : Quantité (doit être > 0)
• UnitPriceExcl : Prix unitaire HTVA (ne peut pas être négatif)
• VATPercentage : Pourcentage TVA (0-100%)

BillitOrderResponse

Réponse retournée lors de l'envoi d'une facture.

Propriétés :

• OrderId : ID unique de la commande
• Status : Statut initial de la commande
• CreatedAt : Date de création

BillitOrderDetails

Détails complets d'une commande existante.

Propriétés principales :

• OrderId : ID de la commande
• Status : Statut actuel
• OrderType : Type de commande
• OrderDirection : Direction (Income/Cost)
• Toutes les propriétés de BillitOrder

Gestion des erreurs

Le service utilise des exceptions spécialisées pour différents types d'erreurs :

BillitValidationException

Lancée lors d'erreurs de validation des données d'entrée.

try
{
    var response = await BillitService.SendInvoice(invalidInvoice);
}
catch (BillitValidationException ex)
{
    Console.WriteLine($"Erreur de validation pour {ex.FieldName}: {ex.Message}");
}

BillitApiException

Lancée lors d'erreurs retournées par l'API Billit.

try
{
    var details = await BillitService.GetOrderStatus(orderId);
}
catch (BillitApiException ex)
{
    Console.WriteLine($"Erreur API {ex.StatusCode}: {ex.Message}");
    Console.WriteLine($"Détails: {ex.ErrorDetails}");
}

BillitException

Exception générique pour les autres erreurs.

Statuts de commande

Les commandes peuvent avoir différents statuts :

• Draft : Brouillon
• ToSend : Prêt à envoyer
• Sent : Envoyé
• ToPay : À payer
• ToInvoice : À facturer
• Invoiced : Facturé
• Paid : Payé
• Refused : Refusé
• Canceled : Annulé

Bonnes pratiques

1. Validation des données

Validez toujours les données avant envoi :

// Le service valide automatiquement, mais vous pouvez pré-valider
try
{
    BillitValidator.ValidateInvoice(invoice);
    var response = await BillitService.SendInvoice(invoice);
}
catch (BillitValidationException ex)
{
    // Gérer l'erreur de validation
}

2. Gestion des PDF

• Le contenu PDF doit être encodé en base64
• Le nom du fichier doit inclure l'extension .pdf
• Vérifiez que le fichier n'est pas corrompu avant encodage

3. Gestion des retry

Le service implémente automatiquement des retry sur les erreurs temporaires (5xx, timeouts). Pas besoin de les implémenter côté client.

4. Logging

Les erreurs sont automatiquement loggées. Pour un logging personnalisé :

try
{
    var response = await BillitService.SendInvoice(invoice);
}
catch (Exception ex)
{
    logger.LogError(ex, "Erreur lors de l'envoi de facture {OrderNumber}", invoice.OrderNumber);
    throw;
}

Exemple complet

using ADDEV.Framework.Backend.Services.Peppol;

public class InvoiceService
{
    public async Task<string> SendInvoiceAsync(InvoiceData data)
    {
        // Construction de l'objet BillitOrder
        var billitOrder = new BillitOrder
        {
            OrderNumber = data.InvoiceNumber,
            OrderDate = data.InvoiceDate,
            ExpiryDate = data.DueDate,
            Customer = MapToBillitCustomer(data.Customer),
            Orderlines = data.Lines.Select(MapToBillitOrderLine).ToList(),
            OrderPDF = new BillitOrderPDF
            {
                FileName = $"{data.InvoiceNumber}.pdf",
                FileContent = Convert.ToBase64String(data.PdfBytes)
            }
        };

        // Envoi
        var response = await BillitService.SendInvoice(billitOrder);

        // Confirmation d'envoi
        await BillitService.ConfirmSendInvoice(response.OrderId);

        return response.OrderId;
    }

    private BillitCustomer MapToBillitCustomer(CustomerData customer)
    {
        return new BillitCustomer
        {
            Name = customer.Name,
            VATNumber = customer.VatNumber,
            Addresses = new List<BillitAddress>
            {
                new BillitAddress
                {
                    AddressType = BillitAddressType.InvoiceAddress,
                    Street = customer.Address.Street,
                    StreetNumber = customer.Address.Number,
                    Zipcode = customer.Address.ZipCode,
                    City = customer.Address.City,
                    CountryCode = customer.Address.CountryCode
                }
            }
        };
    }

    private BillitOrderLine MapToBillitOrderLine(InvoiceLineData line)
    {
        return new BillitOrderLine
        {
            Description = line.Description,
            Quantity = line.Quantity,
            UnitPriceExcl = line.UnitPrice,
            VATPercentage = line.VatRate
        };
    }
}

Support et documentation

Pour plus d'informations :

• Documentation API Billit
• Spécifications Peppol

Versions

• v2.4.7 : Implémentation initiale du service Billit avec envoi, confirmation et récupération de statut
• Support complet de la validation des données et gestion d'erreurs robuste

Dernière mise à jour : 2025-10-19