Fulfillment API · v1
Ihr Shop verkauft. Wir fertigen und versenden.
Ihr Kunde lädt bei Ihnen eine CAD-Datei hoch und bezahlt bei Ihnen. Über diese Schnittstelle holen Sie sich den verbindlichen Preis, legen den Auftrag an und bekommen jeden Statuswechsel als signierten Webhook. Ihre Kunden-Mails verschicken Sie selbst, unter Ihrer Marke.
Zur Einbau-Anleitung mit fertigem CodeGrundlagen
Jede Anfrage trägt Authorization: Bearer <Schlüssel>. Ihre Brand bekommt einen Live- und einen Testschlüssel. Testaufträge laufen durch denselben Ablauf, werden aber nie gedruckt, nie berechnet und tauchen nicht in unserer Produktion auf. Alle Webhooks enthalten "test": true.
Beträge sind Cent-Beträge in EUR, netto. wholesale ist, was wir Ihnen berechnen. retail ist der empfohlene Endkundenpreis mit dem Aufschlag, den wir für Ihre Brand hinterlegt haben. shippingCents ist eine feste Versandpauschale je Auftrag (deckt auch Verpackung/Bearbeitung ab, Standard 9,90 €, für Ihre Brand ggf. individuell hinterlegt), ab wholesale.positionsNetCents≥ 250 € entfällt sie — sie steht sowohl unter wholesale als auch unter retail, mit demselben Wert: Auf Versand erheben wir keinen Aufschlag, Sie geben ihn 1:1 an Ihren Kunden weiter. Es gibt keinen Mindestbestellwert und keinen Zuschlag für kleine Aufträge.
externalOrderId ist pro Brand eindeutig. Senden Sie denselben Auftrag noch einmal, legen wir keinen zweiten an und antworten mit "duplicate": true.
| Endpunkt | Zweck |
|---|---|
| GET/api/v1/catalog | Produkttypen, Materialien und Lieferzeiten Ihrer Brand. |
| GET/api/v1/status | Betriebsstatus: Hinweistext (z. B. Umbau), ob Express angeboten wird und wie viele Werktage zur Lieferzeit hinzukommen. |
| GET/api/v1/catalog/materials/{id} | Einzelnes Material gezielt nachschlagen (z. B. um eine gespeicherte materialId zu prüfen) — ohne den ganzen Katalog zu laden. |
| POST/api/v1/estimate | Unverbindlicher Live-Preis aus Volumen/Maßen — ohne Datei-Upload, nichts wird gespeichert. |
| POST/api/v1/files | Datei anmelden (STEP, IGES, STL, GLB oder OBJ). Antwort enthält eine signierte Upload-URL (30 Min., per PUT) oder übernimmt eine fileUrl direkt. |
| GET/api/v1/files/{fileId} | Prüfstatus: pending, ready oder invalid, dazu Maße und Volumen. |
| POST/api/v1/quotes | Verbindliches Angebot über eine oder mehrere Dateien, 14 Tage gültig. |
| GET/api/v1/quotes/{quoteId} | Angebot erneut abrufen. |
| POST/api/v1/orders | Auftrag aus einem Angebot anlegen oder alles in einem Aufruf (Dateien per URL). |
| GET/api/v1/orders/{externalOrderId} | Status aller Positionen inkl. Tracking. |
| POST/api/v1/orders/{externalOrderId}/cancel | Storno, solange noch keine Position in Produktion ist. |
Live-Preis ohne Datei (optional)
Für einen Konfigurator, bevor der Kunde eine Datei hochgeladen hat: Schicken Sie Volumen und Maße direkt mit. Es wird dieselbe Formel wie beim verbindlichen Angebot gerechnet, aber nichts gespeichert — der Preis ist eine Schätzung, keine Zusage.
Bauen Sie sich keine eigene Kopie unserer Preisformel — ändert sich etwas an Material- oder Maschinenpreisen, laufen eigene Nachbauten sonst unbemerkt auseinander.
POST /api/v1/estimate
{
"productType": "industrial-sla",
"volumeCm3": 12.5,
"sizeMm": [40, 22, 15]
}
200 OK
{
"test": false,
"productType": "industrial-sla",
"materialId": null,
"leadTimeWorkdays": 5,
"unitPriceCents": 718,
"retailUnitPriceCents": 934,
"currency": "EUR",
"fitsMaxSize": true,
"maxSizeMm": [200, 125, 210]
}
// Unverbindlich und nicht persistiert — dieselbe Formel wie POST /api/v1/quotes, nur ohne Datei.
// Praktisch für einen Live-Konfigurator, bevor der Kunde überhaupt eine Datei hochlädt. Für den
// verbindlichen Preis (Checkout) immer SCHRITT 1 + 2 nutzen.Schritt 1
Datei hochladen
Erlaubt sind STEP, IGES, STL, GLB und OBJ bis 200 MB. Sie melden die Datei an und laden sie mit dem Einmal-Token direkt in unseren privaten Speicher. Die Datei läuft also nicht durch Ihren Server.
GLB und OBJ, wie sie KI-Generatoren ausgeben, haben keine verlässliche Maßeinheit. Für diese Formate ist im Angebot targetHeightMm Pflicht (die Datei meldet requiresTargetHeight: true). Wir drehen das Modell auf Z-oben, skalieren gleichmäßig und erzeugen beim Auftrag die fertige STL-Druckdatei in mm. Ein Modell mit offener Hülle (nicht wasserdicht) lehnen wir als invalid ab.
Die Datei geht direkt an die signierte URL (einfaches PUT, keine Bibliothek nötig). Wir messen die Geometrie auf unserer Seite, die Antwort enthält schon das Ergebnis. Maße und Volumen werden nie von Ihnen übernommen. Liegt die Datei schon öffentlich erreichbar vor, schicken Sie stattdessen fileUrl mit, dann holen wir sie selbst ab.
POST /api/v1/files
Authorization: Bearer <API-Schlüssel>
Content-Type: application/json
{ "fileName": "halterung.step" }
201 Created
{
"file": { "id": "6f1c…", "fileName": "halterung.step", "status": "pending" },
"upload": {
"url": "https://biltech3d.de/api/v1/uploads/6f1c…?expires=…&signature=…",
"method": "PUT",
"maxBytes": 209715200,
"expiresAt": "2026-10-06T12:30:00.000Z"
}
}// Die URL ist die Berechtigung: kein API-Key, auch aus dem Browser des Kunden nutzbar.
const res = await fetch(upload.url, { method: "PUT", body: datei })
const { file } = await res.json() // status "ready" oder "invalid" (inkl. Maße), die Prüfung läuft im selben Aufruf
// Die URL gilt einmal und 30 Minuten. Zweiter Versuch: 409, abgelaufen oder verändert: 403, über 200 MB: 413.
// Optional später: GET /api/v1/files/{id}Schritt 2
Preis verbindlich anfragen
Bündeln Sie bis zu 20 Dateien mit Stückzahl in einem Angebot. Wir rechnen mit derselben Formel wie unser eigener Shop. Das Angebot gilt 14 Tage. Diesen Preis zeigen Sie Ihrem Kunden im Checkout.
Ein Material ist für jede Position Pflicht — wir nehmen keinen Auftrag ohne Material an. Gültige Werte für productType und materialId liefert GET /api/v1/catalog. Wollen Sie nur prüfen, ob eine bereits gespeicherte materialId noch gültig ist, reicht GET /api/v1/catalog/materials/{id} — ohne den ganzen Katalog zu laden (404, wenn das Material nicht mehr existiert oder deaktiviert wurde).
materialId auf oberster Ebene ist der Standard für alle Positionen des Aufrufs. Jede Position in items kann mit ihrer eigenen materialId diesen Standard überschreiben — so bündeln Sie verschiedene Materialien in einem einzigen Angebot/Auftrag. Pflicht ist: jede Position braucht am Ende (eigene Angabe oder Standard) genau ein Material, sonst 422. GET /api/v1/quotes/{quoteId} und GET /api/v1/orders/{externalOrderId} geben das aufgelöste materialId je Position zurück.
Jedes Material im Katalog führt colors: eine frei von uns gepflegte Liste wählbarer Farben (Name + Hex) — welche und wie viele hängt vom Material ab. Pro Datei optional colorHex aus dieser Liste mitschicken — ohne Angabe gilt die natürliche Farbe des Materials (erster Eintrag). Hat ein Material nur eine Farbe, ist colors null (nichts zur Auswahl, z. B. Full-Color MJP oder zertifizierte Spezialharze).
POST /api/v1/quotes
{
"productType": "industrial-sla",
"materialId": "5f54fb9c-e26d-496f-a40c-3052425f7b2c",
"items": [
{ "fileId": "6f1c…", "quantity": 25 },
{ "fileId": "9a2e…", "quantity": 1, "targetHeightMm": 100, "colorHex": "#CC0605" },
{ "fileId": "7b3d…", "quantity": 4, "materialId": "a1c9…" }
]
}
// materialId auf oberster Ebene ist der Standard für alle Positionen (hier: die ersten beiden).
// Position 3 überschreibt ihn mit einer eigenen materialId — so mischen Sie Materialien in einem
// Angebot. Pflicht: jede Position braucht am Ende (eigene Angabe oder Standard) genau ein Material,
// sonst 422. Gültige IDs je productType liefert GET /api/v1/catalog.
// colorHex: optional, einer der Hex-Werte des jeweils aufgelösten Materials (catalog.materials[].colors).
// Ohne Angabe gilt dessen natürliche Farbe (erster Eintrag). Ungültige/fremde Hex-Werte → 422.
// targetHeightMm: Höhe (Z) in mm, X/Y skalieren gleichmäßig mit.
// Pflicht für GLB/OBJ, optional für STL/STEP/IGES.
201 Created
{
"quote": {
"id": "a83e…",
"test": false,
"productType": "industrial-sla",
"materialId": "5f54fb9c-e26d-496f-a40c-3052425f7b2c",
"leadTimeWorkdays": 5,
"expiresAt": "2026-10-20T10:00:00.000Z",
"items": [
{ "fileId": "6f1c…", "materialId": "5f54fb9c-e26d-496f-a40c-3052425f7b2c", "…": "…" },
{ "fileId": "9a2e…", "materialId": "5f54fb9c-e26d-496f-a40c-3052425f7b2c", "…": "…" },
{ "fileId": "7b3d…", "materialId": "a1c9…", "…": "…" }
],
"wholesale": { "positionsNetCents": 24990, "shippingCents": 990, "netCents": 25980, "vatCents": 4936, "grossCents": 30916 },
"retail": { "positionsNetCents": 24990, "shippingCents": 990 },
"currency": "EUR"
}
}
// Jedes Element in items trägt sein aufgelöstes materialId — egal ob von der Position selbst
// oder vom Standard übernommen. So sehen Sie immer, welches Material pro Position abgerechnet wurde.Schritt 3
Auftrag anlegen
Sobald Ihr Kunde bezahlt hat, legen Sie den Auftrag mit der quoteId an. Jede Datei wird eine eigene Position und geht in unsere Produktionsplanung. Berechnet wird genau der Angebotspreis.
Für einfache Anbindungen geht es auch in einem Aufruf: Statt quoteId schicken Sie productType, materialId (Standard für alle Positionen) und items mit fileUrl, fileName, quantity und optional einer eigenen materialId je Position. Das Angebot wird dabei im Hintergrund erstellt — genau wie bei POST /api/v1/quotes.
Stornieren können Sie mit POST …/cancel, solange keine Position in Produktion ist. Danach antworten wir mit 409.
Slot-Batch (nur für freigeschaltete interne Marken): Mit dem optionalen Feld slotRef (Ihre eigene Slot-ID) landen die Positionen in einem eigenen, exklusiven Druck-Batch. Alle Aufträge mit derselben slotRef kommen in denselben Batch, fremde Teile nie. productionDate (YYYY-MM-DD, nicht in der Vergangenheit, nur zusammen mit slotRef) ist der gewünschte Fertigungstag; die Uhrzeit legen wir intern fest. Ein Slot enthält ein Material und eine Farbe. Ob alle Dateien auf eine Bauplatte passen und wie viele Slots pro Tag und Drucker möglich sind, prüft der Aufrufer — wir nehmen den Auftrag an. Antworten: 403 ohne Freischaltung, 409 bei abweichendem Tag oder wenn der Slot schon im Druck ist, 422 bei abweichendem Material oder abweichender Farbe. Mit Test-Schlüsseln wird kein Batch angelegt.
POST /api/v1/orders
{
"quoteId": "a83e…",
"externalOrderId": "SHOP-48213",
"dueDate": "2026-10-20",
"customer": {
"firstName": "Max",
"lastName": "Mustermann",
"email": "kunde@example.com",
"street": "Musterweg 5",
"zip": "10115",
"city": "Berlin",
"country": "DE"
}
}
201 Created
{
"duplicate": false,
"quoteId": "a83e…",
"externalOrderId": "SHOP-48213",
"orderGroupNumber": 10428,
"test": false,
"wholesale": { "positionsNetCents": 24990, "shippingCents": 990, "netCents": 25980, "vatCents": 4936, "grossCents": 30916 },
"retail": { "positionsNetCents": 24990, "shippingCents": 990 },
"positions": [
{ "orderNumber": 10428, "externalOrderId": "SHOP-48213", "status": "validation", "fileName": "halterung.step", "quantity": 25, "unitPriceCents": 999, "colorName": "Reinweiß" }
]
}
// Es gibt keinen Top-Level "order" — die Antwort ist flach. Mehrteilige Angebote erzeugen
// mehrere Einträge in "positions", jeweils mit eigener orderNumber. Senden Sie denselben
// externalOrderId noch einmal, antworten wir mit 200 und "duplicate": true (ohne "positions"-
// Preisfelder neu zu berechnen).POST /api/v1/orders
{
"quoteId": "a83e…",
"externalOrderId": "SLOT-48213-1",
"slotRef": "SLOT-48213",
"productionDate": "2026-10-15",
"customer": { "…": "…" }
}
201 Created
{
"duplicate": false,
"externalOrderId": "SLOT-48213-1",
"slot": { "slotRef": "SLOT-48213", "productionDate": "2026-10-15" },
"…": "…"
}
// Weitere Aufträge mit "slotRef": "SLOT-48213" und demselben Tag kommen in denselben Batch.GET /api/v1/orders/SHOP-48213
200 OK
{
"externalOrderId": "SHOP-48213",
"test": false,
"cancellable": true,
"positions": [
{
"orderNumber": 10428,
"externalOrderId": "SHOP-48213",
"position": 1,
"status": "printing",
"statusLabel": "Liegt auf einer Bauplatte im Druck",
"fileName": "halterung.step",
"quantity": 25,
"printedQuantity": 25,
"dimensions": "40 x 22 x 15",
"dueDate": "2026-10-20",
"colorName": "Reinweiß",
"materialId": "5f54fb9c-e26d-496f-a40c-3052425f7b2c",
"unitPriceCents": 999,
"retailUnitPriceCents": 1299,
"updatedAt": "2026-10-09T09:12:00.000Z",
"shipments": []
}
]
}POST /api/v1/orders/SHOP-48213/cancel
{ "reason": "Kunde storniert" }
200 OK
{ "externalOrderId": "SHOP-48213", "cancelled": true, "alreadyCancelled": false }
409 Conflict (mindestens eine Position bereits in Produktion)
{
"error": "Storno nicht mehr möglich — mindestens eine Position ist bereits in Produktion.",
"positions": [{ "externalOrderId": "SHOP-48213", "status": "printing" }]
}Schritt 4
Status per Webhook
Wir rufen Ihre Webhook-URL bei jedem Statuswechsel auf. Darauf versenden Sie Ihre eigenen Kunden-Mails, etwa „Ihr Teil wird gedruckt“ oder die Versandbestätigung mit Tracking. Antwortet Ihr Server nicht mit 2xx, versuchen wir es mit wachsendem Abstand erneut.
Prüfen Sie jede Zustellung mit Ihrem Signatur-Secret. Den Header X-BilTech-Delivery können Sie zum Entdoppeln verwenden.
order.status_changedEine Position wechselt den Status (fromStatus, toStatus).order.shippedPaket ist unterwegs (carrier, z. B. DHL oder Hermes, und trackingNumber). Je Position ein Webhook; Positionen im selben Paket teilen sich die trackingNumber — Versandmail einmal je trackingNumber senden.order.cancelledPosition storniert.order.rejectedPosition abgelehnt — mit strukturiertem reason-Code (siehe Beispiel) und reasonDetail als Freitext, Ihr Shop sollte erstatten.catalog.updatedMaterial hinzugefügt/geändert — Katalog-Cache gezielt invalidieren statt pollen.pingTest-Zustellung aus dem Admin-Bereich.
POST https://ihr-shop.de/webhooks/biltech
X-BilTech-Event: order.shipped
X-BilTech-Delivery: 2b9d…
X-BilTech-Signature: t=1791288000,v1=5c0e…
{
"test": false,
"orderNumber": 10428,
"externalOrderId": "SHOP-48213",
"position": 1,
"status": "shipped",
"carrier": "DHL",
"trackingNumber": "00340434…",
"occurredAt": "2026-10-09T14:02:11Z"
}
// Bestellung mit mehreren Positionen: Wird mehr als eine Position im selben Paket versendet,
// erhalten Sie je Position einen eigenen order.shipped-Webhook (position 1, 2, 3 …), alle mit
// derselben trackingNumber. Verschicken Sie Ihre Versandmail deshalb einmal je Sendung:
// fassen Sie die Webhooks nach (externalOrderId, trackingNumber) zusammen und nennen Sie in der
// Mail alle enthaltenen Positionen, statt bei jedem Webhook eine Mail zu senden.
// Positionen, die später fertig werden, kommen in einer eigenen Sendung mit eigener trackingNumber
// (Teillieferung).POST https://ihr-shop.de/webhooks/biltech
X-BilTech-Event: order.rejected
X-BilTech-Delivery: 7a1f…
X-BilTech-Signature: t=1791288000,v1=9c2a…
{
"test": false,
"orderNumber": 10431,
"externalOrderId": "SHOP-48219",
"position": 1,
"status": "rejected",
"reason": "not_watertight",
"reasonDetail": "Wandstärke unter 0,8 mm, Datei nicht druckbar",
"occurredAt": "2026-10-09T14:02:11Z"
}
// reason ist einer von: not_watertight, wall_too_thin, too_large, too_small, file_invalid, other.
// Damit können Sie automatisiert entscheiden (z. B. immer erstatten bei not_watertight/too_large,
// bei file_invalid den Kunden um eine neue Datei bitten) statt reasonDetail zu parsen.POST https://ihr-shop.de/webhooks/biltech
X-BilTech-Event: catalog.updated
X-BilTech-Delivery: 4e7b…
X-BilTech-Signature: t=1791288000,v1=1d4f…
{
"test": false,
"reason": "material_updated",
"occurredAt": "2026-10-09T14:02:11Z"
}
// Ihr Katalog hat sich geändert (Material hinzugefügt/bearbeitet, z. B. neue Farben oder ein
// Material wurde deaktiviert). Statt GET /api/v1/catalog zyklisch abzufragen, können Sie Ihren
// Cache gezielt auf dieses Event hin invalidieren.
// reason ist einer von: material_created, material_updated, availability_changed (ein Material ist
// vorübergehend nicht oder nur eingeschränkt bestellbar), service_status_changed (Hinweis, Express
// oder Zusatz-Lieferzeit haben sich geändert — GET /api/v1/status).
//
// Materialien im Katalog tragen availability (available | limited | unavailable), orderable und
// optional availabilityNote/availableAgainOn. Ein nicht bestellbares Material lehnt Angebote und
// Bestellungen mit 409 ab. Blenden Sie Express aus, wenn service.expressEnabled false ist; die
// leadTimeWorkdays enthalten service.extraLeadDays bereits.import { createHmac, timingSafeEqual } from "node:crypto"
const [t, v1] = header.split(",").map((p) => p.split("=")[1])
const expected = createHmac("sha256", WEBHOOK_SECRET)
.update(`${t}.${rawBody}`)
.digest("hex")
const ok =
Math.abs(Date.now() / 1000 - Number(t)) < 300 &&
timingSafeEqual(Buffer.from(v1), Buffer.from(expected))Statuswerte je Position
validationDatei und Angaben werden geprüft.queuedWartet auf den nächsten Batch.printingLiegt auf einer Bauplatte im Druck.post_processingWaschen, Aushärten, Qualitätskontrolle.shippingLabel erstellt, Paket wird gepackt.shippedVersendet, Tracking-Nummer liegt vor.rejectedAbgelehnt, z. B. nicht druckbare Geometrie.cancelledStorniert.
Sie brauchen Live- und Testschlüssel für Ihren Shop? Wir richten Ihre Brand mit Aufschlag und Webhook ein.
Zugang anfragen


