Intégration domotique Invoice Ninja, gratuite et open source
Factures impayées et en retard, paiements et devis de votre Invoice Ninja dans Gladys.
Publiée par guim31
- Appareils
- Version 1.0.0
- Nécessite Gladys >=5.1.0
- ★ 0
Suivez votre facturation depuis Gladys : les factures impayées et en retard, l'argent encaissé ce mois-ci et les devis en attente de votre Invoice Ninja, auto-hébergé ou sur le service hébergé invoicing.co. Soyez prévenu quand un paiement arrive, quand une facture passe en retard ou quand un client accepte un devis.
L'intégration ne fait que lire : elle n'écrit jamais dans vos factures, n'envoie aucun e-mail, ne crée rien. Elle interroge l'API d'Invoice Ninja avec un jeton que vous créez. Non affiliée à Invoice Ninja.
Ce que vous obtenez
- Un appareil pour votre entreprise : factures impayées (nombre et montant), factures en retard (nombre et montant), argent encaissé ce mois-ci et devis en attente, avec leur historique.
- Un widget de tableau de bord : les factures en retard avec leurs jours de retard, les derniers paiements et les totaux, chaque bloc et les montants pouvant être masqués.
- Trois déclencheurs de scène : paiement reçu, facture en retard, devis accepté.
- Une action de scène : un résumé en une phrase à envoyer par message ou à faire lire à voix haute, et ses chiffres.
Prérequis
- Gladys Assistant 5.1 ou plus récent.
- Invoice Ninja 5 (testé avec la 5.13 auto-hébergée), joignable depuis la machine de Gladys, ou un compte sur invoicing.co. Invoice Ninja 4 a une autre API et n'est pas pris en charge.
- Un jeton d'API de l'entreprise à suivre. Sur invoicing.co, vérifiez que votre formule comprend l'API.
Testé sur un vrai Invoice Ninja 5.13 auto-hébergé avec des clients, factures, paiements et devis fictifs ; pas testé sur invoicing.co : vos retours sont les bienvenus.
Configuration
Créer un jeton d'API
Dans Invoice Ninja, ouvrez Paramètres → Gestion du compte → Jetons d'API, puis Nouveau jeton. Donnez-lui un nom (par exemple « Gladys »), enregistrez et copiez le jeton affiché. Un jeton appartient à une entreprise : si vous en avez plusieurs, créez-le en ayant sélectionné celle à suivre.
Réglages
| Réglage | Rôle |
|---|---|
| Adresse d'Invoice Ninja | L'adresse à laquelle vous ouvrez Invoice Ninja, par ex. https://factures.example.com |
| Jeton d'API | Le jeton créé ci-dessus. Gardé par Gladys, jamais écrit dans les journaux |
| Fréquence de mise à jour | Fréquence de lecture d'Invoice Ninja : de 5 à 60 minutes, 15 par défaut |
| Langue des textes | Noms des fonctionnalités (à leur création) et phrases envoyées aux scènes ; français par défaut |
Pour le service hébergé, l'adresse est https://invoicing.co. Cliquez sur Tester la connexion : la réponse
donne le nombre de factures impayées, de factures en retard et de devis en attente trouvés, ou ce qui ne va pas.
Ouvrez ensuite l'onglet Découverte et ajoutez l'entreprise.
Appareil
| Fonctionnalité | Signification |
|---|---|
| Factures impayées | Factures envoyées ou partiellement payées avec un solde restant |
| Montant impayé | La somme de leurs soldes |
| Factures en retard | Celles dont l'échéance (ou l'échéance de leur acompte) est passée |
| Montant en retard | La somme de leurs soldes |
| Encaissé ce mois-ci | Les paiements datés de ce mois, remboursements déduits |
| Devis en attente | Les devis envoyés, ni acceptés ni expirés |
Les brouillons, les factures annulées ou supprimées et les données des clients supprimés sont laissés de côté, comme dans le tableau de bord d'Invoice Ninja. Les montants sont dans la devise de l'entreprise : une facture ou un paiement dans une autre devise est converti avec le taux de change qu'Invoice Ninja a enregistré dessus. L'euro, le dollar américain et la livre sterling s'affichent avec leur symbole dans Gladys ; une autre devise est écrite après le nom de l'appareil. Une facture est en retard le lendemain de son échéance, dans le fuseau horaire de Gladys.
Widget de tableau de bord
Ajoutez le widget Aperçu Invoice Ninja à un tableau de bord. Il montre quatre tuiles (factures en retard, montant en retard, montant impayé, encaissé ce mois-ci), les factures en retard avec leur client, leur échéance, leur solde et leurs jours de retard (5 au plus, les plus anciennes d'abord) et les derniers paiements (5 au plus). Ses réglages masquent les montants (il ne reste que des nombres et des dates, pour un tableau de bord vu par tous), les tuiles, les factures en retard ou les paiements. Il fonctionne dès que l'intégration lit Invoice Ninja, même avant l'ajout de l'appareil.
Déclencheurs de scène
| Déclencheur | Quand | Variables |
|---|---|---|
| Paiement reçu | Un nouveau paiement abouti est enregistré, à la main ou par une passerelle | client, montant, devise, numéro du paiement, date, phrase |
| Facture en retard | Une facture impayée dépasse son échéance | numéro de facture, client, montant dû, devise, échéance, jours de retard, phrase |
| Devis accepté | Un devis est approuvé par le client ou converti en facture | numéro du devis, client, montant, devise, phrase |
Ce qui existe à la première lecture sert de point de départ : installer l'intégration ne déclenche rien pour les paiements passés ni pour les factures déjà en retard. Chaque événement est envoyé une fois ; une facture soldée puis de nouveau en retard plus tard déclenche de nouveau. Ce qui a déjà été annoncé est gardé dans les données de l'intégration : un redémarrage ne déclenche rien deux fois. Un événement est vu à la lecture suivante, donc jusqu'à une période de mise à jour plus tard.
Action de scène
Invoice Ninja : lire le résumé répond une phrase comme « 3 facture(s) impayée(s) pour 3 980,50 €, dont 2 en retard pour 1 480,50 €. Encaissé ce mois-ci : 500,00 €. 4 devis en attente. » et les mêmes chiffres en sorties séparées. Elle relit Invoice Ninja si la dernière lecture date de plus d'une période de mise à jour. Quand le serveur ne répond pas, les dernières valeurs servent.
Exemples de scènes
- Un paiement arrive : déclencheur « Invoice Ninja : paiement reçu », puis « Envoyer un message » avec la variable Phrase à envoyer ou à lire.
- Lundi matin : chaque lundi à 8 h, « Invoice Ninja : lire le résumé », puis envoyez sa phrase par message ou faites-la lire par une enceinte.
- Relance : déclencheur « Invoice Ninja : facture en retard », puis un message « Relancer le client » avec le numéro de facture et le client.
- Bonne nouvelle : déclencheur « Invoice Ninja : devis accepté », puis une lampe en vert pendant une minute.
Confidentialité et données
- Le jeton reste dans la configuration de Gladys ; l'intégration ne l'envoie qu'à l'adresse que vous avez indiquée.
- Les journaux de l'intégration ne contiennent jamais de montant, de nom de client, le jeton ni l'adresse : seulement des nombres, des codes d'erreur et des numéros de facture.
- Gardé dans le volume
/datade l'intégration : les identifiants des paiements, factures en retard et devis acceptés déjà annoncés, et l'identifiant de l'entreprise. Aucun montant, aucun nom. - Les noms des clients et les montants sont montrés par le widget et passés aux scènes que vous créez, dans Gladys seulement.
Dépannage
| Message | Que faire |
|---|---|
| Invoice Ninja refuse le jeton d'API | Créez un nouveau jeton, copiez-le en entier, vérifiez qu'il appartient à la bonne entreprise |
| Pas d'API Invoice Ninja 5 à cette adresse | Indiquez l'adresse à laquelle vous ouvrez Invoice Ninja, sans /api/v1 ; Invoice Ninja 4 n'est pas pris en charge |
| Invoice Ninja ne répond pas | Vérifiez que la machine de Gladys joint l'adresse (réseau, VPN, pare-feu, certificat HTTPS) |
| L'adresse d'Invoice Ninja redirige ailleurs | Indiquez l'adresse où arrive le navigateur, souvent en https:// : les redirections ne sont jamais suivies, le jeton ne part donc jamais ailleurs |
| Invoice Ninja limite les requêtes | Choisissez une fréquence de mise à jour plus longue |
| Invoice Ninja répond par une erreur | Consultez les journaux d'Invoice Ninja ; les dernières valeurs sont gardées en attendant |
Le détail de chaque lecture s'écrit dans les journaux avec LOG_LEVEL=debug.
Limites
- Une entreprise par jeton : pour plusieurs entreprises, il faut un jeton par entreprise, et une installation suit une entreprise.
- Chaque lecture fait six requêtes à Invoice Ninja (davantage au-delà de 100 factures impayées ou paiements dans le mois) ; le service hébergé limite son API, gardez donc une fréquence raisonnable.
- Un paiement enregistré en attente (virement à confirmer) et validé plus tard, après plus de 10 nouveaux paiements, n'est pas annoncé.
- Le réglage « Préférer la connexion locale » de Gladys n'a pas d'effet : il n'y a qu'une adresse. L'appareil indique « local » pour un serveur auto-hébergé et « cloud » pour invoicing.co.
- Lecture seule : aucune facture ne peut être créée, envoyée ou marquée payée depuis Gladys.
Paramètres de configuration
Voici les paramètres demandés par Invoice Ninja dans son écran de configuration dans Gladys.
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| Connexion à Invoice Ninja | section | Non | Indiquez l'adresse de votre Invoice Ninja 5 (ou https://invoicing.co pour le service hébergé) et un jeton d'API : Paramètres → Gestion du compte → Jetons d'API. Ajoutez ensuite l'entreprise dans l'onglet Découverte. |
| Adresse d'Invoice Ninja | string | Oui | L'adresse à laquelle vous ouvrez Invoice Ninja, joignable depuis Gladys. |
| Jeton d'API | secret | Oui | Lecture seule : l'intégration n'écrit jamais dans vos factures. Gardé par Gladys, jamais écrit dans les journaux. |
| Fréquence de mise à jour | select | Non | Fréquence de lecture d'Invoice Ninja (six requêtes à chaque fois). |
| Langue des textes | select | Non | Noms des fonctionnalités (à leur création) et textes envoyés aux scènes. |
Comment installer Invoice Ninja dans Gladys
- Dans Gladys, ouvrez Intégrations : Invoice Ninja apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
- Cliquez sur Installer. Gladys télécharge l'image Docker (
ghcr.io/guim31/gladys-invoiceninja:1.0.0), la démarre dans un bac à sable isolé du cœur, et génère l'interface de l'intégration (appareils, découverte et configuration). - Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
- Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/guim31/gladys-invoiceninja.
Invoice Ninja nécessite Gladys >=5.1.0. Le catalogue dans Gladys se rafraîchit toutes les heures : une nouvelle version est donc disponible au plus tard une heure après sa sortie.
Vous n'utilisez pas encore Gladys ? C'est gratuit et open source : suivez le guide d'installation pour démarrer.
À propos des intégrations externes
Invoice Ninja est une intégration externe : une intégration communautaire empaquetée dans un conteneur Docker et publiée sur GitHub, que Gladys installe en un clic et exécute dans un bac à sable isolé de son cœur. Elle est publiée et maintenue par guim31, et non par l'équipe cœur de Gladys.
- Parcourir toutes les intégrations, natives et communautaires
- Créer et publier votre propre intégration externe
- Code source sur GitHub — source de cette documentation