Technická dokumentáciaRozhranie postavené okolo jednej konfigurácie
Rovnaký kanonický payload poháňa verejný workflow, 3D náhľad aj všetky generované dokumenty. Administrácia preto nemusí prekladať parametre medzi jednotlivými výstupmi.
Izolovaný iframe prijíma konfiguráciu cez bezpečný message handshake.
Typ výstupu sa volí priamo v ceste bez vytvárania osobitných integrácií.
Konfigurácia ostáva jediným zdrojom pravdy od návrhu až po CNC výstup.
Kanonické cesty
Verejná doména smeruje priamo do konfigurátora. Ostatné integračné povrchy majú stabilné, explicitné cesty.
/Verejný vstup do celého konfiguračného workflow.
/dokumentaciaTáto technická integračná príručka.
/embedSamostatný 3D náhľad určený pre iframe v administrácii.
/api/configurator/documents/{type}Vygenerovanie alebo stiahnutie konkrétneho výstupu konfigurácie.
/api/configurator/configurationsChránený admin proxy endpoint: GET zoznam a POST admin uloženie.
/api/configurator/configurations/{key}Chránené GET, PUT a PATCH jednej konfigurácie podľa ID alebo identifikátora.
/api/configurator/submissionsSame-origin POST validovanej dokončenej konfigurácie do výrobného workflow.
Embed handshake
Rodičovská aplikácia posiela konfiguráciu až po oznámení pripravenosti iframe. Potvrdenie prijatia umožní administrácii spoľahlivo odhaliť neúplné alebo predčasné odoslanie.
bdvtrade-configurator-preview:readybdvtrade-configurator-preview:set-configbdvtrade-configurator-preview:receivedconst frame = document.querySelector('#bdvtrade-preview');
const CONFIGURATOR_ORIGIN = 'https://konfigurator.bdvtrade.sk';
window.addEventListener('message', event => {
if (event.origin !== CONFIGURATOR_ORIGIN || event.source !== frame.contentWindow) return;
if (event.data?.type === 'bdvtrade-configurator-preview:ready') {
frame.contentWindow.postMessage(
{
type: 'bdvtrade-configurator-preview:set-config',
requestId: 'configuration-2026-001',
payload: configuration,
},
CONFIGURATOR_ORIGIN,
);
}
if (event.data?.type === 'bdvtrade-configurator-preview:received') {
console.info('Náhľad prijal konfiguráciu', event.data.requestId);
}
});Pri každej správe kontrolujte event.origin, event.source, typ správy a schému payloadu. Pri postMessage použite presný targetOrigin. Jedinou výnimkou je úvodný ready signál bez citlivých dát; konfiguráciu embed prijme iba z povoleného originu.
Podporované dokumentové typy
Uložená konfigurácia je spoločný dátový zdroj. Z jej ID alebo identifikátora sa na požiadanie generujú štyri samostatné výstupy.
quote.pdfCenová ponuka
Obchodné zhrnutie konfigurácie, položiek a ceny.
drawing.pdfVýrobný výkres
Kótovaný technický podklad pre kontrolu a výrobu.
model.pdfIzometrický 3D model
Samostatný prezentačný list s čistým izometrickým pohľadom dielu.
tcn.tcnTCN súbor
Parametrický strojový výstup pre podporovaný profil; pred výrobou vyžaduje CAM simuláciu.
Štyri výstupy z jednej uloženej konfigurácie
GET načíta tú istú uloženú konfiguráciu podľa ID alebo identifikátora a vygeneruje z nej výkres, 3D model, TCN alebo cenovú ponuku. POST prijíma konfiguračné dáta priamo v tele požiadavky.
Výstup z uloženej konfigurácie
Admin použije svoju autentifikáciu a rovnaký identifikátor konfigurácie pre všetky štyri URL; server môže namiesto nej vystaviť krátkodobý HMAC odkaz.
GET /api/configurator/documents/drawing?configuration=<id>&productSlug=<slug>
GET /api/configurator/documents/model?configuration=<id>&productSlug=<slug>
GET /api/configurator/documents/tcn?configuration=<id>&productSlug=<slug>
GET /api/configurator/documents/quote?configuration=<id>&productSlug=<slug>
Accept: */*
Authorization: Bearer <access-token>
# Alternatíva: krátkodobý odkaz podpísaný serverom
GET /api/configurator/documents/drawing?configuration=<id>&productSlug=<slug>&expires=<unix-timestamp>&signature=<base64url-hmac>Generovanie z payloadu
Typ v URL určuje výstup; telo obsahuje kanonickú konfiguráciu.
POST /api/configurator/documents/quote
Content-Type: application/json
Authorization: Bearer <access-token>
{
"configuration": {
"productId": "door-handle-edge",
"machineId": "bdv-5axis",
"materialId": "wood",
"widthMm": 600,
"heightMm": 720,
"thicknessMm": 22,
"quantity": 2,
"handle": {
"openSide": "right",
"lengthMm": 180,
"offsetMm": 70,
"faceWidthMm": 30,
"depthMm": 12,
"transitionLengthMm": 50,
"transitionRoundness": 78,
"grooveWidthMm": 12,
"roughingAllowanceMm": 0.5
},
"edgeTreatment": {
"profile": "roundover",
"sizeMm": 2,
"cornerRadiusMm": 2
},
"stockAllowanceMm": {
"widthMm": 3,
"heightMm": 0,
"thicknessMm": 0
},
"finishId": "oil"
}
}Uložený GET výstup nesmie byť verejný iba podľa ID.
Endpoint na stiahnutie uloženého dokumentu musí vyžadovať autentifikáciu alebo podpísanú URL s krátkou platnosťou. Podpis je viazaný na typ dokumentu, ID konfigurácie a expiráciu; server ho overí pred odoslaním súboru.
- Autorizujte prístup ku konfigurácii, nie iba samotné prihlásenie.
- Admin credential sa serverovo overuje cez kanonický product-configurator endpoint ešte pred listom, detailom alebo dokumentovým lookupom.
- Verejné odoslanie je oddelené od admin API, prijíma iba same-origin požiadavku a server sám vyberá cieľový produktový slug.
- Obmedzte platnosť podpísaného odkazu a nepoužívajte ho opakovane bez potreby.
- Podpis je Base64URL HMAC-SHA256 z reťazca
v1 {type} {key} {productSlug} {expires}; expirácia môže byť najviac 24 hodín a tajomstvo patrí iba doCONFIGURATOR_DOCUMENT_SECRET. - Logujte typ výstupu, konfiguráciu, používateľa a čas generovania.