Comment réussir votre intégration API sevdesk

sevdesk est l'un des logiciels de comptabilité les plus utilisés en Allemagne par les petites et moyennes entreprises. Si votre produit cible le marché DACH, vous allez forcément le croiser. L'intégrer vous ouvre un accès direct aux données financières de centaines de milliers de PME germanophones.

En connectant l'API sevdesk à votre produit, vous pouvez :

• Synchroniser automatiquement les contacts, factures et justificatifs
• Pousser des données de pré-comptabilité pour éliminer les saisies manuelles de vos utilisateurs
• Récupérer les créances et dettes ouvertes pour alimenter vos prévisions de trésorerie
• Accéder à des données financières conformes et compatibles DATEV, directement à la source

Dans ce guide, nous vous expliquons comment fonctionne l'API sevdesk, comment configurer l'intégration, les bonnes pratiques à suivre, et comment Chift simplifie l'ensemble du processus grâce à une API Comptabilité Unifiée.

Qu'est-ce que l'API sevdesk ?

L'API sevdesk est une API REST qui permet aux applications externes d'accéder de manière programmatique aux données comptables stockées dans un compte sevdesk. Elle couvre un large éventail de ressources : contacts, factures, avoirs, justificatifs, comptes bancaires et données de référence.

Aperçu technique

• Type d'API : REST
• URL de base : https://my.sevdesk.de/api/v1/
• Format des données : JSON
• Méthodes HTTP supportées : GET, POST, PUT, DELETE

Une seule API, une seule version

sevdesk expose une unique API REST à /api/v1. Il n'existe pas d'endpoint v2, ce qui simplifie les choses : une seule surface à intégrer, un seul modèle de données à comprendre.

sevdesk est également compatible DATEV, ce qui est essentiel pour tout produit devant alimenter l'écosystème comptable allemand. C'est une condition incontournable pour les logiciels qui servent des experts-comptables DACH ou leurs clients PME.

Connectez-vous à sevdesk et à tous les grands logiciels comptables en une seule intégration. Découvrez comment les API Unifiées de Chift aident les éditeurs de logiciels à ajouter des dizaines de connecteurs en un seul go.

{{CTA-1}}

Que pouvez-vous construire avec une intégration sevdesk ?

L'intégration sevdesk ouvre un large éventail de cas d'usage pour les éditeurs de logiciels financiers et de gestion d'entreprise. Voici les plus courants.

Automatisation des écritures pré-comptables

Permettez à vos utilisateurs de pousser des données financières structurées directement dans sevdesk, en générant automatiquement des écritures comptables. Les outils de gestion des dépenses, les plateformes de paiement et les solutions de facturation utilisent ce mécanisme pour supprimer les tâches manuelles répétitives, côté utilisateur comme côté comptable.

Prévision de trésorerie

Les logiciels de gestion de trésorerie peuvent récupérer les factures clients et fournisseurs ouvertes depuis sevdesk pour construire des projections précises et à jour. Avec un accès aux données AR/AP en temps réel, vos utilisateurs anticipent leurs flux de trésorerie plutôt que de s'appuyer sur des exports statiques.

Évaluation de l'éligibilité au financement pour les plateformes de prêt B2B

Les plateformes de crédit digital peuvent exploiter les données financières structurées de sevdesk, notamment les factures, l'historique des paiements et les soldes de comptes, pour réaliser des vérifications d'éligibilité et du scoring en quasi temps réel. Ce qui prenait plusieurs jours peut se réduire à quelques secondes.

Pour plus d'exemples d'intégrations concrètes, consultez nos études de cas Chift.

Comment démarrer avec l'API sevdesk ?

Sevdesk utilise une authentification par token statique, ce qui rend la configuration simple. Il n'y a pas de flux OAuth, pas de processus d'approbation. Voici les étapes :

1. L'utilisateur crée (ou se connecte à) un compte sevdesk sur sevdesk.de. À noter : sevdesk nécessite un abonnement payant. Un essai de 14 jours est disponible, mais il n'existe pas de plan gratuit.
2. L'utilisateur génère un token API depuis son compte : Paramètres → Utilisateur → Token API.
3. Ce token est renseigné dans votre intégration en tant que api_key.
4. Chaque requête API envoie le token dans le header Authorization, brut, sans préfixe Bearer :

