> ## Documentation Index
> Fetch the complete documentation index at: https://developer.comstruct.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Stammdaten-Synchronisation

> Vollständiger Leitfaden für Auftraggeber zur Synchronisation von Stammdaten aus ERP-Systemen

## Ü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.

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

## 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:

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:

```bash theme={null}
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:

<CodeGroup>
  ```json Anfragekörper theme={null}
  {
    "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"
      }
    ]
  }
  ```

  ```bash cURL theme={null}
  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
    }'
  ```
</CodeGroup>

<Note>
  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.
</Note>

### SAP-Projekt-Sync

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

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
curl -X GET "https://api.comstruct.com/v1/accounts" \
  -H "x-api-key: IHR_API_SCHLUESSEL"
```

## Zahlungsbedingungen-Synchronisation

### Zahlungsbedingungen erstellen oder aktualisieren

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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:

<Steps>
  <Step title="Alle Datensätze exportieren">
    Exportieren Sie alle aktiven Datensätze aus Ihrem ERP-System.
  </Step>

  <Step title="Daten transformieren">
    Ordnen Sie ERP-Felder dem comstruct-Format zu.
  </Step>

  <Step title="An API senden">
    Senden Sie alle Datensätze an die entsprechenden Endpunkte.
  </Step>

  <Step title="Fehlende deaktivieren">
    Markieren Sie Datensätze, die nicht im Export sind, als inaktiv.
  </Step>
</Steps>

### Delta-Synchronisation

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

<Steps>
  <Step title="Änderungen verfolgen">
    Verwenden Sie Änderungsverfolgung in Ihrem ERP, um geänderte Datensätze zu identifizieren.
  </Step>

  <Step title="Änderungen exportieren">
    Exportieren Sie nur geänderte Datensätze seit der letzten Synchronisation.
  </Step>

  <Step title="Aktualisierungen senden">
    Senden Sie geänderte Datensätze an die API.
  </Step>
</Steps>

## Best Practices

<CardGroup cols={2}>
  <Card title="Externe IDs verwenden" icon="key">
    Verwenden Sie immer `external_id` für zuverlässige Upsert-Operationen und zur Aufrechterhaltung der Verknüpfung zwischen Systemen.
  </Card>

  <Card title="Anfragen bündeln" icon="layer-group">
    Für SAP-Endpunkte senden Sie mehrere Datensätze in einer einzigen Anfrage für bessere Performance.
  </Card>

  <Card title="Zahlungsbedingungen validieren" icon="check-double">
    Falls Zahlungsbedingungen angegeben werden, stellen Sie sicher, dass die Schlüssel in comstruct existieren, bevor Sie Lieferanten synchronisieren.
  </Card>

  <Card title="Regelmäßige Syncs planen" icon="clock">
    Richten Sie automatisierte Sync-Jobs ein, um Daten aktuell zu halten.
  </Card>
</CardGroup>

## 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

```json theme={null}
{
  "error": "Validation failed",
  "message": "Payment term '60T' not found in tenant"
}
```

## Integrationsarchitektur

```mermaid theme={null}
graph LR
    A[ERP-System] -->|Export| B[ETL-Prozess]
    B -->|Transformieren| C[API-Anfragen]
    C -->|Sync| D[comstruct]
    D -->|Bestätigung| B
```

## 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](mailto:support@comstruct.com)
* [API-Referenz](/api-reference/introduction) für Endpunkt-Details