NexAI CRM: Datenformate

Register der Datenstrukturen und Datenformate nach Art. 26 Buchst. b der Verordnung (EU) 2023/2854 (Data Act), zusammen mit der Beschreibung der offenen Schnittstelle nach Art. 30 Abs. 2 (crm-openapi.json, OpenAPI 3.1). Maschinenlesbar steht dasselbe in crm-datenformate.json.

Diese Datei wird aus dem Quelltext des CRM erzeugt und gilt für die Fassung, mit der sie ausgeliefert wird.

1. Wege, die Daten zu erhalten

• Gesamtexport — alle Datensätze der Organisation als ZIP mit einer CSV-Datei je Tabelle (Abschnitt 2–4). In der Oberfläche auf der Seite „Datenschutz“; über die Schnittstelle GET /api/tenant-export.
• Dateipaket — die Dateien selbst (Abschnitt 5); über die Schnittstelle GET /api/tenant-export/dateien.
• Programmierschnittstelle — lesender Zugriff auf Kontakte, Firmen, Anfragen, Deals, Aufgaben, Termine, Anrufe, Dateien und Belege; beschrieben in crm-openapi.json.
• Einzelne Belege und Buchhaltung — Beleg-PDF, XML der E-Rechnung und DATEV-Dateien (Abschnitt 6).

2. Aufbau des Gesamtexports

Eine ZIP-Datei (Kompression Deflate) mit dem Namen nexai-crm-export-JJJJ-MM-TT.zip. Sie enthält 64 CSV-Dateien, eine je Tabelle, und die Textdatei LIESMICH.txt (UTF-8), die den Inhalt kurz beschreibt. Jede CSV-Datei steht auch dann im Paket, wenn sie keine Zeilen hat — dann nur mit der Kopfzeile.

3. Regeln für alle CSV-Dateien

• Format nach RFC 4180: Komma als Trennzeichen, Zeilenende CRLF.
• Erste Zeile: die Spaltennamen, wie in den Tabellen unten.
• Ein Feld steht in doppelten Anführungszeichen, wenn es ein Komma, ein Anführungszeichen oder einen Zeilenumbruch enthält; ein Anführungszeichen darin wird verdoppelt.
• Zeichenkodierung UTF-8 (RFC 3629) mit Byte-Order-Mark (EF BB BF) am Dateianfang.
• Ein leeres Feld heißt: kein Wert. Ein leerer Text und „kein Wert“ sind in der CSV nicht zu unterscheiden.
• Die Reihenfolge der Zeilen ist nicht festgelegt.
• Gelöschte Datensätze im Papierkorb sind enthalten; sie tragen einen Zeitpunkt in deleted_at.
• Beträge sind Ganzzahlen in Cent, Mengen in Tausendsteln, Steuersätze und Rabatte in Basispunkten — es gibt keine Dezimalzahlen.
• Spalten vom Typ UUID verweisen auf die Spalte id der genannten Datei.

4. Datentypen

Einheiten bei Ganzzahlen stehen in der Spaltenbeschreibung (z. B. „in Cent“).

5. Das Dateipaket

Ein ZIP mit allen Dateien, die im CRM liegen — Byte für Byte: hochgeladene Dateien (Ordner dateien/anhaenge/), abgelegte Beleg-PDFs (belege/pdf/), die XML der E-Rechnungen (belege/e-rechnung/), die Anhänge verschickter Mails (mails/anhaenge/) und das Logo der Organisation (einstellungen/logo.png, .jpg, .svg oder .webp — je nach Bildtyp; in einstellungen.csv steht es nicht). Jeder andere Dateiname beginnt mit der Kennung und einem Bindestrich, danach folgt der Originalname (Zeichen, die ein Dateisystem nicht verträgt, durch _ ersetzt). Dazu LIESMICH.txt und zuordnung.csv (Regeln wie bei allen CSV-Dateien, Spalten unten). Ein Teil umfasst höchstens die gewählte Größe (Vorgabe 2.000 MB) und 60.000 Dateien, geordnet nach Art und Anlagedatum; weitere Teile über ?teil=2, ?teil=3 … Die Zahl der Teile nennen die Kopfzeile x-nexai-teile und GET /api/tenant-export/dateien/umfang. Nicht enthalten: Dateien, deren Inhalt ein Löschlauf schon entfernt hat, und PDFs von Entwürfen und nie per Mail verschickten Angeboten oder Auftragsbestätigungen (sie entstehen bei jedem Abruf neu).

