Eigene Druckdatenprüfung

Der Produktdesigner prüft schon von sich aus Auflösung, Kontrast, Sicherheitsabstand, Überlappung und die Zahl der Druckfarben. Hat deine Produktion weitere Regeln, etwa „ein Logo muss mindestens 15 mm breit sein“ oder „auf Heißfolie keine Schrift unter 6 mm“, ergänzt du eigene Prüfungen: im Browser mit JavaScript oder auf deinem Server per Webhook.

Für eine Regel, die gelten muss, nimmst du den Webhook. Am besten kombinierst du beide: Der Browser zeigt den Hinweis sofort, der Server sichert ab.

Prüfung im Browser

Du meldest eine Prüfung über die JavaScript-Schnittstelle an:

Configento.registerDesignCheck('logo-mindestbreite', (ctx) =>
    ctx.placement && ctx.placement.widthMm < 15
        ? { level: 'block', message: 'Das Logo muss mindestens 15 mm breit sein.' }
        : null,
    { appliesTo: ['logo'] });

• Der Name besteht aus Kleinbuchstaben, Ziffern und Bindestrichen.
• appliesTo nennt die Internen Namen (ID) der Merkmale, für die die Prüfung gilt. Ohne appliesTo läuft sie für jeden eigenen Text und jedes eigene Bild.
• registerDesignCheck gibt eine Funktion zurück, die die Prüfung wieder abmeldet.

Läuft dein Skript, bevor configento.js geladen ist, legst du die Prüfungen vorab an:

window.ConfigentoDesignChecks = {
    'logo-mindestbreite': [check, { appliesTo: ['logo'] }],
};

Was die Prüfung bekommt

Die Prüfung läuft bei jeder Änderung und bekommt ein Objekt ctx:

Was die Prüfung antwortet

• null: alles in Ordnung.
• { level: 'warn', message: '…' }: Der Hinweis steht am Feld, bestellt werden kann trotzdem.
• { level: 'block', message: '…' }: Der Hinweis steht am Feld, und der Konfigurator hält den Warenkorb zurück.
• Eine Liste solcher Ergebnisse, wenn mehrere Dinge nicht passen.

Den Hinweis gestaltest du über die Klasse .cfg-design__check; data-configento-level sagt, ob es eine Warnung oder eine Sperre ist, data-configento-check nennt den Namen deiner Prüfung. Siehe Design anpassen. Wirft eine Prüfung einen Fehler, ignoriert der Konfigurator sie und schreibt den Fehler in die Browser-Konsole.

Prüfung auf deinem Server

Mit einem Webhook prüft dein Server jede Gestaltung, bevor sie in den Warenkorb kommt. So hält die Regel auch dann, wenn jemand den Browser umgeht.

Einrichten

1. Öffne im Admin Einstellungen → API und dort Druckdatenprüfung per Webhook.
2. Trage die Webhook-URL ein. Erlaubt ist nur https an eine öffentliche Adresse.
3. configento.app erzeugt einen Signatur-Schlüssel (dcw_…). Hinterlege ihn auf deinem Server. Neuer Schlüssel ersetzt ihn.
4. Klicke auf Testaufruf senden. Antwortet dein Server, erscheint „Der Webhook hat geantwortet.“
5. Entscheide, ob Warenkorb ablehnen, wenn der Webhook nicht antwortet gelten soll (siehe unten).

Die Anfrage

Beim Hinzufügen zum Warenkorb rechnet configento.app den Preis nach und schickt dabei alle sichtbaren, ausgefüllten eigenen Texte und Bilder per POST an deine URL:

{
  "event": "design_check",
  "component_id": "10000021",
  "locale": "de_DE",
  "fields": [ { "characteristic": { "key": "logo", "type": "customimage" }, "placement": { "widthMm": 12.4, "dpi": 310 } } ]
}

Jedes Element in fields hat denselben Aufbau wie ctx im Browser (gekürzt dargestellt). Nur box ist auf dem Server immer null.

Die Kopfzeilen:

Prüfe die Signatur, bevor du der Anfrage traust, z. B. in Node.js:

const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', process.env.CONFIGENTO_DCW_SECRET)
    .update(req.headers['x-configento-timestamp'] + '.' + rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-configento-signature'] || ''));

Verwirf außerdem Anfragen mit einem Zeitpunkt, der mehr als ein paar Minuten zurückliegt.

Die Antwort

Dein Server antwortet mit Status 2xx und:

{ "findings": [ { "field": "logo", "level": "block", "message": "Das Logo muss mindestens 15 mm breit sein." } ] }

field ist der Interne Name des Merkmals. Eine leere Liste heißt: alles in Ordnung.

Dein Server hat 2 Sekunden Zeit; Weiterleitungen folgt configento.app nicht. Das Ergebnis gilt zusammen mit dem Preis 5 Minuten, eine gleiche Konfiguration fragt in dieser Zeit nicht noch einmal an.

Voraussetzung im Shop

Der Webhook läuft in der Preisprüfung. Sperrt er, kommt die Konfiguration nicht in den Warenkorb, und dein Kunde sieht dort deine Meldung, ab diesen Plugin-Versionen:

Mit älteren Plugin-Versionen wirkt die Sperre ebenso, dein Kunde sieht aber nur die allgemeine Meldung, dass die Konfiguration nicht mehr gültig ist oder der Preis nicht bestätigt werden konnte.

Gib deine Meldung deshalb auch über eine Prüfung im Browser aus, dann sieht dein Kunde sie schon beim Gestalten.

Fehlersuche

1. Die Prüfung im Browser greift nicht: Stimmt der Interne Name in appliesTo? Ist das Skript nach configento.js geladen, oder nutzt du window.ConfigentoDesignChecks? Fehler der Prüfung stehen in der Browser-Konsole.
2. „Der Webhook hat nicht verwertbar geantwortet“: Dein Server antwortet nicht innerhalb von 2 Sekunden, leitet weiter, antwortet ohne 2xx oder ohne gültiges JSON.
3. Die Sperre wirkt nicht im Shop: In Magento steht die Preisprüfung nicht auf Erzwingen. Dein Kunde sieht nur eine allgemeine Meldung: Das Plugin ist älter als die Versionen oben.
4. Die Signatur stimmt nicht: Rechne über den unveränderten Rohtext der Anfrage, nicht über ein neu erzeugtes JSON, und prüfe, ob du nach Neuer Schlüssel den neuen Schlüssel hinterlegt hast.

Nächste Schritte

• Eigener Text auf dem Produkt
• Eigenes Bild auf dem Produkt
• JavaScript-Schnittstelle
• API-Einstieg