Stammdaten-Synchronisation

Übersicht

Dieser Leitfaden erklärt, wie Auftraggeber (Bauunternehmen) ihre Stammdaten aus ERP-Systemen mit comstruct synchronisieren können. Die Stammdaten-Synchronisation stellt sicher, dass Ihre Projekte, Lieferanten, Konten und andere Referenzdaten systemübergreifend aktuell bleiben.

comstruct unterstützt direkte Integration mit SAP und anderen ERP-Systemen. Kontaktieren Sie Ihren Customer Success Manager zur Einrichtung Ihrer Integration.

Stammdatentypen

comstruct unterstützt die Synchronisation folgender Stammdaten:

Datentyp	Beschreibung	Verwendung
Projekte	Bauprojekte und Baustellen	Zuordnung von Lieferungen und Rechnungen
Lieferanten	Lieferanten-/Kreditorinformationen	Verknüpfung von Lieferungen mit Lieferanten
Konten	Sachkonten für Buchungen	Rechnungskontenzuordnung
Zahlungsbedingungen	Zahlungskonditionen	Rechnungsverarbeitung
Steuercodes	MwSt.-/Steuerkonfigurationen	Rechnungssteuerberechnungen
Projektregionen	Regionale Gruppierungen	Projektorganisation
Gesellschaften	Unternehmenseinheiten	Mandantenunterstützung

Voraussetzungen

Bevor Sie Daten synchronisieren, stellen Sie sicher, dass Sie Folgendes haben:

Einen API-Schlüssel mit den entsprechenden Berechtigungen:
- projects:write - Zum Erstellen/Aktualisieren von Projekten
- suppliers:write - Zum Erstellen/Aktualisieren von Lieferanten
- accounts:write - Zur Verwaltung von Sachkonten
- payment_terms:write - Zur Verwaltung von Zahlungsbedingungen
- tax_codes:write - Zur Verwaltung von Steuercodes
- project_regions:write - Zur Verwaltung von Projektregionen
Stammdaten aus Ihrem ERP-System exportiert
Feldzuordnungen für Ihre Datenformate definiert

Authentifizierung

Alle API-Anfragen erfordern eine Authentifizierung mittels eines API-Schlüssels:

curl -X POST "https://api.comstruct.com/v1/projects" \
  -H "x-api-key: IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{"..."}'

Projekt-Synchronisation

Standard-Projekt-Sync

Erstellen oder aktualisieren Sie Projekte mit dem Upsert-Endpunkt:

{
  "external_id": "EXT-2024-001",
  "title": "Autobahnbauprojekt",
  "project_number": "HCP-2024-001",
  "description": "Bau des Autobahnabschnitts A1-A2",
  "region": "Bayern",
  "active": true,
  "address": {
    "address": "Hauptstraße 123",
    "city": "München",
    "zip": "80331"
  },
  "project_invites": [
    {
      "email": "projektleiter@firma.de",
      "role": "Manager"
    }
  ]
}

curl -X POST "https://api.comstruct.com/v1/projects" \
  -H "x-api-key: IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "EXT-2024-001",
    "title": "Autobahnbauprojekt",
    "project_number": "HCP-2024-001",
    "description": "Bau des Autobahnabschnitts A1-A2",
    "region": "Bayern",
    "active": true
  }'

Der Endpunkt führt eine Upsert-Operation durch: Wenn ein Projekt mit derselben external_id oder project_number existiert, wird es aktualisiert. Andernfalls wird ein neues Projekt erstellt.

SAP-Projekt-Sync

Für SAP-Systeme verwenden Sie den dedizierten SAP-Endpunkt mit automatischer Feldzuordnung:

curl -X POST "https://api.comstruct.com/v1/projects/sap" \
  -H "x-api-key: IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "number": "PRJ-2024-001",
      "title": "Autobahnbau A1",
      "type": "Infrastruktur",
      "parent_number": "Bayern",
      "legal_entity_number": "GS-001"
    }
  ]'

SAP-Feldzuordnung:

SAP-Feld	comstruct-Feld	Beschreibung
`number`	`project_number`	Die SAP-Projektnummer
`title`	`title`	Der Projekttitel
`type`	`description`	Der Projekttyp/Beschreibung
`parent_number`	`region`	Wird für Projektregion-Lookup verwendet
`legal_entity_number`	`legal_entity_number`	Wird für Gesellschaftszuordnung verwendet

Lieferanten-Synchronisation

