Spranz Modal - Developer Integration

Overview

The Spranz Modal (Logo Configurator) embeds into external webshops via URL parameters and iframe postMessage. Modal is hosted at https://designer.spranz.de/modal/.

Integration flow

1. Before showing a "Customize Logo" button on a product page, call GET /api/config-check/:sku. If available is true, show the button.
2. When the user clicks the button, open the modal at https://designer.spranz.de/modal/?sku=...&variant=...&technique=...&callback_url=... (iframe or new window).
3. Listen for postMessage events from https://designer.spranz.de. On MAGIC_LOGO_ADD_TO_ORDER, add the item to your cart. On CLOSE_MODAL or CONFIGURATION_CANCELLED, close your iframe.
4. If you passed a callback_url, a server-to-server POST is also fired when the user clicks "Add to Order" — use that for durable storage.

Base URL

https://designer.spranz.de/modal/

URL Parameters

Preflight: config-check

Use this before showing the "Customize Logo" button to detect whether a product can be configured:

GET https://designer.spranz.de/api/config-check/{sku}

Response:
{
  "available": true,
  "hasSvg": true,
  "hasCoordinates": true,
  "sku": "376-00.005",
  "base_sku": "376-00",
  "techniques": [
    { "code": "T8", "name": "Tampondruk", "print_area": "35x25", "position": "mittig", "positions": 1 },
    { "code": "DP-UV7", "name": "Digitale UV-print", "print_area": "60x40", "position": "mittig", "positions": 1 }
  ]
}

available is true when both an SVG template and print coordinates exist. hasSvg can be used as a direct replacement for the deprecated has-svg endpoint.

PostMessage events (iframe)

CONFIGURATOR_READY

Fired once after the modal mounts and is ready for parent interaction.

{ type: "CONFIGURATOR_READY" }

MAGIC_LOGO_ADD_TO_ORDER

Fired when the user clicks "Add to Order".

{
  type: "MAGIC_LOGO_ADD_TO_ORDER",
  transactionId: "uuid",
  basketId: "your-basket-id",
  productSku: "376-00",
  variantSku: "376-00.005",
  selectedVariant: "376-00.005",
  selectedColor: "005",
  quantity: 100,
  techniqueCode: "T8",
  techniqueName: "Tampondruk",
  printArea: "35x25",
  logoConfig: { logoUrl, techniqueCode, techniqueName, position, printArea, colors, scale },
  filesUrl:      "https://designer.spranz.de/api/transactions/{id}/files",
  screenshotUrl: "https://designer.spranz.de/api/transactions/{id}/screenshot",
  pdfUrl:        "https://designer.spranz.de/api/transactions/{id}/pdf",
  logoUrl:       "https://designer.spranz.de/api/transactions/{id}/logo"
}

Detecting "no variant selected": when the user did not choose a color, variantSku and selectedVariant equal productSku and selectedColor is an empty string. Check selectedColor === "" or variantSku === productSku.

CLOSE_MODAL

Fired when the modal wants the parent to close it (after save or after cancel).

{ type: "CLOSE_MODAL" }

CONFIGURATION_CANCELLED

Fired when the user cancels without saving. Always followed by CLOSE_MODAL.

{ type: "CONFIGURATION_CANCELLED" }

Example parent-window listener

window.addEventListener("message", (event) => {
  if (event.origin !== "https://designer.spranz.de") return;
  switch (event.data.type) {
    case "CONFIGURATOR_READY":
      break;
    case "MAGIC_LOGO_ADD_TO_ORDER":
      addToCart(event.data);
      closeModal();
      break;
    case "CONFIGURATION_CANCELLED":
    case "CLOSE_MODAL":
      closeModal();
      break;
  }
});

Server-to-server callback

When callback_url is supplied, a POST is fired on "Add to Order":

POST {callback_url}
Content-Type: application/json

{
  "transactionId": "uuid",
  "productSku": "376-00",
  "variantSku": "376-00.005",
  "selectedVariant": "376-00.005",
  "selectedColor": "005",
  "quantity": 100,
  "techniqueCode": "T8",
  "techniqueName": "Tampondruk",
  "printArea": "35x25",
  "logoConfig": { ... },
  "modalUrl":        "https://designer.spranz.de/api/transactions/{id}/modal",
  "filesUrl":        "https://designer.spranz.de/api/transactions/{id}/files",
  "screenshotUrl":   "https://designer.spranz.de/api/transactions/{id}/screenshot",
  "logoUrl":         "https://designer.spranz.de/api/transactions/{id}/logo",
  "downloadZipUrl":  "https://designer.spranz.de/api/transactions/{id}/download-zip"
}

File endpoints

All file endpoints require a valid transactionId from the callback. They return 404 until the file has been generated — for screenshot, PDF, and logo this happens as part of "Add to Order".

Preselect examples

# Product only — user picks variant + technique
https://designer.spranz.de/modal/?sku=376-00

# Preselect a specific variant + technique
https://designer.spranz.de/modal/?sku=376-00&variant=376-00.005&technique=T8

# Same result with variant embedded in sku
https://designer.spranz.de/modal/?sku=376-00.005&technique=T8

# Preselect by color name
https://designer.spranz.de/modal/?sku=376-00&color=Blau&technique=T8

# With server-to-server callback
https://designer.spranz.de/modal/?sku=376-00.005&technique=T8&basket_id=abc&callback_url=https%3A%2F%2Fyour-server.tld%2Fcallback

CORS

