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

# Custom delivery

> **Erforderliche Berechtigungen:** `deliveries:write`

Verarbeitet Lieferscheine in benutzerdefinierten Formaten. Der Inhalt wird anhand der lieferantenspezifischen Konfiguration automatisch verarbeitet und in comstruct-Lieferungen umgewandelt.

Der Anfragekörper kann entweder als JSON-Objekt mit den Feldern `xmlContent` oder `jsonContent` gesendet werden, oder als roher XML- bzw. JSON-String. Die automatische Erkennung des Formats erfolgt über den Content-Type-Header.


## Overview

This endpoint allows suppliers to submit delivery notes in custom, non-standardized formats to comstruct. The data is automatically processed by system-specific processors and converted into comstruct deliveries.

The endpoint accepts either **JSON** or **XML** as input format.

## Input format

The request body can be sent in two ways:

| Variant        | Content-Type       | Body                                                                 |
| -------------- | ------------------ | -------------------------------------------------------------------- |
| JSON wrapper   | `application/json` | `{ "jsonContent": { ... } }` or `{ "xmlContent": "<xml>...</xml>" }` |
| Raw XML string | `application/xml`  | `<delivery>...</delivery>`                                           |

<Info>
  If you send raw JSON or XML content as a string, comstruct automatically detects the format based on the content.
</Info>

## Example calls

### Send JSON delivery note

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.comstruct.com/v1/deliveries/custom" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "jsonContent": {
        "deliveryNumber": "DN-2024-001",
        "customerName": "Construction Corp",
        "projectNumber": "PRJ-001",
        "deliveryDate": "2024-06-15T08:30:00Z",
        "items": [
          {
            "title": "Concrete C30/37",
            "productNumber": "CONC-C30",
            "quantity": 25.5,
            "unit": "m3"
          },
          {
            "title": "Reinforcement steel B500S",
            "productNumber": "STEEL-B500S",
            "quantity": 3.2,
            "unit": "t"
          }
        ]
      }
    }'
  ```

  ```json Request body theme={null}
  {
    "jsonContent": {
      "deliveryNumber": "DN-2024-001",
      "customerName": "Construction Corp",
      "projectNumber": "PRJ-001",
      "deliveryDate": "2024-06-15T08:30:00Z",
      "items": [
        {
          "title": "Concrete C30/37",
          "productNumber": "CONC-C30",
          "quantity": 25.5,
          "unit": "m3"
        },
        {
          "title": "Reinforcement steel B500S",
          "productNumber": "STEEL-B500S",
          "quantity": 3.2,
          "unit": "t"
        }
      ]
    }
  }
  ```
</CodeGroup>

### Send XML delivery note

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.comstruct.com/v1/deliveries/custom" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "xmlContent": "<delivery><number>DN-2024-002</number><customer>Construction Corp</customer><date>2024-06-15</date><items><item><title>Concrete C30/37</title><quantity>25.5</quantity><unit>m3</unit></item></items></delivery>"
    }'
  ```

  ```json Request body theme={null}
  {
    "xmlContent": "<delivery><number>DN-2024-002</number><customer>Construction Corp</customer><date>2024-06-15</date><items><item><title>Concrete C30/37</title><quantity>25.5</quantity><unit>m3</unit></item></items></delivery>"
  }
  ```
</CodeGroup>

### Successful response

```json theme={null}
{
  "success": true,
  "message": "Delivery note uploaded successfully",
  "deliveryNumber": "DN-2024-001"
}
```

## Response codes

| Code  | Description                                            |
| ----- | ------------------------------------------------------ |
| `201` | Delivery note successfully processed and created       |
| `200` | Delivery note received but no changes (e.g. duplicate) |
| `400` | Invalid input or missing supplier ID                   |
| `401` | Unauthorized - missing or invalid API key              |
| `403` | Forbidden - missing scope `deliveries:write`           |
| `500` | Internal server error                                  |


## OpenAPI

