Intégrations API : PDF, Dinaco, Microsoft Graph, modèles et fichiers

Configurer les intégrations natives et les plugins

Pour la configuration, commencez par la fonction client respective : Bexio est activé via le Plugin Manager et connecté sous Intégrations → Comptabilité. Les Automatisations disposent d'une zone de règles dédiée. Dans la section Intégrations, vous trouverez également DINACO et les systèmes d'accès.

Utilisez les liens techniques suivants pour contextualiser. Les étapes concrètes se trouvent sur les sous-pages liées. Un compte e-mail pour l'envoi Microsoft, une connexion SAML et un objectif de suivi Microsoft Ads sont des connexions distinctes avec leurs propres paramètres.

Outre l’API publique, edoobox possède plusieurs domaines d’intégration. Ils relient les fonctions visibles, comme la génération de PDF, le contrôle d’entrée Dinaco, Microsoft Graph, les modèles, le stockage de fichiers, les exports, SAML et les requêtes auxiliaires externes, aux données de votre compte.

Cette page est un guide pour les administrateurs et les interlocuteurs techniques. Elle ne remplace pas les guides détaillés, mais indique quelles fonctions sont liées sur le plan métier et où vous pouvez continuer à lire lors de la configuration ou du dépannage.

Gestion des accès API dans edoobox avec les clés existantes et le choix des droits.

AGestion des accès APIBAvertissement de sécuritéCÉtat des clés et des droits

Aperçu et délimitation

La API publique convient aux clients externes, aux exports individuels et aux intégrations propres. Les couches d'intégration internes sont utilisées par edoobox lorsque des documents sont créés, des fichiers lus, des modèles rendus, des tickets synchronisés ou des services externes sollicités.

Dinaco : envoie les données de tickets, de sections, d'autorisations et de fusion au contrôle d'accès.
PDF et courrier : rend les PDF, génère des références RF, intègre les données de paiement et envoie des lettres.
Microsoft Graph : envoie des e-mails via un compte Microsoft connecté.
Modèles : traite les modèles d'e-mail et de PDF avec des variables de remplacement, des conditions et des boucles.
Fichiers et exports : gère le stockage, les URL signées et les exports de tableaux.
SAML et requêtes auxiliaires : prend en charge SSO, les données auxiliaires IP et les vérifications de TVA.

Billetterie Dinaco et données d'accès

L'intégration Dinaco relie edoobox à un contrôle d'accès externe. Les connexions d'événements, les sections, les autorisations et les tickets veillent à ce que les données de réservation puissent être traitées dans la solution d'accès.

Sur le plan métier, l'identifiant de client, le secret, l'identifiant d'événement, la section, l'autorisation, le code-barres, les informations de contact et le statut du ticket sont importants. Les autorisations contiennent des critères, un début, une fin et un lien de domaine ; les sections décrivent les zones d'accès. Les tickets peuvent, selon le processus, être valides, nouveaux ou annulés ou bloqués ; vérifiez donc toujours la réservation, le statut du ticket et la synchronisation Dinaco ensemble.

Les jetons d'accès ne sont pas recréés à chaque clic, mais sont mis en cache pendant une courte période. Si les données d'accès ont été modifiées, une erreur peut donc rester visible pendant un court moment. Testez après les modifications avec une seule réservation ou un seul ticket.

Si Dinaco ne se synchronise pas comme prévu, vérifiez d'abord les données d'accès, la connexion d'événement, la période de synchronisation, les sections, la synchronisation manuelle et si les tickets concernés sont du tout valides et pertinents publiquement. L'utilisation dans l'interface se trouve sous Intégration Dinaco et Billetterie, scan d'accès, Dinaco et contrôle de présence.

Exemple d'application : synchroniser manuellement un événement Dinaco

Après le dépôt de l'identifiant de client et du secret, l'administration crée une connexion d'événement. Si les sections ou les données d'accès changent à court terme, elle ouvre la synchronisation pour cet événement et lance la réconciliation manuellement, au lieu d'attendre la prochaine exécution en arrière-plan.

PDF, factures, références QR/RF et envoi postal

Les sorties PDF touchent les modèles, les polices, les images, les pièces jointes, les données de facturation, les codes-barres, les références QR/RF, les données ZUGFeRD, les signatures et, le cas échéant, l'envoi postal. Par conséquent, un problème PDF apparent peut avoir diverses causes : modèle, variable de remplacement, taille de l'image, stockage de fichiers, langue, facture ou signature.

edoobox peut utiliser des modèles PDF comme arrière-plan, rendre du HTML à des positions fixes, intégrer des images et, selon la procédure, générer des factures, des billets, des PDF de réservation, des factures d’annulation, des relances ou des confirmations. Les références RF des paiements sont normalisées et vérifiées ; les factures QR nécessitent aussi des données correctes de facturation et de paiement.

