Link di condivisione
Un agente può creare dall'app un link firmato per condividere un documento di un immobile con chi non ha un account: il cliente, il proprietario, un collega esterno. Chi riceve il link legge quel solo documento, senza accedere.
Il link ha la forma:
https://app.namai.it/<lingua>/s/<token>
L'indirizzo mostrato all'utente è una pagina dell'app. Se vuoi costruire una tua pagina, usa le rotte seguenti con lo stesso <token>.
Il token
- È un token firmato che contiene il tipo di documento, l'agenzia, l'immobile e la lingua.
- È l'unica credenziale: chi lo ha può leggere. Non inoltrarlo oltre chi deve vederlo.
- Scade dopo il periodo di validità (30 giorni per impostazione predefinita). La data è mostrata all'agente quando crea il link.
- Non serve alcun cookie né API key.
Tipi di documento (kind): brochure, assessment (valutazione), report (report per il proprietario), sign (cartello da vetrina).
Rotte
Tutte le rotte sono GET su https://api.namai.it/v1/share/<token>/…. Con un token non valido o scaduto rispondono 404 con { "error": "Link non valido o scaduto" }.
| Rotta | Che cosa restituisce | Vale per |
|---|---|---|
/info |
{ "kind": "brochure", "lang": "it" } |
Tutti |
/report |
Statistiche dell'immobile per il proprietario (JSON) | Solo report |
/document-data?lang=it |
Dati strutturati di brochure, valutazione o cartello (JSON) | brochure, assessment, sign |
/photo/<documentId>?w=800 |
Immagine di una foto dell'immobile | brochure, assessment, sign |
/logo?w=400 |
Logo dell'agenzia | brochure, assessment, sign |
/document |
Il documento generato come file (formato indicato da Content-Type) |
brochure, assessment, sign |
Chiamare con un tipo non adatto (ad esempio /report su una brochure) dà 404.
/info
Dice che documento è e in che lingua. Serve a scegliere quale rotta chiamare:
curl -s https://api.namai.it/v1/share/$TOKEN/info
{ "kind": "brochure", "lang": "it" }
/document-data
Restituisce i dati, non il testo già impaginato: etichette, importi e date li compone chi presenta la pagina. Il parametro lang (it, en, es) permette al lettore di cambiare lingua rispetto a quella del link.
Campi principali della risposta:
| Campo | Contenuto |
|---|---|
kind, lang, generatedAt |
Tipo, lingua e momento di generazione |
defaultLayout |
Layout predefinito dell'agenzia: classic, modern o minimal |
agency |
Nome, indirizzo, partita IVA, telefono, email, hasLogo, docColor (colore personalizzato dei documenti o null) |
agent |
Agente di riferimento (nome, telefono, email) o null |
property |
Codice, tipo annuncio, categoria, superficie, prezzo, titolo e descrizione nella lingua scelta, caratteristiche (piano, locali, condizione, classe energetica, riscaldamento, servizi in zona), note |
photos |
Elenco degli id delle foto: ciascuna si scarica con /photo/<id> |
assessment |
Solo valutazione: proprietari, quotazioni OMI, dati catastali, superfici con coefficienti, intervallo di prezzo (total, from, to). null negli altri casi |
qrSvg |
Solo cartello: codice QR in SVG verso la pagina dell'immobile sul sito, o null se il sito non è pubblicato |
L'indirizzo (property.address) compare nella brochure solo se l'agenzia ha scelto di mostrarlo; nella valutazione compare sempre. I valori che provengono dalle tabelle di namai (categoria, riscaldamento, servizi) sono in italiano in ogni lingua.
/report
Statistiche per il proprietario dell'immobile, senza dati personali di terzi (nessun nome di acquirenti o interessati) e senza dati interni come le provvigioni.
| Campo | Contenuto |
|---|---|
generatedAt, period, lang |
Quando è stato generato e il periodo coperto |
agency, agent |
Contatti dell'agenzia e dell'agente |
property |
Codice, indirizzo, tipo annuncio, prezzo, superficie |
stats.daysOnMarket |
Giorni sul mercato |
stats.price |
Prezzo corrente e iniziale, variazione percentuale, numero di riduzioni |
stats.market |
Prezzo al mq dell'immobile e medio di zona, scostamento percentuale |
stats.activities |
Numero di chiamate, messaggi, visite e proposte, e contatti distinti |
stats.proposals |
Miglior proposta, media, scarto dal prezzo richiesto |
stats.interestedSearches |
Ricerche di clienti compatibili con l'immobile |
stats.agenda |
Appuntamenti passati e futuri |
stats.portals |
Per ogni portale: nome, stato, giorni di pubblicazione |
stats.warrant |
Scadenza del mandato, giorni mancanti, esclusiva |
series.activities |
Attività mese per mese |
Immagini
/photo/<documentId> e /logo accettano w (400, 800, 1200, 1920). Rispondono con i byte dell'immagine, ETag e Cache-Control: private, max-age=3600. Con If-None-Match valido rispondono 304. Se il servizio è occupato rispondono 503 con Retry-After: 2: riprova.
/document
Restituisce il documento generato dal modello di documento dell'agenzia; il formato è indicato dall'header Content-Type. Per il cartello (sign) è il modello della brochure. Aggiungi ?download=1 per ottenere Content-Disposition: attachment (scarica) invece di inline (apri nel browser).
Esempio completo
TOKEN="…" # preso dal link ricevuto
BASE=https://api.namai.it/v1/share/$TOKEN
curl -s $BASE/info
curl -s "$BASE/document-data?lang=en" -o brochure.json
curl -s "$BASE/photo/318?w=800" -o foto.jpg
curl -s "$BASE/document?download=1" -o documento
Limiti
Queste rotte non hanno limiti di frequenza dedicati. Memorizza le risposte lato tuo se la pagina è molto visitata.