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: Erste Implementierung für den Pilotbetrieb. Produktivzugang und Bereitstellung werden mit confBuild vereinbart. 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.
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. Kopieren Sie ihn in die geschützte Konfiguration Ihres ERP-Servers.
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 Hosting-Adresse nach produktiver Bereitstellung lautet:
https://app.confbuild.com/api/v1
Eine gesonderte Pilotadresse kann von confBuild bereitgestellt werden. 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 |
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 |
| 409 | Idempotenzkonflikt oder Grenze aktiver Schlüssel |
| 413 | Paket zu groß |
| 429 | Nach Retry-After erneut versuchen |
| 503 | Vorübergehender Fehler oder Prüfsummenfehler; Verarbeitungsstand nicht fortschreiben |
Fehler liefern { "error": { "code": "…", "message": "…", "requestId": "…" } }. Geben Sie dem Support die Anfragekennung, niemals Ihren Schlüssel.
Integrationsbeispiel
Das Python-Beispiel benötigt nur Python 3. Es lädt Pakete einschließlich Anlagen herunter, prüft die Hashes und schreibt den Cursor erst nach erfolgreicher Verarbeitung fort.
# 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.