B2B-API

Die FabParts-API

Die volle Bestell-Pipeline als REST-API: Datei hochladen, Sofort-Schätzung, exakter Preis aus echtem Slice, Farb-Lagerbestand, Bestellung mit Zahlungslink, Lieferstatus. Registrierung per E-Mail, Authentifizierung per API-Key.

Schnellstart

1. Registrieren, der API-Key kommt per E-Mail:

curl -X POST https://fabparts.de/api/v1/registrierung \
  -H "content-type: application/json" \
  -d '{"email": "einkauf@deine-firma.de", "firma": "Muster GmbH"}'

2. Datei hochladen und Sofort-Schätzung bekommen (der Key gehört in den Header X-Api-Key):

curl -X POST https://fabparts.de/api/v1/angebot \
  -H "X-Api-Key: fpk_DEIN_KEY" \
  -F "datei=@halterung.stl" \
  -F material=PLA -F subtyp=Matte -F preset=standard \
  -F layer=0.20 -F stueckzahl=10 -F unterseite=standard

farbmodus ist optional: einfarbig (Default) oder mehrfarbig für 3MF-Dateien mit Farbzuordnung (bis 4 Slots; die Antwort nennt farbSlots, die Bestellung braucht dann bambuColorIds als Array je Position, 4,90 € Aufpreis je Zusatzfarbe). unterseite ist optional: standard (Default, feine, leicht glänzende Narbung der strukturierten Platte) oder glatt (glatte, glänzende Unterseite mit feinem Bahnmuster von der glatten Platte, Aufpreis 4,90 € je Position, im Preis enthalten). skalierung ist optional: Faktor zwischen 0.001 und 1000 relativ zur hochgeladenen Datei (z. B. 0.1667 für 1:6, 25.4 für eine in Zoll gespeicherte STL, 1000 für einen Blender-Export in Metern, 0.001 für eine 1000-fach zu große, in Metern angelegte STEP-Datei); die Datei wird vor Analyse und Preis gleichmäßig skaliert, die Antwort nennt unter skalierung Faktor, Maße und Originalmaße. 3MF-Dateien mit anderer Einheit als Millimeter rechnen wir automatisch um. raftAus ist optional (1): Ist für das Teil eine Druckunterlage (Raft) vorgesehen, drucken wir es ohne; die Haftung auf der Platte ist dann unsicher, deshalb verlangt die Bestellung die Bestätigung des Druckversuchs (POST /api/v1/angebot/:id/druckversuch mit {"bestaetigt": true}, bei Misserfolg der Wert der Position als Gutschein). Die Antwort nennt unter haftung die Maßnahme (Haftrand oder Raft) oder null.

Antwort: ein Angebot mit id, Prüf-Ampel (check) und Schätzspanne in Cent. Bei Bambu-Studio-Projektdateien mit mehreren Druckplatten kommt zusätzlich eine teile-Liste, ein Angebot je Platte.

3. Exakten Preis berechnen (echter Slice auf unseren Produktionsprofilen, dauert bis zu etwa zwei Minuten):

curl -X POST https://fabparts.de/api/v1/angebot/FP-DEINE-ANGEBOTS-ID/preis \
  -H "X-Api-Key: fpk_DEIN_KEY"

Antwort: {"status": "bestellbar", "preisCent": ..., "versandCent": ...}. Der Preis ist verbindlich, solange das Angebot bestellbar ist.

Alle Endpunkte

