Integrationsleitfaden Schritt für Schritt

Diese Seite richtet sich an IT- und Integrationsverantwortliche, die die Daten ihres Unternehmens an TheFinly senden. Es gibt zwei Wege: automatisches Senden aus Ihrem ERP per API oder manueller Upload mit der Excel-Vorlage.

A) Senden per API

Endpunkte

Summen- und Saldenliste: POST https://<domain>/api/v1/ingest/trial-balance
Offene Posten (Fälligkeitsanalyse Forderungen und Verbindlichkeiten): POST https://<domain>/api/v1/ingest/open-items
Lagerbewegungen: POST https://<domain>/api/v1/ingest/inventory. asOfDate (yyyy-MM-dd) ist optional. Fehlt es, auch im strikten Modus, wird der Bestandsstichtag aus dem letzten Bewegungsdatum abgeleitet, und die Antwort enthält eine Warnung.

Request-Header

Nur HTTPS und POST werden akzeptiert.
Content-Type: application/json
Authorization: Bearer <API_KEY> oder X-Api-Key: <API_KEY>
Das Unternehmen wird immer aus dem API-Schlüssel abgeleitet; geben Sie keine Unternehmens-ID im Body an.

API-Schlüssel

Die Unternehmensleitung Ihres Unternehmens erstellt den Schlüssel auf der Seite Integrationen in TheFinly und übergibt ihn Ihnen über einen sicheren Kanal.
Der Schlüssel wird nur einmal angezeigt; bewahren Sie ihn sicher auf. Teilen Sie ihn nicht per E-Mail oder in Dokumenten.
Wird der Schlüssel bekannt, widerruft die Unternehmensleitung ihn sofort und erstellt einen neuen. Ein Widerruf wirkt sofort.

Minimaler Beispiel-Body (Summen- und Saldenliste)

{
  "externalId": "demo-2024-12",
  "period1": {
    "label": "2023",
    "periodEnd": "2023-12-31",
    "lines": [
      { "accountCode": "DEMO-001", "debit": 400000, "credit": 0, "balance": 400000, "templateKey": "HAZIR_DEGERLER" }
    ]
  },
  "period2": {
    "label": "2024",
    "periodEnd": "2024-12-31",
    "lines": [
      { "accountCode": "DEMO-001", "debit": 450000, "credit": 0, "balance": 450000, "templateKey": "HAZIR_DEGERLER" }
    ]
  }
}

Das Beispiel ist synthetisch und gekürzt. Die vollständige Feldliste, Pflichtschlüssel und den Body für offene Posten finden Sie im API-Dokument, das Ihrem Unternehmen übermittelt wurde. In JSON sind Datumsangaben yyyy-MM-dd und Beträge einfache Zahlen (z. B. 4800000).

Antwortcodes im Überblick

401: Schlüssel fehlt, ist ungültig oder widerrufen.
403: Das Unternehmenskonto ist gesperrt.
409: Dieselbe externalId wurde bereits mit anderem Inhalt gesendet.
413: Request-Body zu groß (höchstens 4 MB).
422: Validierungsfehler; es wird nichts gespeichert, siehe Fehlerliste.
429: Ratenlimit überschritten; kurz warten und erneut versuchen.

B) Manueller Upload mit Excel

Vorlage herunterladen:
Füllen Sie die Vorlage mit den Daten Ihres Unternehmens aus; ändern Sie die Spaltenüberschriften nicht.
Melden Sie sich bei TheFinly an und laden Sie die Datei auf der Seite Hochladen hoch.

Der ERP-Datenimport (Integrationen → Import) erfordert die Berechtigung der Unternehmensleitung.

C) Support

Wenden Sie sich bei Fragen zuerst an die Unternehmensleitung Ihres Unternehmens und bei Bedarf an den TheFinly-Support (support@thefinly.com).

Bei TheFinly anmelden