Pour les modèles PDF, la qualité et la taille des images sont importantes. Les images sont intégrées dans le PDF ; les images vides, inaccessibles ou trop grandes peuvent manquer dans le PDF. Utilisez donc des images de modèle propres, vérifiez les logos et les arrière-plans dans l'aperçu PDF et testez les caractères spéciaux multilingues.

edoobox prend en charge différentes polices et jeux de caractères internationaux afin que les langues avec des caractères spéciaux, des caractères asiatiques ou des symboles puissent être mieux représentés dans les PDF. Si un PDF a une apparence incorrecte, vérifiez en plus de la variable de remplacement la langue, la police, le PDF d'arrière-plan et les images intégrées.

Lors de l'envoi postal, un PDF terminé est transmis à un service d'envoi, y est traité et signalé ultérieurement avec des informations de statut. Consultez à ce sujet Pièces jointes PDF et modèles propres, Factures QR et Envoi postal de la facture.

Exemple d'application : envoyer une facture en PDF et par courrier

Une facture est rendue en PDF, les images sont intégrées et une référence RF est générée. Si l'envoi postal est actif, edoobox transmet le contenu du PDF au service d'envoi, stocke l'identifiant d'envoi externe et met à jour ultérieurement le statut d'envoi.

Microsoft Graph : envoi d’e-mails

Microsoft Graph sert à envoyer des e-mails via un compte Microsoft connecté. Vérifiez la connexion, l’expéditeur prévu et les autorisations d’envoi accordées. Pour chaque message, contrôlez également les destinataires, CC, Reply-To, le contenu HTML et les pièces jointes.

Un message accepté par Microsoft signifie que Graph a accepté la demande d'envoi. Si le message est livré au destinataire ou rejeté ultérieurement, vérifiez toujours via la boîte d'envoi, le message d'erreur, l'avis du fournisseur et, le cas échéant, la boîte aux lettres Microsoft.

Les réponses de Graph sont différenciées sur le plan métier : message accepté, erreur temporaire, erreur de fournisseur ou d'authentification et problèmes de charge utile permanents. Cette classification est importante pour la Boîte d'envoi et les nouvelles tentatives de livraison.

Configurez la connexion selon Connecter un compte Microsoft pour l’envoi d’e-mails. Testez ensuite un seul message avec l’expéditeur prévu et contrôlez la boîte d’envoi ainsi que sa réception. Une connexion réussie ne confirme pas à elle seule un envoi réussi.

Rendu des modèles et variables de remplacement

Les modèles pour e-mails et PDF sont traités en plusieurs étapes. D'abord, les boucles sur les données répétables sont traitées, ensuite les conditions sont vérifiées et enfin les variables de remplacement sont substituées. Cela permet des modèles complexes, par exemple des listes de prestations réservées, des notes conditionnelles, des codes-barres de tickets ou des textes liés à des promotions.

Les modèles PDF et e-mail dépendent en outre de l'abonnement, des langues activées, des arrière-plans PDF propres, des noms de fichiers par langue et des données disponibles. Chaque modèle ne connaît pas toutes les variables de remplacement ; une variable de remplacement peut fonctionner dans une facture, mais rester vide dans un e-mail de rappel.

L'ordre est important : une variable de remplacement dans une condition ou une boucle doit correspondre aux données disponibles pour ce modèle. Vérifiez donc Toutes les variables de remplacement pour e-mails et PDF et Modèles d'e-mail avec IF et EACH.

Exemple d'application : modèle avec condition et boucle

Un modèle d'e-mail contient une liste de prestations réservées et une note de réduction uniquement pour certaines balises. edoobox rend d'abord chaque prestation, vérifie ensuite la condition et remplace enfin les noms, la date et d'autres variables de remplacement.

Fichiers, exports, SAML et requêtes auxiliaires

Les fichiers peuvent se trouver dans différents stockages selon l'environnement. edoobox lit les objets, génère des URL signées pour le téléversement ou le téléchargement et supprime les fichiers si le processus le prévoit. Pour les administrateurs, cela est visible via les documents, les modèles, les téléversements ou le Secure File Manager.

Les URL signées sont limitées dans le temps. Si un lien de téléchargement expire ou si un téléversement ne fonctionne plus, rechargez le fichier depuis l'interface au lieu de transmettre de vieux liens. Cela est particulièrement important pour les supports de cours protégés, les pièces jointes d'e-mail et les exports temporaires.

Les exports de tableaux peuvent générer CSV, XLSX, ODS ou d'autres formats. Pour de très grands volumes de données, un CSV peut être plus judicieux qu'un fichier Excel volumineux ; les grands exports peuvent être traités différemment automatiquement. Les bases métier se trouvent sous Tableaux et possibilités d'export.

