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

# Rechnungs-Integrationsmuster

> Häufige Muster für die Integration der Rechnungsverarbeitung mit comstruct

## Übersicht

comstruct bietet flexible Rechnungsverarbeitungsfunktionen, die verschiedene Integrationsmuster unterstützen. Dieser Leitfaden behandelt die häufigsten Integrationsszenarien und Best Practices für deren Implementierung.

## Integrationsmuster

<CardGroup cols={2}>
  <Card title="Direkter Upload" icon="upload">
    Lieferanten laden Rechnungen direkt zur KI-gestützten Verarbeitung in comstruct hoch.
  </Card>

  <Card title="E-Mail-Weiterleitung" icon="envelope">
    Per E-Mail empfangene Rechnungen werden automatisch an comstruct weitergeleitet.
  </Card>

  <Card title="ERP-Export" icon="database">
    Verarbeitete Rechnungen werden zur Buchung an ERP-Systeme exportiert.
  </Card>

  <Card title="SAP-Rückmeldung" icon="rotate">
    Bidirektionale Synchronisation mit SAP für Rechnungsstatus-Aktualisierungen.
  </Card>
</CardGroup>

***

## Muster 1: Direkter Lieferanten-Upload

Das häufigste Muster, bei dem Lieferanten Rechnungen direkt über die API hochladen.

### Funktionsweise

```mermaid theme={null}
sequenceDiagram
    participant L as Lieferant
    participant C as comstruct API
    participant KI as KI-Parser
    participant DB as Datenbank
    
    L->>C: POST /invoices/custom (PDF)
    C->>KI: Rechnung analysieren
    KI->>C: Extrahierte Daten
    C->>DB: Rechnung speichern
    C->>L: Erfolgsantwort
```

### Implementierung

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

  ```python Python theme={null}
  import requests

  with open('rechnung.pdf', 'rb') as f:
      response = requests.post(
          'https://api.comstruct.com/v1/invoices/custom',
          headers={
              'x-api-key': 'IHR_API_SCHLUESSEL',
              'Content-Type': 'application/pdf'
          },
          data=f.read()
      )
  ```

  ```javascript Node.js theme={null}
  const fs = require('fs');
  const axios = require('axios');

  const rechnungPdf = fs.readFileSync('rechnung.pdf');

  const response = await axios.post(
    'https://api.comstruct.com/v1/invoices/custom',
    rechnungPdf,
    {
      headers: {
        'x-api-key': 'IHR_API_SCHLUESSEL',
        'Content-Type': 'application/pdf'
      }
    }
  );
  ```
</CodeGroup>

### Antwort

```json theme={null}
{
  "success": true,
  "data": {
    "id": "123",
    "external_id": "RE-2024-001",
    "invoice_number": "RE-2024-1234",
    "supplier_name": "Beispiel GmbH",
    "gross_amount": 1190.00,
    "net_amount": 1000.00,
    "tax_amount": 190.00,
    "status": "OPEN"
  }
}
```

### Best Practices

* Verwenden Sie PDF-Format für beste KI-Parsing-Ergebnisse
* Verwenden Sie klare, lesbare Rechnungslayouts
* Stellen Sie sicher, dass PDFs nicht passwortgeschützt sind
* Maximale Dateigröße: 32MiB

***

## Muster 2: E-Mail-basierte Verarbeitung

Per E-Mail empfangene Rechnungen können zur Verarbeitung an comstruct weitergeleitet werden.

### Funktionsweise

```mermaid theme={null}
sequenceDiagram
    participant E as E-Mail-System
    participant W as E-Mail-Weiterleitung
    participant C as comstruct API
    participant KI as KI-Parser
    
    E->>W: Neue Rechnungs-E-Mail
    W->>C: POST /invoices/email
    C->>KI: Anhänge analysieren
    KI->>C: Extrahierte Daten
    C->>W: Erfolg
```

### Implementierung

```bash 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 @email_inhalt
```

### E-Mail-Verarbeitungsfunktionen

* Automatische Anhang-Extraktion
* Unterstützung für mehrere Rechnungen pro E-Mail
* Metadaten-Extraktion aus E-Mail-Headern
* Absenderidentifikation für Lieferantenzuordnung

***

## Muster 3: SAP-Integration

Vollständige bidirektionale Integration mit SAP für Rechnungsverarbeitung und Status-Synchronisation.

### Rechnungsexport nach SAP

