Zum Hauptinhalt springen
Auf dieser Seite▾

Ein individueller Shop oder ERP ist einer, für den es kein fertiges Plug-in gibt, sodass Ihr Entwickler den Konfigurator mit dem Warenkorb verbindet. Die Regel hinter allem hier ist ein Satz: Ein Preis, den der Browser gesendet hat, darf nie zum Warenkorbpreis werden. Ihr Server prüft ihn zuerst bei CutOptim.

CutOptim nimmt keine Zahlungen entgegen und hostet keinen Shop; Warenkorb, Kasse und Zahlung bleiben bei Ihnen. Es gibt noch kein SDK. Die Konfigurator-API-Referenz listet jede Route, jeden Fehlercode und jede Grenze auf, mit einem OpenAPI-3.1-Dokument; diese Seite, die Seite zu Bestellungen und der Referenzcode führen Schritt für Schritt durch die Integration.

Zwei Schlüssel

  • Der öffentliche Schlüssel (publishable key) steht in Ihrer Seite für die Einbettung. Er kann nur tun, was ein Käufer tut, und nur von den Domains, die Sie für ihn aufgelistet haben.
  • Der geheime Schlüssel (secret key) ist für Ihren Server und kommt nie in eine Seite. Er wird als Authorization: Bearer <key> an den Dienst gesendet, standardmäßig https://cfg.cutoptim.com. Senden Sie bei einem POST immer Content-Type: application/json.

Schritt 1: das Angebot vor dem Warenkorb prüfen

Bestellt der Kunde, erhält Ihre Seite ein cutoptim:order-Ereignis mit einem Angebots-Token. Senden Sie das Token an Ihren Server und von dort:

curl -X POST https://cfg.cutoptim.com/cfg/v1/quote/verify \
  -H "Authorization: Bearer $CFG_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"quoteToken":"<token from the page>"}'

Die Antwort ist 200 mit {"valid": true, "redeemed": false, "claims": {...}} oder {"valid": false, "reason": "..."}. Auch eine Ablehnung ist ein 200, lesen Sie also valid. Behandeln Sie einen Timeout, ein 401, ein 500 oder einen unlesbaren Body als nicht geprüft und lehnen Sie die Position ab. Vergleichen Sie dann die Claims mit Ihrer Warenkorbposition: Der Tenant ist Ihrer, die Währung ist die des Warenkorbs, der Ablauf liegt in der Zukunft, und der Angebots-Hash entspricht dem Hash des Angebots, das Ihre Seite angezeigt hat. Der Referenzcode enthält die Funktion, die diesen Hash berechnet.

Eine lokale Prüfung von Form, Tenant und Ablauf des Tokens ist günstiger, kann aber die Signatur nicht beweisen, weil der Signaturschlüssel nicht herausgegeben wird. Nutzen Sie sie nur als Vorprüfung.

Schritt 2: die Bestellung kontrollieren

Die Prüfung des Angebots zeigt, dass das Preisversprechen echt ist. Sie zeigt nicht, welche Bestellung der Browser meint. Bevor Sie anhand einer Bestell-ID speichern oder ausliefern, rufen Sie sie auf Ihrem Server mit GET /cfg/v1/orders/{id} und Ihrem geheimen Schlüssel ab. Sie liefert Plan-Hash, Angebots-Hash, Status, Währung und die drei Summen in kleinsten Währungseinheiten, keine personenbezogenen Daten. Vergleichen Sie sie mit dem, was Sie geprüft haben.

Schritt 3: den Webhook empfangen

Konfigurieren Sie einen Webhook, wie auf der Seite zu Bestellungen beschrieben. Ihr Empfänger:

  1. liest den rohen Body, bevor er ihn parst;
  2. liest den Header CutOptim-Signature, t=<unix seconds>,v1=<hex> (während ein Secret rotiert, kann es zwei v1-Werte geben);
  3. berechnet HMAC-SHA256(secret, "<t>.<raw body>") neu, vergleicht in konstanter Zeit und weist einen Zeitstempel ab, der mehr als etwa fünf Minuten abweicht;
  4. beansprucht die Ereignis-ID aus CutOptim-Event-Id, bevor er irgendeine Arbeit erledigt, und ignoriert eine bereits verarbeitete ID;
  5. ignoriert Ereignistypen, die er nicht kennt, und antwortet mit 2xx, damit der Sender nicht umsonst wiederholt.

Das Empfänger-Secret erhalten Sie mit POST /cfg/v1/admin/webhooks/{id}/secret und Ihrem geheimen Schlüssel. Halten Sie Secrets in Ihrer Umgebung, nie in einer Seite, einem Repository oder einem Log.