Spalten von zuordnung.csv:

6. Weitere Formate

• Beleg-PDF (GET /api/documents/{id}/pdf): PDF/A-3b nach ISO 19005-3. Herausgegebene Belege werden genau so geliefert, wie sie abgelegt wurden; die Kopfzeile x-nexai-sha256 trägt dann ihren SHA-256.
• E-Rechnung (GET /api/documents/{id}/einvoice): die abgelegte XML nach EN 16931 in der Syntax UN/CEFACT CII — als ZUGFeRD/Factur-X (Profil EN 16931, eingebettet in das PDF/A-3) oder als XRechnung 3.0. Die Kennung der Spezifikation (BT-24) steht in e-rechnungen.csv.
• DATEV (GET /api/datev/…): Buchungsstapel und Debitoren im DATEV-Format EXTF Version 700, Zeichenkodierung Windows-1252, Semikolon als Trennzeichen; dazu eine lesbare Umsatzliste als CSV mit Semikolon (Windows-1252).
• Kalender: Termine lassen sich zusätzlich als Kalender-Abonnement im Format iCalendar (RFC 5545) abrufen; jede Person legt ihre Abo-Adresse in der Oberfläche selbst an.

7. Normen und Spezifikationen

• RFC 4180 — CSV-Dateien
• RFC 3629 — UTF-8
• RFC 8259 — JSON
• RFC 3339 — Datum und Uhrzeit (Profil von ISO 8601)
• ISO 8601 — Darstellung von Datum und Uhrzeit
• RFC 9562 — UUID
• ISO 4217 — Währungscodes
• ISO 3166-1 alpha-2 — Ländercodes
• UN/ECE Recommendation 20 — Codes für Maßeinheiten
• FIPS 180-4 — SHA-256
• APPNOTE (PKWARE) — ZIP-Dateiformat
• ISO 19005-3 — PDF/A-3 (Beleg-PDFs als PDF/A-3b)
• EN 16931-1:2017 — Europäische Norm für die elektronische Rechnung, Syntax UN/CEFACT CII
• ZUGFeRD / Factur-X — Hybride E-Rechnung (PDF/A-3 mit eingebetteter CII-XML), Profil EN 16931
• XRechnung 3.0 — Deutscher Standard der E-Rechnung (CII-Syntax)
• DATEV-Format EXTF, Version 700 — Buchungsstapel (Kategorie 21) und Debitoren (Kategorie 16)
• RFC 5545 — iCalendar
• RFC 6750 — Bearer-Token für die Programmierschnittstelle
• OpenAPI 3.1 — Beschreibung der Schnittstelle

8. Was nicht exportiert wird, und warum

• Zugänge: API-Schlüssel, Anmeldesitzungen, Wiederherstellungscodes und Marken zum Zurücksetzen des Passworts. Sie sind kein Datenbestand, sondern ein Schlüssel zum System; im neuen System werden sie neu angelegt.
• Verbindungen zu fremden Konten (eigenes Postfach, Kalender, Absendernummer) mit ihren Zugangsdaten. Im neuen System verbindet man sie neu.
• Kalender-Abo-Adressen und eingetragene Kalender-Links. Die Adresse selbst ist ein Zugang; die Termine stehen in termine.csv.
• Technik des Kalenderabgleichs und zwischengespeicherte belegte Zeiten aus dem eigenen Kalender der Mitarbeitenden. Sie werden beim nächsten Abgleich neu gelesen.
• Das Zustellprotokoll der Webhooks: Kopien von Daten, die ohnehin im Paket stehen.
• Der Stammsatz der Organisation selbst (Name und Kürzel im System); ihre Einstellungen stehen in einstellungen.csv.

