Signer à distance des PDF et des factures ZUGFeRD (PAdES) avec SignPDFRemote

Membres du SDK

LastError Licensekey

Exemples de code

VB.NET, C#, VB6 / VBScript (COM)

Publié le

2026-10-12

En bref : avec SignPDFRemote, le SDK Aloaha ZUGFeRD (à partir de la version 11.0.0.2) signe un PDF – y compris une facture hybride ZUGFeRD/Factur-X – via le CodeB Remote Signature Service, qui fait partie du logiciel CodeB EUID Wallet. Le SDK envoie le PDF au service en HTTPS et le reçoit en retour avec une signature PAdES (niveau B-B à B-LTA). Aucun certificat local, carte à puce ou lecteur de carte n'est nécessaire ; la signature fonctionne aussi sans surveillance dans des traitements par lots et depuis VB6/VBA via COM.

Quand signer à distance ?

• Serveurs et traitements par lots : les factures sont créées et signées automatiquement, sans qu'un certificat ou une carte doive être installé sur le serveur.
• Gestion centralisée des clés : la clé de signature est détenue par le service de signature, et non sur chaque poste de travail.
• Vérifiabilité à long terme : avec le niveau B-LTA, le PDF contient des horodatages et des données de validation pour une vérification ultérieure.

CodeB EUID Wallet – désormais aussi pour ZUGFeRD

Le CodeB Remote Signature Service fait partie du logiciel CodeB EUID Wallet. L'EUID Wallet est donc désormais aussi utilisée pour ZUGFeRD : le SDK Aloaha ZUGFeRD (SignPDFRemote), la ZUGFeRD GUI, le PDF Viewer et l'outil en ligne de commande zugcmd signent les factures électroniques directement via le service de signature de l'EUID Wallet – sans certificat ni carte à puce sur votre propre ordinateur.

Le logiciel comprend la CodeB Wallet – un portefeuille EUDI selon eIDAS 2.0 pour téléphones Android : données d'identité (PID), permis de conduire mobile, contrôle d'identité et signature de PDF sur le téléphone, avancée (AdES) via le service de signature ou qualifiée (QES) avec l'eID maltaise ou une carte D-Trust par NFC. Toutes les fonctions, la vidéo et l'accès : CodeB Wallet – le portefeuille d'identité européen d'Aloaha et myeuid.app.

Vous n'avez pas besoin de l'application pour signer des factures avec le SDK : SignPDFRemote, la ZUGFeRD GUI, le PDF Viewer et zugcmd s'adressent directement au service de signature, de serveur à serveur.

Prérequis

• SDK Aloaha ZUGFeRD à partir de la version 11.0.0.2 avec une licence valide.
• Un compte utilisateur sur un serveur CodeB de production (Remote Signature Service de la CodeB EUID Wallet) ; pour l'appel de serveur à serveur, la connexion par nom d'utilisateur et mot de passe doit être activée pour le locataire.

Important : https://phone.codeb.io est uniquement le serveur de test de CodeB. Il convient pour des essais mais ne doit pas être utilisé en production. Pour la production, il vous faut votre propre serveur ou locataire CodeB – contactez-nous : info@aloaha.com. Les exemples utilisent donc l'espace réservé https://VOTRE-SERVEUR-CODEB.

• Un accès Internet en HTTPS depuis l'ordinateur appelant vers le service de signature.
• Le PDF fait au maximum 10 Mio et n'est pas chiffré.

VB.NET

Dim LicenseKey As String = "VOTRE-CLE-DE-LICENCE"
Dim alo As New Aloaha_ZUGFeRD.XML(Aloaha_ZUGFeRD.iXML.ZUGFeRDProfile.comfort, False, LicenseKey)