Referenzcode

Zwei kleine, abhängigkeitsfreie Beispiele zeigen alle drei Schritte. Sie sind Code zum Lesen und Kopieren, kein gehosteter Dienst:

Ihre Secrets sind Platzhalter. Der In-Memory-Duplikatspeicher in den Beispielen ist ein Stellvertreter: Halten Sie in der Produktion verarbeitete Ereignis-IDs in Ihrer Datenbank und beanspruchen Sie eine ID in derselben Transaktion, die die Bestellung festhält.

Dieselben Schritte, mit den genauen Anfragen und Antworten, stehen in der Referenz: Eigener Shop oder ERP.

Schlüssel rotieren

Ein Schlüssel oder Webhook-Secret kann mit Überlappung rotiert werden, sodass der alte für eine festgelegte Zeit weiter funktioniert, während Sie den neuen ausrollen. Bei einer Webhook-Rotation trägt eine Zustellung sieben Tage lang zwei v1-Signaturen, und das Akzeptieren einer beliebigen davon lässt Sie ohne Ausfallzeit umstellen. Konsolen-Schaltflächen für die Rotation mit Überlappung sind noch nicht gebaut; die Konsole kann Schlüssel erstellen und widerrufen.

Andere Wege, Bestellungen zu empfangen

Für WooCommerce nutzen Sie das Plug-in. Wenn Sie nur Schnittpläne in Ihrer eigenen Software benötigen, ohne eingebetteten Kundenbildschirm, ist das die Engine API.

FAQ

Brauche ich ein Plug-in, um den Konfigurator mit meinem eigenen Shop zu nutzen?
Nein. Der Konfigurator wird mit einem Script und einem Element eingebettet, und Ihr Server erledigt drei Dinge: das Angebot vor dem Warenkorb prüfen, die dazugehörige Bestellung kontrollieren und den signierten Webhook prüfen. Diese Seite beschreibt sie und verlinkt Referenzcode in Node und PHP. Für WooCommerce gibt es ein fertiges Plug-in; für keine andere Plattform.
Wie prüft mein Server einen Preis?
Er sendet das Angebots-Token mit Ihrem geheimen Schlüssel an POST /cfg/v1/quote/verify des Konfigurator-Dienstes. Die Antwort besagt, ob es gültig ist und ob es bereits eingelöst wurde. Danach vergleicht er die Claims im Token mit seiner eigenen Warenkorbposition: Tenant, Währung, Ablauf und Angebots-Hash. Eine nur lokale Prüfung kann die Signatur nicht beweisen, entscheiden Sie darauf daher nie über einen Preis.
Verbraucht die Prüfung eines Angebots dieses?
Nein. Die Prüfung ist schreibgeschützt. Nur das Aufgeben der Bestellung verbraucht das Angebot, einmalig. Ein gültiges Angebot kann als bereits eingelöst zurückkommen, prüfen Sie daher beide Felder.
Woher weiß ich, dass eine Bestell-ID aus dem Browser die Bestellung ist, die ich geprüft habe?
Schlagen Sie sie auf Ihrem Server nach: GET /cfg/v1/orders/{id} mit dem geheimen Schlüssel liefert Plan-Hash, Angebots-Hash, Status und Summen dieser Bestellung, nie personenbezogene Daten. Vergleichen Sie sie mit dem geprüften Angebot. Ohne das könnte ein günstiges, geprüftes Angebot neben der ID einer anderen Bestellung gesendet werden.
Gibt es ein SDK oder ein OpenAPI-Dokument?
Es gibt kein SDK und keinen gehosteten Adapter, aber es gibt eine API-Referenz: jede Route, jeden Fehlercode und jede Grenze, mit einem OpenAPI-3.1-Dokument unter /configurator/openapi.json, das ein Client-Generator lesen kann. Die Referenzdateien sind kleine, abhängigkeitsfreie Beispiele in Node und PHP, die Sie lesen und kopieren. Python, Java und C# sind nicht abgedeckt; die Signatur ist ein einfaches HMAC-SHA256, das jede Sprache berechnen kann.
Welche Konfigurator-Ereignisse kann ich empfangen?
order.created und order.status_changed. Andere Ereignisnamen, die die Konfiguration akzeptiert, etwa Angebots- oder Projektereignisse, werden nie gesendet. Die Zustellung erfolgt mindestens einmal, führen Sie daher Buch über die Ereignis-IDs, die Sie verarbeitet haben.

Aktualisiert: 19. Oktober 2026