Authorization: b7794de0085f5cd00560f160f290af38

Un point important à communiquer à vos utilisateurs : le token a une durée de vie infinie mais est lié au compte utilisateur spécifique. Si cet utilisateur est supprimé, le token est définitivement perdu et ne peut pas être récupéré. Il n'existe pas de flux de rafraîchissement. Pour renouveler les identifiants, l'utilisateur régénère son token dans l'interface, ce qui invalide immédiatement l'ancien.

Chift gère la gestion des identifiants et la configuration de la connexion, afin que votre équipe puisse se concentrer sur l'intégration elle-même.

Comment fonctionne l'authentification de l'API sevdesk ?

L'authentification dans sevdesk diffère de la plupart des API modernes sur un point clé : elle n'utilise pas OAuth. Elle repose sur un token statique unique transmis dans chaque header de requête.

Ce que cela signifie concrètement :

• Aucune expiration de token à gérer
• Aucun flux de rafraîchissement à implémenter
• Aucun scope à configurer

Le token est lié à l'utilisateur qui l'a créé. Si vous recevez une réponse HTTP 401, le token a été invalidé ou révoqué. Ne relancez pas la requête. Affichez une erreur d'authentification explicite et invitez l'utilisateur à renseigner son nouveau token.

Les pièces jointes de justificatifs suivent un flux en deux étapes. D'abord, POST Voucher/Factory/uploadTempFile (en multipart form data) retourne un hash de nom de fichier interne. Ce hash est ensuite passé à POST Voucher/Factory/saveVoucher pour associer le PDF au justificatif. Les deux étapes doivent se compléter avec succès pour que la pièce jointe soit enregistrée.

Bonnes pratiques pour intégrer l'API sevdesk

1. Lisez toujours le corps JSON de l'erreur, pas le code HTTP

C'est la particularité la plus importante de l'API sevdesk : elle retourne une erreur HTTP 500 pour des erreurs qui sont sémantiquement des problèmes de niveau 400. Le code de statut seul ne vous dira pas ce qui s'est passé.

Lisez toujours le corps de la réponse JSON et consultez {"error": {"message": "..."}} pour comprendre le problème réel. Exemple connu : "debitor/creditor number already exists" retourne un 500. Votre intégration doit intercepter les messages d'erreur connus et les mapper à des exceptions explicites, plutôt que de traiter chaque 500 comme une panne serveur.

2. N'attribuez jamais vous-même les numéros clients ou de factures

sevdesk gère ses propres séquences de numérotation, et les écarts dans ces séquences causent des problèmes en aval. Utilisez toujours les endpoints dédiés pour récupérer le prochain numéro disponible :

• GET /Contact/Factory/getNextCustomerNumber
• GET /SevSequence/Factory/getByType

Laissez sevdesk gérer l'énumération. Attribuer des numéros vous-même risque de générer des conflits et des requêtes rejetées.

3. Gérez correctement la pagination

sevdesk utilise les paramètres limit et offset pour la pagination. La valeur par défaut recommandée est de 100 enregistrements par page (maximum : 1 000). Pour obtenir le nombre total d'enregistrements, passez countAll=true. La réponse inclura {"total": "157", "objects": [...]}. Arrêtez la pagination quand len(objects) < limit, ou quand offset + limit >= total.

4. Mettez en cache les bonnes ressources, uniquement celles-là

Certaines ressources sont stables et peuvent être mises en cache sans risque : StaticCountry, SevClient et CheckAccount changent rarement. D'autres ne doivent jamais être mises en cache. Les contacts, factures et justificatifs mutent fréquemment, et les mettre en cache produit des lectures obsolètes après mise à jour, créant des incohérences difficiles à déboguer dans votre logique de synchronisation.

5. Récupérez les lignes séparément

