Skip to content

Report immobile ​

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

Con una sola chiamata ottieni i dati di un immobile partendo dai soli dati catastali. Scegli tu quali gruppi di dati ricevere: ogni gruppo ha il suo prezzo e paghi solo quelli che ti vengono consegnati.

Base URLhttps://api.dokicasa.it
AuthAuthorization: Bearer <api_token>
Content-Typeapplication/json
RispostaAsincrona: 202 subito, risultato via webhook

WARNING

Non c'è una sandbox: ogni chiamata lavora su dati reali, può avviare ricerche al catasto e viene addebitata. Per le prove chiedici di rendere gratuiti i gruppi sul tuo account.

Come funziona ​

  1. Mandi i dati catastali, i gruppi che vuoi e l'URL del tuo webhook.
  2. Rispondiamo 202 con il report_id e l'importo stimato.
  3. Cerchiamo l'immobile nei nostri dati. Se manca o non è aggiornato, avviamo una ricerca al catasto sull'intera particella: la ricerca è compresa nel prezzo.
  4. Raccogliamo i gruppi e ti mandiamo un unico webhook con input e output.

Il tempo dipende dai gruppi: pochi secondi se l'immobile è già nei nostri dati, qualche minuto se serve il catasto, di più con intestatari e storia. Dopo 2 ore consegniamo comunque quello che è pronto: i gruppi mancanti risultano FAILED con codice TIMEOUT e non vengono addebitati.

Gruppi di dati ​

GruppoContenutoNote
datiDati catastali, indirizzo, stato dell'unità
mappaCoordinate, Street View, mappa statica
intestatariIntestatari attuali con quote e storicoDati personali. Avvia una scansione se non ne abbiamo una degli ultimi 90 giorni
documentiDocumenti già disponibili sull'immobile, con linkSe non ce ne sono il gruppo è EMPTY e non si paga
valutazioneStima di mercato, €/m², dati di zonaPuò non essere disponibile per alcuni immobili
comparabiliCompravendite reali vicine, con valutazioneSe non ce ne sono il gruppo è EMPTY e non si paga
propensionePropensione a vendita e affitto
storiaAnalisi degli atti e rating dell'immobileIl gruppo più lento: può richiedere una visura e l'analisi AI

Prezzi e addebito ​

Ogni gruppo ha un prezzo sul tuo listino e il report completo costa la somma dei gruppi scelti. Un gruppo senza prezzo sul listino non è attivo: la chiamata risponde 403 GROUP_NOT_ENABLED. Per attivarli contattaci.

  • Paghi solo i gruppi consegnati con dati (stato READY).
  • Non paghi i gruppi EMPTY o FAILED, l'elenco delle unità, l'immobile non trovato, la ricerca fallita.
  • Lo stesso gruppo sullo stesso immobile non si ripaga per 30 giorni: nel campo charges trovi importo 0 e il report in cui l'hai già pagato.
  • L'addebito avviene a fine report, dal tuo saldo. Prima di partire controlliamo che il saldo copra questo report e quelli ancora in corso: altrimenti 400 AMOUNT_NOT_ENOUGH.

Saldo e movimenti: vedi Crediti / Wallet.

Richiedere un report ​

POST /api/property-report

bash
curl -X POST https://api.dokicasa.it/api/property-report \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "comune": "F205",
    "foglio": "412",
    "particella": "87",
    "subalterno": "3",
    "gruppi": ["dati", "mappa", "valutazione"],
    "reference": "pratica-123",
    "webhook_url": "https://partner.example/hook"
  }'
CampoObbligatorioDescrizione
comuneSìCodice catastale (F205), oppure il nome insieme a provincia
provinciaSe comune è un nomeSigla della provincia
foglioSìFoglio catastale
particellaSìParticella
subalternoNoFino a 4 cifre. Senza, vedi Particella con più unità
sezione_urbanaNoServe dove lo stesso foglio e particella esistono in più sezioni
sezioneNoSezione censuaria
catastoNoF fabbricati (predefinito) o T terreni
gruppiSìUno o più gruppi, senza doppioni
referenceNoUn tuo riferimento, massimo 120 caratteri. Torna nel webhook
webhook_urlSìURL https pubblico: non sono ammessi indirizzi interni

Risposta:

json
{
  "status": "PROCESSING",
  "report_id": 1842,
  "groups": ["dati", "mappa", "valutazione"],
  "estimated_amount": 4.5
}

estimated_amount è la somma dei prezzi dei gruppi: l'importo finale può essere più basso.

Se ripeti la stessa domanda mentre la prima è ancora in corso, ricevi lo stesso report_id e un solo webhook.