' Arguments : PDF d'entrée, sortie ("" = remplacer l'entrée), votre serveur CodeB, utilisateur, mot de passe,
' niveau PAdES, motif, lieu, contact, écraser, licence, niveau effectif (retour)
Dim level As String = ""
If alo.SignPDFRemote("C:\Rechnungen\RE-2026-0001_zugferd.pdf", "C:\Rechnungen\RE-2026-0001_signiert.pdf", _
                     "https://VOTRE-SERVEUR-CODEB", "benutzer@firma.de", "VOTRE-MOT-DE-PASSE", "B-LTA", _
                     "Validation de la facture", "Musterstadt", "", True, LicenseKey, level) Then
    Console.WriteLine("Signé, niveau : " & level)
Else
    Console.WriteLine("Erreur : " & alo.LastError)
End If

C#

var alo = new Aloaha_ZUGFeRD.XML();
alo.Licensekey = licenseKey;
string level = "";
bool ok = alo.SignPDFRemote(@"C:\Rechnungen\RE-2026-0001_zugferd.pdf", @"C:\Rechnungen\RE-2026-0001_signiert.pdf",
                            "https://VOTRE-SERVEUR-CODEB", "benutzer@firma.de", "VOTRE-MOT-DE-PASSE",
                            "B-T", "Validation de la facture", "Musterstadt", "", true, licenseKey, ref level);
Console.WriteLine(ok ? "Signé, niveau : " + level : "Erreur : " + alo.LastError);

VBA / VB6 (COM)

Dim alo As Object, level As String
Set alo = CreateObject("Aloaha_ZUGFeRD.XML")
alo.Licensekey = "VOTRE-CLE-DE-LICENCE"

If alo.SignPDFRemote("C:\Rechnungen\RE-2026-0001_zugferd.pdf", "C:\Rechnungen\RE-2026-0001_signiert.pdf", _
                     "https://VOTRE-SERVEUR-CODEB", "benutzer@firma.de", "VOTRE-MOT-DE-PASSE", "B-LTA", _
                     "Validation de la facture", "Musterstadt", "", True, "", level) Then
    Debug.Print "Signé, niveau : " & level
Else
    Debug.Print "Erreur : " & alo.LastError
End If

Après la mise à jour vers 11.0.0.2, réenregistrez la bibliothèque de types afin que les clients COM voient la nouvelle fonction.

Sans fichiers : SignPDFRemoteBytes

Pour les services web et les applications de base de données, SignPDFRemoteBytes travaille directement avec des octets et renvoie le PDF signé (ou Nothing en cas d'erreur) :

Dim signiert() As Byte = alo.SignPDFRemoteBytes(pdfBytes, "https://VOTRE-SERVEUR-CODEB", "benutzer@firma.de", "VOTRE-MOT-DE-PASSE", "B-T")
If signiert Is Nothing Then Console.WriteLine(alo.LastError)

Avec un niveau minimal : la classe RemoteSigner (à partir de 11.0.0.3)

Pour les serveurs et le traitement par lots, la version 11.0.0.3 et les suivantes fournissent une classe COM distincte Aloaha_ZUGFeRD.RemoteSigner. Elle signe comme SignPDFRemote (cachet d'entreprise via signDocBasic), mais offre en plus :

• Niveau minimal (MinLevel, par défaut B-B) : si le service fournit un niveau inférieur, la signature est considérée comme échouée et aucun fichier n'est écrit.
• Motif d'une rétrogradation (LevelNote) ainsi que les niveaux demandé et produit (RequestedLevel, EffectiveLevel).
• Nouvel essai en cas de limitation de débit (MaxRetries) : en cas de HTTP 429, la classe attend le délai indiqué par le service et réessaie.
• Paramètres depuis le registre (LoadSettings) pour les serveurs : HKLM\Software\Aloaha\ZUGFeRD\CSC avec BaseURL, User, PasswordProtected (chiffré pour la machine avec Windows DPAPI via ProtectPassword), Level, MinLevel, Reason, Location, Contact, TimeoutSeconds, MaxRetries.

Dim rs As New Aloaha_ZUGFeRD.RemoteSigner
rs.LicenseKey = "VOTRE-CLE-DE-LICENCE"
rs.ServerURL = "https://VOTRE-SERVEUR-CODEB"
rs.UserName = "rechnungssiegel"
rs.Password = "VOTRE-MOT-DE-PASSE"
rs.Level = "B-LTA"
rs.MinLevel = "B-T"          ' pas de signature sans horodatage
rs.Reason = "Validation de la facture"
rs.MaxRetries = 2            ' traitement par lots : en cas de HTTP 429, attendre et réessayer

If rs.SealFile("C:\Rechnungen\RE-2026-0001_zugferd.pdf", "C:\Rechnungen\RE-2026-0001_signiert.pdf") Then
    Console.WriteLine("Signé, niveau : " & rs.EffectiveLevel & " " & rs.LevelNote)
Else
    Console.WriteLine("Erreur : " & rs.LastError)
End If

Depuis VBA/VB6 : Set rs = CreateObject("Aloaha_ZUGFeRD.RemoteSigner"), puis les mêmes propriétés. La classe ne suit pas les redirections – le nom d'utilisateur et le mot de passe ne sont envoyés qu'à l'URL de serveur configurée. Le mot de passe n'est jamais affiché.

Niveaux de signature (PAdES)

Si le service ne peut pas produire momentanément un niveau supérieur (par ex. parce que le service d'horodatage est injoignable), il signe avec le niveau immédiatement inférieur au lieu d'interrompre. Le niveau effectivement produit est renvoyé dans le paramètre EffectiveLevel (par ex. AdES-B-T). Vérifiez-le toujours par rapport à votre exigence minimale – le plus simplement avec RemoteSigner.MinLevel, le réglage niveau minimal de la GUI ou zugcmd -minlevel.

Signer une facture ZUGFeRD : l'ordre des étapes

1. Créer les données de facture et les enregistrer en XML (démarrage rapide VB.NET).
2. Intégrer le XML dans le PDF/A-3 avec MergeXMLIntoPDF.
3. Signer avec SignPDFRemote en dernier. La signature est ajoutée sous forme de mise à jour incrémentielle ; le contenu et le XML intégré restent inchangés. Toute modification ultérieure du PDF invalide la signature.
4. Lors de vos tests, vérifiez le PDF signé avec un contrôleur PDF/A (par ex. veraPDF) et un validateur de factures électroniques. B-LT ajoute un dictionnaire /DSS, B-LTA un horodatage de document – les deux sont autorisés par PAdES.

Gestion des erreurs

Si la fonction renvoie False (ou Nothing), la raison se trouve dans LastError. Le mot de passe n'apparaît jamais dans les messages d'erreur.

Sans programmation : ZUGFeRD GUI, PDF Viewer et zugcmd

La même signature à distance est intégrée à l'Aloaha ZUGFeRD GUI (onglet Sign PDF) et à l'Aloaha ZUGFeRD PDF Viewer (menu Tools > Sign PDF / ZUGFeRD PDF) à partir de la version 11.0.0.2. Saisissez une fois l'URL du serveur, l'utilisateur, le mot de passe et le niveau de signature dans les paramètres de signature ; tester la connexion vérifie les identifiants avec un PDF de test ; pendant la signature, une fenêtre de progression indique que le service travaille. À partir de la version 11.0.0.3, l'outil en ligne de commande zugcmd signe aussi à distance (-remoteurl, -remoteuser, -remotepw, -level) – idéal pour le traitement par lots.

Cadre juridique

Le CodeB Remote Signature Service crée des signatures électroniques avancées (AdES) au sens du règlement eIDAS, et non des signatures qualifiées (QES). Les signatures qualifiées (QES) ne sont créées qu'avec une carte de signature qualifiée comme l'eID maltaise ou la D-Trust Card 5.1 – dans la CodeB Wallet par NFC sur le téléphone. Une signature électronique n'est pas exigée pour les factures électroniques en Allemagne ; elle apporte toutefois une preuve vérifiable de l'authenticité et de l'intégrité du document. Le fait qu'un validateur affiche la signature comme « de confiance » dépend de sa confiance dans le certificat émetteur.

Contexte technique

La fonction utilise le point de terminaison signatures/signDocBasic de l'interface CSC v2 (Cloud Signature Consortium) : un POST HTTPS avec authentification basique, le PDF dans la requête, le PDF signé dans la réponse. En savoir plus sur le service : Signatures à distance chez CodeB.