Integrazione Market Scanner

✦

Integra con un assistente AI

Scarica o copia il prompt di integrazione per Market Scanner e incollalo in Claude Code, Cursor o Copilot: contiene auth, esempi end-to-end e checklist.

Apri

Le API dello Scanner di Dokicasa permettono di ottenere visure, ispezioni, note, mappe catastali e ricerche da indirizzo. Sono asincrone: questa guida ti mostra come riceverne i risultati nel modo più efficiente, evitando il polling quando possibile.

Base URL	https://api.dokicasa.it
Auth	Authorization: Bearer <api_token>
Content-Type	application/json

Documentazione e autenticazione

La documentazione interattiva di tutti gli endpoint è su Swagger: api.dokicasa.it/api-doc/ → sezione Scanner (ricerche, polling, recupero risultati).

Tutte le chiamate vanno autenticate con un Bearer token:

Authorization: Bearer YOUR_API_TOKEN

WARNING

Il token non deve mai finire in repo pubblici o sul frontend: trattalo come una password.

Endpoint principali

Tabella riassuntiva — lo schema completo è su Swagger.

Metodo	Path	Cosa fa
POST	/api/scanner/{type}	Crea una richiesta scanner (visura / ispezione / mappa / list-addresses / …). Ritorna scanner_request_id.
GET	/api/scanner-request/{id}	Stato richiesta + risultato finale (per PDF e list-addresses il payload è già qui).
GET	/api/scanner-request/{id}/results	Risultati strutturati per le ricerche "normali" (es. immobili da indirizzo).
WS	private-scanner_request.{id}	Canale WebSocket privato per gli aggiornamenti realtime.

Stati della richiesta

ENQUEUED  →  SCANNING  →  SUCCESS
                       ╲→  ERROR

ENQUEUED e SCANNING sono transitori; SUCCESS ed ERROR sono finali.

Come funziona

Tutte le chiamate scanner sono asincrone. Il flusso è sempre lo stesso, cambia solo come ricevi l'aggiornamento di stato.

1. Crei la richiesta — POST /api/scanner/{type} → ricevi uno scanner_request_id e lo stato iniziale ENQUEUED.
2. Attendi il completamento — scegli uno di questi modi (in ordine di preferenza):
   • WebSocket — push istantaneo, nessun polling.
   • Webhook callback — il nostro server chiama il tuo a fine elaborazione.
   • Polling (fallback) — solo se non puoi usare i due sopra.
3. Ottieni il risultato — quando lo stato è SUCCESS:
   • PDF (visure, ispezioni, mappe, note): il file è già nella risposta di GET /api/scanner-request/{id}.
   • Ricerche strutturate: chiama GET /api/scanner-request/{id}/results.

Aggiornamenti realtime via WebSocket

⭐ Consigliato per app frontend

Approccio raccomandato per web/mobile: nessun polling, aggiornamenti istantanei, barre di avanzamento e notifiche in push.

Ogni richiesta pubblica eventi su un canale privato dedicato:

private-scanner_request.{id}

dove {id} è lo scanner_request_id ritornato dal POST iniziale.

Esempio completo (JavaScript + Pusher/Reverb)

import Pusher from 'pusher-js'

const apiToken = 'YOUR_API_TOKEN'

// 1. Client WebSocket (Reverb sul backend, API Pusher sul client)
const pusher = new Pusher('ra9jcihuz0sx7vtw8yut', {
  wsHost: 'socket.dokicasa.it',
  wsPort: 443,
  wssPort: 443,
  forceTLS: false,
  cluster: 'mt1',
  disableStats: true,
  enabledTransports: ['ws', 'wss'],
  authEndpoint: 'https://api.dokicasa.it/broadcasting/auth',
  auth: { headers: { Authorization: 'Bearer ' + apiToken } },
})

// 2. Creo la richiesta scanner
const { scanner_request_id } = await fetch(
  'https://api.dokicasa.it/api/scanner/intestatari-catasto',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + apiToken,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      comune: 'H501', provincia: 'RM',
      foglio: '123', particella: '45',
      search_catasto_type: 'F',
    }),
  }
).then((r) => r.json())

// 3. Mi iscrivo al canale e ascolto gli stati
const channel = pusher.subscribe(`private-scanner_request.${scanner_request_id}`)
channel.bind('ScannerRequestNotification', ({ message }) => {
  const { status, percentage } = message
  if (status === 'SCANNING') updateProgressBar(percentage)
  if (status === 'SUCCESS') fetchResult(scanner_request_id)
  if (status === 'ERROR') handleError(message)
})

