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

# Lieferanten-Anbindung

> Vollständiger Leitfaden für Lieferanten zur Anbindung an comstruct

## Übersicht

Dieser Leitfaden erklärt, wie Lieferanten sich mit comstruct integrieren können, um Lieferscheine und Rechnungen automatisch zu übermitteln. Durch die Anbindung an comstruct können Lieferanten ihre Logistikprozesse optimieren und Echtzeit-Lieferinformationen an ihre Auftraggeberkunden bereitstellen.

<Info>
  Um Zugang zur comstruct API zu erhalten, wenden Sie sich an Ihren zuständigen Customer Success Manager. Unser Expertenteam unterstützt Sie gerne bei der optimalen Nutzung unserer API.
</Info>

## Was Lieferanten tun können

Als angebundener Lieferant bei comstruct können Sie:

* **Lieferscheine automatisch übermitteln** aus Ihren Systemen
* **Rechnungen hochladen** zur Verarbeitung
* **Lieferstatus verfolgen** in Echtzeit
* **Mit verschiedenen Lieferformaten integrieren** (OpenTrans, PAHM, Q-Point, eigene Formate)

## Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes haben:

1. Einen API-Schlüssel von comstruct
2. Die entsprechenden Berechtigungen für Ihren API-Schlüssel:
   * `deliveries:write` - Zum Erstellen von Lieferscheinen
   * `invoices:write` - Zum Einreichen von Rechnungen
3. Ihre Lieferanten-ID in comstruct konfiguriert

## Authentifizierung

Alle API-Anfragen erfordern eine Authentifizierung mittels eines API-Schlüssels im `x-api-key`-Header.

```bash theme={null}
curl -X POST "https://api.comstruct.com/v1/deliveries" \
  -H "x-api-key: IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{"..."}'
```

## Lieferschein-Integration

### Standard-Lieferformat

Der einfachste Weg, Lieferscheine zu übermitteln, ist das Standard-JSON-Format.

<CodeGroup>
  ```json Anfragekörper theme={null}
  {
    "deliveryNumber": "LS-2024-001",
    "deliveryDate": "2024-01-15T08:30:00Z",
    "projectNumber": "PRJ-001",
    "items": [
      {
        "productNumber": "BETON-C30",
        "title": "Beton C30/37",
        "quantity": 25.5,
        "unit": "m³"
      }
    ]
  }
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.comstruct.com/v1/deliveries" \
    -H "x-api-key: IHR_API_SCHLUESSEL" \
    -H "Content-Type: application/json" \
    -d '{
      "deliveryNumber": "LS-2024-001",
      "deliveryDate": "2024-01-15T08:30:00Z",
      "projectNumber": "PRJ-001",
      "items": [
        {
          "productNumber": "BETON-C30",
          "title": "Beton C30/37",
          "quantity": 25.5,
          "unit": "m³"
        }
      ]
    }'
  ```
</CodeGroup>

### OpenTrans-Format

Wenn Ihr System OpenTrans unterstützt, können Sie Lieferscheine in diesem standardisierten Format übermitteln.

```bash theme={null}
curl -X POST "https://api.comstruct.com/v1/deliveries/opentrans" \
  -H "x-api-key: IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/xml" \
  -d '<DESPADV>...</DESPADV>'
```

### PAHM-Format

Für PAHM-kompatible Systeme:

```bash theme={null}
curl -X POST "https://api.comstruct.com/v1/deliveries/pahm" \
  -H "x-api-key: IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/xml" \
  -d '<pahm-delivery>...</pahm-delivery>'
```

### Q-Point-Integration

Wenn Sie Q-Point für Qualitätsmanagement verwenden:

```bash theme={null}
curl -X POST "https://api.comstruct.com/v1/qpoint" \
  -H "x-api-key: IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{...}'
```

### Eigenes Format

Für nicht-standardisierte Formate können Sie Lieferscheindaten als JSON oder XML über den Custom-Endpunkt senden. Die Daten werden automatisch von system-spezifischen Prozessoren verarbeitet.

<CodeGroup>
  ```bash JSON-Beispiel theme={null}
  curl -X POST "https://api.comstruct.com/v1/deliveries/custom" \
    -H "x-api-key: IHR_API_SCHLUESSEL" \
    -H "Content-Type: application/json" \
    -d '{
      "jsonContent": {
        "deliveryNumber": "LS-2024-001",
        "customerName": "Musterbau GmbH",
        "projectNumber": "PRJ-001",
        "deliveryDate": "2024-06-15T08:30:00Z",
        "items": [
          {
            "title": "Beton C30/37",
            "quantity": 25.5,
            "unit": "m3"
          }
        ]
      }
    }'
  ```

  ```bash XML-Beispiel theme={null}
  curl -X POST "https://api.comstruct.com/v1/deliveries/custom" \
    -H "x-api-key: IHR_API_SCHLUESSEL" \
    -H "Content-Type: application/json" \
    -d '{
      "xmlContent": "<delivery><number>LS-2024-001</number><customer>Musterbau GmbH</customer><items><item><title>Beton C30/37</title><quantity>25.5</quantity><unit>m3</unit></item></items></delivery>"
    }'
  ```
</CodeGroup>

<Info>
  Weitere Details und Beispiele finden Sie in der [API-Referenz](/api-reference/deliveries-custom).
</Info>

## Rechnungseinreichung

