> ## 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. # SAP-Lieferanten erstellen oder aktualisieren > **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. ## Übersicht Mit diesem Endpunkt synchronisieren Kundensysteme Lieferanten aus SAP nach comstruct. Der Request-Body ist immer ein Array, sodass ein einzelner Lieferant und Batches über denselben `POST`-Aufruf verarbeitet werden. Wenn `number` gesetzt ist, wird sie als `external_id` des Lieferanten gespeichert. Existiert für denselben Kunden bereits ein Lieferant mit dieser `external_id`, wird der Datensatz aktualisiert. Senden Sie `number` für jeden SAP-Lieferanten mit. Das Feld ist für die Schema-Validierung nicht zwingend, wird aber für idempotente SAP-Syncs und spätere Lookups benötigt. ## Berechtigungen | Scope | Tenant-Typ | | ----------------- | -------------------- | | `suppliers:write` | Kunden-API-Schlüssel | Der API-Schlüssel muss mit einem Kunden verknüpft sein. ## Header | Header | Pflicht | Beschreibung | | -------------- | ------- | ----------------------------------------- | | `x-api-key` | Ja | API-Schlüssel mit Scope `suppliers:write` | | `Content-Type` | Ja | `application/json` | ## Request-Body Der Body muss ein JSON-Array von Lieferanten enthalten. ### Lieferantenfelder | Feld | Pflicht | Beschreibung | | ----------------- | ------- | ---------------------------------------------------------------------------- | | `title` | Ja | Lieferantenname | | `number` | Nein | SAP-Lieferantennummer; wird zu `external_id` gemappt und für Upserts genutzt | | `legal_uid` | Nein | USt-IdNr. oder Steuernummer | | `country_code` | Nein | ISO 3166-1 Alpha-2 Ländercode | | `comment` | Nein | Freitext-Kommentar zum Lieferanten | | `payment_term` | Nein | Zahlungsbedingungsschlüssel; muss im comstruct-Mandanten existieren | | `default_account` | Nein | Kontonummer des Standardkontos; muss im comstruct-Mandanten existieren | | `wth_tax_code` | Nein | Quellensteuercode; Standardwert ist `00` | | `bank_details` | Nein | Bankverbindungen des Lieferanten | | `address` | Nein | Lieferantenadresse | ### Bankverbindungen (`bank_details[]`) | Feld | Pflicht | Beschreibung | | ------------- | ------- | -------------------------------------------------------------------- | | `iban` | Nein | Gültige IBAN; Einträge ohne IBAN werden ignoriert | | `number` | Nein | Externe Nummer der Bankverbindung; wird bevorzugt als ID gespeichert | | `external_id` | Nein | Alternative externe ID, falls `number` nicht gesetzt ist | ### Adresse (`address`) | Feld | Pflicht | Beschreibung | | -------------- | ------- | ----------------------------- | | `address` | Nein | Straße und Hausnummer | | `city` | Nein | Ort | | `zip` | Nein | Postleitzahl | | `country_code` | Nein | ISO 3166-1 Alpha-2 Ländercode | ## Beispiel ```bash theme={null} curl -X POST "https://api.comstruct.com/v1/suppliers/sap" \ -H "x-api-key: IHR_API_SCHLUESSEL" \ -H "Content-Type: application/json" \ -d '[ { "number": "SAP-SUP-001", "title": "Beispiel Lieferant GmbH", "legal_uid": "DE123456789", "country_code": "DE", "comment": "Bevorzugter Kontakt per E-Mail", "payment_term": "30T", "default_account": "4000", "wth_tax_code": "00", "bank_details": [ { "number": "BANK-001", "iban": "DE89370400440532013000" } ], "address": { "address": "Musterstraße 1", "city": "Berlin", "zip": "10115", "country_code": "DE" } } ]' ``` ## Verhalten * `number` wird als `external_id` gespeichert; vorhandene Lieferanten mit derselben `external_id` und demselben Kunden werden aktualisiert. * Nur die Felder `external_id`, `legal_uid`, `country_code`, `withholding_tax_code`, `payment_term_id`, `title`, `comment`, `address`, `city` und `zip` werden bei Konflikten aktualisiert. * `payment_term` wird gegen die Zahlungsbedingungen des Kunden aufgelöst. Unbekannte Werte führen zu `400`. * `default_account` wird gegen die Konten des Kunden aufgelöst. Unbekannte Werte führen zu `400`. Fehlt das Feld beim Upsert, bleibt ein vorhandenes `default_account_id` erhalten. * Fehlt `wth_tax_code`, speichert comstruct den Standardwert `00`. * Bankverbindungen werden anhand von IBAN, Lieferant und Tenant zusammengeführt; bei Konflikten wird die externe ID der Bankverbindung aktualisiert. ## Response Codes | Code | Beschreibung | | ----- | ------------------------------------------------------------------------------------------------ | | `200` | Lieferantendaten erfolgreich verarbeitet | | `400` | Ungültiger Body, Validierungsfehler, unbekannte Zahlungsbedingung oder unbekanntes Standardkonto | | `401` | Nicht autorisiert — API-Schlüssel ist mit keinem Kunden verknüpft | | `403` | Verboten — fehlender Scope `suppliers:write` | | `500` | Interner Serverfehler | ## 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` und IDS-Endpunkte unter `/ids` liegen **ohne** `/v1`-Präfix (Basis-URL `https://api.comstruct.com`). Kalender verwenden Token-basierte Authentifizierung; IDS ist ein öffentlicher Callback ohne API-Schlüssel. ## 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 - Asynchroner Lieferschein-PDF-Upload (`POST /deliveries/pdf`): 16MiB - 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.10 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. ````