Limeline · API v1 · 28 ottobre 2026

API Limeline

Con l'API colleghi Limeline al programma di gestione dello studio, a Make, Zapier o a un tuo sistema: leggi e crei ticket, leggi le chiamate, carichi condomini, residenti e fornitori, ricevi un avviso a ogni nuovo ticket. Per domande tecniche: [email protected].

Chiave e indirizzo

La chiave si crea nel portale, in Impostazioni → API e webhook (solo titolare o amministratore). Si vede una volta sola: conservala come una password. Ogni richiesta porta l'intestazione Authorization:

Authorization: Bearer lml_…

Indirizzo base:

https://api.limeline.io/v1

Risposte in JSON, testi in italiano, telefoni nel formato internazionale (+393471234567), date ISO 8601. Al massimo 120 richieste al minuto per chiave. Gli errori hanno la forma {"errore": {"codice": "…", "messaggio": "…"}} con codice HTTP 400, 401, 403, 404, 429 o 500.

curl -H "Authorization: Bearer $LIMELINE_KEY" https://api.limeline.io/v1/studio

Leggere

Richiesta	Cosa restituisce
`GET /studio`	Nome dello studio della chiave: per provare che funziona.
`GET /ticket`	Ticket, dal più recente. Filtri: `stato=aperti`, `chiusi` o uno stato preciso; `aggiornati_dal=2026-10-01T00:00:00Z`.
`GET /ticket/{id}`	Un ticket, per codice (il numero che vede il condòmino, es. `2442`) o per `id`.
`GET /chiamate`	Chiamate con riassunto ed esito, dalla più recente. Filtro: `dal=…`. Registrazioni e trascrizioni restano nel portale.
`GET /condomini`	Condomini dello studio.
`GET /residenti`	Residenti. Filtro: `condominio_id=…`.
`GET /fornitori`	Fornitori.
`GET /eventi?dopo={id}`	Gli stessi eventi dei webhook, per chi preferisce chiedere invece di ricevere. Salva `ultimo_id` e ripassalo come `dopo`.

Gli elenchi sono a pagine: limite (fino a 200, predefinito 50) e pagina (da 1). La risposta è {"dati": […], "pagina": 1, "altre": true}: se altre è true, chiedi la pagina successiva.

Stati di un ticket: da_assegnare, fornitore_avvisato, in_corso, completato, annullato.

{
  "id": 1042, "numero": 42, "codice": "2442", "stato": "fornitore_avvisato",
  "urgente": false, "emergenza": false, "categoria": "idraulico",
  "problema": "Perdita d'acqua in cantina",
  "condominio": { "id": "…", "id_esterno": "C-12", "nome": "Condominio Girasole", "indirizzo": "Via Nizza 112" },
  "scala": "B", "interno": "7",
  "residente": { "id": "…", "id_esterno": "R-881", "nome": "Bianchi Anna", "telefono": "+393331112222" },
  "chiamante": { "nome": "Anna Bianchi", "telefono": "+393331112222" },
  "fornitore": { "id": "…", "id_esterno": "F-3", "nome": "Idraulica Rossi" },
  "creato_il": "2026-10-28T08:12:00Z", "aggiornato_il": "2026-10-28T08:13:10Z", "chiuso_il": null,
  "link": "https://app.limeline.io/ticket/1042"
}

Scrivere: condomini, residenti, fornitori

Per tenere Limeline allineato al tuo programma, invia gli elenchi con il tuo identificativo in id_esterno. Se lo stesso id_esterno arriva di nuovo, aggiorniamo il record invece di crearne un altro. Fino a 1000 elementi per richiesta. Per disattivare un record invia "attivo": false.

POST /condomini
{ "condomini": [
  { "id_esterno": "C-12", "nome": "Condominio Girasole", "indirizzo": "Via Nizza 112", "citta": "Torino", "cap": "10126", "provincia": "TO" }
] }

POST /residenti
{ "residenti": [
  { "id_esterno": "R-881", "condominio_id_esterno": "C-12",
    "cognome": "Bianchi", "nome_proprio": "Anna", "scala": "B", "interno": "7",
    "telefono": "333 111 2222", "email": "[email protected]", "tipo": "proprietario" }
] }

POST /fornitori
{ "fornitori": [
  { "id_esterno": "F-3", "nome": "Idraulica Rossi", "telefono": "011 555 0000", "attivita": "Idraulico" }
] }

Il condominio di un residente si indica con condominio_id_esterno (inviato prima con POST /condomini) oppure con il nostro condominio_id. Il nome si può dare intero in nome oppure separato in cognome e nome_proprio. I telefoni italiani possono arrivare in qualsiasi forma: li convertiamo noi. La risposta elenca i record salvati e quelli scartati con il motivo:

