Intégration de l'API Lexware Office : bonnes pratiques et points clés

Lexware Office Intégration de l'API Lexware Office : bonnes pratiques et points clés

Lexware Office est l'un des outils de comptabilité les plus utilisés en Allemagne par les petites entreprises et les indépendants. Lancé à l'origine sous le nom de lexoffice et rebaptisé Lexware Office en 2024, il gère la comptabilité de centaines de milliers de PME dans la région DACH. Si votre logiciel s'adresse aux marchés germanophones et que vos clients utilisent Lexware, accéder à leurs données comptables n'est pas un avantage optionnel. C'est une nécessité concurrentielle.

Dans ce guide, nous expliquons comment fonctionne l'API Lexware Office, comment la configurer, les bonnes pratiques à connaître, et comment Chift accélère l'ensemble du processus.

Qu'est-ce que l'API Lexware Office ?

Lexware Office expose une API REST publique unique à l'adresse https://api.lexware.io/v1. L'API utilise JSON dans tous les cas, à l'exception des endpoints de fichiers qui renvoient des réponses binaires ou PDF. Tous les identifiants de ressources sont des UUIDs.

L'API était initialement hébergée sur api.lexoffice.io et l'ancien nom de domaine continue de fonctionner après le rebranding de 2024, mais api.lexware.io est désormais l'URL de base officielle.

Les principales ressources disponibles via l'API sont :