In den exportierten Dateien fehlen außerdem bewusst:

• Passwort-Hashes und Zwei-Faktor-Geheimnisse der Benutzer.
• Signaturgeheimnisse der Webhooks sowie Geheimnisse und Konfiguration der verbundenen Dienste.
• Das Antwortkennzeichen einer Mail (ein Zugang zum Mailfaden) und Kennungen beim Mailanbieter.
• Interne Angaben zur Aufbewahrung und Versandtechnik (z. B. Wiederholungszeitpunkte).
• Das hinterlegte Logo in einstellungen.csv — es steht als Bilddatei im Dateipaket.

9. Die Dateien im Einzelnen

kontakte.csv

Personen: Kundinnen, Interessenten, Ansprechpartner.

firmen.csv

Firmen mit Anschrift, Rechnungsangaben und Stammdaten der E-Rechnung.

anfragen.csv

Anfragen (Leads): Interesse, das noch kein Geschäft ist.

deals.csv

Deals (Vorgänge) in einer Pipeline, mit Wert, Phase und Ausgang.

objekte.csv

Objekte: Geräte, Fahrzeuge, Anlagen, Verträge — was bei einem Kunden steht oder läuft.

sms.csv

SMS an Kontakte, mit Zustellstand und Umfang.

zahlungseingaenge.csv

Zahlungen, die zu einer Rechnung eingegangen sind.

freigabe-regeln.csv

Regeln, ab welchem Rabatt ein Beleg eine Freigabe braucht.

freigaben.csv

Freigabeanfragen: wer welchen Rabatt beantragt, genehmigt oder abgelehnt hat.

automatisierungen.csv

Automatisierungen: Regeln „wenn Ereignis, dann Aufgabe oder Notiz“.

automatisierungen-protokoll.csv

Protokoll der Automatisierungen: warum eine Regel ausgelöst hat oder nicht.

abwesenheiten.csv

Abwesenheiten (Urlaub) mit Vertretung und Übergabe; ohne Grund der Abwesenheit.

feste-berichte.csv

Feste Berichte: welcher Bericht wie oft an wen per Mail geht. Ohne Zahlen.

chargen.csv

Chargen und Seriennummern von Artikeln. Der Bestand ergibt sich aus lagerbewegungen.csv.

lagerbewegungen.csv

Das Bewegungsbuch des Lagers. Der Bestand ist die Summe von quantity_milli.

wiederkehrendes.csv

Wiederkehrende Termine (Wartung, Prüfung, Verlängerung) an einem Datensatz.

preisverzeichnis.csv

Artikel und Leistungen mit Preis und Steuersatz.

deal-positionen.csv

Positionen eines Deals (Grundlage der Belege).

termine.csv

Termine im CRM.

belege.csv

Angebote, Auftragsbestätigungen, Rechnungen und Stornos. Absender und Empfänger stehen als eingefrorener Stand in JSON-Spalten.

beleg-positionen.csv

Positionen der Belege.

abo-vertraege.csv

Abo-Verträge der monatlichen bzw. jährlichen Abrechnung.

abo-pausen.csv

Frühere, beendete Pausen eines Abo-Vertrags (ab paused_from bis vor resumed_on).

abo-preise.csv

Preis eines Abo-Vertrags je Periode ab einem Monat (beim Jahresvertrag der Jahresbetrag).

abo-zusatzposten.csv

Zusatzposten eines Abo-Vertrags (z. B. weitere Zugänge).

abrechnungslaeufe.csv

Monatliche Abrechnungsläufe (einer je Monat).

abrechnungslauf-posten.csv

Ergebnis eines Abrechnungslaufs je Firma.

abgerechnet.csv

Welche Abrechnungsperiode schon berechnet ist und auf welchem Beleg — verhindert Doppelrechnungen.

belegnummern.csv

Stand der Nummernkreise je Belegart und Jahr.