NOTE

Non sono coperte le province di Trento e Bolzano, che hanno il catasto tavolare.

Il webhook ​

A fine lavorazione mandiamo un POST al tuo webhook_url:

json
{
  "event": "property_report.completed",
  "report_id": 1842,
  "status": "PARTIAL",
  "reference": "pratica-123",
  "input": {
    "comune": "F205",
    "foglio": "412",
    "particella": "87",
    "subalterno": "3",
    "gruppi": ["dati", "mappa", "valutazione"],
    "reference": "pratica-123"
  },
  "output": {
    "property_id": 4595749,
    "groups": {
      "dati": { "status": "READY", "data": { "categoria": "A/2", "rendita": "500,00", "stato": "ACTIVE" } },
      "mappa": { "status": "READY", "data": { "lat": 45.46, "lng": 9.19 } },
      "valutazione": {
        "status": "FAILED",
        "code": "NOT_AVAILABLE",
        "message": "Valutazione non disponibile per questo immobile. Non addebitata."
      }
    }
  },
  "charges": {
    "total_amount": 2.5,
    "groups": {
      "dati": { "amount": 2 },
      "mappa": { "amount": 0.5 }
    }
  },
  "requested_at": "2026-11-03T10:15:00+01:00",
  "completed_at": "2026-11-03T10:16:12+01:00"
}

Firma e consegna ​

L'header Signature è l'HMAC-SHA256 del body grezzo, firmato con il tuo api_token. È lo stesso meccanismo degli altri webhook: vedi Firma.

Rispondi subito con un 2xx: aspettiamo 3 secondi e facciamo fino a 3 tentativi, il secondo dopo circa 10 secondi e il terzo dopo circa 100. Se il tuo server era giù, il report resta disponibile con il GET.

Stato del report ​

statusSignificatooutputAddebito
READYTutti i gruppi consegnatiproperty_id, groupsGruppi READY
PARTIALSolo alcuni gruppi consegnatiproperty_id, groupsGruppi READY
NOT_AVAILABLEImmobile trovato, nessun gruppo consegnatoproperty_id, groupsNessuno
SUBALTERNO_REQUIREDLa particella ha più unitàunits, units_count, incompleteNessuno
MULTIPLE_MATCHESPiù immobili con questi datialternativesNessuno
PROPERTY_NOT_FOUNDIl catasto non lo restituiscemessage, a volte unitsNessuno
SEARCH_FAILEDRicerca non riuscita: riprova più tardimessageNessuno

Stato di un gruppo ​

statusSignificatoSi paga
READYDati in dataSì
EMPTYNessun dato disponibileNo
FAILEDNon riuscito: motivo in code e messageNo

Codici di FAILED: NOT_AVAILABLE, OWNERS_NOT_FOUND, TIMEOUT.

Particella con più unità ​

Se non indichi il subalterno e la particella ha più unità, ricevi gratis l'elenco e ripeti la chiamata scegliendo quella che ti interessa. Se l'unità è una sola, il report prosegue su quella.

json
{
  "event": "property_report.completed",
  "report_id": 1843,
  "status": "SUBALTERNO_REQUIRED",
  "output": {
    "message": "La particella ha piu' unita': ripetere la chiamata indicando il subalterno.",
    "incomplete": false,
    "units_count": 2,
    "units": [
      { "catasto": "F", "foglio": "412", "particella": "87", "subalterno": "3", "status": "ACTIVE" },
      { "catasto": "F", "foglio": "412", "particella": "87", "subalterno": "4", "status": "SUPPRESSED" }
    ]
  }
}

incomplete: true vuol dire che il catasto non ha restituito tutte le unità: l'elenco può avere un buco. Le unità soppresse restano nell'elenco e si possono richiedere: il gruppo dati riporta "stato": "SUPPRESSED".

Con MULTIPLE_MATCHES ripeti la chiamata indicando sezione_urbana, scegliendola da alternatives.

Contenuto dei gruppi ​

Ogni gruppo sta in output.groups.<gruppo>.data.

dati ​

Vuoti i campi che il catasto non riporta. Per i terreni valgono qualita, ha, are, ca, reddito_dominicale, reddito_agrario.

json
{
  "catasto": "F", "comune": "MILANO", "provincia": "MI", "codice_belfiore": "F205",
  "sezione": null, "sezione_comune": null, "foglio": "412", "particella": "87", "subalterno": "3",
  "categoria": "A/2", "classe": "3", "consistenza": "5 vani", "rendita": "500,00", "partita": "",
  "zona_cens": "2", "indirizzo": "VIA ROMA", "numero_civico": "12", "scala": "A", "piano": "2",
  "interno": "5", "indirizzo_completo": "VIA ROMA N. 12", "stato": "ACTIVE"
}