EndpunktZweck
POST /api/v1/registrierungKonto anlegen, Key per Mail. Ohne Key aufrufbar.
GET /api/v1/kontoEigenes Konto: Limits, heutiger Verbrauch, Bestell-Freigabe.
GET /api/v1/farbenBestellbare Farben je Material/Ausführung, live aus dem Lagerbestand.
POST /api/v1/angebotDatei hochladen (STL, 3MF, OBJ oder STEP, multipart; STEP wird automatisch umgewandelt, dauert je nach Modell bis zu zwei Minuten), Sofort-Schätzung.
POST /api/v1/angebot/:id/preisExakter Preis aus echtem Slice.
POST /api/v1/angebot/:id/stueckzahlStückzahl eines bestellbaren Angebots ändern (ohne neuen Slice), Body {"stueckzahl": 25}.
POST /api/v1/bestellungBestellung anlegen, Antwort enthält die Stripe-Zahlungs-URL. Erst nach Freischaltung.
GET /api/v1/bestellung/:id/statusBestellstatus abfragen (alle Werte in der Status-Referenz unten).
POST /api/v1/nachbestellenAus einer früheren Bestellung frische Angebote mit gleicher Konfiguration anlegen, Body {"bestellungId": "FP-B-..."}.
DELETE /api/v1/angebot/:idEigenes Angebot sofort löschen, Antwort ist ein Löschprotokoll. Details im Abschnitt Datei-Löschung.
POST /api/v1/shopify/verbindenShopify-Shop mit dem Konto verknüpfen, Antwort enthält den Install-Link. Details im Abschnitt Shopify-Anbindung.
GET /api/v1/shopifyVerbundene Shops mit Mapping-Zahl und Bestellständen.

Feldnamen sind deutsch und identisch zur Weboberfläche (dieselbe Pipeline dahinter). Beträge sind immer ganze Cent, inklusive 19 % MwSt.

Maschinenlesbare Spezifikation: openapi.json (OpenAPI 3.1) zum Import in Postman, Insomnia oder zur Client-Generierung. Diese Seite lässt sich außerdem über die Druckfunktion des Browsers als sauber formatiertes PDF speichern.

Status-Referenz

Angebot (Antwortfeld status):

WertBedeutung
neuUpload angenommen, Analyse läuft.
geschaetztSchätzspanne liegt vor, exakter Preis noch nicht berechnet.
check_fehlerDatei abgelehnt oder Druckvorbereitung fehlgeschlagen; Gründe stehen in check.hinweise.
bestellbarExakter Preis liegt vor (preisCent, versandCent) und gilt 14 Tage.
bestelltAngebot ist Teil einer Bestellung.

Bestellung (GET /api/v1/bestellung/:id/status):

WertBedeutung
neuAngelegt, Zahlung offen (verfällt unbezahlt nach 24 Stunden).
rechnung_angefragtRechnungskauf angefragt, wartet auf unsere Freigabe (werktags kurzfristig).
bezahltZahlungseingang bestätigt, Produktion startet automatisch.
in_produktionWird gefertigt.
versendetPaket übergeben beziehungsweise zur Abholung bereit.
reklamationReklamation angenommen, Neudruck in Arbeit.
storniertStorniert.
verfallenUnbezahlt verfallen; die Angebote sind wieder frei bestellbar.

Statusabfrage per Polling, empfohlen im Minutenabstand oder seltener. Webhooks bieten wir derzeit nicht an; wenn ihr sie braucht, schreibt an bestellung@fabparts.de.

Fehler-Referenz

Jeder Fehler kommt als JSON mit einer deutschen Klartext-Meldung: {"fehler": "..."}. Die Codes:

CodeBedeutungTypische Auslöser
401Key fehlt oder ungültigHeader X-Api-Key vergessen, Key gesperrt.
403Nicht freigeschaltetBestellen vor der manuellen Konto-Freigabe.
404Nicht gefundenUnbekannte Angebots- oder Bestell-ID; beim Löschen auch: Angebot gehört nicht zu diesem API-Konto.
409Zustand verhindert die AktionLöschung während Bestellvorgang oder Produktion; die Meldung nennt den Grund.
422Eingabe ungültigDatei zu groß oder defekt, fehlende Zustimmungs-Flags, ungültige Konfiguration, nicht vorrätige Farbe.
429Tageskontingent erschöpftUpload- oder Slice-Limit erreicht, Reset um Mitternacht UTC.
502Nachgelagerter Dienst nicht erreichbarFertigungs-Gateway beim Slice oder bei der Artefakt-Löschung; Aufruf später wiederholen.