Nachdem Rechnungen in comstruct verarbeitet und freigegeben wurden, können sie nach SAP exportiert werden.

```mermaid theme={null}
sequenceDiagram
    participant C as comstruct
    participant SAP as SAP-System
    
    C->>SAP: Rechnungsdaten exportieren
    SAP->>SAP: Rechnungsbeleg erstellen
    SAP->>C: POST /invoices/callback
    C->>C: Status aktualisieren
```

### SAP-Rückmeldungs-Integration

SAP kann Status-Aktualisierungen an comstruct zurücksenden:

```bash theme={null}
curl -X POST "https://api.comstruct.com/v1/invoices/callback" \
  -H "x-api-key: IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "RE-2024-001",
    "success": true,
    "sap_document_number": "5100000123"
  }'
```

### Rückmeldungs-Anfrageschema

| Feld                  | Typ     | Erforderlich | Beschreibung                        |
| --------------------- | ------- | ------------ | ----------------------------------- |
| `external_id`         | string  | Ja           | Externe ID der Rechnung             |
| `success`             | boolean | Ja           | Ob SAP-Verarbeitung erfolgreich war |
| `sap_document_number` | string  | Nein         | SAP-Belegnummer (bei Erfolg)        |
| `error_message`       | string  | Nein         | Fehlerdetails (bei Misserfolg)      |

***

## Muster 4: Workflow-Integration (JobRouter)

Für Kunden, die Workflow-Systeme wie JobRouter für Rechnungsfreigabe verwenden.

### Workflow-Verarbeitung

```bash theme={null}
curl -X POST "https://api.comstruct.com/v1/workflows/trigger" \
  -H "x-api-key: IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "RE-2024-001",
    "base64document": "JVBERi0xLjQK...",
    "project_number": "PRJ-001",
    "creditor_name": "Beispiel GmbH",
    "invoice_number": "RE-2024-1234",
    "invoice_date": "2024-01-15",
    "due_date": "2024-02-15",
    "receipt_date": "2024-01-16",
    "net_amount": 1000.00,
    "total_amount": 1190.00,
    "tenant": "tenant-123",
    "dimensions": [
      { "dimension_label": "Kostenstelle", "option_title": "Verwaltung" },
      { "dimension_label": "Abteilung", "option_title": "Einkauf" }
    ]
  }'
```

Das optionale `receipt_date`-Feld (Buchungsdatum) akzeptiert ein Datum im Format `YYYY-MM-DD`. Wird es nicht
angegeben, verwendet comstruct das aktuelle Datum als Buchungsdatum.

Das `dimensions`-Feld ist optional. Es akzeptiert ein Array von `{ dimension_label, option_title }`-Paaren,
die gegen die im Mandanten konfigurierten Rechnungsdimensionen und deren Optionen aufgelöst werden.
Übergebene Dimensionswerte haben Vorrang vor KI-extrahierten Werten — analog zum bestehenden Verhalten
bei vordefinierten Kontierungen (`accounts`).

### Workflow-Status prüfen

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

### Status-Antwort

```json theme={null}
{
  "success": true,
  "status": "PROCESSING",
  "url": "https://app.comstruct.com/invoices/123",
  "history": [
    {
      "created_at": "2024-01-15T10:30:00Z",
      "newStatus": "PROCESSING",
      "previousStatus": "NEW",
      "message": "Verarbeitung gestartet"
    }
  ]
}
```

***

## Rechnungsstatus-Ablauf

Das Verständnis des Rechnungslebenszyklus hilft bei der Gestaltung von Integrationen:

```mermaid theme={null}
stateDiagram-v2
    [*] --> OPEN: Rechnung erstellt
    OPEN --> PROCESSING: Verarbeitung gestartet
    PROCESSING --> APPROVED: Freigegeben
    PROCESSING --> REJECTED: Abgelehnt
    APPROVED --> EXPORTED: An ERP gesendet
    EXPORTED --> BOOKED: ERP bestätigt
    REJECTED --> [*]
    BOOKED --> [*]
```

### Status-Definitionen

| Status       | Beschreibung                               |
| ------------ | ------------------------------------------ |
| `OPEN`       | Rechnung erstellt, wartet auf Verarbeitung |
| `PROCESSING` | Rechnung wird geprüft                      |
| `APPROVED`   | Zur Zahlung freigegeben                    |
| `REJECTED`   | Rechnung abgelehnt                         |
| `EXPORTED`   | Zur Buchung an ERP gesendet                |
| `BOOKED`     | Erfolgreich im ERP gebucht                 |

