Skip to main content

​
Ü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:
DatentypBeschreibungVerwendung
ProjekteBauprojekte und BaustellenZuordnung von Lieferungen und Rechnungen
LieferantenLieferanten-/KreditorinformationenVerknüpfung von Lieferungen mit Lieferanten
KontenSachkonten für BuchungenRechnungskontenzuordnung
ZahlungsbedingungenZahlungskonditionenRechnungsverarbeitung
SteuercodesMwSt.-/SteuerkonfigurationenRechnungssteuerberechnungen
ProjektregionenRegionale GruppierungenProjektorganisation
GesellschaftenUnternehmenseinheitenMandantenunterstützung

​
Voraussetzungen

Bevor Sie Daten synchronisieren, stellen Sie sicher, dass Sie Folgendes haben:
  1. 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
  2. Stammdaten aus Ihrem ERP-System exportiert
  3. 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": "[email protected]",
      "role": "Manager"
    }
  ]
}
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",
      "accounting_area": "GS-001"
    }
  ]'
SAP-Feldzuordnung:
SAP-Feldcomstruct-FeldBeschreibung
numberproject_numberDie SAP-Projektnummer
titletitleDer Projekttitel
typedescriptionDer Projekttyp/Beschreibung
parent_numberregionWird für Projektregion-Lookup verwendet
accounting_arealegal_entity_numberWird 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",
      "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

FeldErforderlichBeschreibung
numberJaLieferantennummer aus Ihrem ERP
titleJaLieferantenname
country_codeJaISO 3166-1 Alpha-2 Ländercode
payment_termJaZahlungsbedingung-Schlüssel (muss in comstruct existieren)
legal_uidNeinUSt-IdNr./Steuernummer
bank_detailsNeinBankverbindungsinformationen
addressNeinLieferantenadresse

​
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:
1

Alle Datensätze exportieren

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

Daten transformieren

Ordnen Sie ERP-Felder dem comstruct-Format zu.
3

An API senden

Senden Sie alle Datensätze an die entsprechenden Endpunkte.
4

Fehlende deaktivieren

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

​
Delta-Synchronisation

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

Änderungen verfolgen

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

Änderungen exportieren

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

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

Stellen Sie sicher, dass Zahlungsbedingungen-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

FehlerUrsacheLösung
Payment term not foundReferenzierte Zahlungsbedingung existiert nichtZahlungsbedingungen vor Lieferanten synchronisieren
Duplicate external_idKonfliktende externe IDsEindeutige externe IDs sicherstellen
Invalid country_codeNicht-ISO LändercodeISO 3166-1 Alpha-2 Codes verwenden

​
Fehlerantwort-Format

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

​
Integrationsarchitektur

​
Empfehlungen zur Zeitplanung

DatentypSync-HäufigkeitBegründung
ProjekteTäglichHohe Änderungshäufigkeit
LieferantenWöchentlichGeringere Änderungshäufigkeit
KontenWöchentlichÄndert sich selten
ZahlungsbedingungenBei BedarfSehr stabil
SteuercodesBei BedarfSehr stabil

​
Support

Für Integrationsunterstützung: