# Dokicasa SDK — Istruzioni di integrazione per Claude Code Questo file e' progettato per essere consegnato a **Claude Code** (o ad altri assistenti AI) come prompt di integrazione. Contiene tutto cio' che serve all'assistente per integrare il Web Component `` nel sito del partner senza dover consultare la documentazione interattiva. > **Per Claude/assistente AI:** Leggi tutto questo file prima di scrivere > codice. Le sezioni "Vincoli", "Sicurezza" e "Common pitfalls" contengono > regole non negoziabili. Se manca un parametro (slug del contratto, > API key, secret), CHIEDI all'utente prima di inventarlo. --- ## TL;DR L'SDK Dokicasa e' un **Web Component** distribuito come singolo file JS (~50 KB gzip). Si integra in qualsiasi stack (React, Vue, Svelte, Astro, WordPress, Laravel, HTML statico) con due righe: ```html ``` Lo `user-token` e' un **JWT short-lived** che il backend del partner DEVE generare server-side (mai client-side) firmandolo con la `sk_live_...`. --- ## 1. Contesto - **Cosa offre l'SDK:** rendering completo del form di creazione contratto immobiliare di Dokicasa (compilazione guidata multi-step, validazione, salvataggio bozze, firma elettronica, generazione PDF, invio). - **Cosa NON deve fare il partner:** riprodurre i campi del form, gestire la validazione, salvare i dati, generare PDF, gestire la firma. Tutto questo e' opaco e gestito dall'SDK. - **Cosa deve fare il partner:** 1. Caricare lo script nel `` o appena prima di ``. 2. Renderizzare `` con i 3 attributi richiesti. 3. Generare un JWT lato server per ogni sessione utente. 4. (Opzionale ma consigliato) ascoltare gli eventi `load`, `saved`, `error` per analytics e UX feedback. 5. (Opzionale) ricevere il webhook `contract.completed` sul proprio endpoint per aggiornare il proprio sistema. --- ## 2. Vincoli (non negoziabili) - **MAI** mettere la `sk_live_...` nel codice frontend. Esporrebbe la possibilita' di firmare contratti a nome del partner. - **MAI** generare il JWT in browser. Sempre server-side. - L'`api-key` (`pk_live_...`) puo' stare nel frontend MA solo se il dominio del partner e' nella whitelist `allowed_origins` configurata nel pannello Dokicasa. - Il JWT scade in **15 minuti**. Per sessioni lunghe genera un endpoint che lo refresha (vedi sezione "Refresh JWT"). - Lo script SDK NON e' un'NPM package. Niente `npm install`, niente `import`. E' un `

``` --- ## 5. Quick start (Node.js / Express) ```js import express from 'express'; import jwt from 'jsonwebtoken'; const app = express(); app.get('/contratto/:slug', requireAuth, (req, res) => { const token = jwt.sign({ external_id: String(req.user.id), email: req.user.email, name: req.user.fullName, }, process.env.DOKICASA_SK_LIVE, { issuer: 'partner_abc', audience: 'dokicasa', expiresIn: '15m', }); res.send(` `); }); ``` --- ## 6. Quick start (React + Next.js) ### a) Endpoint API (`pages/api/dokicasa-token.ts`) ```ts import jwt from 'jsonwebtoken'; import type { NextApiRequest, NextApiResponse } from 'next'; import { getServerSession } from 'next-auth'; export default async function handler(req: NextApiRequest, res: NextApiResponse) { const session = await getServerSession(req, res, authOptions); if (!session) return res.status(401).end(); const token = jwt.sign({ external_id: session.user.id, email: session.user.email, }, process.env.DOKICASA_SK_LIVE!, { issuer: 'partner_abc', audience: 'dokicasa', expiresIn: '15m', }); res.json({ token, apiKey: process.env.NEXT_PUBLIC_DOKICASA_PK_LIVE }); } ``` ### b) Componente React ```tsx 'use client'; import { useEffect, useRef, useState } from 'react'; import Script from 'next/script'; export default function ContractForm({ slug }: { slug: string }) { const ref = useRef(null); const [auth, setAuth] = useState<{ token: string; apiKey: string } | null>(null); useEffect(() => { fetch('/api/dokicasa-token').then(r => r.json()).then(setAuth); }, []); useEffect(() => { if (!ref.current) return; const handler = (e: any) => console.log('saved', e.detail); ref.current.addEventListener('saved', handler); return () => ref.current?.removeEventListener('saved', handler); }, [auth]); if (!auth) return

Caricamento...

; return ( <>