# 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.

Quelle: https://swiss3d.ch/help/api · Aktualisiert: 2026-11-06

## Ü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.

_Diagramm: Aufrufe aus Ihrem System und Benachrichtigungen per Webhook_

![API-Schlüssel der Firma](https://swiss3d.ch/help/img/api-schluessel.webp)
_API-Bereich mit Basis-URL und Schlüsseln_

## API-Schlüssel erstellen

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

![API-Schlüssel erstellen](https://swiss3d.ch/help/img/api-neu.webp)
_Name, Konto, Gültigkeit, Berechtigungen und IP-Beschränkung_

- **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.

![Neuer Schlüssel wird einmal angezeigt](https://swiss3d.ch/help/img/api-secret.webp)
_Der Schlüssel erscheint nur einmal_

> **Wichtig:** Der Schlüssel wird nur ein einziges Mal angezeigt; Swiss3D kann ihn nicht wiederherstellen. Legen Sie ihn sicher ab. Ist er verloren oder möglicherweise kompromittiert, widerrufen Sie ihn in der Liste und erstellen einen neuen.

### Berechtigungen

| Bereich | Umfang |
| --- | --- |
| Konto und Adressen | Konto, Firma, Rolle und Adressen (lesen) |
| Dateien | Modelle, Zeichnungen und Anhänge hoch- und herunterladen |
| Sofortpreise und Offerten | Sofortpreise anlegen, Offerten und Anfragen |
| Bestellungen | Bestellen, Status, Sendungen, Belege, Nachbestellung, Storno-Anfrage |
| Rechnungen | Rechnungen, Kontoauszug, Belege als PDF (lesen) |
| Teile und Projekte | Teile-Bibliothek, Revisionen, Projekte |
| Nachrichten | Nachrichten zu Bestellungen, Offerten, Teilen und Anfragen |
| Freigaben | Bestellfreigaben lesen und erteilen (Administratoren) |
| Webhooks | Webhooks über die API verwalten |

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**.

![API-Dokumentation im Portal](https://swiss3d.ch/help/img/api-doku.webp)
_Leitfaden und API-Referenz im Portal_

## 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.

![Webhook einrichten](https://swiss3d.ch/help/img/api-webhook-neu.webp)
_Webhook-Endpunkt mit Ereignissen_

| Gruppe | Ereignisse |
| --- | --- |
| Bestellungen | order.created , order.status_changed , order.ready_for_pickup , order.shipped , order.delivered , order.cancelled |
| Rechnungen | invoice.created , invoice.paid |
| Kommunikation | message.created , problem.resolved |
| Freigaben | approval.requested , approval.approved , approval.rejected , approval.cancelled |
| Teile | part.released |

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

![API-Protokoll](https://swiss3d.ch/help/img/api-protokoll.webp)
_Alle Aufrufe der letzten 30 Tage_

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

## Grenzen und Fehler

| Regel | Wert |
| --- | --- |
| Aufrufe pro Minute und Schlüssel | 600; für Preise, Uploads und Bestellungen 60 |
| Listen | page und limit (25, 50 oder 100) |
| Beträge | CHF. Positionen exkl. MWST, Totale inkl. Versand und MWST |
| Download-Links | 5 Minuten gültig |

| Status | Bedeutung |
| --- | --- |
| 400 | Eingabe ungültig, das Feld steht in field |
| 401 | Schlüssel fehlt, ungültig, abgelaufen oder widerrufen |
| 402 | Kauf auf Rechnung nicht möglich |
| 403 | Berechtigung oder Rolle reicht nicht |
| 404 | Nicht gefunden |
| 409 | Konflikt, etwa geänderter Preis oder Freigabe nötig |
| 429 | Zu viele Aufrufe; Retry-After nennt die Wartezeit |

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

## Häufige Fragen

### Wer kann die Swiss3D API nutzen?

Firmenkunden mit einem Firmenkonto. Die Schlüssel verwalten Sie im Portal unter Organisation › API.

### Wie verhindere ich doppelte Bestellungen über die API?

Mit einem Idempotency-Key, etwa Ihrer PO-Nummer. Sendet Ihr System denselben Aufruf erneut, liefert die API innert 24 Stunden dieselbe Bestellung zurück.

### Wie prüfe ich, ob ein Webhook wirklich von Swiss3D kommt?

Über den Header Swiss3D-Signature: Er enthält eine HMAC-SHA256-Signatur über Zeitstempel und Inhalt, die Sie mit Ihrem Signatur-Geheimnis nachrechnen.