Zum Hauptinhalt springen

​
Ü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": "projektleiter@firma.de",
      "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",
      "legal_entity_number": "GS-001"
    }
  ]'
SAP-Feldzuordnung:
SAP-Feldcomstruct-FeldBeschreibung
numberproject_numberDie SAP-Projektnummer
titletitleDer Projekttitel
typedescriptionDer Projekttyp/Beschreibung
parent_numberregionWird für Projektregion-Lookup verwendet
legal_entity_numberlegal_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_termNeinZahlungsbedingung-Schlüssel (muss, falls angegeben, 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

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

FehlerUrsacheLösung
Payment term not foundAngegebene Zahlungsbedingung existiert nichtZahlungsbedingungen vor Lieferanten synchronisieren oder Feld weglassen
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: