Configurer des processus de travail pour DocuWare E-Invoicing Service

DocuWare E-Invoicing Service connecte votre entité juridique, par exemple une entreprise, aux réseaux de facturation électronique et aux administrations fiscales propres à chaque pays afin d'envoyer et de recevoir des factures électroniques conformes.

Le Workflow Designer de DocuWare automatise et pilote le traitement des factures électroniques dans DocuWare. Combinés à E-Invoicing Service, les processus de travail gèrent les scénarios suivants :

• Envoi de factures électroniques aux destinataires via le réseau configuré

• Validation des règles techniques et métier pour les factures électroniques

• Traitement des factures électroniques entrantes

Vous configurez et utilisez ces fonctions dans DocuWare Configurations > Collaboration > Workflow Designer. Pour une présentation générale du Workflow Designer, voir l'aide du Workflow Designer.

Prérequis

• Avant de configurer des processus de travail pour E-Invoicing Service, assurez-vous que E-Invoicing Service a été configuré pour l'entité juridique concernée et que l'utilisateur du processus de travail dispose de l'autorisation Utiliser sur la configuration de E-Invoicing Service. Voir Configurer DocuWare E-Invoicing Service.

• ConfigurationName : lors de la configuration de E-Invoicing Service, vous attribuez un nom unique à chaque configuration. Ce nom est disponible en tant que variable de processus ConfigurationName et est utilisé dans l'activité Service Web pour référencer la configuration E-Invoicing Service correcte. Veillez à ce que la valeur corresponde exactement au nom de la configuration tel que défini dans DocuWare Configurations > Integrations > E-Invoicing.

Fonctions de E-Invoicing Service dans le Workflow Designer

Les fonctions de E-Invoicing Service sont appelées depuis un processus de travail DocuWare via l'activité Service Web. E-Invoicing Service est préenregistré sous le nom DocuWare E-Invoicing dans le Workflow Designer ; aucune configuration manuelle de l'URL n'est donc requise.

Pour utiliser une fonction, ajoutez une activité Service Web, sélectionnez DocuWare E-Invoicing sous Service web défini, puis choisissez le point de terminaison souhaité. Configurez les onglets Requête, En-têtes HTTP et Corps de requête HTTP comme décrit ci-dessous pour chaque point de terminaison. Vous pouvez également utiliser Affectation des données pour mapper les valeurs de réponse vers des champs d'index de document, et Codes d'état pour définir le traitement des codes de réponse HTTP.

L'activité Service Web traite un document à la fois. Chaque exécution de processus gère une seule facture électronique et toutes les actions associées à ce document.

Remarque : logique de traitement et de synchronisation

DocuWare E-Invoicing Service traite les factures électroniques de manière asynchrone. Lorsqu'une facture électronique est envoyée au réseau, le service renvoie immédiatement un Task ID, mais la livraison effective s'effectue en arrière-plan. Le processus de travail ne peut pas vérifier le résultat instantanément. Il doit attendre et interroger l'état actuel via un point de terminaison d'état dédié.

Ce comportement asynchrone s'applique également aux messages d'erreur, qui peuvent n'être disponibles qu'après le traitement de la requête par le réseau.

Points de terminaison dans le Workflow Designer pour E-Invoicing

Les points de terminaison suivants sont disponibles sous le service web DocuWare E-Invoicing :

1. Envoyer une facture électronique

Point de terminaison : Post /v1/invoices/

Envoie une facture électronique stockée dans DocuWare au réseau configuré pour livraison au destinataire.

Paramètres du corps de requête HTTP :

Corps de requête HTTP JSON :

{
  "documentId": "Index field DocumentID",
  "fileCabinetId": "System variables File Cabinet GUID",
  "configuration": "ConfigurationName",
  "statusField": "Index field Invoice_Status",
  "validateInvoice": true,
  "networkIdField": "(Optional) Index field Network ID",
  "transportTypeCode": "(Optional) Index field TransportTypeCode"
}

Corps de réponse HTTP JSON (200) :

{
  "taskId": "{id}"
}

La valeur configuration doit correspondre exactement au nom de la configuration tel que défini dans DocuWare Configurations > Integrations > E-Invoicing. Voir Configurer DocuWare E-Invoicing Service.

2. Obtenir une mise à jour du statut

Point de terminaison : Get /v1/tasks/{id}/status

