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

# Create or update SAP suppliers

> **Erforderliche Berechtigungen:** `suppliers:write`

Empfängt und verarbeitet Lieferanten aus dem SAP-System. Akzeptiert ein Array von SAP-Lieferanten als Rohdaten.
`number` wird als `external_id` gespeichert und für Upserts pro Kunde verwendet.
API-Schlüssel muss mit einem Kunden verknüpft sein.
**Validierung**: Der Body muss ein Array sein, `title` ist je Lieferant erforderlich, und angegebene Zahlungsbedingungen müssen im comstruct-Mandanten existieren.


## Overview

Use this endpoint to sync suppliers from SAP into comstruct. The request body is
always an array, so a single supplier and batches are handled through the same
`POST` call.

When `number` is present, comstruct stores it as the supplier `external_id`. If a
supplier with the same `external_id` already exists for the customer, that
supplier is updated.

<Info>
  Send `number` for every SAP supplier. The field is not required by schema
  validation, but it is required for idempotent SAP syncs and later lookups.
</Info>

## Permissions

| Scope             | Tenant type      |
| ----------------- | ---------------- |
| `suppliers:write` | Customer API key |

The API key must be linked to a customer.

## Headers

| Header         | Required | Description                          |
| -------------- | -------- | ------------------------------------ |
| `x-api-key`    | Yes      | API key with scope `suppliers:write` |
| `Content-Type` | Yes      | `application/json`                   |

## Request body

The body must be a JSON array of suppliers.

### Supplier fields

| Field             | Required | Description                                                         |
| ----------------- | -------- | ------------------------------------------------------------------- |
| `title`           | Yes      | Supplier name                                                       |
| `number`          | No       | SAP supplier number; mapped to `external_id` and used for upserts   |
| `legal_uid`       | No       | VAT ID or tax ID                                                    |
| `country_code`    | No       | ISO 3166-1 alpha-2 country code                                     |
| `comment`         | No       | Free-text supplier comment                                          |
| `payment_term`    | No       | Payment term key; must exist in the comstruct customer tenant       |
| `default_account` | No       | Default account number; must exist in the comstruct customer tenant |
| `wth_tax_code`    | No       | Withholding tax code; defaults to `00`                              |
| `bank_details`    | No       | Supplier bank details                                               |
| `address`         | No       | Supplier address                                                    |

### Bank details (`bank_details[]`)

| Field         | Required | Description                                                   |
| ------------- | -------- | ------------------------------------------------------------- |
| `iban`        | No       | Valid IBAN; entries without IBAN are ignored                  |
| `number`      | No       | External bank account number; preferred as the stored bank ID |
| `external_id` | No       | Alternative external ID when `number` is not present          |

### Address (`address`)

| Field          | Required | Description                     |
| -------------- | -------- | ------------------------------- |
| `address`      | No       | Street and house number         |
| `city`         | No       | City                            |
| `zip`          | No       | Postal code                     |
| `country_code` | No       | ISO 3166-1 alpha-2 country code |

## Example

```bash theme={null}
curl -X POST "https://api.comstruct.com/v1/suppliers/sap" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "number": "SAP-SUP-001",
      "title": "Acme Supplies GmbH",
      "legal_uid": "DE123456789",
      "country_code": "DE",
      "comment": "Preferred contact by email",
      "payment_term": "30T",
      "default_account": "4000",
      "wth_tax_code": "00",
      "bank_details": [
        {
          "number": "BANK-001",
          "iban": "DE89370400440532013000"
        }
      ],
      "address": {
        "address": "Example Street 1",
        "city": "Berlin",
        "zip": "10115",
        "country_code": "DE"
      }
    }
  ]'
```

## Behavior

* `number` is stored as `external_id`; existing suppliers with the same `external_id` and customer are updated.
* On conflicts, only `external_id`, `legal_uid`, `country_code`, `withholding_tax_code`, `payment_term_id`, `title`, `comment`, `address`, `city`, and `zip` are updated.
* `payment_term` is resolved against the customer's payment terms. Unknown values return `400`.
* `default_account` is resolved against the customer's accounts. Unknown values return `400`. When omitted on upsert, any existing `default_account_id` is preserved.
* If `wth_tax_code` is omitted, comstruct stores the default value `00`.
* Bank details are merged by IBAN, supplier, and tenant; on conflicts, the bank detail external ID is updated.

## Response codes