• Contacts (clients et fournisseurs)
• Factures, avoirs et acomptes sur factures (documents de vente sortants)
• Justificatifs (factures d'achat, notes de frais, pièces comptables)
• Paiements et transactions bancaires
• Pièces jointes (PDF uniquement)

Il n'existe pas de v2 ni d'endpoint alternatif. L'API est stable en v1, et c'est la version utilisée par Chift.

Comment configurer l'intégration Lexware Office

La connexion à l'API Lexware s'effectue en quelques étapes simples :

1. L'utilisateur final crée ou se connecte à son compte Lexware Office sur lexware.de ou lexoffice.de. Un abonnement payant est nécessaire pour accéder à l'API publique.
2. L'utilisateur génère une clé API depuis le portail API public de Lexware : rendez-vous sur app.lexware.de, puis allez dans Einstellungen > Öffentliche API.
3. La clé API a une durée de vie infinie et est limitée à une seule organisation. Il n'y a pas de flux de renouvellement. La révocation consiste simplement à supprimer la clé dans le portail.
4. Point important : Lexware exige une approbation avant d'émettre des clés API. Prévoyez environ un mois de délai avant que vos utilisateurs puissent activer l'intégration.
5. Chaque requête API inclut le token dans l'en-tête Authorization avec le préfixe Bearer, accompagné de Accept: application/json.

Chift gère automatiquement le stockage des tokens et l'authentification des requêtes, de sorte que votre équipe n'a pas à s'en occuper pour chaque client.

{{CTA-1}}

Que peut-on construire avec une intégration Lexware Office ?

Connecter Lexware Office via Chift ouvre un large éventail de cas d'usage concrets pour les éditeurs de logiciels ciblant les marchés DACH.

Automatiser les écritures comptables depuis des outils de pré-comptabilité

Les plateformes de gestion des dépenses ou de facturation peuvent pousser des données financières structurées directement dans Lexware Office sous forme de justificatifs ou de factures, en éliminant les ressaisies manuelles et en tenant la comptabilité à jour sans effort supplémentaire pour l'utilisateur final.

Synchroniser les données clients et fournisseurs

Gardez les contacts cohérents entre votre CRM ou ERP et Lexware Office. Toute mise à jour effectuée dans votre produit peut s'y répercuter automatiquement, réduisant les doublons et la dérive des données.

Alimenter les prévisions de trésorerie avec des données AP/AR réelles

Les outils de gestion de trésorerie peuvent extraire les créances et dettes en cours depuis Lexware Office pour construire des projections précises. Des données en temps réel permettent de meilleures décisions pour les PME que vous servez.

Faciliter le crédit digital grâce à des données financières à jour

Les plateformes de prêt peuvent récupérer l'ancienneté des factures, l'historique des paiements et les soldes de compte depuis Lexware Office via l'API Comptabilité Unifiée de Chift, afin d'évaluer les risques et d'automatiser les décisions de crédit, sans demander aux clients d'exporter des tableurs manuellement.

Consultez les études de cas de Chift pour plus d'exemples concrets.

Bonnes pratiques pour l'API Lexware Office

L'API Lexware présente quelques spécificités qu'il vaut mieux comprendre avant de se lancer. Les maîtriser dès le départ vous évitera beaucoup de débogage.

Respecter la limite de débit

Lexware impose une limite stricte de 2 requêtes par seconde par clé API. C'est l'une des limites les plus contraignantes parmi les API comptables majeures. N'effectuez pas d'appels en parallèle sur la même connexion. Sérialisez vos requêtes et mettez en place une logique de réessai automatique pour les réponses HTTP 429. Notez que Lexware n'inclut pas d'en-tête Retry-After dans ses réponses 429, donc votre client doit gérer le backoff lui-même.

Toujours lire avant d'écrire

Chaque ressource modifiable dans Lexware Office porte un entier version. Les requêtes PUT doivent inclure le numéro de version courant, sans quoi le serveur rejette la mise à jour avec un HTTP 409. C'est un mécanisme de verrouillage optimiste. Récupérez toujours l'état actuel d'une ressource avant de tenter de la modifier.

Comprendre les deux modèles de documents

Lexware Office distingue clairement deux types de documents financiers, qui ne sont pas interchangeables :

• /vouchers couvre les factures d'achat, les notes de frais et les pièces comptables. Vous pouvez y joindre des fichiers PDF, mais Lexware ne peut pas générer de PDF à partir de justificatifs.
• /invoices, /credit-notes et /down-payment-invoices sont des documents de vente sortants avec mise en page complète et génération de PDF.

Router un document vers le mauvais endpoint provoquera des erreurs. Choisissez le bon modèle pour chaque cas d'usage dès le départ.

Utiliser correctement le cycle de vie brouillon/ouvert

Créez d'abord les documents en brouillon. Les brouillons sont librement modifiables. Passez-les au statut open uniquement lorsqu'ils sont prêts, en ajoutant ?finalize=true comme paramètre de requête. Une fois finalisés, les factures et avoirs ne peuvent plus être modifiés. Pour corriger une facture finalisée, il faut l'annuler et en créer une nouvelle.

Gérer les pièces jointes en deux étapes

Joindre un fichier à un justificatif nécessite deux étapes : d'abord envoyer le fichier via /files en multipart pour obtenir un ID de fichier, puis référencer cet ID lors de la création ou mise à jour du justificatif. Seuls les PDFs sont acceptés comme type de pièce jointe.

Analyser les erreurs via i18nKey

Lexware utilise le code HTTP 406 pour les erreurs de validation métier (et non 400 ou 422), ce qui peut surprendre les développeurs. Les erreurs retournent un corps structuré avec une IssueList. Analysez le champ i18nKey, qui est stable et lisible par les machines, plutôt que de vous fier aux champs de message lisibles par l'humain qui peuvent changer.

Paginer correctement les endpoints de liste

Les endpoints de liste utilisent page (indexé à partir de zéro) et size (maximum 250 par page). Les réponses incluent totalPages et totalElements. Itérez jusqu'à ce que votre index de page atteigne totalPages - 1.

Connecter Lexware Office via Chift

Construire et maintenir une intégration directement contre l'API Lexware prend du temps que votre équipe préférerait consacrer ailleurs. Il faut gérer la limitation de débit, le verrouillage optimiste, les deux modèles de documents, le délai d'approbation, l'analyse des erreurs et la pagination, avant même d'avoir écrit une seule ligne de code fonctionnel.

L'API Comptabilité Unifiée de Chift vous donne accès à Lexware Office et à une bibliothèque croissante de connecteurs comptables via une seule intégration. Nous gérons la maintenance de l'API, l'authentification et le mapping des données à votre place. Quand Lexware met à jour son API ou modifie son comportement, nous adaptons notre connecteur. Vous restez concentré sur votre produit.

Pour les éditeurs de logiciels ciblant les marchés DACH, Lexware Office est l'une des connexions comptables les plus importantes à offrir à vos clients. Avec Chift, vous pouvez l'activer en un clic une fois votre intégration initiale en place.

Réservez une démo pour voir à quel point c'est simple.

API Lexware Office : questions fréquentes

Quelle méthode d'authentification utilise l'API Lexware Office ?

‍Lexware utilise une clé API statique transmise comme token Bearer dans l'en-tête Authorization. Les clés ont une durée de vie infinie et sont limitées à une organisation. Il n'y a pas de flux OAuth ni de mécanisme de renouvellement de token.

Quelle est la limite de débit de l'API Lexware ?

‍Lexware impose une limite stricte de 2 requêtes par seconde par clé API. C'est la contrainte principale. Il n'y a pas de quota par minute ou par heure au-delà de cette limite par seconde.

Combien de temps faut-il pour obtenir une clé API Lexware ?

‍Lexware exige une approbation avant de délivrer des clés API aux intégrateurs. Prévoyez environ un mois de délai. Tenez-en compte dans la planification de votre projet.

Quelle est la différence entre les justificatifs et les factures dans Lexware Office ?

‍Les justificatifs sont destinés aux documents entrants comme les factures d'achat et les notes de frais. Les factures, avoirs et acomptes sur factures sont des documents de vente sortants. Ils utilisent des endpoints distincts et ne sont pas interchangeables. Seuls les documents de vente peuvent être générés en PDF par Lexware.

L'API Lexware supporte-t-elle la multi-location ?

‍Chaque clé API est limitée à une seule organisation. Pour intégrer plusieurs clients, chaque client génère sa propre clé API, qui est stockée et utilisée séparément par connexion.