# Dokicasa Market Scanner — Istruzioni di integrazione per assistenti AI

Sei un assistente che integra le **API Market Scanner di Dokicasa** (visure,
ispezioni, note, mappe catastali, ricerca da indirizzo). Segui queste istruzioni.

## Contesto

- **Base URL:** `https://api.dokicasa.it`
- **Auth:** header `Authorization: Bearer <api_token>` su ogni chiamata.
- **Le API sono ASINCRONE:** crei una richiesta, ricevi uno `scanner_request_id`,
  poi attendi l'esito (WebSocket o webhook; il polling è l'ultima opzione).
- **Content-Type:** `application/json`.

## Vincoli (non negoziabili)

1. Non esporre mai l'`api_token` nel frontend o in repository pubblici.
2. Preferisci **WebSocket** (app frontend) o **webhook** (backend) al polling.
   Se proprio devi pollare: intervallo minimo 3s, backoff esponenziale, stop a
   `SUCCESS`/`ERROR`, timeout sensato (es. 5 min).
3. Per i PDF (visura/ispezione/nota/mappa) il file è già nella risposta di
   `GET /api/scanner-request/{id}` — non chiamare `/results`.
4. Gli errori transient vengono ritentati lato Dokicasa ogni ~5 min: non reinviare.
   Il credito è scalato solo al primo esito positivo.

## Endpoint principali

| Metodo | Path | Uso |
|---|---|---|
| `POST` | `/api/scanner/{type}` | Crea richiesta → ritorna `scanner_request_id`, stato `ENQUEUED` |
| `GET`  | `/api/scanner-request/{id}` | Stato + risultato finale (PDF e list-addresses qui) |
| `GET`  | `/api/scanner-request/{id}/results` | Risultati strutturati (es. immobili) |
| WS     | `private-scanner_request.{id}` | Aggiornamenti realtime |

Stati: `ENQUEUED` → `SCANNING` → `SUCCESS` | `ERROR`.

## Flusso consigliato (3 step)

1. **Crea** la richiesta con `POST /api/scanner/{type}` (aggiungi `callback` per il
   webhook, oppure iscriviti al canale WS `private-scanner_request.{id}`).
2. **Attendi** lo stato `SUCCESS` via WebSocket o webhook.
3. **Recupera** il risultato: PDF → `GET /api/scanner-request/{id}`; ricerche
   strutturate → `GET /api/scanner-request/{id}/results`.

## WebSocket (Pusher/Reverb)

```js
import Pusher from 'pusher-js'
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 } },
})
const ch = pusher.subscribe(`private-scanner_request.${id}`)
ch.bind('ScannerRequestNotification', ({ message }) => {
  if (message.status === 'SUCCESS') fetchResult(id)
})
```

## Webhook (server-to-server)

Aggiungi `"callback": "https://tuo-server.com/scanner-done"` al body del POST.
A fine elaborazione ricevi un POST con `id`, `status` finale e i dati.
**Idempotenza:** identifica la richiesta dall'`id` e rispondi sempre `2xx`,
anche sui duplicati.

## Ricerca da indirizzo (2 fasi)

1. `POST /api/scanner/list-addresses` → la lista normalizzata è nel campo
   `results` di `GET /api/scanner-request/{id}`.
2. Usa un indirizzo come `address_value` nella chiamata immobili, poi
   `GET /api/scanner-request/{id}/results`.

## Checklist finale

- [ ] Token in variabile d'ambiente, mai nel client.
- [ ] WebSocket o webhook implementati (no polling se evitabile).
- [ ] Gestione esplicita dello stato `ERROR` (leggi il messaggio).
- [ ] Per i PDF leggo direttamente `GET /api/scanner-request/{id}`.
- [ ] Documentazione di riferimento: https://api.dokicasa.it/api-doc/ (sezione Scanner).