Public API: Eigene Software mit Norman verbinden

Was kann ich mit der API umsetzen?

Über die Public API kann Software unterstützte Norman-Datensätze mit HTTP-Anfragen lesen oder ändern. Du kannst Transaktionen in ein Dashboard übernehmen, Kunden aus deinem CRM pflegen, Rechnungsentwürfe vorbereiten oder Belege hochladen.

Die öffentliche Referenz umfasst Unternehmensdaten, Transaktionen, bestehende Bankverbindungen, Kunden, den Produkt- und Leistungskatalog, Rechnungen, wiederkehrende Rechnungspläne, Dokumente sowie das Lesen von Steuerberichten und Steuereinstellungen. Auch Dokumentenerkennung, PDF/XML-Abruf und die Zuordnung von Rechnungen zu Zahlungen sind enthalten. Die verfügbaren Aktionen unterscheiden sich je Ressource. Zahlungen, Bankautorisierung und das Einreichen von Steuererklärungen gehören nicht zu diesem Public-API-Vertrag.

Die genauen Operationen, Felder und Beispiele stehen in der Entwicklerdokumentation. Wenn du die OpenAPI-JSON-Datei für deine Integration brauchst, wende dich an den Support.

Den passenden Ablauf wählen

• Dokumente und OCR: Lade einen Beleg hoch, lies erkannte Felder aus, starte die Erkennung erneut oder sende einen Bildausschnitt. Bereits verarbeitete Dokumente lassen sich ohne OCR importieren; eine externe Quelle und ID machen Wiederholungen zuordenbar.
• Stapelverarbeitung: Lade bis zu 20 Dokumente mit höchstens 10 MB pro Datei und 50 MB insgesamt hoch. Frage anschließend Fortschritt, erstellte Transaktionen und Fehler je Datei ab. Dabei können Transaktionen erstellt oder zugeordnet werden. Der Upload benötigt daher write_documents und write_transactions, die Statusabfrage beide Leseberechtigungen. Ein abgeschlossener Auftrag kann fehlgeschlagene Dateien enthalten.
• Zusätzliche Belege: Hänge einen Lieferschein oder eine weitere Datei ohne OCR an eine Transaktion, ohne den Hauptbeleg zu ersetzen. Korrekturen an Dokumentdaten können verknüpfte Transaktionen aktualisieren und benötigen beide Schreibberechtigungen.
• Rechnungen: Synchronisiere Produkte und Leistungen, hole einen Vorschlag für die nächste Rechnungsnummer, rufe PDF/XML ab, ordne Zahlungen zu und sende zulässige Mahnungen. Lies einen bestehenden Wiederholungsplan oder stoppe die Serie. Für den Produktkatalog gelten die Rechnungsberechtigungen.
• Vertragsvorschläge: Lies Rechnungsbedingungen aus einem Vertrag aus und prüfe Empfänger, Beträge, Termine und Hinweise, bevor du eine Rechnung erstellst. Positionspreise im Vorschlag verwenden Hauptwährungseinheiten, beim Erstellen einer Rechnung dagegen Untereinheiten. Der Vorschlag erstellt oder versendet selbst keine Rechnung.

Die vollständigen Beispiele findest du unter Dokumente und OCR und Rechnungsabläufe. Jede Operation nennt ihre benötigten Berechtigungen.

Einen Schlüssel erstellen

1. Öffne Automatisierungen → Integrationen → Public API oder die Schlüsselverwaltung.
2. Wähle das Unternehmen, auf dessen Daten die Integration zugreifen soll. Kopiere bei Bedarf seine Unternehmens-ID.
3. Erstelle einen benannten Schlüssel, wähle seine Rechte und ein Ablaufdatum. Für Berichte reicht zunächst Nur Lesen / Read only. Rechnungsstellung / Invoicing umfasst Lese- und Schreibrechte für Kunden und Rechnungen.
4. Kopiere den angezeigten Schlüssel. Der vollständige Wert wird nur einmal angezeigt; die Liste zeigt weiterhin Präfix und Status.
5. Speichere ihn als Umgebungsvariable auf deinem Server oder im Zugangsdaten-Speicher deines Automatisierungstools. Er gehört nicht in eine öffentliche Webseite, ein Repository, einen Screenshot oder einen geteilten Workflow-Export.

