Studio en iframe#

Proposez l'édition de documents DokKraft dans votre propre produit : le studio se charge dans une iframe de vos domaines, authentifiée par un jeton de courte durée — votre clé API ne quitte jamais votre serveur.

Flux d'intégration#

1. Votre backend appelle POST /api/v1/embed/sessions avec sa clé dfk_.
2. L'API renvoie une url signée (défaut : 2 heures).
3. Votre front charge l'URL dans une <iframe> d'une origine déclarée dans allowed_domains.
4. Le studio et votre page communiquent par postMessage.

Créer la session#

curl -X POST "https://dokkraft.blocsland.com/api/v1/embed/sessions" \
  -H "Authorization: Bearer dfk_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "PUBLIC_ID_DU_TEMPLATE",
    "allowed_domains": ["https://app.votre-produit.com"],
    "ttl_minutes": 120,
    "permissions": { "variables": "frozen", "ai": false }
  }'

Réponse 201 :

{
  "url": "https://dokkraft.blocsland.com/embed/studio/dem_…",
  "token": "dem_…",
  "expires_at": "2026-09-14T12:00:00+00:00",
  "permissions": { "variables": "frozen", "ai": false, "save": true, "export_pdf": true }
}

Permissions#

Permission	Défaut	Effet
variables	frozen	Variables figées (frozen) ou éditables (editable) dans l'iframe
ai	false	Assistant IA disponible
save	true	Enregistrement du template autorisé
export_pdf	true	Export PDF autorisé

Pont postMessage#

Source attendue des messages : dokkraft-embed (iframe → parent) et dokkraft-host (parent → iframe). Filtrez toujours event.origin.

Direction	Type	Payload
parent → iframe	save	{} — déclenche l'enregistrement
parent → iframe	generate	{} — génère le PDF
parent → iframe	ping	{} — test de vie
iframe → parent	ready	{} — studio chargé
iframe → parent	dirty	{ dirty: boolean } (débounce)
iframe → parent	saved	{ templateId, name, created }
iframe → parent	generated	{ dataUrl, filename }
iframe → parent	state	{ dirty, templateId, name, isVariant }
iframe → parent	error	{ code?, added?, removed?, message }
iframe → parent	session.revoked	{ reason: "revoked" } — session révoquée en direct (WebSocket)
iframe → parent	session.expired	{ reason: "expired" } — TTL dépassé
Les messages session.revoked et session.expired arrivent sans action de votre part : la session a été fermée (révocation via DELETE /api/v1/embed/sessions/{token}, expiration du TTL ou de la clé API). L'iframe se verrouille d'elle-même — à vous de masquer vos boutons et de réémettre une session. L'expiration du TTL est suivie par un minuteur local à l'iframe ; DokKraft pousse en plus session.expired par WebSocket si l'onglet était endormi au moment du TTL (détection côté serveur chaque minute).

// Parent → iframe (origines filtrées des deux côtés)
iframe.contentWindow.postMessage(
  { source: 'dokkraft-host', type: 'save' },
  new URL(iframe.src).origin,
);

// iframe → parent
window.addEventListener('message', (event) => {
  if (event.origin !== attendu) return;
  if (event.data?.source !== 'dokkraft-embed') return;
  if (event.data.type === 'generated') download(event.data.dataUrl);
});

Sécurité#

• Le jeton dem_… est à durée de vie courte (5 à 1440 minutes) et ne porte aucune session.
• Les origines sont vérifiées des deux côtés : ne mettez jamais de wildcard dans allowed_domains.
• Un template figé (variables: frozen) ne laisse éditer que le contenu, pas la structure.