The API allows requests from: localhost:8080, spranz.mymoodia.de, www.spranz.de, spranz.de, and designer.spranz.de. Need another origin? Contact Wayne.

Changelog

• 2026-04-15 — Added variant and color URL params; technique URL param now actually preselects. Removed has-svg (use config-check). Fixed techniqueName for 549 rows so it shows the descriptive name.
• 2026-03-25 — CLOSE_MODAL and CONFIGURATION_CANCELLED postMessage events added; variantSku/selectedVariant/selectedColor separated in payload.
• 2026-03-24 — Callback fires on "Add to Order" (not on close); screenshot endpoint supports PNG and JPG.

API Endpoints

{
  "basketId": "uuid",
  "productSku": "376-00.005",
  "variantSku": "376-00.005",
  "techniqueCode": "T8",
  "techniqueName": "Tampondruk",
  "printArea": "35x25",
  "quantity": 500,
  "logoConfig": { ... },
  "callbackUrl": "https://shop.nl/callback"
}

{
  "transaction_id": "uuid",
  "basket_id": "uuid",
  "product_sku": "376-00.005",
  "quantity": 500,
  "callback_url": "https://shop.nl/callback",
  "status": "draft",
  "files": {
    "screenshot": "/api/transactions/{id}/screenshot",
    "pdf": "/api/transactions/{id}/pdf",
    "logo": "/api/transactions/{id}/logo"
  }
}

{
  "transaction_id": "uuid",
  "basket_id": "uuid",
  "product_sku": "376-00.005",
  "technique_code": "T8",
  "technique_name": "Tampondruk",
  "quantity": 500,
  "status": "draft",
  "logo_config": { ... },
  "files": { ... }
}

{
  "transaction_id": "uuid",
  "files": {
    "screenshot": "/api/transactions/{id}/screenshot",
    "screenshot_hq": "/api/transactions/{id}/screenshot?quality=high",
    "logo_original": "/api/transactions/{id}/logo",
    "pdf": "/api/transactions/{id}/pdf"
  }
}

{
  "success": true,
  "data": {
    "filename": "korrekturabzug_376-00.005.pdf",
    "url": "/api/transactions/{id}/pdf"
  }
}

{"success": true, "message": "Transaction cancelled"}

HTML response met PDF preview, download links voor Screenshot, Logo, EPS, PDF, en Download ZIP knop

PNG/JPEG afbeelding van product met logo overlay

PNG/JPG/SVG logo bestand

EPS vector bestand

PDF bestand met product preview

ZIP bestand met alle transaction bestanden

Code Examples

URL Voorbeeld - Order Mode

https://spranz-modal.magiceverse.online/modal/?sku=376-00.005&quantity=500&technique=T8&mode=order&callbackUrl=https://shop.nl/api/logo-callback

URL Voorbeeld - Configure Mode

https://spranz-modal.magiceverse.online/modal/?sku=376-00.005&mode=configure

Callback Payload

{
  "transactionId": "4c663aef-c103-466d-bd89-3a14bc26b20d",
  "productSku": "376-00.005",
  "variantSku": "376-00.005",
  "quantity": 500,
  "techniqueCode": "T8",
  "techniqueName": "Tampondruk",
  "printArea": "35x25",
  "filesUrl": "/api/transactions/4c663aef-c103-466d-bd89-3a14bc26b20d/files",
  "screenshotUrl": "/api/transactions/4c663aef-c103-466d-bd89-3a14bc26b20d/screenshot",
  "logoUrl": "/api/transactions/4c663aef-c103-466d-bd89-3a14bc26b20d/logo"
}

Iframe PostMessage Listener

window.addEventListener("message", (event) => {
  // Verify origin for security
  if (event.origin !== "https://spranz-modal.magiceverse.online") return;
  
  if (event.data.type === "MAGIC_LOGO_ADD_TO_ORDER") {
    const { transactionId, productSku, quantity, techniqueCode, filesUrl } = event.data;
    
    console.log("Logo configuratie ontvangen:", {
      transactionId,
      productSku,
      quantity,
      techniqueCode
    });
    
    // Voeg toe aan winkelwagen
    addToCart({
      sku: productSku,
      quantity: quantity,
      logoTransactionId: transactionId,
      filesUrl: filesUrl
    });
  }
});

PHP Callback Handler

<?php
// Ontvang callback van Spranz Modal
$payload = json_decode(file_get_contents("php://input"), true);

if ($payload && isset($payload["transactionId"])) {
    // Log de transactie
    error_log("Logo transactie ontvangen: " . $payload["transactionId"]);
    
    // Sla op in database
    $db->prepare("INSERT INTO logo_orders (transaction_id, sku, quantity, technique) VALUES (?, ?, ?, ?)")
       ->execute([
           $payload["transactionId"],
           $payload["productSku"],
           $payload["quantity"],
           $payload["techniqueCode"]
       ]);
    
    // Download bestanden via API
    $filesUrl = "https://spranz-modal.magiceverse.online" . $payload["filesUrl"];
    // ... fetch files
    
    http_response_code(200);
    echo json_encode(["success" => true]);
}

Netwerk Pad naar Bestanden

Windows netwerk share:
\\192.168.1.26\magic_logo_transactions\spranz\{transactionId}\

Bestanden:
- screenshot.jpg      (preview)
- screenshot_hq.jpg   (hoge kwaliteit)
- logo_original.png   (origineel logo)
- logo_processed.png  (verwerkt logo)
- print.pdf          (korrekturabzug)