Invoice Ninja Smart-Home-Integration, kostenlos und Open Source

Offene und überfällige Rechnungen, Zahlungen und Angebote deines Invoice Ninja in Gladys.

• Veröffentlicht von guim31
• Geräte
• Version 1.0.0
• Erfordert Gladys >=5.1.0
• ★ 0

Auf GitHub ansehenAlle Integrationen

Behalte deine Rechnungen in Gladys im Blick: die offenen und überfälligen Rechnungen, das diesen Monat eingegangene Geld und die offenen Angebote deines Invoice Ninja, selbst gehostet oder beim gehosteten Dienst invoicing.co. Lass dich benachrichtigen, wenn eine Zahlung eingeht, eine Rechnung überfällig wird oder ein Kunde ein Angebot annimmt.

Die Integration liest nur: sie schreibt nie in deine Rechnungen, verschickt keine E-Mail, legt nichts an. Dazu fragt sie die API von Invoice Ninja mit einem Token ab, das du erstellst. Nicht mit Invoice Ninja verbunden.

Was du bekommst

• Ein Gerät für dein Unternehmen: offene Rechnungen (Anzahl und Betrag), überfällige Rechnungen (Anzahl und Betrag), diesen Monat eingegangenes Geld und offene Angebote, mit ihrem Verlauf.
• Ein Dashboard-Widget: die überfälligen Rechnungen mit ihren Tagen Verzug, die letzten Zahlungen und die Summen; jeder Block und die Beträge lassen sich ausblenden.
• Drei Szenen-Auslöser: Zahlung erhalten, Rechnung überfällig, Angebot angenommen.
• Eine Szenen-Aktion: eine Übersicht als Satz zum Senden per Nachricht oder zum Vorlesen, und ihre Zahlen.

Voraussetzungen

• Gladys Assistant 5.1 oder neuer.
• Invoice Ninja 5 (getestet mit 5.13, selbst gehostet), vom Gladys-Rechner aus erreichbar, oder ein Konto bei invoicing.co. Invoice Ninja 4 hat eine andere API und wird nicht unterstützt.
• Ein API-Token des zu verfolgenden Unternehmens. Prüfe bei invoicing.co, ob dein Tarif die API enthält.

Getestet mit einem echten, selbst gehosteten Invoice Ninja 5.13 mit erfundenen Kunden, Rechnungen, Zahlungen und Angeboten; nicht getestet mit invoicing.co: Rückmeldungen sind willkommen.

Konfiguration

Ein API-Token erstellen

Öffne in Invoice Ninja Einstellungen → Kontoverwaltung → API-Tokens, dann Neues Token. Gib ihm einen Namen (zum Beispiel „Gladys“), speichere und kopiere das angezeigte Token. Ein Token gehört zu einem Unternehmen: hast du mehrere, erstelle es, während das zu verfolgende ausgewählt ist.

Einstellungen

Einstellung	Wirkung
Adresse von Invoice Ninja	Die Adresse, unter der du Invoice Ninja öffnest, z. B. https://rechnungen.example.com
API-Token	Das oben erstellte Token. Von Gladys gespeichert, nie in die Protokolle geschrieben
Aktualisierungsintervall	Wie oft Invoice Ninja gelesen wird: 5 bis 60 Minuten, standardmäßig 15
Sprache der Texte	Namen der Funktionen (bei ihrer Erstellung) und Sätze für die Szenen; standardmäßig Französisch

Für den gehosteten Dienst lautet die Adresse https://invoicing.co. Klicke auf Verbindung testen: die Antwort nennt die Anzahl der gefundenen offenen Rechnungen, überfälligen Rechnungen und offenen Angebote, oder was nicht stimmt. Öffne dann den Tab Entdecken und füge das Unternehmen hinzu.

Gerät

Funktion	Bedeutung
Offene Rechnungen	Versendete oder teilweise bezahlte Rechnungen mit Restbetrag
Offener Betrag	Die Summe ihrer Restbeträge
Überfällige Rechnungen	Die, deren Fälligkeit (oder die Fälligkeit ihrer Teilzahlung) vorbei ist
Überfälliger Betrag	Die Summe ihrer Restbeträge
Diesen Monat bezahlt	Zahlungen mit Datum in diesem Monat, abzüglich Erstattungen
Offene Angebote	Versendete Angebote, weder angenommen noch abgelaufen