SAP-Lieferanten-Sync

Synchronisieren Sie Lieferanten aus SAP:

curl -X POST "https://api.comstruct.com/v1/suppliers/sap" \
  -H "x-api-key: IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "number": "LIF-001",
      "title": "Beispiel Lieferant GmbH",
      "country_code": "DE",
      "comment": "Bevorzugter Kontakt per E-Mail",
      "payment_term": "30T",
      "legal_uid": "DE123456789",
      "bank_details": [
        {
          "number": "BANK001",
          "iban": "DE89370400440532013000"
        }
      ],
      "address": {
        "address": "Müllerstraße 1",
        "city": "Berlin",
        "zip": "10115",
        "country_code": "DE"
      }
    }
  ]'

Lieferantendaten-Anforderungen

Feld	Erforderlich	Beschreibung
`number`	Ja	Lieferantennummer aus Ihrem ERP
`title`	Ja	Lieferantenname
`country_code`	Ja	ISO 3166-1 Alpha-2 Ländercode
`comment`	Nein	Freitext-Kommentar zum Lieferanten
`payment_term`	Nein	Zahlungsbedingung-Schlüssel (muss, falls angegeben, in comstruct existieren)
`legal_uid`	Nein	USt-IdNr./Steuernummer
`bank_details`	Nein	Bankverbindungsinformationen
`address`	Nein	Lieferantenadresse

Konten-Synchronisation

Sachkonten erstellen oder aktualisieren

curl -X POST "https://api.comstruct.com/v1/accounts" \
  -H "x-api-key: IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "4711",
    "title": "Material - Beton",
    "description": "Sachkonto für Betonmaterialien",
    "active": true
  }'

Bestehende Konten auflisten

curl -X GET "https://api.comstruct.com/v1/accounts" \
  -H "x-api-key: IHR_API_SCHLUESSEL"

Zahlungsbedingungen-Synchronisation

Zahlungsbedingungen erstellen oder aktualisieren

curl -X POST "https://api.comstruct.com/v1/payment-terms" \
  -H "x-api-key: IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "30T",
    "title": "30 Tage netto",
    "days_for_payment": 30,
    "discount_days": 14,
    "discount_percentage": 2.0
  }'

Steuercode-Synchronisation

Steuercodes erstellen oder aktualisieren

curl -X POST "https://api.comstruct.com/v1/tax-codes" \
  -H "x-api-key: IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "V19",
    "title": "MwSt. 19%",
    "percentage": 19.0,
    "active": true
  }'

Projektregionen-Synchronisation

Projektregionen erstellen oder aktualisieren

curl -X POST "https://api.comstruct.com/v1/project-regions" \
  -H "x-api-key: IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "REGION-NORD",
    "title": "Region Nord"
  }'

Synchronisationsstrategien

Vollständige Synchronisation

Eine vollständige Synchronisation ersetzt alle Daten mit den aktuellen aus Ihrem ERP:

Alle Datensätze exportieren

Exportieren Sie alle aktiven Datensätze aus Ihrem ERP-System.

Daten transformieren

Ordnen Sie ERP-Felder dem comstruct-Format zu.

An API senden

Senden Sie alle Datensätze an die entsprechenden Endpunkte.

Fehlende deaktivieren

Markieren Sie Datensätze, die nicht im Export sind, als inaktiv.

Delta-Synchronisation

Eine Delta-Synchronisation aktualisiert nur geänderte Datensätze:

Änderungen verfolgen

Verwenden Sie Änderungsverfolgung in Ihrem ERP, um geänderte Datensätze zu identifizieren.

Änderungen exportieren

Exportieren Sie nur geänderte Datensätze seit der letzten Synchronisation.

Aktualisierungen senden

Senden Sie geänderte Datensätze an die API.

Best Practices

Externe IDs verwenden

Verwenden Sie immer external_id für zuverlässige Upsert-Operationen und zur Aufrechterhaltung der Verknüpfung zwischen Systemen.

Anfragen bündeln

Für SAP-Endpunkte senden Sie mehrere Datensätze in einer einzigen Anfrage für bessere Performance.

Zahlungsbedingungen validieren

Falls Zahlungsbedingungen angegeben werden, stellen Sie sicher, dass die Schlüssel in comstruct existieren, bevor Sie Lieferanten synchronisieren.

Regelmäßige Syncs planen

Richten Sie automatisierte Sync-Jobs ein, um Daten aktuell zu halten.