SAML prend en charge les flux SSO avec métadonnées, formats NameID, plages de connexion et réponses IdP. Les requêtes auxiliaires externes peuvent fournir des informations IP ou de TVA et sont parfois mises en cache. La configuration de SAML se trouve sous Activer le Single Sign On via SAML dans edoobox.

API publique ou intégration interne ?

Si un système externe doit lire ou écrire des données, utilisez l’API publique. Créez des clés API avec des droits clairement définis et documentez l’intégration qui utilise chacune d’elles.

Les chemins d'intégration internes ne sont pas conçus comme une interface stable pour les systèmes clients. Ils expliquent cependant pourquoi une fonction visible a plusieurs prérequis. Un exemple : une facture envoyée via Microsoft peut toucher simultanément au modèle d'e-mail, au rendu PDF, à la pièce jointe de fichier, au jeton Microsoft et à la boîte d'envoi.

Pour les projets externes, les interlocuteurs techniques doivent donc toujours vérifier en premier lieu : existe-t-il une fonction API documentée ? Existe-t-il une intégration edoobox existante ? Ou s'agit-il d'une fonction interne qui ne doit pas être sollicitée directement ?

Relier vos propres données d'offre et les destinataires d'événements

Un site web d'offres API lit les données offer, les ressources text séparées et les liens de partage fournis par edoobox. Un cache propre appartient à l'intégration du site web ; ce n'est pas une réservation de place. Le processus Site web d'offres propre et planificateur de cours décrit les listes complètes, les versions linguistiques et les données obsolètes.

Pour les images, utilisez les valeurs image.url et image.url300 réellement renvoyées. Les images d'aperçu, les fichiers de sortie publics et les extraits pour les réseaux sociaux sont traités différemment selon le chemin d'image. Un suffixe de taille ajouté manuellement ne constitue donc pas un contrat API universel. Les URL d'image et les proportions d'origine expliquent l'étendue documentée.

Des événements appropriés peuvent déclencher une récupération ciblée. Le guide Webhook explique la configuration via /v2/webhook avec le droit requis, l'adresse cible, les sujets et la vérification HMAC. Les webhooks de fournisseurs de paiement, de scanners et d'intégration générale sont des connexions distinctes. La configuration n'implique pas une livraison garantie de chaque changement de statut métier.

Séparer proprement la configuration et les tests

Ne testez pas les intégrations directement avec des actions de masse en production. Utilisez une offre de test, une réservation de test, une facture de test ou une petite sélection d'enregistrements. Vous détecterez ainsi les erreurs sans affecter de nombreux participants, factures ou e-mails.

Pour Microsoft, testez d'abord l'authentification et un e-mail unique. Pour PDF, vérifiez un modèle avec de vraies données de démonstration. Pour Dinaco, testez une connexion d'événement et un ticket. Pour SAML, testez une seule personne administratrice avec des attributs définis.

Règles d'exploitation, types d'erreurs et caches

Les intégrations fonctionnent avec différents caches et règles de répétition. Les jetons Dinaco, les modèles PDF, les requêtes auxiliaires, les jetons d'envoi postal ou les jetons OAuth externes ne sont pas récupérés à nouveau à chaque clic. Par conséquent, une modification peut apparaître avec un léger retard.

Les erreurs sont visibles différemment selon l'intégration : Dinaco signale des erreurs de synchronisation, Microsoft Graph fournit des erreurs HTTP et JSON, le rendu PDF peut échouer sur des images ou des modèles, l'envoi postal peut fournir des messages de statut externes, SAML peut bloquer sur des attributs ou des métadonnées.

Lors du dépannage, indiquez toujours le chemin concret : envoi de messagerie, rendu PDF, envoi postal, stockage de fichiers, connexion SAML, accès API, requête auxiliaire ou billetterie Dinaco. Plus le chemin est précis, plus le support ou la technique peut vérifier rapidement les journaux et les messages de statut appropriés.

Liste de contrôle avant la configuration

Quelle fonction métier doit être connectée ?
Quels droits, clés, fournisseurs ou comptes sont nécessaires ?
Les modèles, variables de remplacement et langues sont-ils entièrement entretenus ?
Qui est responsable des systèmes externes tels que Microsoft, Dinaco, IdP SAML ou l'envoi postal ?
Comment tester : offre de démonstration, réservation de test, e-mail de test, ticket de test ou facture de test ?
De quels journaux, pièces justificatives ou messages de statut le support a-t-il besoin en cas d’erreur ?

Guides associés

Suivi côté serveur V2

La nouvelle intégration Tracking V2 gère Google Analytics, Microsoft Ads et ChatGPT / OpenAI Ads pour chaque compte. Elle complète les événements du navigateur par l’envoi côté serveur des achats, des paiements et des opérations d’annulation et de remboursement. En cas d’intégration dans une page, le contexte actuel du site et le consentement sont nécessaires ; consultez iFrame et consentement.