Zum Inhalt springen

Schnittstellen

Über die Schnittstelle (API) sprechen andere Programme direkt mit fineelik. Das brauchen Sie nur, wenn Sie eigene Software anbinden wollen. Diese Seite erklärt die Einrichtung, die technischen Einzelheiten stehen in der API-Referenz (englisch).

Alles liegt unter Einstellungen, Schnittstellen und gehört zum Grundpaket.

  • Abholen (Pull): Ihr System fragt fineelik regelmäßig nach neuen Ereignissen und Rechnungsdaten. Dafür brauchen Sie einen API-Schlüssel.
  • Webhooks: fineelik meldet Ereignisse von selbst an eine HTTPS-Adresse. Der Empfänger ruft die Rechnungsdaten dann über die API ab.

Ein API-Schlüssel ist der Zugang für eine Maschine. Administratoren legen ihn an.

  1. Legen Sie den Schlüssel an. Vergeben Sie einen Namen (bis 32 Zeichen) und wählen Sie die Laufzeit: 90, 180 oder 365 Tage.
  2. Ordnen Sie ihn Ihrem Buchungskreis zu. Ein Schlüssel arbeitet immer nur in genau einem Buchungskreis. Ohne Zuordnung gilt der Standardbuchungskreis. Für mehrere Buchungskreise legen Sie je einen Schlüssel an.
  3. Kopieren Sie ihn sofort. Er erscheint nur einmal.
  4. Hinterlegen Sie ihn im anderen System.

Ein Schlüssel darf nur einliefern, Rechnungen lesen und eine Freigabe von außen zurückmelden. Die Rückmeldung einer Freigabe klappt nur, wenn der Besitzer Administrator ist. Der Schlüssel gehört der Person, die ihn anlegt. Wird deren Konto deaktiviert, funktioniert er nicht mehr. Er lässt sich jederzeit zurückziehen. Was er darf, steht unter Authentication.

Mit dem Modul Verträge übergibt ein Schlüssel außerdem Verträge aus ELO und liest ihren Stand (Rechte agreements.integration_write und agreements.integration_read). Diese Rechte hat nur der Administrator, der Schlüssel muss also einem Administrator gehören.

  1. Klicken Sie auf Webhook anlegen.
  2. Tragen Sie die Adresse ein, sie muss mit https:// beginnen.
  3. Wählen Sie die Ereignisse und den Buchungskreis.
  4. Kopieren Sie das Geheimnis. Es ist nur einmal sichtbar. Der Empfänger prüft damit die Signatur.
  5. Klicken Sie in der Lade auf Test senden.
Ereignis Wann fineelik es meldet
Beleg angenommen Ein Beleg ist eingegangen, per Upload, E-Mail oder aus dem führenden System
Status geändert Jeder Statuswechsel, zum Beispiel freigegeben oder abgelehnt
Daten nach der Prüfung geändert Kontierung oder Beträge wurden korrigiert, ohne dass sich der Status ändert
Verarbeitung gescheitert Die Verarbeitung ist nach allen Versuchen fehlgeschlagen
Vertrag: Bedingungen freigegeben Die Abgleichsbedingungen eines in ELO geführten Vertrags wurden in fineelik freigegeben.
Vertrag: Bedingungen geändert Die Abgleichsbedingungen eines in ELO geführten Vertrags haben sich geändert oder warten auf eine Freigabe.
Vertrag: Partner zugeordnet Der Vertragspartner eines in ELO geführten Vertrags wurde einem Lieferanten zugeordnet.
Vertrag: Schlagworte geändert Die Schlagworte eines in ELO geführten Vertrags haben sich geändert.
Vertrag: Automatik geändert Der Schalter “automatisch freigeben” eines in ELO geführten Vertrags wurde geändert.

Mit dem Modul Verträge tragen die Rechnungsdaten und jedes Ereignis zusätzlich einen Vertragsblock: zu welchem Vertrag die Rechnung gehört, das Ergebnis des Abgleichs (Sollbetrag, Istbetrag, Abweichung und erlaubte Abweichung) und ob fineelik die Rechnung automatisch freigeben würde, samt den Gründen dagegen. So kann ein führendes System wie ELO seine Freigabe überspringen, wenn alles passt. Bei vertraulichen Verträgen steht für Maschinen nur das Ergebnis und ob eine automatische Freigabe möglich wäre, keine Nummer und keine Beträge. Die einzelnen Felder stehen in der API-Referenz.

Mit dem Modul Verträge übergibt die ELO-Komponente Verträge aus ELO Contract an fineelik und bekommt zurück, was fineelik dazu pflegt:

  • Übergabe: Die Komponente schickt den Vertrag mit seiner Kennung in ELO bei jeder Anlage und Änderung. Derselbe Stand noch einmal ändert nichts, ein älterer Stand wird nicht übernommen.
  • Dokument: Das Vertragsdokument kommt einzeln dazu. Dasselbe Dokument zweimal legt fineelik nur einmal ab.
  • Rückweg: Die Ereignisse Vertrag: … oben melden Freigabe, geänderte Bedingungen, Partnerzuordnung, Schlagworte und die Automatik, jeweils mit dem ganzen Stand des Vertrags.
  • In den Rechnungsdaten trägt der Vertragsblock bei Verträgen aus ELO die Kennung des Vertrags in ELO. Ändert sich nur der Vertragsblock einer schon geprüften Rechnung, meldet fineelik Daten nach der Prüfung geändert.
  • Läuft die Freigabe außerhalb von fineelik, zählt die Rückmeldung aus ELO für die Stichprobe der automatischen Freigabe genau einmal je Rechnung.

Die Einzelheiten für Entwickler stehen unter Contracts from ELO (englisch).

Die Liste zeigt den Zustand je Webhook: Läuft, Pausiert, Scheitert seit … oder Kein Zugriff.

  • fineelik versucht es mit wachsendem Abstand weiter: nach 1, 5, 15 und 60 Minuten, danach alle 6 Stunden. Ereignisse bleiben erhalten.
  • Der Empfänger muss innerhalb von 10 Sekunden mit einem 2xx-Status antworten.
  • Pausieren stoppt die Zustellung, nach dem Fortsetzen liefert fineelik nach. Auch eine neue Adresse löst sofort einen neuen Versuch aus.
  • Nach Geheimnis erneuern scheitern die Zustellungen, bis der Empfänger das neue Geheimnis kennt.
  • Kein Zugriff heißt: Die Person, die den Webhook angelegt hat, hat keinen Zugriff mehr auf die Buchungskreise des Webhooks, darf keine Rechnungen mehr sehen oder ihr Konto ist deaktiviert. Geben Sie den Zugriff zurück, dann liefert fineelik nach. Oder legen Sie den Webhook neu an.
  • Webhooks anlegen und ändern darf nur die Administration. Wer Einstellungen lesen darf, sieht sie.
  • Das Zustellprotokoll zeigt jede Zustellung, Einträge älter als 30 Tage werden gelöscht.

Die Karte KI-Assistenten (Claude, ChatGPT) auf derselben Seite schaltet den Zugang für Claude und ChatGPT und legt fest, welche Rollen sie verbinden dürfen. Mehr dazu unter KI-Assistenten.

Die Karte Dokumentenverwaltung auf derselben Seite verbindet fineelik mit ELO, siehe fineelik mit ELO.