Les positions de factures, d'avoirs et de justificatifs ne sont pas retournées en ligne par défaut. Elles se trouvent sur des endpoints séparés (InvoicePos, CreditNotePos, VoucherPos) et doivent être récupérées par ID parent. Tenez compte de ces appels supplémentaires lors de la conception de votre flux de synchronisation.

6. Implémentez une logique de retry avec backoff pour le rate limiting

sevdesk ne publie pas de limites de taux explicites, mais des réponses HTTP 429 peuvent survenir sous charge. Implémentez un backoff exponentiel et relancez sur 429. Ne relancez pas sur 401 : cela signifie que le token n'est plus valide.

Pourquoi intégrer sevdesk via Chift ?

Construire une intégration directe avec sevdesk est faisable. Mais une fois que vous avez géré les particularités d'authentification, le parsing des erreurs, la pagination, les règles de cache et le flux d'upload en deux étapes, vous devez encore maintenir cette intégration à mesure que l'API évolue. Et recommencer pour chaque autre outil comptable sur votre roadmap.

Avec l'API Comptabilité Unifiée de Chift, vous intégrez une seule fois et accédez à sevdesk, Exact Online, Xero, Sage, Pennylane, MyUnisoft, Visma eAccounting, et bien d'autres, le tout via le même modèle de données normalisé.

Voici ce que cela change pour votre équipe :

• Votre équipe technique construit une seule intégration, puis reste concentrée sur votre produit principal
• Les nouveaux connecteurs s'activent en un clic, sans développement supplémentaire
• L'authentification, la gestion des erreurs et le mapping des données sont entièrement pris en charge par Chift
• Monitoring, logs et maintenance long terme inclus
• Un support expert d'une équipe qui comprend aussi bien les enjeux techniques que business des intégrations financières

Votre équipe tech gagne du temps. Votre équipe commerciale peut dire oui à plus de demandes d'intégration. Et votre produit devient le choix naturel pour les clients qui ont besoin que leurs données financières circulent.

Vous voulez voir comment Chift connecte votre produit à sevdesk et à plus de 50 outils financiers ? Contactez notre équipe pour une démo.

FAQ intégration API sevdesk

Quels endpoints expose l'API sevdesk ?

L'API REST sevdesk à /api/v1 couvre un large éventail de ressources, notamment :

• Contacts /Contact
• Factures et lignes /Invoice, /InvoicePos
• Avoirs et lignes /CreditNote, /CreditNotePos
• Justificatifs et lignes /Voucher, /VoucherPos
• Comptes bancaires /CheckAccount
• Données de référence /StaticCountry, /SevClient

Consultez la documentation API sevdesk pour la liste complète des endpoints disponibles.

Quelles sont les limites de taux de l'API sevdesk ?

sevdesk ne publie pas de limites de taux explicites. Aucun quota numérique par minute ou par heure n'est indiqué dans leur documentation officielle. Cela dit, des réponses HTTP 429 peuvent survenir sous forte charge. Implémentez toujours une logique de retry avec backoff exponentiel pour les gérer correctement.

L'API sevdesk supporte-t-elle OAuth ?

Non. L'authentification repose entièrement sur un token statique transmis brut dans le header Authorization, sans préfixe Bearer, sans flux OAuth et sans expiration. Le token est valide jusqu'à ce que l'utilisateur le régénère ou que son compte soit supprimé.

Que se passe-t-il si le token sevdesk d'un utilisateur est perdu ou renouvelé ?

Si l'utilisateur supprime son compte, le token API est définitivement perdu et ne peut pas être récupéré. S'il régénère son token dans l'interface sevdesk, l'ancien est immédiatement invalidé. Vous recevrez une réponse HTTP 401 à votre prochaine requête. Affichez une erreur explicite et invitez l'utilisateur à renseigner son nouveau token dans les paramètres de votre intégration.

L'API sevdesk est-elle adaptée au développement d'intégrations logicielles ?

Oui. L'API REST sevdesk à /api/v1 est conçue pour les intégrations tierces et couvre tous les objets comptables principaux : contacts, factures, justificatifs, avoirs, et plus encore. C'est une base solide pour construire une connectivité comptable dans des produits ciblant le marché DACH.