Documentation comptable et API KWISATZ
Interface avec Pennylane
L’interface Comptabilité avancée transmet les écritures générées par KWISATZ directement dans le dossier comptable Pennylane au moyen de l’API. Elle évite la création puis l’import manuel d’un fichier comptable, tout en conservant les contrôles du pont comptable KWISATZ.
Réponse directe
Utilisez une version KWISATZ compatible — la base support documente la configuration à partir de 3.57 R12 — avec l’option Interface Comptabilité avancée. Dans le pont comptable, sélectionnez Pennylane, renseignez l’accès API prévu par la version, puis faites valider les journaux et comptes par le cabinet. Testez une facture ou une courte journée de caisse et contrôlez les écritures reçues avant tout déploiement.
L’export API n’est pas une sauvegarde et ne doit pas être relancé
sans contrôle. Une seconde transmission de la même période peut créer
des écritures comptables en double.
Conseil pour les paramètres et configurations
Conseil technicien : ne renseignez pas seul le token, l’URL, les scopes, les journaux ou les comptes, et ne relancez jamais une période dont le résultat est incertain. La configuration doit être contrôlée par un technicien KWISATZ et validée par le cabinet comptable. Utilisez une version compatible, une sauvegarde récente et un export pilote.
1. Repères de version
Les références de version ci-dessous sont conservées comme repères documentaires. Les menus, options et comportements doivent être contrôlés sur la version et la sérialisation réellement installées ; une évolution plus récente peut avoir modifié le fonctionnement.
2. Licence et disponibilité
La dépendance de licence mentionnée dans ce document provient des sources. Sa disponibilité peut varier selon la version, la sérialisation, le partenaire ou l’installation ; faites-la valider techniquement avant de modifier l’environnement.
3. Distinguer KWISATZ des opérations externes
Un enregistrement dans KWISATZ ne prouve pas automatiquement qu’une opération a été exécutée dans un système externe : débit ou remboursement TPE, mouvement physique d’espèces, envoi de SMS ou d’e-mail, ou action réalisée sur une plateforme.
4. Protection des données
5. Distinguer les trois périmètres
Conseil technicien : toute modification du pont comptable, du token API, des journaux, des comptes, de la TVA, des préférences, des droits ou de la période d’export doit être réalisée ou validée avec l’aide d’un technicien KWISATZ et du cabinet comptable. Sauvegardez le dossier et commencez par un test limité et identifiable.
| Périmètre | Fonction | Couvert par l’interface comptable |
|---|---|---|
| Pont comptable API | Transmet les écritures comptables produites par les flux KWISATZ pris en charge par le connecteur. | Oui, selon la version et le flux exporté. |
| Facturation électronique | Émission ou réception de factures structurées et gestion de leurs statuts. | Périmètre distinct à confirmer. |
| E-reporting | Transmission réglementaire de données de transaction et de paiement. | Non couvert par le seul pont comptable. |
L’utilisation de Pennylane comme comptabilité ne prouve pas que les flux de facturation électronique ou d’e-reporting sont activés dans KWISATZ. Faites qualifier séparément chaque besoin.
Le besoin « envoyer les écritures sans fichier TXT » correspond à l’interface comptable.
Le besoin « envoyer ou recevoir les factures électroniques » correspond à un autre flux.
6. Prérequis
Conseil technicien : toute modification du pont comptable, du token API, des journaux, des comptes, de la TVA, des préférences, des droits ou de la période d’export doit être réalisée ou validée avec l’aide d’un technicien KWISATZ et du cabinet comptable. Sauvegardez le dossier et commencez par un test limité et identifiable.
- version KWISATZ compatible ; la base support indique 3.57 R12 minimum pour les champs API ;
- option de licence Interface Comptabilité avancée ;
- dossier Pennylane de la société cible et accès API autorisé ;
- token ou authentification pris en charge par la version KWISATZ ;
- scopes suffisants et limités au besoin du connecteur ;
- journaux, comptes de ventes, achats, TVA, clients, fournisseurs et règlements validés par le cabinet ;
- connexion HTTPS sortante fonctionnelle ;
- date de démarrage des exports définie ;
- procédure de contrôle des périodes et de prévention des doublons.
Le développement du connecteur est documenté dans la branche 3.57. Utilisez toutefois la révision recommandée par le support KWISATZ au jour du déploiement, car l’API Pennylane et le connecteur ont évolué.
Ne mettez pas en service l’interface sur un dossier Pennylane de production
avant validation du plan comptable, des journaux et d’un export pilote.
7. API Pennylane, authentification et scopes
Conseil technicien : générez un token dédié au connecteur, limitez ses scopes et vérifiez GET /me. Ne copiez jamais un token entre sociétés ou environnements.
Pennylane propose plusieurs contextes d’API. Le connecteur KWISATZ doit utiliser le dossier de la société cible avec l’authentification réellement prise en charge par la version installée.
API v2
La documentation officielle Pennylane actuelle repose sur l’API v2 et des scopes granulaires. Une ancienne configuration doit être contrôlée avant tout nouvel export.
Scopes à contrôler pour les écritures comptables
| Scope v2 | Rôle |
|---|---|
journals:readonly ou journals:all | Lecture des journaux ; le droit d’écriture ne doit être accordé que si le connecteur en a besoin. |
ledger_accounts:readonly ou ledger_accounts:all | Lecture des comptes ; la création ou modification exige le scope complet. |
ledger_entries:all | Création des écritures comptables. |
file_attachments:all | Uniquement si le connecteur transmet réellement des pièces jointes. |
L’appel GET /me permet de contrôler le contexte de société et les scopes du token. Réalisez ce contrôle sans afficher le secret dans les captures ou les documents transmis.
IDs propres à chaque société
Les identifiants des journaux et comptes sont propres à chaque dossier Pennylane. Le connecteur doit les rechercher dans la société cible ; ils ne doivent pas être recopiés depuis une autre entreprise.
N’utilisez jamais le token ou les identifiants d’une société pour une autre.
Un mauvais contexte peut créer des écritures dans le mauvais dossier comptable.
8. Configurer l’interface dans KWISATZ
Conseil technicien : à partir de la version support documentée 3.57 R12, utilisez les champs API du pont comptable. Toute modification directe de PREFERENCES.INI doit rester exceptionnelle.
- Effectuez une sauvegarde complète du dossier KWISATZ.
- Vérifiez la version et l’option Interface Comptabilité avancée.
- Ouvrez la configuration du pont comptable disponible dans la version.
- Sélectionnez Pennylane comme type de pont.
- Renseignez l’URL et le token dans les champs prévus par la version.
- Faites valider les journaux, comptes et règles de TVA.
- Enregistrez puis redémarrez l’application si la version l’exige.
- Testez l’accès et un export limité avant la production.
La base support mentionne un paramétrage manuel dans PREFERENCES.INI pour certaines premières versions, puis des champs API visibles dans Outils > Préférences > Pont comptable à partir de 3.57 R12. Toute intervention directe dans le fichier doit être réservée au technicien.
Cette fiche ne publie pas les noms internes des balises ni de valeur de token.
Ne copiez pas un bloc de préférences provenant d’un autre client.
Authentification de production
Pennylane prend officiellement en charge les tokens d’entreprise et OAuth 2.0. Utilisez uniquement la méthode supportée par le connecteur KWISATZ installé ; ne transposez pas une procédure destinée à une autre intégration.
Un token masqué dans KWISATZ ou Pennylane ne peut pas toujours être relu en clair.
Conservez la procédure de rotation et le contact de l’administrateur,
sans stocker le secret dans un document public.
9. Aligner les journaux et le plan comptable
Conseil technicien : faites valider chaque journal, compte de ventes, TVA, client, fournisseur et règlement par le cabinet avant l’export.
Journaux
| Flux KWISATZ | Journal cible type | Contrôle |
|---|---|---|
| Vente directe / Ticket Z | Journal de caisse ou journal POS validé par le cabinet. | Contrôler le code et l’identifiant du dossier cible. |
| Factures clients | Journal des ventes défini dans le dossier Pennylane. | Ne pas confondre avec le journal caisse. |
| Factures fournisseurs | Journal des achats défini dans le dossier Pennylane. | Valider le code réel dans Pennylane. |
| Financier | Journal défini selon la nature de l’écriture. | Rapprocher les modes de règlement et banques. |
Comptes essentiels
| Élément KWISATZ | Compte à contrôler |
|---|---|
| Familles et produits | Comptes de ventes et d’achats, avec distinction locale, UE, hors UE ou exonérée selon le dossier. |
| Taux de TVA | TVA collectée et TVA déductible. |
| Clients | Compte collectif ou auxiliaire validé par le cabinet. |
| Fournisseurs | Compte collectif ou auxiliaire validé par le cabinet. |
| Règlements | Espèces, cartes, chèques, banques, comptes d’attente et autres moyens. |
| Écarts et frais | Comptes spécifiques validés par le cabinet. |
L’export reprend les comptes réellement enregistrés sur les fiches.
Une famille correcte ne garantit pas qu’un produit, un client
ou un règlement n’a pas conservé un ancien compte.
Comptes clients alphanumériques
La base support décrit des rejets sur certains comptes clients alphanumériques. Traitez ce comportement comme un cas de dossier : faites contrôler le format attendu dans Pennylane et le compte saisi dans la fiche client avant de généraliser une règle.
Affectation des taux de TVA dans Pennylane
Dans certains dossiers, le compte de ventes doit être associé au traitement fiscal attendu côté Pennylane. Faites vérifier ce mapping si les écritures arrivent avec une TVA non affectée.
Si les montants HT et TVA sont corrects dans le journal KWISATZ
mais apparaissent « non affectés » dans Pennylane, contrôlez d’abord
le paramétrage fiscal du compte de ventes côté Pennylane.
10. Procédures d’export
Conseil technicien : toute modification du pont comptable, du token API, des journaux, des comptes, de la TVA, des préférences, des droits ou de la période d’export doit être réalisée ou validée avec l’aide d’un technicien KWISATZ et du cabinet comptable. Sauvegardez le dossier et commencez par un test limité et identifiable.
Vente directe
Utilisez la procédure de pont comptable de Vente directe disponible dans la version installée.
- sélectionnez une période courte ;
- contrôlez le centre, la caisse et le magasin ;
- vérifiez le journal ;
- lancez l’envoi ;
- comparez avec la statistique de caisse ou le Ticket Z.
Factures et avoirs clients
Utilisez la procédure de pont comptable des factures clients ou la fonction équivalente disponible.
Financier clients
Utilisez la procédure du financier clients lorsque ce flux doit être exporté séparément.
Achats et fournisseurs
Utilisez les procédures fournisseurs prévues pour les factures, avoirs et règlements lorsque ces flux sont compris dans le déploiement.
Ne transférez pas deux fois une même opération :
par exemple un règlement déjà intégré dans le journal de caisse
puis une seconde fois depuis le financier.
Les tickets de livraison ou tickets destinés à une facturation différée
peuvent être exclus du journal de caisse afin d’éviter de comptabiliser
à la fois le ticket et la facture générée ultérieurement.
11. Effectuer le premier test
Conseil technicien : toute modification du pont comptable, du token API, des journaux, des comptes, de la TVA, des préférences, des droits ou de la période d’export doit être réalisée ou validée avec l’aide d’un technicien KWISATZ et du cabinet comptable. Sauvegardez le dossier et commencez par un test limité et identifiable.
- Demandez au cabinet les journaux et comptes attendus.
- Choisissez une facture simple ou une seule journée de caisse.
- Conservez l’édition KWISATZ de référence.
- Lancez l’export API.
- Contrôlez dans Pennylane la société et le journal.
- Vérifiez chaque compte.
- Comparez HT, TVA et TTC.
- Vérifiez l’égalité débit/crédit.
- Contrôlez les dates, pièces et libellés.
- Faites valider le résultat par le cabinet.
- Consignez la période comme transférée.
| Test | Résultat attendu |
|---|---|
| Ticket Z | Ventes HT, TVA et règlements équilibrés dans le journal de caisse. |
| Facture client | Compte client, vente et TVA correctement ventilés. |
| Avoir client | Écriture inversée ou conforme au schéma validé. |
| Facture fournisseur | Compte fournisseur, achat et TVA déductible. |
| Règlement | Journal et compte de banque, caisse ou règlement corrects. |
Ne commencez pas par une reprise d’un mois ou d’un exercice complet.
Une erreur de compte reproduite sur des centaines d’écritures
devient difficile à identifier et à annuler.
12. Journaliser les exports
Repère de diagnostic :
COMPTA_EXPORT. Ce repère interne ne doit pas être modifié directement. Faites analyser et valider le réglage par un technicien KWISATZ après sauvegarde et relevé de la configuration.Utilisez également Outils > Journal des écritures comptables exportées lorsque cette fonction est disponible.
Contrôlez :
- date et heure de l’export ;
- poste et utilisateur ;
- période ;
- type de flux ;
- journal et comptes ;
- montants débit et crédit ;
- résultat API ;
- identifiant ou référence externe lorsqu’elle est disponible ;
- erreur ou fichier de diagnostic.
La base support mentionne le fichier PLN.ASK pour certains diagnostics. Conservez-le pour le technicien après avoir vérifié qu’aucun token ou secret n’est transmis en clair.
13. Volumes, temporisation et erreur 429
Conseil technicien : respectez les en-têtes de limitation et vérifiez les écritures déjà créées avant toute reprise après une erreur 429 ou une coupure réseau.
Au 3 août 2026, la documentation officielle de l’API Pennylane v2 indique une limite de 25 requêtes par période de 5 secondes au niveau du token. Le dépassement renvoie 429 Too Many Requests avec un en-tête retry-after.
- Respectez le délai indiqué par
retry-after. - Ne relancez pas immédiatement toute la période.
- Découpez les reprises historiques en petites périodes.
- Contrôlez ce qui a déjà été créé avant chaque reprise.
- Effectuez les gros envois hors période d’activité.
- Conservez les journaux API.
La gestion de l’erreur 429 est documentée dans le développement KWISATZ
du 20 février 2026. Une version antérieure peut nécessiter une mise à jour.
Après un délai ou un message « Pennylane n’a pas répondu »,
vérifiez d’abord les écritures déjà reçues. Une réponse perdue
ne signifie pas nécessairement que Pennylane n’a rien créé.
14. Pennylane et la facturation électronique
Conseil technicien : ne présentez pas l’interface comptable comme un connecteur de facturation électronique ou d’e-reporting sans validation explicite du périmètre déployé.
Pennylane propose également des services de facturation électronique. Ce périmètre est distinct de l’export d’écritures comptables KWISATZ.
Capacités actuelles de l’API Pennylane
La documentation officielle Pennylane décrit des endpoints d’import de factures électroniques en Factur-X, UBL ou CII. Leur existence ne prouve pas que le connecteur comptable KWISATZ les utilise.
| Flux | Scope Pennylane | Statut dans KWISATZ |
|---|---|---|
| Écritures comptables | Scopes des journaux, comptes et écritures. | Interface Comptabilité avancée selon la version. |
| Factures électroniques | API et services dédiés Pennylane. | Connecteur KWISATZ distinct à confirmer. |
| Cycles de vie et e-reporting | Services réglementaires de la plateforme. | Ne pas assimiler au pont comptable. |
Une communication commerciale indiquant « interface Pennylane »
doit toujours préciser s’il s’agit du pont comptable,
de l’envoi de factures électroniques, de la réception fournisseur
ou de l’e-reporting.
15. Sécurité
Conseil technicien : toute modification du pont comptable, du token API, des journaux, des comptes, de la TVA, des préférences, des droits ou de la période d’export doit être réalisée ou validée avec l’aide d’un technicien KWISATZ et du cabinet comptable. Sauvegardez le dossier et commencez par un test limité et identifiable.
- utiliser le minimum de scopes nécessaire ;
- ne jamais publier le token ou le secret OAuth2 ;
- ne pas copier un token entre sociétés ;
- restreindre l’accès à
PREFERENCES.INI; - masquer les secrets dans les captures et journaux ;
- prévoir la rotation et la révocation des accès ;
- utiliser uniquement HTTPS ;
- contrôler le proxy et l’inspection TLS de l’entreprise ;
- désactiver l’ancien token après remplacement ;
- conserver une trace des responsables de l’activation.
Un token d’écriture comptable permet de créer des données financières.
Il doit être traité comme un secret critique.
16. Diagnostic rapide
Conseil technicien : toute modification du pont comptable, du token API, des journaux, des comptes, de la TVA, des préférences, des droits ou de la période d’export doit être réalisée ou validée avec l’aide d’un technicien KWISATZ et du cabinet comptable. Sauvegardez le dossier et commencez par un test limité et identifiable.
Erreur 401 — token absent ou invalide
Vérifiez la présence et la validité du token, l’environnement et le dossier cible. Faites remplacer le secret selon la procédure, sans l’envoyer dans un message non sécurisé.
Erreur 403 — accès interdit
Contrôlez les scopes du token et l’accès au dossier. GET /me permet de confirmer le contexte et les scopes actifs.
Le journal de caisse est introuvable
Vérifiez le code du journal dans les préférences KWISATZ,
son existence dans Pennylane et les droits
journals.
Les IDs sont propres à la société et doivent être recherchés à nouveau.
Erreur 422 — compte impossible à créer ou requête invalide
Consultez le corps détaillé de l’erreur. Contrôlez le compte, le journal, les champs obligatoires, la TVA et l’équilibre de l’écriture. Corrigez la donnée avant toute relance.
Le compte client alphanumérique est rejeté
Ouvrez la fiche client, onglet administratif,
et renseignez un compte numérique conforme au dossier Pennylane.
À défaut, utilisez temporairement un compte collectif validé.
La TVA apparaît non affectée dans Pennylane
Comparez d’abord les écritures dans le journal KWISATZ.
Si les comptes et montants sont corrects, associez côté Pennylane
chaque compte de ventes au taux de TVA attendu.
Erreur 429 ou blocage sur un gros export
Respectez retry-after, réduisez les rafales et contrôlez les écritures déjà créées avant de reprendre l’envoi.
Pennylane ne répond pas
Vérifiez l’état du service, Internet, le proxy et les journaux.
Ne relancez pas toute la période avant d’avoir recherché les écritures
déjà reçues dans Pennylane.
Les écritures sont envoyées dans la mauvaise société
Désactivez l’interface, conservez les journaux et faites contrôler le token ainsi que le contexte retourné par GET /me. Toute correction dans Pennylane doit être validée par le cabinet.
Le chiffre d’affaires KWISATZ est supérieur à l’export
Recherchez les tickets de livraison ou tickets BL destinés
à une facturation différée. Ils peuvent être comptabilisés
lors de la facture de gestion et non dans le journal de caisse.
L’export a réussi mais aucune écriture n’est visible
Contrôlez le bon exercice, le journal, la société,
les filtres de Pennylane et le résultat API. Vérifiez également
si l’écriture est en brouillon, en attente ou dans un autre journal.
Le menu Pennylane n’est pas disponible
Vérifiez la version, la sérialisation de l’option
Interface Comptabilité avancée et le type de pont comptable.
Une note de développement ne garantit pas la présence dans une ancienne version.
17. Recette complète
Conseil technicien : toute modification du pont comptable, du token API, des journaux, des comptes, de la TVA, des préférences, des droits ou de la période d’export doit être réalisée ou validée avec l’aide d’un technicien KWISATZ et du cabinet comptable. Sauvegardez le dossier et commencez par un test limité et identifiable.
- Vérifier l’authentification et les scopes.
- Récupérer les journaux du bon dossier.
- Récupérer les comptes du bon dossier.
- Exporter une journée de caisse.
- Exporter une facture client.
- Exporter un avoir client.
- Exporter un règlement client.
- Exporter une facture fournisseur.
- Exporter un règlement fournisseur.
- Tester un compte absent.
- Tester un compte client invalide.
- Sur un environnement de test, vérifier qu’un scope insuffisant produit un refus compréhensible.
- Tester une temporisation contrôlée sans créer volontairement une charge excessive.
- Vérifier les doublons après une interruption réseau.
- Faire valider le résultat par le cabinet comptable.
L’interface est validée lorsque chaque flux arrive dans le bon journal,
avec des écritures équilibrées, des comptes reconnus, une TVA correctement affectée
et une traçabilité suffisante pour éviter tout double transfert.
18. Liste de contrôle de mise en service
Conseil technicien : toute modification du pont comptable, du token API, des journaux, des comptes, de la TVA, des préférences, des droits ou de la période d’export doit être réalisée ou validée avec l’aide d’un technicien KWISATZ et du cabinet comptable. Sauvegardez le dossier et commencez par un test limité et identifiable.
- La version KWISATZ est validée pour l’API Pennylane utilisée.
- L’option Interface Comptabilité avancée est active.
- Le dossier Pennylane cible est identifié.
- Le token ou l’authentification prise en charge possède les scopes nécessaires.
- Le test
GET /meconfirme la bonne société. - Les journaux sont validés.
- Les comptes clients et fournisseurs sont conformes.
- Les comptes de ventes, achats et TVA sont alignés.
- Les taux de TVA sont affectés côté Pennylane.
- Une facture et une journée de caisse ont été testées.
- Les erreurs 401, 403, 422 et 429 sont comprises et documentées.
- La journalisation des exports est contrôlée.
- Les périodes transférées sont consignées.
- Le cabinet comptable a validé le résultat.
19. Évolutions documentées
Conseil technicien : toute modification du pont comptable, du token API, des journaux, des comptes, de la TVA, des préférences, des droits ou de la période d’export doit être réalisée ou validée avec l’aide d’un technicien KWISATZ et du cabinet comptable. Sauvegardez le dossier et commencez par un test limité et identifiable.
| Date | Évolution |
|---|---|
| 26–30 janvier 2026 | Développement de l’export Pennylane par API et de la journalisation COMPTA_EXPORT dans la branche 3.57. |
| 9 février 2026 | Compilation documentée en 3.57r3 pendant le développement du connecteur. |
| 16 février 2026 | Ajout de l’option de licence Interface Comptabilité avancée. |
| 20 février 2026 | Gestion documentée de l’erreur 429 dans le suivi du connecteur. |
| Version support 3.57 R12 | Présence documentée des champs API URL et API Token dans les préférences du pont comptable. |
20. Sources documentaires
- Suivi de développement KWISATZ — Pennylane, COMPTA_EXPORT, option Interface Comptabilité avancée et erreur 429.
- Base support KWISATZ — version 3.57 R12, champs API URL/API Token, comptes, erreurs d’export et fichier PLN.ASK.
- Documentation officielle Pennylane Company API v2 — scopes, GET /me, écritures comptables et intégration POS.
- Documentation officielle Pennylane — limite de 25 requêtes par 5 secondes et en-tête retry-after.
- Documentation officielle Pennylane — import de factures électroniques Factur-X, UBL et CII.