Lieferanten-Anbindung

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

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.

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:

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

Authentifizierung

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

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.

{
  "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³"
    }
  ]
}

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³"
      }
    ]
  }'

OpenTrans-Format

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

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:

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:

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.

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"
        }
      ]
    }
  }'

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>"
  }'

Weitere Details und Beispiele finden Sie in der API-Referenz.

Rechnungseinreichung

Standard-Rechnungs-Upload

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

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

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

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	PDF-Inhalt als rohes Base64 oder als `data:application/pdf;base64,...` Data-URI; HTTP(S)-URLs werden nicht unterstützt
`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

Eindeutige Referenzen verwenden

Verwenden Sie immer eindeutige Referenznummern für jede Lieferung, um Nachverfolgung zu ermöglichen und Duplikate zu vermeiden.

Projektnummern angeben

Geben Sie immer die Projektnummer des Auftraggebers an, damit Lieferungen korrekt zugeordnet werden.

Vor dem Senden validieren

Validieren Sie Ihr Datenformat lokal, bevor Sie es übermitteln, um Verarbeitungsfehler zu vermeiden.

Fehler behandeln

Implementieren Sie ordnungsgemäße Fehlerbehandlung und Wiederholungslogik für vorübergehende Fehler.

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

{
  "error": "Validation failed",
  "message": "The provided data did not pass validation checks"
}

Ihre Integration testen

Test-Zugangsdaten erhalten

Fordern Sie Test-API-Zugangsdaten von Ihrem Customer Success Manager an.

Test-Lieferung übermitteln

Übermitteln Sie einen Test-Lieferschein mit Beispieldaten, um Ihre Integration zu verifizieren.

In comstruct überprüfen

Prüfen Sie in der comstruct-App, ob Ihre Lieferung korrekt angezeigt wird.

Live schalten

Sobald die Tests abgeschlossen sind, wechseln Sie zu den Produktionszugangsdaten.

Support

Bei Problemen oder Fragen:

Kontaktieren Sie Ihren Customer Success Manager
E-Mail: support@comstruct.com
Sehen Sie sich die API-Referenz für detaillierte Endpunkt-Dokumentation an

Einführung

Integrationsleitfäden

Übersicht

Was Lieferanten tun können

Voraussetzungen

Authentifizierung

Lieferschein-Integration

Standard-Lieferformat

OpenTrans-Format

PAHM-Format

Q-Point-Integration

Eigenes Format

Rechnungseinreichung

Standard-Rechnungs-Upload

Lieferdaten-Schema

Pflichtfelder

Projektzuordnung (mindestens eines empfohlen)

Optionale Felder

Positionen (items)

Best Practices

Eindeutige Referenzen verwenden

Projektnummern angeben

Vor dem Senden validieren

Fehler behandeln

Fehlerbehandlung

Beispiel-Fehlerantwort

Ihre Integration testen

Support

​Übersicht

​Was Lieferanten tun können

​Voraussetzungen

​Authentifizierung

​Lieferschein-Integration

​Standard-Lieferformat

​OpenTrans-Format

​PAHM-Format

​Q-Point-Integration

​Eigenes Format

​Rechnungseinreichung

​Standard-Rechnungs-Upload

​Lieferdaten-Schema

​Pflichtfelder

​Projektzuordnung (mindestens eines empfohlen)

​Optionale Felder

​Positionen (items)

​Best Practices

Eindeutige Referenzen verwenden

Projektnummern angeben

Vor dem Senden validieren

Fehler behandeln

​Fehlerbehandlung

​Beispiel-Fehlerantwort

​Ihre Integration testen

​Support

Übersicht

Was Lieferanten tun können

Voraussetzungen

Authentifizierung

Lieferschein-Integration

Standard-Lieferformat

OpenTrans-Format

PAHM-Format

Q-Point-Integration

Eigenes Format

Rechnungseinreichung

Standard-Rechnungs-Upload

Lieferdaten-Schema

Pflichtfelder

Projektzuordnung (mindestens eines empfohlen)

Optionale Felder

Positionen (items)

Best Practices

Fehlerbehandlung

Beispiel-Fehlerantwort

Ihre Integration testen

Support