Einbau-Anleitung · Next.js-Shop

In sechs Schritten vom Shop in die Fertigung.

Diese Anleitung baut die Schnittstelle in die eigene Website ein, am Beispiel sla-bulk.de. Jede Datei ist vollständig und lässt sich direkt kopieren. Die Referenz aller Felder steht in der API-Dokumentation.

Schritt 1

Zugang anlegen

In der Leitstelle unter Stammdaten die Marke wählen, z. B. SLA-BULK.de. Dort erst einen Testschlüssel erzeugen, dann die Webhook-URL des Shops eintragen und speichern. Dabei entsteht das Signatur-Secret.

Schlüssel und Secret erscheinen genau einmal, schon als fertige Zeile für die .env. Gespeichert wird nur ein Hash. Geht ein Schlüssel verloren, erzeugen Sie einfach einen neuen.

.env.local
# .env.local im Shop (z. B. sla-bulk.de)
BILTECH_API_URL=https://biltech3d.de
BILTECH_API_KEY=bt_test_…          # erst Test, zum Livegang bt_live_…
BILTECH_WEBHOOK_SECRET=whsec_…

Schritt 2

Client-Datei im Shop

Eine Datei kapselt alle Aufrufe. Sie läuft nur auf dem Server (server-only), der Schlüssel landet also nie im Browser.

Fehler kommen als BiltechError mit HTTP-Status und deutscher Meldung zurück. Die Meldung können Sie Ihrem Kunden direkt anzeigen. Shop-Bestellnummern dürfen Buchstaben, Ziffern, . _ - enthalten.

Einmalig biltech.catalog() aufrufen, um die materialId (und optional colors für eine Farbauswahl) für Ihre Produkte zu hinterlegen — beides ist in Schritt 4 Pflicht beziehungsweise optional.

lib/biltech.ts
import "server-only"

const BASE = `${process.env.BILTECH_API_URL}/api/v1`

export class BiltechError extends Error {
  constructor(public status: number, message: string, public details?: unknown) {
    super(message)
  }
}

async function api<T>(path: string, body?: unknown): Promise<T> {
  const res = await fetch(BASE + path, {
    method: body === undefined ? "GET" : "POST",
    headers: {
      Authorization: `Bearer ${process.env.BILTECH_API_KEY}`,
      ...(body === undefined ? {} : { "Content-Type": "application/json" }),
    },
    body: body === undefined ? undefined : JSON.stringify(body),
    cache: "no-store",
  })
  const data = await res.json().catch(() => ({}))
  if (!res.ok) throw new BiltechError(res.status, data.error ?? `HTTP ${res.status}`, data.details)
  return data as T
}

export type ProductType = "industrial-sla" | "full-color-mjp"
export type FileStatus = "pending" | "ready" | "invalid"

export type BiltechFile = { id: string; fileName: string; status: FileStatus; error: string | null }
export type Upload = { url: string; method: "PUT"; maxBytes: number; expiresAt: string }

export type MaterialColor = { name: string; hex: string }
export type Material = { id: string; name: string; color: string | null; colors: MaterialColor[] | null }
export type Catalog = {
  test: boolean
  markupPct: number
  productTypes: { id: ProductType; name: string; leadTimeWorkdays: number; materials: Material[] }[]
}

export type Quote = {
  id: string
  test: boolean
  expiresAt: string
  leadTimeWorkdays: number
  retail: { positionsNetCents: number; shippingCents: number }
}

export type Customer = {
  firstName: string
  lastName: string
  email: string
  company?: string
  street: string
  zip: string
  city: string
  country: string // ISO, z. B. "DE"
}