Récupère l'état de traitement actuel d'une facture électronique envoyée au réseau. La valeur {id} dans la route correspond au Task ID renvoyé dans la réponse à une requête HTTP précédente du même processus de travail. Stockez cette valeur dans une variable de processus globale pour la transmettre à ce point de terminaison.

En-têtes HTTP : Accept: application/json (préconfiguré)

Corps de requête HTTP : aucun

Configuration de la route :

Corps de réponse HTTP JSON (200) :

{
  "taskId": "{id}"
}

3. Mettre à jour le statut d'une facture

Point de terminaison : Put /v1/invoices/status/

Met à jour le statut d'une facture électronique reçue stockée dans DocuWare. Utilisez ce point de terminaison pour définir le statut de la facture en fonction d'événements métier tels que la confirmation de paiement ou l'approbation.

Ce point de terminaison s'applique uniquement aux factures reçues, c'est-à-dire aux factures émises par un fournisseur qui ont été reçues et nécessitent une action. Seules les valeurs de statut indiquées ci-dessous sont valides pour ce point de terminaison.

Le statut des factures émises (sortantes) est mis à jour automatiquement via le réseau. Il n'est pas nécessaire de mettre à jour le statut d'une facture envoyée depuis le processus de travail. Vous pouvez utiliser les valeurs de statut des factures émises dans le processus de travail DocuWare pour piloter des processus, mais ne les utilisez pas pour mettre à jour le statut d'une facture au sein du réseau.

Pour plus d'informations et pour une référence des statuts des factures électroniques, voir Comprendre les statuts de DocuWare E-Invoicing Service.

En-têtes HTTP : Accept: application/json + Content-Type: application/json (préconfiguré)

Paramètres du corps de requête HTTP :

Corps de requête HTTP JSON :

{
  "documentId": "Index field DocumentID",
  "fileCabinetId": "System variables File Cabinet GUID",
  "statusValue": "Paid"
}

Corps de réponse HTTP JSON (200) :

{
  "taskId": "{id}"
}

Valeurs de statut inscrites dans statusValue :

4. Créer un rapport de validation

Point de terminaison : Post /v1/invoices/validation/report

Exécute un contrôle des règles techniques et métier sur une facture électronique stockée dans DocuWare et génère un rapport de validation. Le résultat est inscrit dans un champ index dédié et un rapport de validation est joint à la facture électronique.

Cette fonction est disponible uniquement pour l'Allemagne.

En-têtes HTTP : Accept: application/json + Content-Type: application/json (préconfiguré)

Paramètres du corps de requête HTTP :

Corps de requête HTTP JSON :

{
  "documentId": "Index field DocumentID",
  "fileCabinetId": "System variables File Cabinet GUID",
  "configuration": "ConfigurationName",
  "validationStatusField": "Index field Validation_Status"
}

Corps de réponse HTTP JSON (200) :

{
  "taskId": "{id}"
}

Valeurs de résultat de validation inscrites dans validationStatusField :

Gestion des erreurs

Lors du traitement des factures électroniques via DocuWare E-Invoicing Service, des erreurs peuvent survenir à différentes étapes du processus de travail. Avant d'expliquer comment les traiter, il est utile de comprendre où elles sont signalées et quels types d'erreurs peuvent se produire.

Les erreurs sont signalées de l'une des manières suivantes :

• Historique du processus de travail – enregistre l'exécution du processus et toute activité ayant échoué

• Visionneuse de tâches – affiche l'historique de traitement et les détails des erreurs pour les factures électroniques envoyées et reçues. Voir Configurer DocuWare E-Invoicing Service – Historique

• Réponse du service web – renvoie un message d'erreur directement depuis l'API de E-Invoicing Service, qui peut être mappé vers un champ index du document

Types d'erreurs et solutions

Les types d'erreurs suivants peuvent survenir. Les étapes nécessaires à la résolution dépendent de l'erreur et de sa cause :

Configuration et installation

• ConfigurationName invalide ou incohérent

• Aucune licence active ou contrat résilié pour l'entité juridique

• L'utilisateur du processus de travail ne dispose pas de l'autorisation Utiliser sur la configuration E-Invoicing Service

• Mauvais environnement sélectionné (préproduction au lieu de production)

Solution : vérifiez et corrigez la configuration de E-Invoicing Service, puis réessayez.

Certificat et authentification

• Certificat électronique expiré ou invalide (Pologne/KSeF)