{ "salvati": [ … ], "scarti": [ { "indice": 3, "motivo": "telefono non valido: 12" } ] }

Il fornitore caricato dall'API non riceve ancora interventi: chi avvisare per ogni tipo di guasto si decide nel portale, in Fornitori.

Creare un ticket

Un ticket aperto dal tuo programma (per esempio una segnalazione arrivata per email o allo sportello) segue le stesse regole di quelli dell'assistente: Limeline avvisa il fornitore scelto per quel condominio e quel tipo di guasto, aspetta che accetti e poi segue il lavoro fino alla fine.

POST /ticket
{ "ticket": {
  "id_esterno": "SEG-2026-118",
  "residente_id_esterno": "R-881",
  "problema": "Perdita d'acqua in cantina, vicino ai contatori",
  "categoria": "idraulico",
  "urgente": true
} }

Campo
`problema`	Obbligatorio. Cosa succede, in parole semplici: lo legge il fornitore.
`categoria`	Obbligatorio: `idraulico`, `elettricista`, `ascensore`, `fabbro`, `antennista`, `disinfestazioni`, `pulizie`, `spurghi`, `decoratore`, `cancello`, `muratore`, `altro`, `amministrativo`.
`residente_id_esterno` o `residente_id`	Chi segnala. Il condominio, la scala e l'interno li prendiamo dal residente.
`condominio_id_esterno` o `condominio_id`	Se non c'è un residente: il condominio è obbligatorio.
`id_esterno`	Il tuo identificativo. Se invii di nuovo lo stesso `id_esterno` con la stessa categoria, ricevi il ticket già creato (`"gia_esistente": true`), non un doppione.
`nome`, `telefono`, `scala`, `interno`	Facoltativi: se mancano, dal residente.
`urgente`	`true` per un intervento urgente.
`avvisa_fornitore`	`false` per creare il ticket senza avvisare nessuno: lo assegni poi dal portale. Per `altro` e `amministrativo` il fornitore non viene mai avvisato: se ne occupa l'ufficio.
`note`	Note interne per l'ufficio.

La risposta (codice 201) contiene il ticket, come in GET /ticket/{id}, con id_esterno e "avviso_fornitore": "in_corso" o "no". Lo stato cambia da solo quando il fornitore risponde: seguilo con i webhook o con GET /ticket/{id}.

Webhook

In Impostazioni → API e webhook indichi un indirizzo https:// e gli eventi che ti interessano. A ogni evento Limeline invia una richiesta POST con il ticket o la chiamata completi:

Evento	Quando
`ticket.creato`	Nuovo ticket da una chiamata, da WhatsApp o dall'API.
`ticket.aggiornato`	Cambia lo stato, il fornitore, l'urgenza o la descrizione.
`chiamata.conclusa`	La chiamata è finita ed è pronto il riassunto.

POST https://tuo-indirizzo…
Content-Type: application/json
X-Limeline-Evento: ticket.creato
X-Limeline-Timestamp: 1793180000
X-Limeline-Firma: sha256=5f1c…

{ "id": 3120, "tipo": "ticket.creato", "creato_il": "2026-10-28T08:12:00Z", "dati": { …ticket… } }

Rispondi con un codice 2xx entro 10 secondi. Se non rispondi, riproviamo dopo 1, 5 e 15 minuti, poi dopo 1, 3, 6 e 12 ore. Lo stesso evento può arrivare più di una volta: usa id per riconoscerlo. Il pulsante Prova nel portale invia un evento prova.

Verificare la firma

Quando crei il webhook ricevi un segreto (whsec_…), mostrato una volta sola. La firma è l'HMAC-SHA256 di {timestamp}.{corpo} con il segreto, in esadecimale. Controllala e scarta le richieste più vecchie di 5 minuti:

// Node.js
const crypto = require("crypto");
function firmaValida(req, corpo, segreto) {
  const ts = req.headers["x-limeline-timestamp"];
  const attesa = "sha256=" + crypto.createHmac("sha256", segreto).update(`${ts}.${corpo}`).digest("hex");
  const ricevuta = req.headers["x-limeline-firma"] || "";
  const recente = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  return recente && ricevuta.length === attesa.length &&
    crypto.timingSafeEqual(Buffer.from(ricevuta), Buffer.from(attesa));
}

In arrivo

Cambiare lo stato di un ticket dall'API (annullarlo, chiuderlo).

I dati restano quelli dello studio: la chiave dà accesso solo allo studio che l'ha creata. Revocala dal portale se non serve più.