Betriebsdetails für die Integration

Bestellen über die API

Bestellen erfordert eine einmalige manuelle Freischaltung deines Kontos (kurze Prüfung durch uns, du bekommst eine E-Mail). Danach:

curl -X POST https://fabparts.de/api/v1/bestellung \
  -H "X-Api-Key: fpk_DEIN_KEY" \
  -H "content-type: application/json" \
  -d '{
    "positionen": [{"angebotId": "FP-...", "bambuColorId": "10101"}],
    "kunde": {"email": "einkauf@deine-firma.de", "firma": "Muster GmbH",
              "name": "Erika Musterfrau",
              "strasse": "Beispielweg 1", "plz": "32791", "ort": "Lage"},
    "zustimmung": {"agb": true, "widerruf_kenntnis": true,
                   "angaben_geprueft": true, "beschaffenheit": true},
    "versandArt": "versand",
    "dateiAufbewahren": true
  }'

Optional kunde.land als zweistelliger Ländercode (Standard DE). Angenommen wird nur, was GET /api/laender unter lieferung auflistet (Deutschland und die jeweils freigeschalteten EU-Länder); bei Lieferung dorthin kommt das Porto der jeweiligen Zone zum Teilepreis hinzu und wird mit in Rechnung gestellt. Bei Lieferung ins EU-Ausland berechnen wir dir als Auftraggeber weiterhin die deutsche Umsatzsteuer; die Pflichten als Verkäufer im Zielland (Umsatzsteuer, Verpackungsregistrierung) liegen bei dir.

Antwort: {"id": "FP-B-...", "url": "https://checkout.stripe.com/..."}. Die Zahlung läuft über den Stripe-Link (Karte, PayPal); nach Zahlungseingang startet die Produktion automatisch und dein System kann den Status pollen. Alternativ bestellt ihr auf Rechnung: "zahlart": "rechnung" (nur mit kunde.firma) legt die Bestellung als Rechnungskauf-Anfrage an, wir geben werktags kurzfristig frei, die Rechnung hat 14 Tage Zahlungsziel; der Status wechselt dann von rechnung_angefragt auf bezahlt. Die zustimmung-Flags bestätigen AGB, den Ausschluss des Widerrufsrechts bei Anfertigung nach Kundenspezifikation, die Prüfung der Angaben und die Kenntnisnahme der fertigungstypischen Beschaffenheit von FDM-Teilen (sichtbare Schichtlinien, siehe Ratgeber und AGB Punkt 7); alle vier sind Pflicht. kunde.firma ist optional: Ist sie gesetzt, erscheint die Firma auf Rechnung und Versandunterlagen, kunde.name bleibt die Ansprechperson.

Direktversand an deinen Endkunden (Streckengeschäft): Mit "direktversand": true (nur mit kunde.firma) geht das Paket direkt an die Lieferadresse aus kunde, also an deinen Endkunden: ohne Preisunterlagen, mit einem neutralen Lieferschein im Namen deiner Firma (optionaler Freitext dafür: "lieferschein_text": "Ersatzteillieferung zu Ihrem Auftrag 4711", max. 200 Zeichen). Deine Rechnung kommt wie immer per E-Mail; als Rechnungsanschrift dient kunde.rechnungsadresse, falls gesetzt. Der gesetzliche Produktsicherheits-Beileger (Charge, Material, Herstellerangabe FabStack GmbH) liegt jedem Paket bei; was dein Endkunde sieht und welche Angaben in dein eigenes Angebot gehören, steht im Produktsicherheits-Datenblatt für Wiederverkäufer. Verkaufst du unter eigener Marke, gib "hersteller": {"name", "strasse", "plz", "ort", "email"} mit (nur mit kunde.firma, alle fünf Felder Pflicht): der Beileger nennt dann dich als Hersteller und FabStack als Fertiger. So lieferst du 3D-gedruckte Teile an deine Kunden, ohne sie selbst anzufassen: kein Wareneingang, kein Umverpacken, kein Weiterversand.

