namai — API pubbliche per sviluppatori

Questa documentazione descrive le API di namai pensate per essere usate da sistemi esterni: feed di immobili, siti web personalizzati (headless) e link di condivisione. Non descrive le API interne usate dall'app di gestione (/v1/biz/*), che richiedono una sessione utente con Google Authenticator e non sono un'interfaccia per terze parti.

Le superfici disponibili

Superficie	A cosa serve	Autenticazione	Documento
`GET /cus/property`	Feed JSON degli immobili in vendita/affitto con foto	API key (Bearer)	feed-immobili.md
`/site/*`	Dati del sito vetrina di un'agenzia: configurazione, immobili, eventi, form contatti	Nessuna: l'agenzia si riconosce dall'host	sito-vetrina.md
`/v1/share/:token/*`	Lettura di una brochure, valutazione o report tramite link firmato	Token firmato nell'URL	link-condivisione.md

Valgono per tutte le convenzioni (formato degli errori, paginazione, date, lingue) e le regole di autenticazione.

Provare le API

Il feed (/cus/*) si può provare dal browser su api.namai.it/docs/api: premi Authorize, incolla la tua API key, apri una rotta e premi Try it out, poi Execute. Le chiamate sono vere: rispondono con i dati della tua agenzia.

Indirizzi

Ambiente	Indirizzo	Per cosa
Produzione, API	`https://api.namai.it`	Feed (`/cus/`, `/biz/feed/`) e link di condivisione (`/v1/share/*`)
Produzione, siti	`https://<sottodominio>.namai.it` oppure il dominio dell'agenzia	`/site/*`, `/robots.txt`, `/sitemap.xml`
Sviluppo	`http://localhost:3002` (porta predefinita, variabile `PORT`)	Tutto; i siti si risolvono con l'header `Host`

Le rotte /site/* rispondono solo sull'host del sito dell'agenzia: lo stesso percorso su api.namai.it risponde 404.

Avvio rapido

Elenco degli immobili con la tua API key:

curl -s https://api.namai.it/cus/property \
  -H "Authorization: Bearer <API_KEY>"

Primi 12 immobili del sito di un'agenzia, ordinati per prezzo crescente:

curl -s "https://demo.namai.it/site/properties?sort=price_asc&limit=12&lang=it"

Risposta (abbreviata):

{
  "rows": [
    {
      "id": 41,
      "code": "VE-0041",
      "price": 245000,
      "priceOnRequest": false,
      "squareMeters": 96,
      "city": "058091",
      "dscity": "Roma",
      "images": ["/site/image/property/318"],
      "slug": "trilocale-roma-41",
      "offerStatus": null
    }
  ],
  "total": 37
}

Cosa non c'è

Nessun webhook in uscita. namai non notifica i sistemi esterni: i feed si leggono a intervalli (pull).
Nessuna scrittura tramite API key. Le API key permettono solo di leggere i feed. Gli unici punti di scrittura pubblici sono il form contatti e le prenotazioni degli eventi del sito, protetti da anti-spam.
Nessun portale self-service per le chiavi. Vedi autenticazione.
Swagger. Le rotte /site/* sono escluse dal documento OpenAPI; per quelle vale questa documentazione. Il feed è provabile in produzione su /docs/api; i link di condivisione compaiono solo nel documento completo /docs/v1, acceso negli ambienti di sviluppo.