Entwürfe, stornierte und gelöschte Rechnungen sowie die Daten gelöschter Kunden bleiben außen vor, wie im Dashboard von Invoice Ninja. Die Beträge sind in der Währung des Unternehmens: eine Rechnung oder Zahlung in einer anderen Währung wird mit dem Wechselkurs umgerechnet, den Invoice Ninja dazu gespeichert hat. Euro, US-Dollar und Pfund Sterling erscheinen in Gladys mit ihrem Symbol; eine andere Währung steht hinter dem Namen des Geräts. Eine Rechnung ist am Tag nach ihrer Fälligkeit überfällig, in der Zeitzone von Gladys.

Dashboard-Widget

Füge das Widget Invoice-Ninja-Übersicht einem Dashboard hinzu. Es zeigt vier Kacheln (überfällige Rechnungen, überfälliger Betrag, offener Betrag, diesen Monat bezahlt), die überfälligen Rechnungen mit Kunde, Fälligkeit, Restbetrag und Tagen Verzug (höchstens 5, die ältesten zuerst) und die letzten Zahlungen (höchstens 5). Seine Einstellungen blenden die Beträge aus (es bleiben nur Anzahlen und Daten, für ein Dashboard, das alle sehen), die Kacheln, die überfälligen Rechnungen oder die Zahlungen. Es funktioniert, sobald die Integration Invoice Ninja liest, auch bevor das Gerät hinzugefügt ist.

Szenen-Auslöser

Auslöser	Wann	Variablen
Zahlung erhalten	Eine neue abgeschlossene Zahlung wird erfasst, von Hand oder über ein Gateway	Kunde, Betrag, Währung, Zahlungsnummer, Datum, Satz
Rechnung überfällig	Eine offene Rechnung überschreitet ihre Fälligkeit	Rechnungsnummer, Kunde, offener Betrag, Währung, Fälligkeit, Tage überfällig, Satz
Angebot angenommen	Ein Angebot wird vom Kunden angenommen oder in eine Rechnung umgewandelt	Angebotsnummer, Kunde, Betrag, Währung, Satz

Was beim ersten Lesen existiert, ist der Ausgangspunkt: die Installation löst nichts für vergangene Zahlungen oder schon überfällige Rechnungen aus. Jedes Ereignis wird einmal gesendet; eine bezahlte Rechnung, die später wieder überfällig wird, löst erneut aus. Was schon gemeldet wurde, bleibt in den Daten der Integration: ein Neustart löst nichts doppelt aus. Ein Ereignis wird beim nächsten Lesen bemerkt, also bis zu einem Aktualisierungsintervall später.

Szenen-Aktion

Invoice Ninja: Übersicht lesen antwortet mit einem Satz wie „3 offene Rechnung(en) über 3.980,50 €, davon 2 überfällig über 1.480,50 €. Diesen Monat bezahlt: 500,00 €. 4 offene(s) Angebot(e).“ und denselben Zahlen als einzelne Ausgaben. Invoice Ninja wird erneut gelesen, wenn das letzte Lesen älter als ein Aktualisierungsintervall ist. Antwortet der Server nicht, werden die letzten Werte verwendet.

Szenen-Beispiele

• Eine Zahlung geht ein: Auslöser „Invoice Ninja: Zahlung erhalten“, dann „Nachricht senden“ mit der Variable Satz zum Senden oder Vorlesen.
• Montagmorgen: jeden Montag um 8:00 „Invoice Ninja: Übersicht lesen“, dann den Satz per Nachricht senden oder von einem Lautsprecher vorlesen lassen.
• Mahnung: Auslöser „Invoice Ninja: Rechnung überfällig“, dann eine Nachricht „Kunden erinnern“ mit Rechnungsnummer und Kunde.
• Gute Nachricht: Auslöser „Invoice Ninja: Angebot angenommen“, dann eine Lampe eine Minute lang grün.

Datenschutz und Daten

• Das Token bleibt in der Konfiguration von Gladys; die Integration sendet es nur an die eingegebene Adresse.
• Die Protokolle der Integration enthalten nie einen Betrag, einen Kundennamen, das Token oder die Adresse: nur Anzahlen, Fehlercodes und Rechnungsnummern.
• Im Volume /data der Integration gespeichert: die IDs der schon gemeldeten Zahlungen, überfälligen Rechnungen und angenommenen Angebote sowie die ID des Unternehmens. Kein Betrag, kein Name.
• Kundennamen und Beträge zeigt das Widget und erhalten die Szenen, die du baust, nur innerhalb von Gladys.

