# Lead Finder

> Strumento interno di Shawe Solutions per trovare, arricchire e convertire potenziali clienti.
> Progettato perché a usarlo siano soprattutto modelli e agenti AI.

## Cos'è

Shawe Solutions vende cinque cose, e Lead Finder serve a trovare chi potrebbe comprarle:

- **Shawe** (`shawe`) — Gestionale prenotazioni per il wellness.
- **Shawe Art** (`shawe_art`) — Gestionale inventario e vendite per chi vende arte.
- **Sito web custom** (`website`) — Progettazione e sviluppo di un sito su misura.
- **Automazioni AI** (`ai_automation`) — Automazione di processi ripetitivi con AI.
- **Soluzioni su misura** (`custom`) — Sviluppo custom fuori dai prodotti standard.

Un *lead* è un'attività commerciale reale. Il lavoro consiste nel capire di cosa ha bisogno,
raccogliere prove, dare un punteggio, produrre qualcosa di concreto e registrare tutto.

## Come si usa

Serve una chiave API, passata come `Authorization: Bearer <chiave>`. La stessa chiave vale
sia per le API REST sia per il server MCP.

- **REST**: `https://ricercatore.shawe.it/api/v1` — schema completo su [https://ricercatore.shawe.it/api/v1/openapi.json](https://ricercatore.shawe.it/api/v1/openapi.json)
- **MCP**: `https://ricercatore.shawe.it/api/mcp` (streamable HTTP) — vedi `docs/mcp.md` nel repository
- **Questa pagina**: chiamando `https://ricercatore.shawe.it/` con una chiave API e `Accept: text/markdown`
  ricevi **un lead diverso ogni volta**, già assegnato a te e lockato per 30 minuti.

## Se hai trovato un'attività nuova

Non controllare prima se esiste: lo fa il sistema. Manda quello che hai e ricevi in risposta
su quale lead è finito e cosa è cambiato.

- una pagina web: `POST /api/v1/ingest/url`, o il tool MCP `ingest_url`
- un PDF (visura, elenco camerale): `POST /api/v1/ingest/file`, o `ingest_file`
- un elenco CSV: `POST /api/v1/ingest/csv`, o `ingest_csv`
- dei campi che hai già in mano: il tool MCP `record_business`

Il confronto è su partita IVA, scheda Google, telefono normalizzato e dominio del sito: se uno
combacia, l'attività viene riconosciuta e aggiornata. Se si somigliano soltanto, il sistema non
fonde: crea la scheda e lascia la coppia da confermare a una persona.

## Il flusso di lavoro

1. Prendi un lead: `POST /api/v1/leads/next`, oppure il tool MCP `claim_next_lead`.
2. Leggi cosa sappiamo già: `GET /api/v1/leads/{id}`.
3. Raccogli quello che manca e registralo: `POST /api/v1/lead-data`.
   **Ogni dato deve avere una fonte e un livello di affidabilità.**
4. Assegna un punteggio con le motivazioni: `POST /api/v1/leads/{id}/score`.
5. Produci qualcosa e registralo: `POST /api/v1/assets`.
6. Aggiorna lo stato: `POST /api/v1/leads/{id}/status`.

## Regole

- Non inventare dati. Se non trovi un'informazione, registra che non l'hai trovata.
- Ogni valore ha una fonte: `GET /api/v1/leads/{id}/field-values` dice chi ha detto cosa e
  perché quel valore è quello mostrato. Guardalo prima di correggere un campo a mano.
- Ogni contenuto prodotto per un lead va registrato, anche se costruito altrove.
- Un punteggio senza motivazioni viene rifiutato.
- Scrivi in italiano tutto ciò che leggerà una persona.

## Formato delle risposte

Ogni endpoint REST risponde con `{ ok, data, error, hints }`.
`error` porta un `code` stabile e un `hint` che dice cosa fare per rimediare.
`hints` suggerisce il passo successivo: sono consigli, non istruzioni.

## Altro

- [/llms-full.txt](https://ricercatore.shawe.it/llms-full.txt) — la versione completa, con tutti i valori ammessi
- [/api/v1/openapi.json](https://ricercatore.shawe.it/api/v1/openapi.json) — lo schema OpenAPI