export const biltech = {
  catalog: () => api<Catalog>("/catalog"),

  registerFile: (fileName: string) =>
    api<{ file: BiltechFile; upload: Upload }>("/files", { fileName }),

  getFile: (fileId: string) => api<{ file: BiltechFile }>(`/files/${fileId}`),

  // targetHeightMm: Pflicht für GLB/OBJ (z. B. 100 = 10 cm hoch), X/Y skalieren mit
  // colorHex: optional, muss zu einer Farbe aus catalog.materials[].colors passen (sonst 422)
  quote: (
    productType: ProductType,
    materialId: string,
    items: { fileId: string; quantity: number; targetHeightMm?: number; colorHex?: string }[],
  ) => api<{ quote: Quote }>("/quotes", { productType, materialId, items }),

  placeOrder: (input: {
    quoteId: string
    externalOrderId: string
    customer: Customer
    dueDate?: string
    note?: string
  }) => api<{ duplicate: boolean }>("/orders", input),

  getOrder: (externalOrderId: string) =>
    api<{
      cancellable: boolean
      positions: {
        status: string
        statusLabel: string
        shipments: { carrier: string; trackingNumber: string }[]
      }[]
    }>(
      `/orders/${externalOrderId}`,
    ),

  cancelOrder: (externalOrderId: string) =>
    api<{ cancelled: boolean }>(`/orders/${externalOrderId}/cancel`, {}),
}

Schritt 3

Upload direkt aus dem Browser

Ihr Server meldet die Datei an und reicht nur die signierte Upload-URL an den Browser weiter. Der Browser schickt die Datei (STEP, IGES, STL, GLB oder OBJ bis 200 MB) per PUT direkt an BilTech3D. Die URL gilt 30 Minuten und einmal, Ihr API-Key bleibt auf Ihrem Server. Große Dateien laufen also nie durch Ihren Server.

KI-Modelle (GLB/OBJ) direkt weitergeben: Liefert der Generator die Datei serverseitig, laden Sie sie mit demselben PUT aus Ihrem Server hoch. Lassen Sie den Kunden die Höhe wählen (z. B. 100 mm) und übergeben Sie sie als targetHeightMm an priceCart. Die anderen Maße skalieren gleichmäßig mit, im Angebot stehen die fertigen Maße.

BilTech3D misst die Geometrie im selben Aufruf. Die Antwort enthält schon ready oder invalid, ein Polling oder ein zusätzliches Paket ist nicht nötig.

app/api/biltech/datei/route.ts
import { biltech, BiltechError } from "@/lib/biltech"

export async function POST(request: Request) {
  const { fileName } = await request.json()
  try {
    return Response.json(await biltech.registerFile(String(fileName)))
  } catch (error) {
    if (error instanceof BiltechError) {
      return Response.json({ error: error.message }, { status: error.status })
    }
    throw error
  }
}
app/api/biltech/datei/[id]/route.ts
import { biltech } from "@/lib/biltech"

export async function GET(_: Request, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  return Response.json(await biltech.getFile(id))
}
lib/upload-cad.ts (Browser)
"use client"

export async function uploadCad(file: File) {
  const res = await fetch("/api/biltech/datei", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ fileName: file.name }),
  })
  const data = await res.json()
  if (!res.ok) throw new Error(data.error)

  // Die signierte URL ist die Berechtigung: Die Datei geht direkt an BilTech3D, nicht durch Ihren Server.
  const upload = await fetch(data.upload.url, { method: "PUT", body: file })
  const result = await upload.json()
  if (!upload.ok) throw new Error(result.error ?? "Upload fehlgeschlagen")

  // Die Prüfung läuft im selben Aufruf, die Antwort enthält schon das Ergebnis.
  if (result.file.status === "invalid") throw new Error(result.file.error ?? "Datei nicht druckbar")
  return result.file
}

Schritt 4

Preis zeigen, nach Zahlung fertigen

priceCart holt das verbindliche Angebot. materialId ist Pflicht (gültige IDs je productType liefert GET /catalog) — ohne Material nehmen wir keinen Auftrag an. Zeigen Sie Teile- und Versandpreis getrennt oder zusammen (retail.positionsNetCents + retail.shippingCents) als Endkundenpreis — shippingCents trägt keinen Aufschlag, Sie geben ihn 1:1 weiter. quoteId mit dem Warenkorb speichern. Das Angebot gilt 14 Tage.

Erst wenn die Zahlung bestätigt ist, rufen Sie sendToProduction auf. Der Aufruf ist sicher wiederholbar: Dieselbe Bestellnummer legt nie einen zweiten Auftrag an. Kommt der Zahlungs-Webhook also doppelt, ist das kein Problem.

