Market Scanner — SDK JavaScript
L'SDK JavaScript fa per te tutto il lavoro del Market Scanner: lancia la ricerca, ne segue l'avanzamento in tempo reale sul WebSocket, passa da solo al polling se il socket cade, e ti restituisce il risultato con un solo await. Errori, ritentativi, timeout e annullamento sono già gestiti.
| Pacchetto | @dokicasa/sdk (TypeScript, ESM + CommonJS, nessuna dipendenza obbligatoria) |
| Ambienti | Node 18+ e browser moderni, con hook per React 18+ e composable per Vue 3.3+ |
| Base URL | https://api.dokicasa.it (produzione), https://api-dev.dokicasa.it (sandbox) |
| Auth | il tuo token API, come Authorization: Bearer (lo mette l'SDK) |
| Tempo reale | facoltativo, con pusher-js |
Prima di tutto, la sandbox
Con environment: 'sandbox' l'SDK usa api-dev.dokicasa.it: stesse API e stesso socket della produzione, ma dati di esempio e nessun costo. Il token di prova è nella pagina del Market Scanner.
Installazione
npm install @dokicasa/sdk
# solo se vuoi gli aggiornamenti in tempo reale:
npm install pusher-jsIn alternativa, dallo stesso pacchetto ospitato qui: npm install https://docs.dokicasa.it/sdk/market-scanner/dokicasa-sdk-0.2.0.tgz.
Senza un bundler puoi importare direttamente il file ESM:
<script src="https://cdn.jsdelivr.net/npm/pusher-js@8.4.0/dist/web/pusher.min.js"></script>
<script type="module">
import { createClient } from 'https://docs.dokicasa.it/sdk/market-scanner/index.js';
const dk = createClient({ token: tokenDellUtente, realtime: { Pusher: window.Pusher } });
</script>I tipi TypeScript sono inclusi (index.d.ts).
Avvio rapido
import { createClient } from '@dokicasa/sdk';
import Pusher from 'pusher-js';
const dk = createClient({
token: process.env.DOKICASA_TOKEN,
environment: 'sandbox', // 'production' quando sei pronto
realtime: { Pusher }, // facoltativo: senza, l'SDK fa polling
});
const visura = await dk.scanner.run(
'visura-catasto',
{ comune: 'Roma', provincia: 'RM', foglio: '123', particella: '45', tipo_visura: 'ANALITICA' },
{ onProgress: (p) => console.log(p.status, p.percentage, p.source) },
);
const pdf = await dk.scanner.downloadDocument(visura); // { data, filename, contentType }run lancia la ricerca e aspetta che finisca. Per lanciarla e aspettarla in due momenti diversi usa create e poi wait(id).
In produzione le ricerche costano
Ogni run / create in produzione è una ricerca vera e consuma credito. L'SDK non rilancia mai da solo una ricerca: ritenta solo le letture.
React e Vue
Per le app React e Vue c'è useScanner(): lancia la ricerca, la segue (socket + polling) e ti dà uno stato pronto per la UI. Quando il componente sparisce l'attesa si chiude da sola.
| Campo | Cosa contiene |
|---|---|
phase | idle, creating, running, success, error, cancelled |
isRunning | true mentre la ricerca viene lanciata o seguita |
percentage | 0-100 per una barra (100 a ricerca finita) |
progress | ultimo aggiornamento: stato Sister, percentuale, source (realtime o polling) |
requestId | id della ricerca (salvalo per riprenderla) |
result / error | richiesta finale con i risultati / errore tipizzato |
run(tipo, parametri) | lancia e segue; l'esito è nello stato, nessuna eccezione |
resume(id) · cancel() · reset() | riprende una ricerca, smette di aspettare, azzera |
import { createClient } from '@dokicasa/sdk';
import { DokicasaProvider, useScanner } from '@dokicasa/sdk/react';
import Pusher from 'pusher-js';
const dk = createClient({ token: userToken, environment: 'sandbox', realtime: { Pusher } });
function Visura({ particella }) {
const scan = useScanner();
return (
<>
<button disabled={scan.isRunning} onClick={() => scan.run('visura-catasto', particella)}>Cerca</button>
{scan.isRunning && <button onClick={scan.cancel}>Annulla</button>}
<progress value={scan.percentage} max={100} />
{scan.phase === 'success' && <a href={scan.result.result.pdf_path}>Visura pronta</a>}
{scan.error && <p role="alert">{scan.error.message}</p>}
</>
);
}
// <DokicasaProvider client={dk}><Visura particella={...} /></DokicasaProvider><!-- main.ts: createApp(App).use(DokicasaPlugin, { client: dk }) -->
<script setup lang="ts">
import { useScanner } from '@dokicasa/sdk/vue';
const props = defineProps<{ particella: Record<string, string> }>();
const { run, cancel, phase, isRunning, percentage, result, error } = useScanner();
</script>
<template>
<button :disabled="isRunning" @click="run('visura-catasto', props.particella)">Cerca</button>
<button v-if="isRunning" @click="cancel">Annulla</button>
<progress :value="percentage" max="100" />
<a v-if="phase === 'success'" :href="result?.result.pdf_path">Visura pronta</a>
<p v-if="error" role="alert">{{ error.message }}</p>
</template>- Una ricerca alla volta per hook: per più ricerche insieme, un
useScanner()per ognuna. - Per riprendere una ricerca salvata (es. nell'URL):
useScanner({ resumeId }). In Vue accetta un ref o un getter e segue la nuova ricerca quando cambia. - Il motore è
ScanStore, senza framework: va bene per Svelte, Angular o JavaScript puro. - Nel browser usa il token del singolo utente, mai quello del partner. Il dominio della tua app va abilitato da Dokicasa (CORS): chiedilo al tuo referente con gli indirizzi di sviluppo e staging. Nel frattempo, in sviluppo, passa dal proxy di Vite (esempio nel README del pacchetto).
Configurazione
Di solito basta il token. Ogni altro valore è configurabile:
const dk = createClient({
token: 'xxx', // oppure getToken: async () => leggiIlToken()
environment: 'production', // 'production' | 'sandbox'
baseUrl: 'https://api.dokicasa.it', // sovrascrive l'ambiente (es. un tuo proxy)
timeoutMs: 60000, // timeout di ogni chiamata
retry: { maxRetries: 3, baseDelayMs: 500, maxDelayMs: 10000 }, // oppure false
polling: { intervalMs: 2000, maxIntervalMs: 15000, backoffFactor: 1.5 },
realtime: { Pusher, key, wsHost, wsPort, forceTLS, authEndpoint, pusherOptions }, // oppure false
headers: { 'X-Correlation-Id': 'abc' },
fetch: customFetch,
logger: console,
onRequest: (req) => {}, // hook per log e metriche
onResponse: (res) => {}, // con stato e durata
});| Opzione | Default | A cosa serve |
|---|---|---|
token / getToken | obbligatorio | Autenticazione. getToken viene chiamato a ogni richiesta (token rinnovabili). |
environment | production | Sceglie insieme URL dell'API e del socket, sempre allineati. |
retry | 3 ritentativi sulle letture | Su rete giù, timeout, 429 e 5xx, rispettando Retry-After. |
polling | da 2 a 15 secondi | Quando il socket non c'è, il polling rallenta da solo. |
realtime | attivo se c'è pusher-js | false per usare solo il polling. |
actingUser | — | Partner SSO: chiamate per conto di un utente (vedi sotto). |
Ricerche
I parametri sono quelli dell'API, con i tipi TypeScript per ogni tipo di ricerca (elenco dei tipi).
await dk.scanner.run('catasto', { comune, foglio, particella, search_catasto_type: 'F' });
await dk.scanner.run('tax-data', { tax_code: 'XXXXXX00X00X000X' });
await dk.scanner.run('ispezione-tax-data', { tax_code, provincia, comune });
await dk.scanner.run('mappa-catasto', { comune, provincia, foglio, particella, tipo_richiesta: 'ATTUALITA', tipo_foglio: 'INTERO', formato: 'A3' });Ricerche in più passi. Se l'API chiede una scelta (più immobili, sezioni, omonimi), il risultato ha needs_selection: si rilancia con il valore scelto.
let r = await dk.scanner.run('visura-catasto', { ...dati, enable_multi_step: true });
if (r.result.needs_selection) {
r = await dk.scanner.run('visura-catasto', { ...dati, selected_value: r.result.rows_immobili[0].value });
}Risultati, documenti, export.
const req = await dk.scanner.get(id); // richiesta completa
for await (const immobile of dk.scanner.iterateResults(id, { filters: { categoria: ['A/2'] } })) { /* ... */ }
const { filters } = await dk.scanner.filters(id); // valori disponibili per i filtri
await dk.scanner.exportXls(id, { categoria: ['A/2'] }); // Excel per email (a pagamento)
await dk.scanner.monitor(id, { models: [] }); // monitora tutto (a pagamento)Prima di lanciare. dk.system.services() restituisce prezzo e crediti per ogni tipo, dk.system.health() lo stato di Sister. Con checkHealth: true l'SDK non lancia la ricerca se il servizio è fermo, e quindi non spendi.
Tempo reale
Con pusher-js, run e wait seguono la ricerca sul canale privato private-scanner_request.{id}, senza polling. Il socket è best effort e l'SDK lo tratta così:
- con il socket attivo fa solo un controllo di sicurezza lento, per recuperare un evento perso;
- se il socket cade o il canale viene negato, passa al polling con intervalli crescenti;
- appena iscritto rilegge lo stato (l'evento finale può essere arrivato prima);
- a fine attesa chiude il canale; i canali sono condivisi tra chi ascolta.
const stop = dk.scanner.watch(id, (e) => console.log(e.status, e.percentage)); // solo ascolto
dk.realtime.user(userId, { onToast: (t) => notifica(t.message) }); // eventi personali
dk.realtime.onStateChange((stato) => console.log('socket', stato));
dk.close(); // a fine usoPer aprire il socket già all'avvio dell'app (la prima ricerca è più rapida): await dk.realtime.connect().
Censimento e monitoraggi
const { scanner_request_id: padre } = await dk.census.create(); // o { searchMode: 'MULTI_ADDRESS' }
const candidati = await dk.census.findAddresses({ indirizzo, comune, provincia });
await dk.census.addAddress(padre, { indirizzo, comune, provincia, address_value, numero_civico });
const censimento = await dk.census.wait(padre);
await dk.monitorings.fromCatasto({ comune, provincia, foglio, particella, webhook_url });
const lista = await dk.monitorings.list({ type: 'IMMOBILE' });
const { wallet } = await dk.account.wallet();Si può avere un solo censimento alla volta per utente (CensusInProgressError).
Errori
Ogni errore estende DokicasaError e ha un code; quelli dell'API anche status e body. Si gestiscono con instanceof:
| Classe | Quando | Dati utili |
|---|---|---|
InsufficientFundsError | Crediti o saldo insufficienti (AMOUNT_NOT_ENOUGH) | missingAmount, checkoutLink |
ValidationError | Dati non validi (422), codice fiscale non valido | fields, isDuplicate |
CensusInProgressError | Censimento già in corso (PENDING_CENSIMENTO) | |
ServiceUnavailableError | Sister fermo, in manutenzione o sovraccarico | |
RateLimitError | Troppe richieste (429) | retryAfterSeconds |
PartnerPricingRequiredError | Tipo di ricerca non abilitato sul tuo account | scannerType |
AuthenticationError / PermissionError / NotFoundError | 401 / 403 / 404 | |
ScanFailedError | Ricerca finita in ERROR o CANCELLED | request |
TimeoutError / AbortError / NetworkError | Tempo scaduto, annullata, rete giù |
try {
await dk.scanner.run('visura-catasto', dati);
} catch (e) {
if (e instanceof InsufficientFundsError) return apriCheckout(e.checkoutLink);
if (e instanceof ValidationError && e.isDuplicate) return avvisa('Ricerca già in corso');
if (e instanceof ServiceUnavailableError) return avvisa('Catasto momentaneamente non disponibile');
throw e;
}Doppioni
L'API rifiuta una ricerca identica fatta pochi secondi dopo (un'ora per i documenti): ValidationError con isDuplicate === true. Non è un errore da mostrare come tale.
Attese, timeout e annullamento
const controller = new AbortController();
const r = await dk.scanner.run('ispezione-tax-data', dati, {
signal: controller.signal, // annulla chiamate e attesa
timeoutMs: 10 * 60_000, // attesa massima (default 15 minuti)
maxConsecutiveErrors: 5, // errori di rete tollerati durante l'attesa
throwOnFailure: false, // restituisce la richiesta anche se è finita in ERROR
});Annullare l'attesa non ferma la ricerca: prosegue lato server e puoi riprenderla con dk.scanner.wait(id).
Partner SSO: per conto di un utente
Se i tuoi utenti entrano in Dokicasa con l'accesso diretto (SSO), puoi chiamare per conto di uno di loro con il tuo token: ricerche, crediti e canali in tempo reale saranno i suoi.
const agente = dk.as({ email: 'agente@example.com' }); // oppure dk.as('<slug>:<id esterno>')
await agente.account.wallet();
await agente.scanner.run('catasto', dati);L'SDK manda l'header X-Dokicasa-User (email:<email> oppure <slug del partner>:<id esterno>). Vale solo per gli utenti collegati al tuo account partner; per gli altri la risposta è 403 ACTING_USER_FORBIDDEN, con lo stesso messaggio anche per gli utenti che non esistono.
Attivazione su richiesta
L'header va abilitato da Dokicasa sul tuo account partner: chiedilo al tuo referente.
Webhook
Per non restare in attesa passa webhook alla ricerca. Verifica la firma sul corpo grezzo, prima di fare JSON.parse (dettagli della firma):
import { parseWebhook } from '@dokicasa/sdk';
app.post('/webhook/dokicasa', express.raw({ type: '*/*' }), async (req, res) => {
try {
const evento = await parseWebhook({ body: req.body, signature: req.get('Signature'), secret: process.env.DOKICASA_TOKEN });
res.sendStatus(200);
} catch {
res.sendStatus(401);
}
});Demo, esempi e prove
Il pacchetto npm contiene tutto il progetto: sorgenti, test, demo ed esempi, in node_modules/@dokicasa/sdk/. Le demo partono con un comando, senza clonare nulla:
DOKICASA_TOKEN=<token sandbox> npx -p @dokicasa/sdk dokicasa-sdk-demo| Pagina | Cosa fa |
|---|---|
Playground (localhost:5174) | qualsiasi ricerca, con l'origine di ogni aggiornamento (socket o polling), scelta nei passi, PDF ed errori spiegati |
Esempi dal vivo (/esempi) | 12 esempi (visura, codice fiscale, censimento, monitoraggi, errori, webhook, partner SSO, prezzi, annullamento...) con il codice accanto |
Vue (/vue) e React (/react) | lo stesso componente con useScanner(): ricerca, barra, annulla, riprendi per id, PDF |
Ci sono anche gli stessi 12 esempi da lanciare in Node (examples/), 132 test unitari e una suite di prove end-to-end contro la sandbox: DOKICASA_E2E_TOKEN=<token> npm run test:e2e.
Sicurezza
- Il token API vale come una password: non metterlo nel codice e non pubblicarlo nel frontend. Nel browser usa il token del singolo utente, mai quello del partner.
- Dal tuo server la chiamata deve partire da un'origine abilitata sul tuo account (
ORIGIN_NOT_ALLOWEDaltrimenti).