# Dokicasa Property report — Integration instructions for AI assistants

You are an assistant integrating the Dokicasa **Property report** API: from cadastral references
alone it returns a property's data, split into groups with different prices. Full documentation:
https://docs.dokicasa.it/en/report-immobile

## Rules

- Call: `POST https://api.dokicasa.it/api/property-report` with `Authorization: Bearer <api_token>`.
- Required: `comune` (cadastral code, or name with `provincia`), `foglio`, `particella`, `gruppi`,
  `webhook_url` (public https). Optional: `subalterno`, `sezione_urbana`, `sezione`, `catasto`
  (`F`/`T`), `reference`.
- Groups: `dati`, `mappa`, `intestatari`, `documenti`, `valutazione`, `comparabili`, `propensione`, `storia`.
- The call returns `202` with `report_id`: the result comes by webhook. Don't poll tightly:
  `GET /api/property-report/{id}` is for reading a report again, and while `PROCESSING` its `output`
  is `null`.
- Verify the webhook with the `Signature` header: HMAC-SHA256 of the raw body with the `api_token`.
  Compute it on the raw body, not on re-encoded JSON.
- The webhook endpoint must return `2xx` within 3 seconds: store the body and process it later.
  There are up to 3 attempts, so handle duplicates with `report_id`.
- Handle every report status: `READY`, `PARTIAL`, `NOT_AVAILABLE`, `SUBALTERNO_REQUIRED` (repeat,
  choosing from `output.units`), `MULTIPLE_MATCHES` (repeat with `sezione_urbana` chosen from
  `output.alternatives`), `PROPERTY_NOT_FOUND`, `SEARCH_FAILED` (retry later).
- Read each group from `output.groups.<group>` and check its `status`: `READY`, `EMPTY`, `FAILED`.
  `PARTIAL` is a normal outcome, not an error.
- The charge is the sum of `READY` groups. Request only the groups you really need.
- Errors to handle: `400 AMOUNT_NOT_ENOUGH`, `403 GROUP_NOT_ENABLED`, `422` (validation), `429`.
- There is no sandbox: don't run test calls without asking the person guiding you.
- `intestatari` holds personal data: don't log it and don't keep it longer than needed.
- Links in `documenti` are downloaded with the same `Authorization: Bearer <api_token>`.