***

## Rechnungen auflisten und filtern

### Alle Rechnungen auflisten

```bash theme={null}
curl -X GET "https://api.comstruct.com/v1/invoices?limit=25&offset=0" \
  -H "x-api-key: IHR_API_SCHLUESSEL"
```

### Nach Status filtern

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

### Einzelne Rechnung abrufen

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

Die Antwort entspricht einem Listeneintrag (u. a. `invoice_accounts`, `created_at`, `updated_at`), ohne Verlauf und ohne Positionen.

### Rechnungspositionen abrufen

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

Antwort: `{ "items": [ ... ] }` (nach `index` sortiert).

### Antwortformat

```json theme={null}
{
  "data": [
    {
      "id": "123",
      "external_id": "RE-2024-001",
      "invoice_number": "RE-2024-1234",
      "status": "OPEN",
      "gross_amount": 1190.00,
      "supplier_name": "Beispiel GmbH",
      "project_number": "PRJ-001",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-16T09:00:00Z"
    }
  ],
  "total": 150,
  "limit": 25,
  "offset": 0,
  "hasNext": true,
  "hasPrevious": false,
  "totalPages": 6,
  "currentPage": 0
}
```

***

## Rechnungs-PDFs herunterladen

Originale PDF für eine Rechnung abrufen:

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

***

## Fehlerbehandlung

### Häufige Fehler

| Fehlercode | Beschreibung               | Lösung                                  |
| ---------- | -------------------------- | --------------------------------------- |
| 400        | Ungültiges Rechnungsformat | PDF-Gültigkeit prüfen                   |
| 401        | Fehlende Berechtigung      | `invoices:write` Berechtigung anfordern |
| 404        | Rechnung nicht gefunden    | Rechnungs-ID überprüfen                 |
| 500        | Parsing fehlgeschlagen     | Support mit Rechnung kontaktieren       |

### Fehlerantwort

```json theme={null}
{
  "success": false,
  "error": "Failed to parse invoice: Invalid data format"
}
```

### Wiederholungsstrategie

Für vorübergehende Fehler (5xx) implementieren Sie exponentielles Backoff:

```python theme={null}
import time
import requests

def rechnung_hochladen_mit_wiederholung(pdf_pfad, max_versuche=3):
    for versuch in range(max_versuche):
        try:
            with open(pdf_pfad, 'rb') as f:
                response = requests.post(
                    'https://api.comstruct.com/v1/invoices/custom',
                    headers={
                        'x-api-key': 'IHR_API_SCHLUESSEL',
                        'Content-Type': 'application/pdf'
                    },
                    data=f.read()
                )
            
            if response.status_code < 500:
                return response.json()
                
        except requests.exceptions.RequestException:
            pass
        
        time.sleep(2 ** versuch)  # Exponentielles Backoff
    
    raise Exception("Maximale Versuche überschritten")
```

***

## Best Practices Zusammenfassung

<AccordionGroup>
  <Accordion title="Datenqualität">
    * Verwenden Sie hochauflösende PDF-Scans (mindestens 300 DPI)
    * Stellen Sie sicher, dass Rechnungen nicht schief oder gedreht sind
    * Vermeiden Sie passwortgeschützte PDFs
    * Verwenden Sie nach Möglichkeit standardisierte Rechnungslayouts
  </Accordion>

  <Accordion title="Integrationsdesign">
    * Implementieren Sie idempotente Uploads mit externen IDs
    * Speichern Sie API-Antworten für Debugging
    * Verwenden Sie Webhooks oder Polling für Status-Aktualisierungen
    * Implementieren Sie ordnungsgemäße Fehlerbehandlung und Wiederholungslogik
  </Accordion>

  <Accordion title="Performance">
    * Bündeln Sie Uploads außerhalb der Spitzenzeiten
    * Komprimieren Sie PDFs, um die Upload-Zeit zu reduzieren
    * Verwenden Sie Connection-Pooling für mehrere Anfragen
    * Überwachen Sie API-Antwortzeiten
  </Accordion>

  <Accordion title="Sicherheit">
    * Speichern Sie API-Schlüssel sicher
    * Verwenden Sie HTTPS für alle Anfragen
    * Validieren Sie Antworten vor der Verarbeitung
    * Implementieren Sie Audit-Logging
  </Accordion>
</AccordionGroup>

***

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