async function fetchResult(id) {
  const data = await fetch(`https://api.dokicasa.it/api/scanner-request/${id}`, {
    headers: { Authorization: 'Bearer ' + apiToken },
  }).then((r) => r.json())
  console.log('Risultato finale:', data)
}

✓ Pro: nessun polling, ricezione istantanea, UX migliore. Funziona ovunque ci sia un client WS (web, mobile, server con client Pusher).

Webhook callback (server-to-server)

⭐ Consigliato per integrazioni backend

Passi un URL nella creazione della richiesta: a fine elaborazione, Dokicasa ti POSTa il risultato.

Aggiungi il campo callback al body del POST iniziale:

{
  "comune": "H501",
  "foglio": "123",
  "particella": "45",
  "callback": "https://tuo-server.com/dokicasa/scanner-done"
}

Cosa riceve il tuo endpoint

A fine elaborazione (stato SUCCESS o ERROR), il nostro server fa POST all'URL con:

• l'id della richiesta scanner;
• lo status finale (SUCCESS / ERROR);
• i dati di risultato (intestatari, immobili, PDF processato, metadati, …) quando disponibili.

NOTE

Il webhook è già attivo in produzione: se callback è valorizzato, la chiamata parte in automatico a fine elaborazione — nessuna configurazione nel pannello.

Idempotenza

Il sistema può rinviare il webhook in caso di errori di rete. Identifica la richiesta tramite l'id nel body e rispondi 2xx anche sui duplicati, per evitare retry inutili.

Caso d'uso: ricerca da indirizzo

Hai un indirizzo e vuoi gli immobili al catasto associati. Flusso in 2 fasi: risoluzione indirizzo → immobili.

1. list-addresses (risoluzione indirizzo) — POST /api/scanner/list-addresses. Attendi via socket/webhook/polling. La lista degli indirizzi normalizzati è già nel campo results della risposta di GET /api/scanner-request/{id} — non serve chiamare /results.
2. Immobili da indirizzo — usa un indirizzo del passo 1 come address_value nella chiamata di scanner immobili (endpoint preciso su Swagger, sezione Scanner).
3. Recupero risultati — quando arriva SUCCESS, chiama GET /api/scanner-request/{id}/results per la lista immobili.

Caso d'uso: visure, ispezioni, note, mappe (PDF)

Tutte le richieste che producono un PDF (visura catastale, ispezione, nota, mappa) seguono lo stesso pattern.

1. Crei la richiesta — POST /api/scanner/{type} (il tipo dipende dal documento, vedi Swagger).
2. Attendi il completamento — via WebSocket o webhook: lo stato passa per ENQUEUED → SCANNING fino a SUCCESS o ERROR.
3. Retry automatico su errori transient — se durante l'elaborazione c'è un errore temporaneo (linea con i servizi esterni), il sistema riprova da solo ogni ~5 minuti. Non devi reinviare nulla. Il credito viene scalato solo al primo esito positivo.
4. Ottieni il PDF — il file è restituito direttamente nella risposta di GET /api/scanner-request/{id} (non serve /results). In più il PDF viene inviato automaticamente via email all'indirizzo associato al token, quindi l'utente finale lo riceve comunque anche senza integrare il download lato client.

Polling — solo come ultima opzione

Sconsigliato

Hai due meccanismi push (WebSocket e webhook) che eliminano la necessità di polling. Valutali prima: il polling aumenta latenza e carico server senza vantaggi reali.

Se proprio devi pollare, interroga periodicamente:

GET /api/scanner-request/{id}

Linee guida pratiche:

• Intervallo minimo consigliato: 3 secondi tra una chiamata e l'altra.
• Backoff esponenziale dopo qualche tentativo (es. 3s → 6s → 12s).
• Limite di tentativi sensato (es. 5 minuti totali), poi timeout lato tuo.
• Interrompi appena lo stato è SUCCESS o ERROR.

Risposta tipica:

{ "id": 12345, "status": "SCANNING", "percentage": 42 }

Note operative

• Conserva sempre l'id (scanner_request_id) restituito alla creazione: serve per ogni operazione successiva.
• Gestisci esplicitamente lo stato ERROR: leggi il messaggio per capire la causa.
• Non condividere mai il token API: trattalo come una password.
• In produzione, preferisci webhook o socket al polling.