Für Entwickler — Formavis LABS

Zugang

Zugänge stellen wir persönlich aus — schreiben Sie uns, wofür Sie die Schnittstelle nutzen möchten. Sie erhalten zwei Schlüssel: einen für den Übungsbetrieb und einen für den Echtbetrieb.

Der Schlüssel geht als Authorization: Bearer … mit. Wir speichern ihn nur als Prüfsumme — geht er verloren, stellen wir einen neuen aus, nachsehen können wir ihn nicht.

Übungsbetrieb

Erst ausprobieren, dann bestellen

Die Sandbox ist dieselbe Anwendung mit denselben Prüfungen — nur ohne Folgen: Es wird nichts gefertigt, nichts berechnet und nichts verschickt.

Der Fertigungsverlauf ist gerafft. Eine Bestellung durchläuft alle Stufen im Minutentakt statt in Tagen — Sie sehen den ganzen Ablauf in einer Viertelstunde.
Webhooks kommen echt. Dieselben Ereignisse, dieselben Signaturen wie später im Echtbetrieb.
Preise bleiben Schätzungen. Im Übungsbetrieb läuft kein Slicer; der Ablauf ist derselbe, nur der Betrag ist nicht verbindlich.

Schnellstart

Vier Aufrufe bis zur Bestellung

# 1. Werkstoffe ansehen
curl -H "Authorization: Bearer $KEY" \
  https://sandbox.labs.formavis.de/api/ext/v1/materials

# 2. Modell hochladen
curl -X POST https://sandbox.labs.formavis.de/api/ext/v1/uploads \
  -H "Authorization: Bearer $KEY" \
  -F "file=@teil.stl"

# 3. Preis berechnen
curl -X POST https://sandbox.labs.formavis.de/api/ext/v1/quotes \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"upload_token":"…","article_code":"FIL-10094","quantity":20}'

# 4. Bestellen — Idempotency-Key ist Pflicht
curl -X POST https://sandbox.labs.formavis.de/api/ext/v1/orders \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: PO-2026-4711" \
  -H "Content-Type: application/json" \
  -d '{"quote_tokens":["…"],"email":"einkauf@example.org",
       "name":"Einkauf","customer_reference":"PO-2026-4711"}'

Der Idempotency-Key ist Pflicht. Wiederholt Ihr System nach einer Zeitüberschreitung, bekommen Sie mit demselben Schlüssel die erste Antwort zurück statt einer zweiten Bestellung. Am einfachsten nehmen Sie Ihre eigene Bestellnummer.

Endpunkte

Was die Schnittstelle kann

Endpunkte der Partner-API
Methode	Pfad	Zweck	Berechtigung
`GET`	`/materials`	Werkstoffe und Filamente	`catalog:read`
`GET`	`/options`	Zulässige Werte und Grenzen	`catalog:read`
`POST`	`/uploads`	Modelldatei hochladen	`files:write`
`GET`	`/uploads/{token}`	Upload prüfen	`files:write`
`POST`	`/quotes`	Preis berechnen	`quotes:write`
`GET`	`/quotes/{token}`	Angebot abrufen	`quotes:read`
`POST`	`/orders`	Bestellung aufgeben	`orders:write`
`GET`	`/orders/{nummer}`	Bestellung abrufen	`orders:read`
`GET`	`/orders/{nummer}/status`	Fertigungsstatus	`production:read`
`GET`	`/webhooks`	Eingetragene Ziele	`webhooks:manage`
`POST`	`/webhooks`	Ziel eintragen	`webhooks:manage`
`DELETE`	`/webhooks/{id}`	Ziel entfernen	`webhooks:manage`

Die vollständige Beschreibung als OpenAPI-Spezifikation liegt unter https://labs.formavis.de/api/ext/v1/openapi.json — ohne Schlüssel abrufbar, damit Sie vor dem Zugang sehen, was Sie erwartet.

Wir bremsen bei 120 Aufrufen pro Minute je Schlüssel. Läuft ein Stapel dagegen, kommt 429 mit Retry-After. Wer regelmäßig mehr braucht, bekommt mehr — sagen Sie uns Bescheid, statt es zu umgehen.

Webhooks

Statt zu fragen, benachrichtigt werden