Fehlerbehebung

Meldung	Was tun
Invoice Ninja lehnt das API-Token ab	Erstelle ein neues Token, kopiere es vollständig, prüfe, dass es zum richtigen Unternehmen gehört
Keine Invoice-Ninja-5-API unter dieser Adresse	Gib die Adresse ein, unter der du Invoice Ninja öffnest, ohne /api/v1; Invoice Ninja 4 wird nicht unterstützt
Invoice Ninja antwortet nicht	Prüfe, dass der Gladys-Rechner die Adresse erreicht (Netzwerk, VPN, Firewall, HTTPS-Zertifikat)
Die Adresse von Invoice Ninja leitet weiter	Gib die Adresse ein, bei der der Browser landet, oft mit https://: Weiterleitungen werden nie verfolgt, das Token geht also nie anderswohin
Invoice Ninja begrenzt die Anfragen	Wähle ein längeres Aktualisierungsintervall
Invoice Ninja antwortet mit einem Fehler	Sieh in die Protokolle von Invoice Ninja; die letzten Werte bleiben so lange erhalten

Die Einzelheiten jedes Lesens stehen mit LOG_LEVEL=debug in den Protokollen.

Grenzen

• Ein Unternehmen pro Token: für mehrere Unternehmen braucht es ein Token pro Unternehmen, und eine Installation verfolgt ein Unternehmen.
• Jedes Lesen stellt sechs Anfragen an Invoice Ninja (mehr ab 100 offenen Rechnungen oder Zahlungen im Monat); der gehostete Dienst begrenzt seine API, halte das Intervall also vernünftig.
• Eine als ausstehend erfasste Zahlung (Überweisung noch nicht bestätigt), die später nach mehr als 10 neuen Zahlungen abgeschlossen wird, wird nicht gemeldet.
• Der Schalter „Lokale Verbindung bevorzugen“ von Gladys hat keine Wirkung: es gibt nur eine Adresse. Das Gerät zeigt „lokal“ für einen selbst gehosteten Server und „Cloud“ für invoicing.co.
• Nur lesend: von Gladys aus lässt sich keine Rechnung erstellen, versenden oder als bezahlt markieren.

Konfigurationseinstellungen

Diese Einstellungen fragt Invoice Ninja in seinem Konfigurationsbildschirm in Gladys ab.

Einstellung	Typ	Pflichtfeld	Beschreibung
Verbindung zu Invoice Ninja	section	Nein	Gib die Adresse deines Invoice Ninja 5 (oder https://invoicing.co für den gehosteten Dienst) und ein API-Token an: Einstellungen → Kontoverwaltung → API-Tokens. Füge dann das Unternehmen im Tab „Entdecken“ hinzu.
Adresse von Invoice Ninja	string	Ja	Die Adresse, unter der du Invoice Ninja öffnest, von Gladys aus erreichbar.
API-Token	secret	Ja	Nur lesend: die Integration schreibt nie in deine Rechnungen. Von Gladys gespeichert, nie in die Protokolle geschrieben.
Aktualisierungsintervall	select	Nein	Wie oft Invoice Ninja gelesen wird (jedes Mal sechs Anfragen).
Sprache der Texte	select	Nein	Namen der Funktionen (bei ihrer Erstellung) und Texte für die Szenen.

So installierst du Invoice Ninja in Gladys

1. Öffne in Gladys Integrationen: Invoice Ninja erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
2. Klicke auf Installieren. Gladys lädt das Docker-Image (ghcr.io/guim31/gladys-invoiceninja:1.0.0) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration).
3. Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
4. Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/guim31/gladys-invoiceninja.

Invoice Ninja benötigt Gladys >=5.1.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.

Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.

Über externe Integrationen

Invoice Ninja ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von guim31 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.

• Alle Integrationen durchsuchen, native und aus der Community
• Deine eigene externe Integration bauen und veröffentlichen
• Quellcode auf GitHub — Quelle dieser Dokumentation

Abonniere den Newsletter von Gladys Assistant

Ein paar E-Mails im Monat zu neuen Releases und Neuigkeiten aus dem Projekt. Verschickt von Pierre-Gilles Leymarie, dem Gründer des Projekts. Jederzeit abbestellbar 🙂