app/actions/biltech.ts
"use server"

import { biltech } from "@/lib/biltech"

export async function priceCart(
  materialId: string,
  items: { fileId: string; quantity: number; targetHeightMm?: number; colorHex?: string }[],
) {
  const { quote } = await biltech.quote("industrial-sla", materialId, items)
  // quote.id mit dem Warenkorb speichern, Preis kommt nie aus dem Browser
  return {
    quoteId: quote.id,
    positionsNetCents: quote.retail.positionsNetCents,
    shippingNetCents: quote.retail.shippingCents,
    netCents: quote.retail.positionsNetCents + quote.retail.shippingCents,
    expiresAt: quote.expiresAt,
    leadTimeWorkdays: quote.leadTimeWorkdays,
  }
}

// Aufrufen, sobald die Zahlung bestätigt ist (z. B. im Zahlungs-Webhook)
export async function sendToProduction(order: {
  number: string
  quoteId: string
  customer: Parameters<typeof biltech.placeOrder>[0]["customer"]
}) {
  await biltech.placeOrder({
    quoteId: order.quoteId,
    externalOrderId: order.number,
    customer: order.customer,
  })
}

Schritt 5

Status empfangen und Kunden informieren

Jede Statusänderung kommt signiert an diese Route. Die Kunden-Mails verschickt Ihr Shop unter seiner eigenen Marke. BilTech3D schreibt Ihren Kunden selbst nie.

  • order.status_changed → printingMail: „Ihr Teil wird gerade gedruckt.“
  • order.shippedVersandmail mit carrier + trackingNumber.
  • order.rejectedKunden informieren und Zahlung erstatten.
  • order.cancelledBestellung im Shop als storniert markieren.
  • pingNichts tun, nur 200 antworten.

Lokal ohne öffentliche Adresse? Dann erreicht Sie kein Webhook. Fragen Sie in dem Fall biltech.getOrder(nummer) ab, etwa beim Öffnen der Bestellansicht. Das liefert denselben Stand.

app/api/biltech/webhook/route.ts
import { createHmac, timingSafeEqual } from "node:crypto"

function isValidSignature(rawBody: string, header: string) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)))
  const timestamp = Number(parts.t)
  if (!parts.v1 || !Number.isFinite(timestamp)) return false
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false

  const expected = createHmac("sha256", process.env.BILTECH_WEBHOOK_SECRET!)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex")
  return parts.v1.length === expected.length && timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
}

export async function POST(request: Request) {
  const rawBody = await request.text()
  if (!isValidSignature(rawBody, request.headers.get("x-biltech-signature") ?? "")) {
    return new Response("invalid signature", { status: 401 })
  }

  const deliveryId = request.headers.get("x-biltech-delivery")
  const event = request.headers.get("x-biltech-event")
  const payload = JSON.parse(rawBody)

  // 1. deliveryId schon verarbeitet? Dann sofort 200 zurückgeben.
  // 2. Bestellung payload.externalOrderId, Position payload.position aktualisieren.
  // 3. Eigene Kunden-Mail unter der Shop-Marke senden (siehe Tabelle).
  console.log(event, deliveryId, payload.externalOrderId, payload.status)

  return new Response("ok")
}

Schritt 6

Livegang

  1. 1Testauftrag mit bt_test_… angelegt, im Shop als Bestellung sichtbar.
  2. 2Test-Webhook aus den Stammdaten kommt an und besteht die Signaturprüfung.
  3. 3Doppelter Aufruf von placeOrder legt keinen zweiten Auftrag an (duplicate: true).
  4. 4BILTECH_API_KEY auf bt_live_… getauscht und neu deployt.
  5. 5Webhook-URL in den Stammdaten zeigt auf die Live-Domain des Shops.

Testaufträge erscheinen nie auf dem Produktionsboard und werden nie berechnet. Live-Aufträge laufen wie jeder andere Auftrag in die Planung und werden über die monatliche Sammelrechnung abgerechnet.