````yaml POST /deliveries/custom
openapi: 3.0.3
info:
  title: comstruct Public API
  description: >
    Die comstruct API ist eine umfassende und flexible Lösung zur Optimierung
    des Materialbeschaffungsprozesses für Unternehmen. Diese API bietet eine
    einfache Schnittstelle für Entwickler, um auf Materialbeschaffungsdaten
    zuzugreifen und diese zu verwalten, einschließlich Lieferanteninformationen,
    Lieferungen und Projekte.


    ## Erste Schritte

    Um Zugang zur comstruct API zu erhalten, wenden Sie sich bitte an Ihren
    zuständigen Customer Success Manager. Unser Expertenteam steht Ihnen mit
    erstklassigem Support zur Verfügung, um Ihnen zu helfen, das Beste aus
    unserer API herauszuholen.


    ## Authentifizierung

    Alle API-Endpunkte unter `/v1` erfordern eine Authentifizierung mittels
    API-Schlüssel im `x-api-key`-Header. Jeder API-Schlüssel hat spezifische
    Berechtigungen (Scopes), die bestimmen, welche Endpunkte und Operationen
    verfügbar sind. Die Authentifizierung wird durch Middleware durchgesetzt,
    die den API-Schlüssel und die Berechtigungen für jede Anfrage validiert.


    Kalender-Endpunkte unter `/calendars` verwenden Token-basierte
    Authentifizierung anstelle von API-Schlüsseln.


    ## Datenformate

    - Alle Zeitstempel sind im ISO 8601-Format (UTC)

    - Geldbeträge werden als Dezimalzahlen dargestellt

    - IDs sind UUIDs, sofern nicht anders angegeben


    ## Anfragegrößenbeschränkungen

    - PDF-Rechnungsverarbeitung, benutzerdefinierte Rechnungsverarbeitung und
    Workflow-Verarbeitung: 32MiB

    - Alle anderen Endpunkte: 10MiB


    ## Fehlerbehandlung

    Die API verwendet Standard-HTTP-Statuscodes und gibt detaillierte
    Fehlermeldungen im JSON-Format zurück. Weitere Details finden Sie in den
    Fehlerschemas.


    ## Integrationsmuster

    - **SAP-Integration**: Spezialisierte Endpunkte für SAP-ERP-Systeme

    - **Projektverwaltung**: Vollständiges Projektlebenszyklusmanagement mit
    Benutzerrollen

    - **Lieferverfolgung**: Unterstützung mehrerer Lieferscheinformate
    (OpenTrans, PAHM, Q-Point, benutzerdefiniert)

    - **Rechnungsverarbeitung**: Automatisierte Rechnungsanalyse und
    -validierung mit KI/GPT-Unterstützung

    - **Auftragsverwaltung**: IDS-Auftragsverarbeitung mit XML-Parsing und
    Projektkalenderintegration

    - **Kalenderintegration**: Separate Kalender-Endpunkte für
    iCalendar-Abonnement-Feeds
  version: 1.0.9
  license:
    name: Proprietary
    url: https://comstruct.com
  contact:
    name: comstruct ICT GmbH
    url: https://comstruct.com
    email: support@comstruct.com
  termsOfService: https://comstruct.com/datenschutzerklarung/
  x-logo:
    url: https://app.comstruct.com/logo-light-text.png
    altText: comstruct logo
servers:
  - url: https://api.comstruct.com/v1
    description: Haupt-API-Endpunkte (erfordert API-Schlüssel-Authentifizierung)
    variables: {}
  - url: https://api.comstruct.com
    description: Basisserver für Kalender- und IDS-Endpunkte (andere Authentifizierung)
    variables: {}
security:
  - ApiKey: []