### Standard-Rechnungs-Upload

Reichen Sie Rechnungen zur Verarbeitung mit KI-gestützter Datenextraktion ein:

<CodeGroup>
  ```bash PDF-Upload theme={null}
  curl -X POST "https://api.comstruct.com/v1/invoices/custom" \
    -H "x-api-key: IHR_API_SCHLUESSEL" \
    -H "Content-Type: application/pdf" \
    --data-binary @rechnung.pdf
  ```

  ```bash E-Mail-Upload theme={null}
  curl -X POST "https://api.comstruct.com/v1/invoices/email" \
    -H "x-api-key: IHR_API_SCHLUESSEL" \
    -H "Content-Type: application/octet-stream" \
    --data-binary @rechnungsdaten
  ```
</CodeGroup>

## Lieferdaten-Schema

### Pflichtfelder

| Feld             | Typ      | Beschreibung                                  |
| ---------------- | -------- | --------------------------------------------- |
| `deliveryNumber` | string   | Eindeutige Lieferscheinnummer (pro Lieferant) |
| `deliveryDate`   | datetime | ISO 8601 formatiertes Lieferdatum             |

### Projektzuordnung (mindestens eines empfohlen)

| Feld            | Typ    | Beschreibung                           |
| --------------- | ------ | -------------------------------------- |
| `projectId`     | uuid   | Direkte Projekt-ID (höchste Priorität) |
| `projectNumber` | string | Projektnummer des Auftraggebers        |
| `projectTitle`  | string | Projekttitel für Fuzzy-Matching        |
| `customerName`  | string | Kundenname für Projektsuche            |

### Optionale Felder

| Feld            | Typ    | Beschreibung                               |
| --------------- | ------ | ------------------------------------------ |
| `vehicleNumber` | string | Kennzeichen des Lieferfahrzeugs            |
| `plant`         | string | Werk/Anlage der Herkunft                   |
| `comment`       | string | Optionaler Kommentar                       |
| `documentUrl`   | string | Link zum Lieferschein-Dokument             |
| `status`        | string | Lieferstatus (z.B. DELIVERED, IN\_TRANSIT) |

### Positionen (items)

| Feld                    | Typ    | Beschreibung                                                 |
| ----------------------- | ------ | ------------------------------------------------------------ |
| `items[].title`         | string | Produktbeschreibung (Pflichtfeld)                            |
| `items[].productNumber` | string | Ihre Produktreferenz                                         |
| `items[].quantity`      | number | Gelieferte Menge                                             |
| `items[].unit`          | string | Mengeneinheit (Standard: "pau")                              |
| `items[].type`          | string | Produkttyp (wird automatisch ermittelt wenn nicht angegeben) |

## Best Practices

<CardGroup cols={2}>
  <Card title="Eindeutige Referenzen verwenden" icon="fingerprint">
    Verwenden Sie immer eindeutige Referenznummern für jede Lieferung, um Nachverfolgung zu ermöglichen und Duplikate zu vermeiden.
  </Card>

  <Card title="Projektnummern angeben" icon="folder">
    Geben Sie immer die Projektnummer des Auftraggebers an, damit Lieferungen korrekt zugeordnet werden.
  </Card>

  <Card title="Vor dem Senden validieren" icon="check">
    Validieren Sie Ihr Datenformat lokal, bevor Sie es übermitteln, um Verarbeitungsfehler zu vermeiden.
  </Card>

  <Card title="Fehler behandeln" icon="shield">
    Implementieren Sie ordnungsgemäße Fehlerbehandlung und Wiederholungslogik für vorübergehende Fehler.
  </Card>
</CardGroup>

## Fehlerbehandlung

Die API verwendet Standard-HTTP-Statuscodes:

| Status | Beschreibung                                                            |
| ------ | ----------------------------------------------------------------------- |
| `200`  | Erfolg                                                                  |
| `400`  | Ungültiger Anfragekörper oder Validierung fehlgeschlagen                |
| `401`  | Nicht autorisiert - ungültiger API-Schlüssel oder fehlende Berechtigung |
| `403`  | Verboten - API-Schlüssel nicht mit Lieferant verknüpft                  |
| `500`  | Interner Serverfehler                                                   |

### Beispiel-Fehlerantwort

```json theme={null}
{
  "error": "Validation failed",
  "message": "The provided data did not pass validation checks"
}
```

## Ihre Integration testen

<Steps>
  <Step title="Test-Zugangsdaten erhalten">
    Fordern Sie Test-API-Zugangsdaten von Ihrem Customer Success Manager an.
  </Step>

  <Step title="Test-Lieferung übermitteln">
    Übermitteln Sie einen Test-Lieferschein mit Beispieldaten, um Ihre Integration zu verifizieren.
  </Step>

  <Step title="In comstruct überprüfen">
    Prüfen Sie in der comstruct-App, ob Ihre Lieferung korrekt angezeigt wird.
  </Step>

  <Step title="Live schalten">
    Sobald die Tests abgeschlossen sind, wechseln Sie zu den Produktionszugangsdaten.
  </Step>
</Steps>

## Support

Bei Problemen oder Fragen:

* Kontaktieren Sie Ihren Customer Success Manager
* E-Mail: [support@comstruct.com](mailto:support@comstruct.com)
* Sehen Sie sich die [API-Referenz](/api-reference/introduction) für detaillierte Endpunkt-Dokumentation an