Skip to content

Market Scanner — SDK JavaScript ​

Integra con un assistente AI
Scarica o copia il prompt di integrazione per Market Scanner — SDK JavaScript e incollalo in Claude Code, Cursor o Copilot: contiene auth, esempi end-to-end e checklist.
Apri

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)
AmbientiNode 18+ e browser moderni, con hook per React 18+ e composable per Vue 3.3+
Base URLhttps://api.dokicasa.it (produzione), https://api-dev.dokicasa.it (sandbox)
Authil tuo token API, come Authorization: Bearer (lo mette l'SDK)
Tempo realefacoltativo, 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 ​

bash
npm install @dokicasa/sdk
# solo se vuoi gli aggiornamenti in tempo reale:
npm install pusher-js

In 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:

html
<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 ​

js
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.

CampoCosa contiene
phaseidle, creating, running, success, error, cancelled
isRunningtrue mentre la ricerca viene lanciata o seguita
percentage0-100 per una barra (100 a ricerca finita)
progressultimo aggiornamento: stato Sister, percentuale, source (realtime o polling)
requestIdid della ricerca (salvalo per riprenderla)
result / errorrichiesta 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
tsx
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>
vue
<!-- 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:

js
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
});
OpzioneDefaultA cosa serve
token / getTokenobbligatorioAutenticazione. getToken viene chiamato a ogni richiesta (token rinnovabili).
environmentproductionSceglie insieme URL dell'API e del socket, sempre allineati.
retry3 ritentativi sulle lettureSu rete giù, timeout, 429 e 5xx, rispettando Retry-After.
pollingda 2 a 15 secondiQuando il socket non c'è, il polling rallenta da solo.
realtimeattivo se c'è pusher-jsfalse 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).

js
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.

js
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.

js
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.
js
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 uso

Per aprire il socket già all'avvio dell'app (la prima ricerca è più rapida): await dk.realtime.connect().

Censimento e monitoraggi ​

js
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:

ClasseQuandoDati utili
InsufficientFundsErrorCrediti o saldo insufficienti (AMOUNT_NOT_ENOUGH)missingAmount, checkoutLink
ValidationErrorDati non validi (422), codice fiscale non validofields, isDuplicate
CensusInProgressErrorCensimento già in corso (PENDING_CENSIMENTO)
ServiceUnavailableErrorSister fermo, in manutenzione o sovraccarico
RateLimitErrorTroppe richieste (429)retryAfterSeconds
PartnerPricingRequiredErrorTipo di ricerca non abilitato sul tuo accountscannerType
AuthenticationError / PermissionError / NotFoundError401 / 403 / 404
ScanFailedErrorRicerca finita in ERROR o CANCELLEDrequest
TimeoutError / AbortError / NetworkErrorTempo scaduto, annullata, rete giù
js
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 ​

js
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.

js
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):

js
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:

bash
DOKICASA_TOKEN=<token sandbox> npx -p @dokicasa/sdk dokicasa-sdk-demo
PaginaCosa 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_ALLOWED altrimenti).