Ein Schlüssel, ein Unternehmen

Sende Authorization: Bearer YOUR_API_KEY mit der Anfrage. Der Schlüssel ist an sein Unternehmen gebunden. Unternehmens-IDs im Pfad, im Request-Body oder im optionalen Header X-Company-Id müssen dazu passen. Referenzierte Kunden und Dokumente müssen ebenfalls zu diesem Unternehmen gehören.

Lese- und Schreibrechte sind getrennt. read_transactions erlaubt das Lesen von Transaktionen. write_invoices erlaubt unterstützte Rechnungsänderungen, enthält aber nicht automatisch Leserechte für Rechnungen. full_access umfasst die öffentlichen Operationen für das Unternehmen des Schlüssels. Accountrechte, Tarifanforderungen und Dokumentstatus gelten weiterhin.

Die erste Anfrage senden

Dieses Beispiel liest das Unternehmen des Schlüssels. Ersetze den Platzhalter lokal:

export NORMAN_API_KEY='nrm_replace_with_your_key'

curl --fail-with-body 'https://api.norman.finance/api/v1/companies/' \
  -H "Authorization: Bearer $NORMAN_API_KEY"

Bei Erfolg erhältst du HTTP-Status 200 und eine Liste results. Speichere die publicId des Unternehmens für Pfade, die eine Unternehmens-ID benötigen. Archivierte Unternehmen sind standardmäßig ausgeblendet; nutze bei Bedarf ?include_archived=true.

Mit read_transactions kannst du danach die erste Seite der Transaktionen lesen:

curl --fail-with-body 'https://api.norman.finance/api/v1/accounting/transactions/?page=1&page_size=20' \
  -H "Authorization: Bearer $NORMAN_API_KEY"

Listenantworten enthalten results, next, previous und count. Folge für einen vollständigen Export next, bis der Wert null ist. Eine leere Transaktionsliste kann eine erfolgreiche Antwort sein.

Den nächsten Schritt umsetzen

Die Beispiele zeigen Kundenanlage, Rechnungsentwürfe, Dokument-Uploads und Exporte über mehrere Seiten. JSON-Felder verwenden camelCase; Query-Parameter wie page_size schreibst du wie in der Referenz. Transaktionsbeträge und Preise pro Rechnungsposition verwenden die kleinste Währungseinheit: 4999 entspricht bei EUR 49,99 €. Prüfe das Request-Schema, bevor du Antwortwerte für eine Änderung übernimmst.

Schlüssel wechseln und Fehler lösen

Erstelle einen Ersatzschlüssel, aktualisiere die Integration, prüfe eine Anfrage und widerrufe anschließend den alten Schlüssel. Abgelaufene oder widerrufene Schlüssel funktionieren nicht mehr. Der Zugriff hängt außerdem vom aktuellen Account- und Unternehmenszugriff der Person ab, die den Schlüssel erstellt hat.

• 401: Prüfe den Bearer-Header sowie Ablaufdatum und Widerruf.
• 403: Prüfe Rechte, Unternehmen, unterstützte Operation und Accountanforderungen.
• 400 oder 422: Korrigiere anhand der Antwort die Feldwerte oder den Dokumentstatus.
• 429: Warte die im Header Retry-After genannte Zeit ab.

Prüfe nach einem Timeout vor einer erneuten Schreibanfrage, ob der Datensatz bereits angelegt wurde. Mehr dazu unter Fehler und Wiederholungen.

Für visuelle Abläufe geht es mit n8n oder Make weiter. Für KI-Assistenten nutze die MCP-Anleitung.