tags:
  - name: Projects
    description: Endpunkte für Projekte.
  - name: Projects (SAP)
    description: SAP-spezifische Projekt-Endpunkte.
  - name: Project Regions
    description: Endpunkte für die Verwaltung von Projektregionen.
  - name: Deliveries
    description: Endpunkte für Lieferungen.
  - name: Deliveries (Supplier)
    description: Lieferantenspezifische Liefer-Endpunkte.
  - name: Accounts
    description: Endpunkte für die Verwaltung von Sachkonten.
  - name: Payment Terms
    description: Endpunkte für die Verwaltung von Zahlungsbedingungen.
  - name: Tax Codes
    description: Endpunkte für die Verwaltung von Steuercodes.
  - name: Company Codes
    description: Endpunkte für die Verwaltung von Buchungskreisen (juristische Einheiten).
  - name: Suppliers
    description: Endpunkte für die Verwaltung von Lieferanten.
  - name: Purchase Orders
    description: Endpunkte für Bestellungen.
  - name: Purchase Orders (SAP)
    description: SAP-spezifische Bestellungs-Endpunkte.
  - name: Orders (Supplier)
    description: >-
      Lieferantenspezifische Bestellungs-Endpunkte (Bestätigung, Ablehnung,
      Bearbeitung).
  - name: Suppliers (SAP)
    description: SAP-spezifische Lieferanten-Endpunkte.
  - name: Invoices
    description: Endpunkte für Rechnungen.
  - name: Invoices (Supplier)
    description: Lieferantenspezifische Rechnungs-Endpunkte.
  - name: Invoices (SAP)
    description: SAP-spezifische Rechnungs-Endpunkte.
  - name: Invoice Dimensions
    description: >
      Rechnungs-Dimensionen (benutzerdefinierte Eigenschaften) und Zuweisungen
      auf Rechnung (`header`), Position (`line_item`) oder Kontierung
      (`account`).


      Dimensionen haben den Typ `option` (vordefinierte Werte) oder `text`
      (Freitext über `dimension_id` + `text_value`). Bulk-Konto-POST
      (`/assignments/account/bulk`) unterstützt nur Options-Zuweisungen über
      `option_ids`; Freitext auf Kontoebene über Einzel-POST, PATCH-Bulk oder
      Positions-Bulk.
  - name: Workflows
    description: Endpunkte für Workflow- und Prozessmanagement.
  - name: Calendar
    description: Kalender-Abonnement-Endpunkte mit separater Authentifizierung.
  - name: Orders
    description: Endpunkte für Auftragsverarbeitung und -verwaltung.
paths:
  /deliveries/custom:
    post:
      tags:
        - Deliveries (Supplier)
        - Deliveries
      summary: Lieferung im eigenen Format erstellen
      description: >
        **Erforderliche Berechtigungen:** `deliveries:write`


        Verarbeitet Lieferscheine in benutzerdefinierten Formaten. Der Inhalt
        wird anhand der lieferantenspezifischen Konfiguration automatisch
        verarbeitet und in comstruct-Lieferungen umgewandelt.


        Der Anfragekörper kann entweder als JSON-Objekt mit den Feldern
        `xmlContent` oder `jsonContent` gesendet werden, oder als roher XML-
        bzw. JSON-String. Die automatische Erkennung des Formats erfolgt über
        den Content-Type-Header.
      operationId: createDeliveryFromCustom
      requestBody:
        description: Lieferscheindaten im JSON- oder XML-Format
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                xmlContent:
                  type: string
                  description: XML-Inhalt des Lieferscheins (alternativ zu jsonContent)
                jsonContent:
                  oneOf:
                    - type: object
                    - type: string
                  description: JSON-Inhalt des Lieferscheins (alternativ zu xmlContent)
            examples:
              jsonDelivery:
                summary: JSON-Lieferschein
                value:
                  jsonContent:
                    deliveryNumber: LS-2024-001
                    customerName: Musterbau GmbH
                    items:
                      - title: Beton C30/37
                        quantity: 25.5
                        unit: m3
              xmlDelivery:
                summary: XML-Lieferschein
                value:
                  xmlContent: >-
                    <delivery><number>LS-2024-001</number><customer>Musterbau
                    GmbH</customer></delivery>
          application/xml:
            schema:
              type: string
            examples:
              rawXml:
                summary: Roher XML-Lieferschein
                value: >-
                  <?xml
                  version="1.0"?><delivery><number>LS-2024-001</number><customer>Musterbau
                  GmbH</customer></delivery>
      responses:
        '200':
          description: >-
            Lieferschein wurde empfangen, aber nicht erstellt (z.B. Duplikat
            oder keine Änderungen).
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Delivery note has no changes
        '201':
          description: Der Lieferschein wurde erfolgreich verarbeitet und erstellt.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Delivery note uploaded successfully
                  deliveryNumber:
                    type: string
                    example: LS-2024-001
        '400':
          description: Ungültiger Anfragekörper oder fehlende Lieferanten-ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                  statusCode:
                    type: number
                    example: 400
        '401':
          description: Nicht autorisiert - Fehlender oder ungültiger API-Schlüssel
        '403':
          description: Keine Berechtigung - fehlender Scope `deliveries:write`
        '500':
          description: >-
            Ein interner Serverfehler ist bei der Verarbeitung der Anfrage
            aufgetreten.
      security:
        - ApiKey:
            - deliveries:write
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >
        API-Schlüssel zur Authentifizierung. Kontaktieren Sie Ihren Customer
        Success Manager, um einen API-Schlüssel zu erhalten.


        Jeder Endpunkt erfordert spezifische Berechtigungen (Scopes); die
        erforderlichen Scopes werden pro Endpunkt angezeigt.

````