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

# API-Referenz

> Vollständige Referenz aller comstruct API-Endpunkte

## Übersicht

Die comstruct API bietet eine RESTful-Schnittstelle zur Verwaltung der Baumaterial-Beschaffung. Diese Referenz dokumentiert alle verfügbaren Endpunkte mit interaktiven "Try it"-Funktionen.

## Basis-URL

Alle API-Anfragen sollten an folgende Adresse gesendet werden:

```
https://api.comstruct.com/v1
```

<Note>
  Kalender- (`/calendars/...`) und IDS-Endpunkte (`/ids/...`) verwenden die Basis-URL `https://api.comstruct.com` **ohne** das `/v1`-Präfix.
</Note>

## Authentifizierung

Alle Endpunkte erfordern API-Schlüssel-Authentifizierung über den `x-api-key`-Header:

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

### Berechtigungen (Scopes)

API-Schlüssel haben spezifische Berechtigungen im Format `ressource:aktion`. Jeder Endpunkt erfordert nur die für ihn relevanten Scopes – die erforderlichen Berechtigungen werden pro Endpunkt angezeigt.

**Verfügbare Berechtigungen:**

| Berechtigung            | Beschreibung                                                                                                                      |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `projects:read`         | Projektdaten lesen                                                                                                                |
| `projects:write`        | Projekte erstellen und ändern                                                                                                     |
| `deliveries:read`       | Lieferdaten lesen                                                                                                                 |
| `deliveries:write`      | Lieferungen erstellen und ändern                                                                                                  |
| `deliveries:patch`      | Lieferungen und Lieferkomponenten bearbeiten; asynchronen Lieferschein-PDF-Upload (`POST /deliveries/pdf`) (Kunden-API-Schlüssel) |
| `invoices:read`         | Rechnungsdaten lesen                                                                                                              |
| `invoices:write`        | Rechnungen erstellen und ändern                                                                                                   |
| `project_regions:read`  | Projektregionsdaten lesen                                                                                                         |
| `project_regions:write` | Projektregionen erstellen und ändern                                                                                              |
| `accounts:read`         | Kontodaten lesen                                                                                                                  |
| `accounts:write`        | Konten erstellen und ändern                                                                                                       |
| `payment_terms:read`    | Zahlungsbedingungsdaten lesen                                                                                                     |
| `payment_terms:write`   | Zahlungsbedingungen erstellen und ändern                                                                                          |
| `tax_codes:read`        | Steuercodedaten lesen                                                                                                             |
| `tax_codes:write`       | Steuercodes erstellen und ändern                                                                                                  |
| `legal_entities:read`   | Buchungskreise lesen                                                                                                              |
| `legal_entities:write`  | Buchungskreise erstellen und ändern                                                                                               |
| `users:read`            | Benutzerdaten lesen (Projekt-Benutzerverwaltung)                                                                                  |
| `roles:read`            | Rollendaten lesen (Projekt-Rollenzuweisung)                                                                                       |
| `tenant_settings:read`  | Mandanteneinstellungen lesen                                                                                                      |
| `suppliers:write`       | Lieferanten erstellen und ändern                                                                                                  |
| `purchase_orders:write` | Bestellungen erstellen                                                                                                            |
| `orders:write`          | Bestellungen als Lieferant aktualisieren (bestätigen, ablehnen, bearbeiten)                                                       |

<Note>
  Als Administrator können Sie API-Schlüssel selbst in der comstruct-Anwendung erstellen: **Administration → API-Schlüssel**. Dort legen Sie Berechtigungen (Scopes) fest und erhalten den Schlüssel einmalig bei der Erstellung.

  Alternativ hilft Ihnen Ihr Customer Success Manager bei der Einrichtung.
</Note>

## API-Endpunkt-Gruppen

<CardGroup cols={2}>
  <Card title="Projekte" icon="folder">
    Projektverwaltung und -abfragen.

    * Projekte auflisten
    * Projekt erstellen/aktualisieren
    * Projekt nach ID abrufen
    * Projektkomponenten abrufen
    * SAP-Projekte importieren
  </Card>

  <Card title="Lieferungen" icon="truck">
    Lieferschein-Verwaltung.

    * Lieferungen auflisten
    * Lieferscheine erstellen
    * Lieferung aktualisieren und Lieferkomponenten setzen
    * OpenTrans/PAHM/Custom-Formate
  </Card>

  <Card title="Rechnungen" icon="file-invoice">
    Rechnungsverarbeitung.

    * Rechnungen auflisten und einzeln abrufen
    * Rechnungen hochladen
    * KI-gestützte Analyse
  </Card>

  <Card title="Stammdaten" icon="database">
    Referenzdaten verwalten.

    * Konten
    * Zahlungsbedingungen
    * Steuercodes
    * Buchungskreise
    * Projektregionen
  </Card>
</CardGroup>

## Ratenlimits

Die API setzt Ratenlimits ein, um eine faire Nutzung und Systemstabilität zu gewährleisten. Limits gelten pro IP-Adresse.

| Limit          | Wert         |
| -------------- | ------------ |
| Anfragenanzahl | 750 Anfragen |
| Intervall      | 30 Sekunden  |

Bei Überschreitung des Limits können Anfragen gedrosselt oder mit HTTP `403 Forbidden` abgelehnt werden. Implementieren Sie Exponential-Backoff und Retry-Logik in Ihren Integrationen, um Ratenlimit-Antworten zuverlässig zu verarbeiten.

<Tip>
  Bei Integrationen mit hohem Aufkommen kontaktieren Sie Ihren Customer Success Manager, um Ihre Anforderungen zu besprechen.
</Tip>

## HTTP-Statuscodes

| Code  | Beschreibung                                                   |
| ----- | -------------------------------------------------------------- |
| `200` | Erfolg                                                         |
| `201` | Erfolgreich erstellt                                           |
| `400` | Ungültige Anfrage                                              |
| `401` | Nicht autorisiert                                              |
| `403` | Verboten – fehlende Berechtigung oder Ratenlimit überschritten |
| `404` | Nicht gefunden                                                 |
| `500` | Serverfehler                                                   |

## Interaktive API-Dokumentation

Jede Endpunkt-Seite enthält eine **"Try it"**-Funktion, mit der Sie API-Aufrufe direkt testen können. Geben Sie einfach Ihren API-Schlüssel ein und testen Sie die Endpunkte.

<Card title="OpenAPI-Spezifikation" icon="download" href="/api-reference/openapi.yaml">
  Laden Sie die vollständige OpenAPI 3.0 Spezifikation herunter.
</Card>