# Dokicasa Report immobile — Istruzioni di integrazione per assistenti AI

Sei un assistente che integra l'API **Report immobile** di Dokicasa: dai soli dati catastali
restituisce i dati di un immobile, divisi in gruppi con prezzi diversi. Documentazione completa:
https://docs.dokicasa.it/report-immobile

## Regole

- Chiamata: `POST https://api.dokicasa.it/api/property-report` con `Authorization: Bearer <api_token>`.
- Obbligatori: `comune` (codice catastale, oppure nome con `provincia`), `foglio`, `particella`,
  `gruppi`, `webhook_url` (https pubblico). Facoltativi: `subalterno`, `sezione_urbana`, `sezione`,
  `catasto` (`F`/`T`), `reference`.
- Gruppi: `dati`, `mappa`, `intestatari`, `documenti`, `valutazione`, `comparabili`, `propensione`, `storia`.
- La chiamata risponde `202` con `report_id`: il risultato arriva via webhook. Non fare polling
  stretto: `GET /api/property-report/{id}` serve a rileggere un report, e finche' e' `PROCESSING`
  ha `output` a `null`.
- Il webhook va verificato con l'header `Signature`: HMAC-SHA256 del body grezzo con l'`api_token`.
  Calcolalo sul body grezzo, non su un JSON reinterpretato.
- L'endpoint del webhook deve rispondere `2xx` entro 3 secondi: salva il body e lavoralo dopo.
  Ci sono fino a 3 tentativi, quindi gestisci i doppioni con `report_id`.
- Gestisci tutti gli stati del report: `READY`, `PARTIAL`, `NOT_AVAILABLE`, `SUBALTERNO_REQUIRED`
  (ripeti scegliendo da `output.units`), `MULTIPLE_MATCHES` (ripeti con `sezione_urbana` scelta da
  `output.alternatives`), `PROPERTY_NOT_FOUND`, `SEARCH_FAILED` (riprova piu' tardi).
- Leggi ogni gruppo da `output.groups.<gruppo>` e controlla il suo `status`: `READY`, `EMPTY`, `FAILED`.
  `PARTIAL` e' un esito normale, non un errore.
- Si paga la somma dei gruppi `READY`. Chiedi solo i gruppi che servono davvero.
- Errori da gestire: `400 AMOUNT_NOT_ENOUGH`, `403 GROUP_NOT_ENABLED`, `422` (validazione), `429`.
- Non c'e' sandbox: non lanciare chiamate di prova senza chiederlo a chi ti sta guidando.
- `intestatari` contiene dati personali: non loggarli e non salvarli piu' del necessario.
- I link in `documenti` si scaricano con lo stesso `Authorization: Bearer <api_token>`.
