ERP-Übergabe per REST-API
Die ERP-Übergabe-API stellt freigegebene Stücklisten und zugehörige Dokumente als unveränderliche Pakete bereit. Ihr ERP-Dienstleister kann diese Daten abrufen, Artikel zuordnen und in Ihren betrieblichen Ablauf übernehmen. Nach der Freigabe ist kein geöffnetes confBuild-Fenster erforderlich.
Status (9. Oktober 2026): Die REST-API und die ERP-Übergabe im Editor sind produktiv verfügbar. Eigentümer privater Projekte erstellen ihren projektbezogenen API-Zugang direkt im Stücklisten-Dialog. Für die Einführung in Ihr ERP vereinbaren wir einen Pilotumfang. Die Schnittstelle ist eine Grundlage für individuelle Integrationen; eine fertige Anbindung an SAP, Microsoft Dynamics oder Odoo ist damit nicht zugesagt.
OpenAPI 3.1 herunterladen · Python-Beispiel herunterladen
Ein Paket freigeben
- Öffnen Sie Ihr eigenes gespeichertes Projekt im confBuild-Editor und dessen Stückliste.
- Prüfen Sie die Positionen und die aktiven Filter. ERP-Übergabe übernimmt genau die angezeigten Positionen, einschließlich der aktuellen Such-/Ausblendfilter. Eine Konstruktion kann daher auch nur teilweise übergeben werden.
- Tragen Sie optional eine externe Referenz ein, beispielsweise Ihre Angebotsnummer. JSON und CSV werden automatisch aus der übergebenen Stückliste erzeugt.
- Fügen Sie bei Bedarf PDF-, STEP- oder DXF-Dateien hinzu. Bestätigen Sie, dass sie zu diesem Stand gehören. Die API speichert deren Bytes unverändert; ein automatischer CAD-/Zeichnungsabgleich erfolgt nicht.
- Bestätigen Sie die Freigabe und wählen Sie Paket freigeben. Sie erhalten eine Freigabekennung, laufende Nummer und Hinweise zur Datenabdeckung.
Jede Freigabe bleibt unverändert. Modelländerungen aktualisieren bestehende Pakete nicht. Für einen neuen Stand öffnen Sie die aktuelle Stückliste erneut und geben ein neues Paket frei. „Freigegeben“ bezeichnet Ihre Übergabeentscheidung, keine automatische technische Zertifizierung.
Bei einem Verbindungsabbruch geben Sie dieselben Angaben und Dateien im selben Browser-Tab erneut frei. Der Dialog merkt sich die laufende Anfrage im Sitzungsspeicher, auch nach erneutem Öffnen oder Neuladen dieses Tabs. Gespeichert werden nur eine Prüfsumme und eine Wiederholungskennung, keine Stückliste oder Zugangsdaten. Anlagen müssen erneut ausgewählt und eine externe Referenz identisch eingegeben werden. Nach bestätigtem Erfolg ist eine erneute Freigabe ein neues Paket. Bei gesperrtem Sitzungsspeicher gilt der Schutz nur bis zum Neuladen; ein neuer Tab oder andere Angaben gelten als neue Anfrage.
API-Zugang erstellen
Im selben Dialog erstellen Sie unter API-Zugänge für dieses Projekt einen benannten Schlüssel. Er erscheint einmalig und wird serverseitig nur als Hash gespeichert. Über Schlüssel kopieren übernehmen Sie ihn in die geschützte Konfiguration Ihres ERP-Servers; anschließend können Sie ihn ausblenden. Die Liste zeigt aktive, abgelaufene und widerrufene Zugänge.
Ein Schlüssel kann ausschließlich Freigaben dieses einen Projekts lesen. Er kann weder Modelle ändern noch neue Pakete freigeben oder andere Schlüssel verwalten. Über den Dialog ausgestellte Schlüssel sind 90 Tage gültig; die Verwaltungs-API erlaubt 1–365 Tage. Pro Projekt sind höchstens 20 aktive Schlüssel erlaubt. Widerrufen Sie einen Schlüssel im Dialog, um weitere Zugriffe zu sperren. Bereits heruntergeladene Kopien bleiben beim Empfänger.
Der erste Umfang unterstützt den Eigentümer eines privaten Projekts. Geteilte Firmenprojekte oder öffentliche Vorlagen müssen in den eigenen Projektbestand übernommen werden. Wird das Quellprojekt gelöscht oder ist es nicht mehr dem Eigentümer zugeordnet, verweigert die API weitere Abrufe.
Basisadresse und erster Abruf
Die produktive Basisadresse lautet:
https://app.confbuild.com/api/v1
Den aktuellen Vertrag liefert auch OpenAPI direkt von der API. Alle privaten Endpunkte verwenden Authorization: Bearer …. Schlüssel gehören auf Ihren Server, nicht in öffentliches JavaScript oder URLs.
# CONFBUILD_API_KEY zuvor sicher als Umgebungsvariable setzen.
curl --fail-with-body \
-H "Authorization: Bearer $CONFBUILD_API_KEY" \
'https://app.confbuild.com/api/v1/releases?limit=25'
Die Antwort enthält items und nextCursor. Jede Freigabe hat eine aufsteigende sequence. Für regelmäßige Abfragen speichern Sie die höchste vollständig verarbeitete Sequenz und übergeben sie als cursor. nextCursor: null bedeutet lediglich, dass aktuell keine weitere Seite vorliegt; es ersetzt Ihren gespeicherten Verarbeitungsstand nicht.
curl --fail-with-body \
-H "Authorization: Bearer $CONFBUILD_API_KEY" \
"https://app.confbuild.com/api/v1/releases/$RELEASE_ID/bom"
Endpunkte
| Methode | Pfad | Funktion |
|---|---|---|
| GET | /releases?cursor=0&limit=25 |
Freigaben des Projekts, aufsteigend |
| GET | /releases/{id} |
Metadaten, Hinweise, Dokumentmanifest |
| GET | /releases/{id}/bom |
Eingefrorene Stückliste als JSON |
| GET | /releases/{id}/documents |
Dokumente mit Typ, Größe und SHA-256 |
| GET | /releases/{id}/documents/{documentId} |
Geschützter Download |
| GET | /openapi.json |
Öffentliche API-Beschreibung |
Die Verwaltungsendpunkte POST /releases, GET/POST /keys und DELETE /keys/{id} benötigen ein aktuelles Firebase-ID-Token des Projekteigentümers, keinen Leseschlüssel. Bei GET/DELETE wird projectId als Query-Parameter mitgegeben, bei POST im JSON-Body. Diese Vorgänge übernimmt der confBuild-Dialog. Für eigene Verwaltungsclients beschreibt die OpenAPI-Datei die vollständigen Anfrageformate.
POST /releases verlangt einen Idempotency-Key mit 16–128 Zeichen aus Buchstaben, Zahlen, Bindestrich und Unterstrich. Wiederholungen mit demselben Inhalt liefern dieselbe Freigabe (200); neue Freigaben liefern 201. Anderer Inhalt mit demselben Schlüssel wird mit 409 abgewiesen. Nach Timeout denselben Schlüssel und denselben Body erneut verwenden.
Daten verstehen
| Feld | Bedeutung |
|---|---|
articleNumber |
Interne Artikelnummer aus der Stückliste, sonst null |
manufacturerPartNumber |
Herstellerartikelnummer, getrennt von der internen Nummer |
lineId |
Kennung einer Stücklistengruppierung, keine automatische ERP-Artikelnummer |
quantity, unit |
Menge und Einheit: piece, meter, sqm, kg, liter |
sourcing |
make, buy oder unknown |
material |
Werkstoffbezeichnung aus der Stückliste |
mechanicalMaterialId, materialStatus |
Im ersten Editor-Adapter noch null / unknown; keine geprüfte Werkstoff-ID aus der Bezeichnung ableiten |
articleRevision |
Im ersten Editor-Adapter unbekannt (null) |
sourceRevision |
Vom Projekt übernommene Revisionsbezeichnung, kein Nachweis eines serverseitig geprüften CAD-Stands |
contentHash |
Prüfsumme des Übergabepakets und Dokumentmanifests |
externalReference |
Optionale Zuordnung zum Angebot/Auftrag im ERP |
Für eigene Freigabe-Clients: Pflichtnamen, lineId und Einträge in sourceIds/assemblies dürfen nicht leer sein oder nur aus Leerzeichen bestehen. Äußere Leerzeichen werden entfernt; leere optionale Textfelder werden zu null und bleiben als fehlende Angaben erkennbar. Textfelder haben höchstens 500 Zeichen, lineId 128 und Quellkennungen 250; die Grenzen gelten vor dem Entfernen äußerer Leerzeichen. position ist eine positive ganze Zahl bis 9.007.199.254.740.991. Unbekannte Quellen als leeres Array [] übergeben. lineId-Kennungen müssen nach dem Entfernen äußerer Leerzeichen weiterhin eindeutig sein.
JSON ist das maßgebliche strukturierte Format. CSV ist eine flache Auswahl derselben Stücklistendaten; Formelanfänge in Textzellen werden für Tabellenprogramme entschärft. Anlagen tragen provenance: publisher-attested, automatisch erzeugte Stücklistendokumente generated-from-bom. Prüfen Sie beim Download Dateigröße und SHA-256 gegen das Manifest.
Die API liefert keine Preise, Bestände, Arbeitspläne oder vollständigen Modellparameter. Fehlende Artikel-, Werkstoff- oder Quellenangaben erscheinen als null beziehungsweise Warnung. Artikelzuordnung und Umwandlung einer Konstruktionsstückliste in eine Fertigungsstückliste gehören zur konkreten ERP-Integration.
Grenzen und Fehler
Maximal 2.000 Positionen und 600 KB normalisierte Metadaten/Stückliste pro Freigabe. Optional bis zu acht Anlagen, jeweils 3 MiB und zusammen 6 MiB; maximal 9 MiB Anfragegröße. Dateinamen dürfen ASCII-Buchstaben, Zahlen, Leerzeichen, Punkt, Bindestrich und Unterstrich enthalten und müssen auf PDF/STEP/STP/DXF enden.
Pro Schlüssel bzw. Eigentümer gelten 120 authentifizierte Anfragen pro Minute, für die Schlüsselerstellung zusätzlich fünf und für Freigabeversuche zehn pro Eigentümer und Minute. 429 enthält Retry-After: 60. Zusätzliche vorgeschaltete Schutzgrenzen können früher greifen.
| HTTP-Status | Umgang damit |
|---|---|
| 400 | Anfragefelder, Kennungen oder Seitengröße korrigieren |
| 401 | Schlüssel/Anmeldung fehlt, ist abgelaufen oder widerrufen |
| 403 | Vorgang liegt außerhalb des Schlüsselumfangs |
| 404 | Projekt, Freigabe oder Dokument nicht zugänglich |
| 405 | HTTP-Methode für diesen Endpunkt nicht unterstützt |
| 409 | Idempotenzkonflikt oder Grenze aktiver Schlüssel |
| 413 | Paket zu groß |
| 429 | Nach Retry-After erneut versuchen |
| 431 | Anfrageheader verkleinern |
| 503 | Vorübergehender Fehler oder Prüfsummenfehler; Verarbeitungsstand nicht fortschreiben |
Fehler liefern { "error": { "code": "…", "message": "…", "requestId": "…" } }. Die Anfragekennung steht auch im Header X-Request-Id, einschließlich abgewiesener zu großer Pakete. Geben Sie dem Support die Anfragekennung, niemals Ihren Schlüssel. Fehler einer vorgeschalteten Hosting- oder Netzwerkschicht können davon abweichen.
Integrationsbeispiel
Das Python-Beispiel benötigt nur Python 3. Es lädt Pakete einschließlich Anlagen herunter, prüft Dateigrößen und SHA-256-Prüfsummen und schreibt den Cursor erst nach einem vollständig geprüften Download fort. Bei einem Abbruch werden bereits geprüfte Dateien beim nächsten Aufruf wiederverwendet; beschädigte Dateien werden erneut geladen. Vorübergehende Netzwerkfehler und HTTP 429/502/503/504 werden bis zu viermal versucht, mit Wartezeiten von 2, 4 und 8 Sekunden beziehungsweise Retry-After (höchstens 60 Sekunden). Authentifizierungsfehler werden sofort gemeldet. Antwortgrößen und fortlaufende Cursor werden geprüft. Starten Sie nur einen Abrufprozess je Zielordner.
# Schlüssel zuvor sicher als CONFBUILD_API_KEY bereitstellen.
python3 confbuild-handover-pull.py
Optional steuern CONFBUILD_API_BASE und CONFBUILD_OUTPUT_DIR API-Adresse und Zielordner. Bei Schlüsselrotation einen neuen Zielordner wählen oder den gespeicherten Cursor bewusst zurücksetzen. Das Beispiel überträgt keine Daten in ein ERP; der kundenspezifische Import folgt danach.