Anmerkung an uns: Mit "anmerkung": "..." (optional, max. 500 Zeichen) gibst du uns einen Freitext zur Bestellung mit, etwa Wünsche zur Farbe oder Hinweise zur Lieferung. Wir lesen ihn vor dem Druck; Bestellungen mit Anmerkung starten deshalb erst, nachdem wir sie gesichtet haben. Änderungen am Modell selbst (Größe, Ausrichtung, Schichthöhe) gehören in die Angebotsparameter, nicht in die Anmerkung.

Shopify-Anbindung: Bestellungen automatisch übernehmen

Verkaufst du personalisierte Produkte (etwa Hundemarken oder Namensschilder) über einen Shopify-Shop, auch mit angebundenem Etsy-Kanal, übernimmt FabParts die Bestellungen automatisch: Jede neue Shopify-Bestellung wird je Position zu einem Angebot und dann zu einer FabParts-Bestellung auf Rechnung mit Direktversand an deinen Endkunden. Nach dem Versand melden wir das Fulfillment mit Sendungsnummer an Shopify zurück, dein Kunde bekommt die Versandbestätigung aus deinem Shop.

  1. Konto mit freigeschaltetem Bestellen (siehe oben); die Bestellungen laufen als Rechnungskauf mit 14 Tagen Zahlungsziel.
  2. Verknüpfung starten: POST /api/v1/shopify/verbinden mit {"shop": "dein-shop.myshopify.com"}. Die Antwort enthält einen installUrl, eine Stunde gültig.
  3. Den Link im Browser öffnen und die App in Shopify freigeben (Rechte: Bestellungen lesen, Fulfillments schreiben, Produkte lesen). Danach ist der Shop mit deinem Konto verbunden; GET /api/v1/shopify zeigt den Stand.
  4. Wir hinterlegen je Shopify-Variante das FabParts-Produkt samt Parameter-Vorlage (Personalisierung aus der Line-Item-Eigenschaft „Personalization", weitere Felder aus weiteren Eigenschaften), Material und Farben. Schick uns dafür die Varianten-IDs und die gewünschte Zuordnung an bestellung@fabparts.de.
curl -X POST https://fabparts.de/api/v1/shopify/verbinden \
  -H "X-Api-Key: fpk_DEIN_KEY" -H "content-type: application/json" \
  -d '{"shop": "dein-shop.myshopify.com"}'

Bestellungen ohne Mapping oder mit Lieferadresse außerhalb unseres Liefergebiets (Deutschland und die freigeschalteten EU-Länder, abrufbar unter GET /api/laender) legen wir nicht an; du bekommst dazu eine E-Mail mit dem Grund. Lieferscheine tragen deine Firma und die Shopify-Bestellnummer, Herstellerangaben für den Produktsicherheits-Beileger hinterlegen wir auf Wunsch je Shop. Stornierst du eine Bestellung in Shopify, bevor wir sie angelegt haben, wird sie bei uns verworfen; danach schreib uns kurz.

Datei-Löschung auf Knopfdruck

Für sensible Konstruktionsdaten: DELETE /api/v1/angebot/:id löscht ein über deinen API-Key hochgeladenes Angebot sofort, ohne auf unsere automatischen Löschfristen zu warten. Die Antwort ist ein Löschprotokoll mit Zeitstempel, das du für deine eigene Dokumentation ablegen kannst.

curl -X DELETE https://fabparts.de/api/v1/angebot/FP-... \
  -H "X-Api-Key: fpk_DEIN_KEY"

Limits und Freischaltung