order.confirmedAuftrag ist in der Fertigung angelegt.
order.status_changedDer Fertigungsstatus hat sich geändert.
order.shippedDie Sendung ist unterwegs.
order.on_holdDer Auftrag ist angehalten, es gibt eine Rückfrage.

Jede Zustellung trägt X-Formavis-Signature mit Zeitstempel und Prüfsumme. Prüfen Sie beides — ohne den Zeitstempel ließe sich eine abgefangene Zustellung später erneut einspielen. Zustellungen, die älter als fünf Minuten sind, sollten Sie ablehnen.

Rechnen Sie mit Wiederholungen: Bei einem Fehlschlag versuchen wir es sechsmal mit wachsendem Abstand. Die Kennung in X-Formavis-Delivery bleibt dabei gleich — dieselbe zweimal zu sehen ist normal.

import hmac, hashlib

def signatur_gueltig(secret: str, header: str, rumpf: str) -> bool:
    """header: 't=1754500000,v1=abc…' aus X-Formavis-Signature"""
    teile = dict(p.split("=", 1) for p in header.split(","))
    erwartet = hmac.new(
        secret.encode(), f"{teile['t']}.{rumpf}".encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(teile["v1"], erwartet)

Fertigungsstatus

Sechs Stufen, mehr nicht

Ihr System erfährt, woran ein Auftrag ist — nicht, wie unsere Produktion arbeitet. Interne Zustände, Maschinen und Auslastung bleiben drin.

01in Prüfung
02für Produktion vorbereitet
03in Fertigung
04Qualitätsprüfung
05versandbereit
06versendet

Fehler

Codes statt Prosa

Jeder Fehler trägt einen stabilen code. Programmieren Sie dagegen, nicht gegen den Text — der kann sich ändern, der Code nicht.

UNAUTHORIZED401: Kein Schlüssel im Aufruf. Kopfzeile Authorization: Bearer <Schlüssel> setzen.
INVALID_KEY401: Schlüssel unbekannt, widerrufen oder abgelaufen. Neuen Schlüssel anfordern. Die drei Fälle sind absichtlich nicht unterscheidbar.
INSUFFICIENT_SCOPE403: Der Zugang hat diese Berechtigung nicht. Erweiterung des Zugangs anfragen.
ACCOUNT_REQUIRED403: Dem Zugang ist kein Kundenkonto zugeordnet. Für Katalog und Preise reicht der Zugang; zum Bestellen brauchen wir das Konto.
IDEMPOTENCY_KEY_REQUIRED400: Schreibender Aufruf ohne Idempotency-Key. Eine im eigenen System eindeutige Kennung mitsenden, etwa die Bestellnummer.
IDEMPOTENCY_MISMATCH409: Derselbe Schlüssel wurde schon mit anderem Inhalt verwendet. Für eine neue Bestellung einen neuen Schlüssel verwenden.
QUOTE_NOT_FOUND404: Angebot unbekannt oder abgelaufen. Preis neu berechnen.
QUOTE_ALREADY_ORDERED409: Zu diesem Angebot besteht bereits eine Bestellung. Bestehende Bestellung abrufen statt neu bestellen.
ORDER_NOT_FOUND404: Bestellung unbekannt — oder sie gehört einem anderen Konto. Bestellnummer prüfen. Fremde Bestellungen antworten bewusst wie unbekannte.
ORDER_REJECTED409: Die Bestellung ist fachlich nicht möglich. Meldung lesen — meist Lieferart und Gewicht oder ein fehlender Preis.
INVALID_WEBHOOK400: Ziel-URL nicht erlaubt. https verwenden, keine internen Netze.
UPLOAD_REJECTED400: Datei nicht brauchbar — falscher Typ, leer oder nicht messbar. STL, 3MF oder OBJ senden. Bei 413: Die Datei ist zu groß.
UPLOAD_NOT_FOUND404: Upload unbekannt oder nach der Aufbewahrungsfrist gelöscht. Datei erneut hochladen.
RATE_LIMITED429: Zu viele Aufrufe in einer Minute. Die Sekunden aus Retry-After abwarten. Für Stapelbetrieb sprechen Sie uns an.

Zugang anfragen

Schreiben Sie uns, wofür Sie die Schnittstelle nutzen möchten — wir stellen Schlüssel für Übungs- und Echtbetrieb aus.

Zugang anfragen Kleinserien ansehen