Report immobile
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 URL | https://api.dokicasa.it |
| Auth | Authorization: Bearer <api_token> |
| Content-Type | application/json |
| Risposta | Asincrona: 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
- Mandi i dati catastali, i gruppi che vuoi e l'URL del tuo webhook.
- Rispondiamo
202con ilreport_ide l'importo stimato. - Cerchiamo l'immobile nei nostri dati. Se manca o non è aggiornato, avviamo una ricerca al catasto sull'intera particella: la ricerca è compresa nel prezzo.
- 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
| Gruppo | Contenuto | Note |
|---|---|---|
dati | Dati catastali, indirizzo, stato dell'unità | |
mappa | Coordinate, Street View, mappa statica | |
intestatari | Intestatari attuali con quote e storico | Dati personali. Avvia una scansione se non ne abbiamo una degli ultimi 90 giorni |
documenti | Documenti già disponibili sull'immobile, con link | Se non ce ne sono il gruppo è EMPTY e non si paga |
valutazione | Stima di mercato, €/m², dati di zona | Può non essere disponibile per alcuni immobili |
comparabili | Compravendite reali vicine, con valutazione | Se non ce ne sono il gruppo è EMPTY e non si paga |
propensione | Propensione a vendita e affitto | |
storia | Analisi degli atti e rating dell'immobile | Il 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
EMPTYoFAILED, 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
chargestrovi importo0e 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
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"
}'| Campo | Obbligatorio | Descrizione |
|---|---|---|
comune | Sì | Codice catastale (F205), oppure il nome insieme a provincia |
provincia | Se comune è un nome | Sigla della provincia |
foglio | Sì | Foglio catastale |
particella | Sì | Particella |
subalterno | No | Fino a 4 cifre. Senza, vedi Particella con più unità |
sezione_urbana | No | Serve dove lo stesso foglio e particella esistono in più sezioni |
sezione | No | Sezione censuaria |
catasto | No | F fabbricati (predefinito) o T terreni |
gruppi | Sì | Uno o più gruppi, senza doppioni |
reference | No | Un tuo riferimento, massimo 120 caratteri. Torna nel webhook |
webhook_url | Sì | URL https pubblico: non sono ammessi indirizzi interni |
Risposta:
{
"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:
{
"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
status | Significato | output | Addebito |
|---|---|---|---|
READY | Tutti i gruppi consegnati | property_id, groups | Gruppi READY |
PARTIAL | Solo alcuni gruppi consegnati | property_id, groups | Gruppi READY |
NOT_AVAILABLE | Immobile trovato, nessun gruppo consegnato | property_id, groups | Nessuno |
SUBALTERNO_REQUIRED | La particella ha più unità | units, units_count, incomplete | Nessuno |
MULTIPLE_MATCHES | Più immobili con questi dati | alternatives | Nessuno |
PROPERTY_NOT_FOUND | Il catasto non lo restituisce | message, a volte units | Nessuno |
SEARCH_FAILED | Ricerca non riuscita: riprova più tardi | message | Nessuno |
Stato di un gruppo
status | Significato | Si paga |
|---|---|---|
READY | Dati in data | Sì |
EMPTY | Nessun dato disponibile | No |
FAILED | Non riuscito: motivo in code e message | No |
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.
{
"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.
{
"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
{
"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.
{
"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.
{
"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
{
"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.
{
"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
{
"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
{
"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
| HTTP | error | Significato |
|---|---|---|
400 | AMOUNT_NOT_ENOUGH | Saldo insufficiente: total_amount e available_amount nella risposta |
401 | Token mancante o non valido | |
403 | GROUP_NOT_ENABLED | Gruppi senza prezzo sul tuo listino, elencati in groups |
404 | NOT_FOUND | Report inesistente o di un altro account |
422 | COMUNE_NOT_FOUND | Codice catastale non riconosciuto |
422 | PROVINCIA_REQUIRED | Comune indicato per nome senza provincia |
422 | PROVINCE_NOT_COVERED | Trento o Bolzano |
422 | WEBHOOK_URL_NOT_ALLOWED | Il webhook punta a un indirizzo non pubblico |
422 | Campi non validi: dettagli in errors | |
429 | Più di 30 chiamate al minuto |