• Code PIN du certificat incorrect (Pologne/KSeF)

Solution : renouvelez votre certificat électronique auprès du ministère polonais des Finances et mettez-le à jour dans la configuration de E-Invoicing Service.

• Peppol ID inactif ou non enregistré pour votre compte

Solution : contactez le support DocuWare.

Destinataire

• Peppol ID du destinataire introuvable sur le réseau

Solution : vérifiez les coordonnées du destinataire sur la facture électronique et contactez-le pour confirmer son Peppol ID.

Document

• Document introuvable dans l'armoire

• Envoi en doublon – la facture a déjà été envoyée

• Transition de statut invalide

Solution : vérifiez les données de la facture électronique et assurez-vous que la configuration du processus de travail est correcte.

Réseau et connectivité

• Point d'accès inaccessible

• Réseau Peppol temporairement indisponible

• Service KSeF temporairement indisponible

• Système de l'administration fiscale en maintenance

Solution : consultez l'état sur la page d'état publique du réseau concerné.

Gestion des erreurs par le processus de travail

Lorsqu'une facture électronique est envoyée via le point de terminaison Envoyer une facture électronique, E-Invoicing Service renvoie immédiatement un Task ID. La livraison effective sur le réseau s'effectue en arrière-plan et se termine généralement en 1 à 3 minutes. Le processus de travail doit interroger le résultat via le point de terminaison Obtenir une mise à jour du statut.

Le modèle suivant est recommandé pour gérer les erreurs dans le processus de travail sortant :

1. Envoyer et stocker le Task ID

Après l'appel à Post /v1/invoices/, stockez le Task ID renvoyé dans une variable de processus globale. Ce Task ID est requis pour toutes les vérifications d'état ultérieures.

2. Attendre et interroger le statut

Ajoutez une activité Temporisation de 1 à 3 minutes avant d'appeler Get /v1/tasks/{id}/status. Vérifiez le résultat de la tâche :

• Terminé → vérifiez le champ index du statut de la facture :

  • Statut = sent → la facture électronique a été livrée avec succès, poursuivez le processus de travail

  • Statut = error → la livraison a échoué, passez à la gestion des erreurs

• Retry → E-Invoicing Service tente automatiquement de relivrer. Ajoutez une Temporisation d'environ 40 minutes et interrogez à nouveau via Get /v1/tasks/{id}/status. Le service poursuit ses tentatives pendant 24 heures maximum.

3. Traiter les erreurs

Lorsqu'une erreur définitive est confirmée :

• Utilisez la configuration Affectation des données de l'activité Service Web pour écrire le message d'erreur de la réponse de l'API dans un champ index dédié de l'armoire (par exemple Errors).

• Créez une Tâche de processus pour l'utilisateur responsable afin qu'il examine l'erreur et agisse conformément à la configuration de la tâche.

Information

Le message d'erreur renvoyé par E-Invoicing Service peut être mappé vers un champ index du document à l'aide du chemin JSON $errorMessage dans l'onglet Affectation des données de l'activité Service Web. L'erreur est ainsi visible directement sur le document, sans qu'il soit nécessaire d'accéder à la Visionneuse de tâches.

Recommandations pour la gestion des erreurs

• Incluez un champ index dédié aux erreurs (par exemple Errors de type Mot-clé) dans l'armoire pour capturer les messages d'erreur de E-Invoicing Service.

• Concevez la Tâche de processus pour les cas d'erreur avec des instructions claires sur la marche à suivre.

• Utilisez la Visionneuse de tâches dans DocuWare Configurations > Integrations > E-Invoicing pour consulter l'historique complet de traitement et les messages d'erreur détaillés pour toutes les factures électroniques envoyées et reçues. Dans certains cas, une nouvelle tentative pour la tâche de facture électronique peut être lancée depuis la Visionneuse de tâches.

• Pour les erreurs de réseau ou de connectivité, E-Invoicing Service réessaie automatiquement pendant 24 heures maximum. Évitez tout renvoi manuel pendant cette période afin de prévenir les envois en doublon.

Référence des statuts de facture

Les valeurs de statut suivantes sont utilisées pour les factures électroniques. Certaines valeurs sont définies automatiquement par le processus d'arrière-plan en lien avec le réseau Peppol ou d'autres réseaux tels que KSeF en Pologne.

Facture émise

Facture reçue

Facture simplifiée émise

Versions prises en charge : DocuWare Cloud