mappa ​

json
{
  "lat": 45.4642, "lng": 9.19, "geocode_source": "google",
  "street_view_url": "https://...", "static_map_url": "https://..."
}

intestatari ​

Gli intestatari vengono dall'ultima scansione: searched_at dice quando è stata fatta.

json
{
  "owners": [
    {
      "denominazione": null, "nome": "MARIO", "cognome": "ROSSI",
      "codice_fiscale": "RSSMRA80A01F205X", "partita_iva": null,
      "quota": "1/1", "titolarita": "Proprieta'"
    }
  ],
  "searched_at": "2026-10-20 09:12:44",
  "history": [
    { "nome": "MARIO", "cognome": "ROSSI", "codice_fiscale": "RSSMRA80A01F205X", "quota": "1/1", "pivot_created_at": "2026-10-20" }
  ]
}

IMPORTANT

Sono dati personali: puoi trattarli solo se hai una base giuridica per farlo.

documenti ​

Il link url si apre con il tuo token (Authorization: Bearer <api_token>) e vale solo per i documenti consegnati da quel report.

json
{
  "documents": [
    {
      "id": 981233, "name": "Visura catastale", "document_type": "visura", "extra_type": null,
      "url": "https://api.dokicasa.it/api/property-report/1842/documents/981233",
      "created_at": "2026-10-20T09:15:02+02:00"
    }
  ]
}

valutazione ​

json
{
  "valid": true, "price_per_sqm": 2050, "price_per_sqm_estimated": 2100,
  "price_per_sqm_lower": 1800, "price_per_sqm_upper": 2400, "surface_sqm": 90,
  "estimation": {
    "estimated_market_value": 189000, "estimated_value_min_normal": 162000,
    "estimated_value_max_normal": 216000, "confidence_level": null
  },
  "zone": { "nome": "B29", "rischio_sismico": "medio", "zone_quality": 2 },
  "demographics": { "population": {}, "housing_stock": {}, "seismic_risk": "medio" },
  "market_context": { "omi": {}, "price": {}, "transactions": {}, "offer": {}, "buildings": {} }
}

comparabili ​

confidence vale alta, intermedia, bassa o molto bassa; valuation è la stima ricavata dai comparabili.

json
{
  "query": { "latitude": 45.46, "longitude": 9.19, "radius_m": 500, "categories": ["A2"], "years": 3 },
  "zone_stats": {},
  "confidence": "alta",
  "low_confidence": false,
  "comparables_count": 24,
  "evaluated": 24,
  "returned": 8,
  "valuation": {},
  "comparables": []
}

propensione ​

json
{
  "score_sale": 62, "score_rent": 48, "label": "Propenso alla vendita", "confidence": "media",
  "reasons": [], "suggested_action": "...", "blocks_with_data": 4,
  "calculated_at": "2026-11-03T10:15:30+01:00"
}

storia ​

json
{
  "analysis": "Testo dell'analisi",
  "rating": { "codice": "B", "motivo": "...", "parziale": false },
  "atti": [
    {
      "anno": 2015, "mese": "03", "tipo_evento": "...", "descrizione": "...",
      "note_tecniche": "...", "data_efficacia_in_atti": "...", "numero_registro_particolare": "..."
    }
  ],
  "recap_comunale": { "intestatari": [], "titoli_edilizi": [], "variazioni_interne": [] },
  "structured_output": {},
  "immobili_soppressi_collegati": [],
  "codici_fiscali": [],
  "last_refreshed_at": "2026-11-03T10:20:00+01:00",
  "is_stale": false
}

Rileggere un report ​

GET /api/property-report/{id}

Risponde con lo stesso formato del webhook. Finché il report è PROCESSING, output è null: i dati si vedono a report finito. Un report di un altro account risponde 404.

Errori ​

HTTPerrorSignificato
400AMOUNT_NOT_ENOUGHSaldo insufficiente: total_amount e available_amount nella risposta
401Token mancante o non valido
403GROUP_NOT_ENABLEDGruppi senza prezzo sul tuo listino, elencati in groups
404NOT_FOUNDReport inesistente o di un altro account
422COMUNE_NOT_FOUNDCodice catastale non riconosciuto
422PROVINCIA_REQUIREDComune indicato per nome senza provincia
422PROVINCE_NOT_COVEREDTrento o Bolzano
422WEBHOOK_URL_NOT_ALLOWEDIl webhook punta a un indirizzo non pubblico
422Campi non validi: dettagli in errors
429Più di 30 chiamate al minuto