Fehlerbehandlung

Häufige Fehler

Fehler	Ursache	Lösung
`Payment term not found`	Angegebene Zahlungsbedingung existiert nicht	Zahlungsbedingungen vor Lieferanten synchronisieren oder Feld weglassen
`Duplicate external_id`	Konfliktende externe IDs	Eindeutige externe IDs sicherstellen
`Invalid country_code`	Nicht-ISO Ländercode	ISO 3166-1 Alpha-2 Codes verwenden

Fehlerantwort-Format

{
  "error": "Validation failed",
  "message": "Payment term '60T' not found in tenant"
}

Integrationsarchitektur

Empfehlungen zur Zeitplanung

Datentyp	Sync-Häufigkeit	Begründung
Projekte	Täglich	Hohe Änderungshäufigkeit
Lieferanten	Wöchentlich	Geringere Änderungshäufigkeit
Konten	Wöchentlich	Ändert sich selten
Zahlungsbedingungen	Bei Bedarf	Sehr stabil
Steuercodes	Bei Bedarf	Sehr stabil

Support

Für Integrationsunterstützung:

Kontaktieren Sie Ihren Customer Success Manager
E-Mail: support@comstruct.com
API-Referenz für Endpunkt-Details

Einführung

Integrationsleitfäden

Übersicht

Stammdatentypen

Voraussetzungen

Authentifizierung

Projekt-Synchronisation

Standard-Projekt-Sync

SAP-Projekt-Sync

Lieferanten-Synchronisation

SAP-Lieferanten-Sync

Lieferantendaten-Anforderungen

Konten-Synchronisation

Sachkonten erstellen oder aktualisieren

Bestehende Konten auflisten

Zahlungsbedingungen-Synchronisation

Zahlungsbedingungen erstellen oder aktualisieren

Steuercode-Synchronisation

Steuercodes erstellen oder aktualisieren

Projektregionen-Synchronisation

Projektregionen erstellen oder aktualisieren

Synchronisationsstrategien

Vollständige Synchronisation

Delta-Synchronisation

Best Practices

Externe IDs verwenden

Anfragen bündeln

Zahlungsbedingungen validieren

Regelmäßige Syncs planen

Fehlerbehandlung

Häufige Fehler

Fehlerantwort-Format

Integrationsarchitektur

Empfehlungen zur Zeitplanung

Support

​Übersicht

​Stammdatentypen

​Voraussetzungen

​Authentifizierung

​Projekt-Synchronisation

​Standard-Projekt-Sync

​SAP-Projekt-Sync

​Lieferanten-Synchronisation

​SAP-Lieferanten-Sync

​Lieferantendaten-Anforderungen

​Konten-Synchronisation

​Sachkonten erstellen oder aktualisieren

​Bestehende Konten auflisten

​Zahlungsbedingungen-Synchronisation

​Zahlungsbedingungen erstellen oder aktualisieren

​Steuercode-Synchronisation

​Steuercodes erstellen oder aktualisieren

​Projektregionen-Synchronisation

​Projektregionen erstellen oder aktualisieren

​Synchronisationsstrategien

​Vollständige Synchronisation

​Delta-Synchronisation

​Best Practices

Externe IDs verwenden

Anfragen bündeln

Zahlungsbedingungen validieren

Regelmäßige Syncs planen

​Fehlerbehandlung

​Häufige Fehler

​Fehlerantwort-Format

​Integrationsarchitektur

​Empfehlungen zur Zeitplanung

​Support

Übersicht

Stammdatentypen

Voraussetzungen

Authentifizierung

Projekt-Synchronisation

Standard-Projekt-Sync

SAP-Projekt-Sync

Lieferanten-Synchronisation

SAP-Lieferanten-Sync

Lieferantendaten-Anforderungen

Konten-Synchronisation

Sachkonten erstellen oder aktualisieren

Bestehende Konten auflisten

Zahlungsbedingungen-Synchronisation

Zahlungsbedingungen erstellen oder aktualisieren

Steuercode-Synchronisation

Steuercodes erstellen oder aktualisieren

Projektregionen-Synchronisation

Projektregionen erstellen oder aktualisieren

Synchronisationsstrategien

Vollständige Synchronisation

Delta-Synchronisation

Best Practices

Fehlerbehandlung

Häufige Fehler

Fehlerantwort-Format

Integrationsarchitektur

Empfehlungen zur Zeitplanung

Support