| Code  | Description                                                                      |
| ----- | -------------------------------------------------------------------------------- |
| `200` | Supplier data processed successfully                                             |
| `400` | Invalid body, validation error, unknown payment term, or unknown default account |
| `401` | Unauthorized — API key is not linked to a customer                               |
| `403` | Forbidden — missing `suppliers:write` scope                                      |
| `500` | Internal server error                                                            |


## OpenAPI

````yaml POST /suppliers/sap
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:
  /suppliers/sap:
    post:
      tags:
        - Suppliers (SAP)
      summary: Lieferanten aus SAP-System erstellen oder aktualisieren
      description: >
        **Erforderliche Berechtigungen:** `suppliers:write`


        Empfängt und verarbeitet Lieferanten aus dem SAP-System. Akzeptiert ein
        Array von SAP-Lieferanten als Rohdaten.

        `number` wird als `external_id` gespeichert und für Upserts pro Kunde
        verwendet.

        API-Schlüssel muss mit einem Kunden verknüpft sein.

        **Validierung**: Der Body muss ein Array sein, `title` ist je Lieferant
        erforderlich, und angegebene Zahlungsbedingungen müssen im
        comstruct-Mandanten existieren.
      operationId: createSuppliersFromSAP
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/SapSupplierInput'
            examples:
              single_supplier:
                summary: Einzelner SAP-Lieferant
                value:
                  - number: EXTERNAL-09092
                    title: Beispiel GmbH-8
                    legal_uid: D456789900022202
                    country_code: US
                    comment: Bevorzugter Kontakt per E-Mail
                    payment_term: 90T
                    wth_tax_code: '90'
                    bank_details:
                      - number: '9999912'
                        iban: DE89370400440532013000
                      - external_id: '8881112'
                        iban: GB33BUKB20201555555555
                    address:
                      address: Müllerstraße 1
                      city: Berlin
                      zip: '10115'
                      country_code: DE
      responses:
        '200':
          description: Lieferantendaten erfolgreich empfangen
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Supplier data received successfully
        '400':
          description: Ungültiger Anfragekörper oder Validierung fehlgeschlagen
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
        '401':
          description: Nicht autorisiert - Schlüssel ist mit keinem Kunden verknüpft
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized. Key is not linked to any customer.
        '403':
          description: Verboten - Fehlende Berechtigung
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Unauthorized. Missing scope: suppliers:write'
        '500':
          description: Interner Serverfehler
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
      security:
        - ApiKey:
            - suppliers:write
components:
  schemas:
    SapSupplierInput:
      type: object
      required:
        - title
      properties:
        number:
          type: string
          description: >-
            Lieferantennummer aus SAP; wird als `external_id` gespeichert und
            für Upserts verwendet
          example: EXTERNAL-09092
        title:
          type: string
          description: Lieferantenname/Titel
          example: Beispiel GmbH-8
        legal_uid:
          type: string
          description: Optionale Umsatzsteuer-ID
          example: D456789900022202
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 Ländercode
          example: US
        comment:
          type: string
          description: Freitext-Kommentar zum Lieferanten
          example: Bevorzugter Kontakt per E-Mail
        payment_term:
          type: string
          description: >-
            Optionaler SAP-Zahlungsbedingungsschlüssel; muss, falls angegeben,
            im comstruct-Mandanten existieren
          example: 90T
        default_account:
          type: string
          description: >-
            Optionale Kontonummer des Standardkontos; muss, falls angegeben, im
            comstruct-Mandanten existieren
          example: '4000'
        wth_tax_code:
          type: string
          description: Optionaler Quellensteuercode
          example: '90'
        bank_details:
          type: array
          description: Optionale Bankverbindungen
          items:
            $ref: '#/components/schemas/SapSupplierBankDetailsInput'
        address:
          $ref: '#/components/schemas/SapSupplierAddressInput'
    SapSupplierBankDetailsInput:
      type: object
      properties:
        number:
          type: string
          description: >-
            Externe Nummer des Lieferanten-Bankkontos; wird bevorzugt als
            externe ID gespeichert
          example: '9999912'
        external_id:
          type: string
          description: Alternative externe ID, falls `number` nicht gesetzt ist
          example: BANK-EXT-001
        iban:
          type: string
          description: IBAN in Großbuchstaben, ohne Leerzeichen
          example: DE89370400440532013000
    SapSupplierAddressInput:
      type: object
      properties:
        address:
          type: string
          example: Müllerstraße 1
        city:
          type: string
          example: Berlin
        zip:
          type: string
          example: '10115'
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 Ländercode
          example: DE
  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.

````