briefvorlagen.csv

Vorlagen für Einleitung und Schluss je Belegart.

pipelines.csv

Pipelines (Abfolgen von Phasen für Deals).

pipeline-phasen.csv

Phasen einer Pipeline.

anrufe.csv

Telefonate, z. B. vom Sprachassistenten, mit Ergebnis und vereinbartem Termin.

gespraechsprotokolle.csv

Wortlaut der Gespräche (im System verschlüsselt, im Export lesbar).

verarbeitungszwecke.csv

Zwecke, zu denen personenbezogene Daten verarbeitet werden.

einwilligungen.csv

Rechtsgrundlage je Kontakt und Zweck, mit Einwilligung und Widerruf.

werbewidersprueche.csv

Werbewidersprüche (Art. 21 Abs. 3 DSGVO): die Sperrliste gegen Direktwerbung, eine Zeile je Kennung (Telefonnummer, E-Mail-Adresse oder Firmen-Domain) und Umfang. Sie gilt auch für Kontakte, die später angelegt werden, und bleibt bestehen, wenn der Kontakt gelöscht wird. Eine Zeile wird nie gelöscht, nur aufgehoben. Die Kennung selbst steht im System nur als Schlüsselhash, der nur in dieser Installation etwas bedeutet — er ist nicht in der Datei; hint zeigt sie absichtlich unvollständig. Wer die Sperrliste in ein anderes System übernimmt, trägt die Widersprüche dort anhand der Kontakte neu ein.

aufgaben.csv

Aufgaben und Wiedervorlagen.

notizen.csv

Notizen an Kontakten, Firmen, Anfragen, Deals und Objekten.

beleg-dateien.csv

Abgelegte Beleg-PDFs: Größe und Fingerabdruck. Die Dateien selbst liefert das Dateipaket.

e-rechnungen.csv

Ausgestellte E-Rechnungen (XML): Spezifikation, Größe, Fingerabdruck.

dateien.csv

Hochgeladene Dateien: Name, Typ, Größe. Die Dateien selbst liefert das Dateipaket.

mails.csv

Ein- und ausgehende E-Mails zu Kontakten.

mail-anhaenge.csv

Welche Mail welchen Beleg als Anhang trug — Verweis, Dateiname, Größe, Fingerabdruck.

zusatzfelder.csv

Selbst angelegte Zusatzfelder je Datensatzart.

zusatzfeld-werte.csv

Werte der Zusatzfelder.

gespeicherte-ansichten.csv

Gespeicherte Ansichten (Filter) der Listen.

aenderungshistorie.csv

Änderungsprotokoll: wer wann was getan hat.

aufbewahrungsregeln.csv

Aufbewahrungs- und Löschregeln je Datenart.

loeschauftraege.csv

Nachweis durchgeführter Löschungen und Anonymisierungen.

systemereignisse.csv

Ereignisse im System (Zeitleiste, Auslöser für Automatisierungen und Webhooks).

benutzer.csv

Benutzerkonten — ohne Passwort und ohne Zwei-Faktor-Geheimnis.

rollen.csv

Rollen.

rollenrechte.csv

Rechte je Rolle.

benutzerrollen.csv

Welche Person welche Rolle hat.

vertriebspartner.csv

Vertriebspartner, wie sie aus dem Partnerportal gemeldet werden.

einstellungen.csv

Einstellungen der Organisation: Absender auf Belegen, Bankverbindung, Schalter. Ohne Logo — das steht als Bilddatei im Dateipaket (einstellungen/logo.…).

webhooks.csv

Ausgehende Webhooks — ohne das Signaturgeheimnis.

integrationen.csv

Verbundene Dienste — ohne Geheimnis und ohne Konfiguration.

standorte.csv

Standorte (Filialen).

standort-zuordnung.csv

Welche Person zu welchem Standort gehört.

teams.csv

Teams.

team-zuordnung.csv

Wer zu welchem Team gehört.

hinweise.csv

Hinweise des Systems an die Verwaltung (z. B. Betriebsstörungen).