API und Webhooks

Mit der Swiss3D API verbinden Sie Ihr ERP- oder Einkaufssystem mit dem Kundenportal: Preise abfragen, bestellen, Status, Sendungen und Rechnungen holen und per Webhook über Ereignisse informiert werden.

Aktualisiert am 6. November 2026 · Swiss3D-Team

Überblick#

Die API bietet dieselben Funktionen wie das Portal; was über die API entsteht, sehen Sie im Portal und umgekehrt. Sie steht Firmenkunden mit Firmenkonto zur Verfügung, unter Organisation›API.

API-Schlüssel erstellen#

Mit Schlüssel erstellen legen Sie fest, wofür der Schlüssel gilt und was er darf.

• Konto: Firma (Standard) oder persönlich, dann nur für Ihre eigenen Bestellungen.
• Gültigkeit: unbegrenzt oder 30, 90, 180 oder 365 Tage.
• IP-Beschränkung (optional): bis 20 Adressen oder Netze (CIDR).
• Bis 25 aktive Schlüssel pro Konto. Zu jedem neuen Schlüssel erhalten Sie eine E-Mail.

Berechtigungen#

Ein Schlüssel kann nie mehr als die Rolle seiner Inhaberin oder seines Inhabers: Besteller vergeben keine Freigaben, Betrachter nur Lesen und Nachrichten. Die Rechte werden bei jedem Aufruf mit der aktuellen Rolle abgeglichen.

Erster Aufruf#

Der Schlüssel gehört in den Header Authorization. Die gültige Basis-URL steht im Portal oben im Bereich API.

# SWISS3D_API = Basis-URL aus dem Portal (Organisation › API)
# Eine Bestellung mit Positionen, Sendungen und Belegen
curl "$SWISS3D_API/orders/1211090" \
  -H "Authorization: Bearer s3_live_…"

{
  "object": "order",
  "number": "1211090",
  "status": "delivered",
  "references": { "po_number": "PO-2026-0418", "cost_center": null },
  "sub_orders": [ { "number": "1211090-1", "status": "delivered" }, … ],
  "items": [ { "name": "Halterung_Sensor.stl", "process": "SLS", "quantity": 10, "unit_price": 76.34 }, … ],
  "totals": { "subtotal": 2065.18, "shipping": 7, "tax": 167.85, "total": 2240.02 }
}

Alle Endpunkte mit Beispielen in curl, Node.js und Python stehen im Reiter Dokumentation.

Bestellen über die API#

Der Ablauf: Datei hochladen (POST /v1/files, bis 20 MB direkt, sonst bis 1 GB über eine Upload-URL), Sofortpreis anlegen, dann POST /v1/orders.

• Bestellt wird auf Rechnung, mit Lieferung in die Schweiz oder nach Liechtenstein.
• Idempotency-Key ist bei Bestellungen Pflicht, etwa Ihre PO-Nummer. Ein wiederholter Aufruf liefert dieselbe Bestellung, nie eine zweite (24 Stunden lang).
• "dry_run": true prüft Preis, Lieferung und Pflichtangaben, ohne zu bestellen.
• expected_subtotal sichert den Preis, den Ihr System bestätigt hat; bei Abweichung kommt 409 price_changed.
• Über der Freigabeschwelle kommt 409 approval_required; mit "request_approval": true entsteht stattdessen eine Freigabeanfrage.

Webhooks#

Webhooks melden Ereignisse sofort an Ihr System. Unter Webhooks › Endpunkt hinzufügen geben Sie eine https://-Adresse an, die aus dem Internet erreichbar ist, und wählen die Ereignisse.

Jede Zustellung trägt den Header Swiss3D-Signature mit Zeitstempel und HMAC-SHA256-Signatur über Zeitstempel und Inhalt. Prüfen Sie die Signatur mit dem Signatur-Geheimnis, verwerfen Sie Zustellungen älter als 5 Minuten und antworten Sie innert 10 Sekunden mit 2xx.

Swiss3D-Signature: t=1793967180,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
# gültig, wenn HMAC-SHA256(geheimnis, "<t>.<Rumpf>") = v1

Fehlgeschlagene Zustellungen wiederholt Swiss3D bis zu acht Mal über etwa zwei Tage. Ein Ereignis kann deshalb mehrfach ankommen; verarbeiten Sie jede Ereignis-ID nur einmal. Test senden prüft Ihren Endpunkt jederzeit.

Protokoll#

Filtern Sie nach Schlüssel oder nach Fehler. Eine Zeile zeigt Request-ID, IP-Adresse und Fehlercode.

Grenzen und Fehler#

Fehler enthalten immer eine request_id. Geben Sie sie an, wenn Sie Swiss3D zu einem Fehler kontaktieren.

Häufige Fragen#