API, webhook e MCP di Tilly

tly_7_Q2hpYXZlIGRpIGVzZW1waW8sIG5vbiB2YWxlIG5pZW50ZQ

curl https://tilly.omegasuite.it/api/v1/me -H "Authorization: Bearer tly_…"

{ "error": { "code": "invalid", "message": "Campo «assignee_id»: operatore non trovato o disattivato (vedi GET /agents).", "details": [...] } }

{
  "data": {
    "id": 1042,
    "url": "https://tilly.omegasuite.it/app/tickets/1042",
    "subject": "La fattura di settembre non torna",
    "status": "open",
    "status_id": 2,
    "status_label": "Aperto",
    "priority": "high",
    "type": "question",
    "channel": "email",
    "requester": { "id": 87, "name": "Marta Rinaldi", "email": "marta@esempio.it", "phone": null },
    "assignee": { "id": 3, "name": "Luca Bassi", "email": "luca@tuaazienda.it" },
    "group": { "id": 1, "name": "Amministrazione" },
    "organization": { "id": 12, "name": "Rinaldi Srl" },
    "brand_id": 1,
    "form_id": 1,
    "tags": ["fatture", "urgente"],
    "fields": { "numero_ordine": "A-5531" },
    "preview": "Buongiorno, nella fattura di settembre…",
    "satisfaction": null,
    "created_at": "2026-10-14T08:12:40.118Z",
    "updated_at": "2026-10-14T09:30:02.551Z",
    "last_public_at": "2026-10-14T09:30:02.551Z",
    "due_at": null,
    "solved_at": null,
    "closed_at": null,
    "first_reply_at": "2026-10-14T09:30:02.551Z",
    "follower_ids": [],
    "cc": [],
    "problem_id": null,
    "merged_into_id": null,
    "comments": [
      {
        "id": 5120,
        "ticket_id": 1042,
        "public": true,
        "author": { "type": "customer", "id": 87, "name": "Marta Rinaldi" },
        "html": "<p>Buongiorno, nella fattura di settembre…</p>",
        "text": "Buongiorno, nella fattura di settembre…",
        "via": "email",
        "attachments": [
          { "id": 77, "name": "fattura.pdf", "size": 48211, "content_type": "application/pdf",
            "url": "https://tilly.omegasuite.it/api/v1/attachments/77" }
        ],
        "created_at": "2026-10-14T08:12:40.118Z"
      }
    ]
  }
}

# Le chiavi si creano in Amministrazione → App e integrazioni → API e chiavi
export TILLY_KEY="tly_…"

# I ticket aperti, 25 alla volta
curl "https://tilly.omegasuite.it/api/v1/tickets?status=open,pending" \
  -H "Authorization: Bearer $TILLY_KEY"

# Un ticket nuovo a nome di un cliente (lo crea se non c'è)
curl -X POST "https://tilly.omegasuite.it/api/v1/tickets" \
  -H "Authorization: Bearer $TILLY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ordine-A-5531" \
  -d '{
    "subject": "Reso dell’ordine A-5531",
    "requester": { "email": "marta@esempio.it", "name": "Marta Rinaldi" },
    "comment": { "body": "Il pacco è arrivato danneggiato." },
    "priority": "high",
    "tags": ["reso"]
  }'

# Rispondere al cliente e mettere il ticket in attesa
curl -X PATCH "https://tilly.omegasuite.it/api/v1/tickets/1042" \
  -H "Authorization: Bearer $TILLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "comment": { "body": "Le mando l’etichetta per il reso.", "public": true }, "status": "pending" }'

// Node.js 18 o più recente (fetch è già dentro)
const API = 'https://tilly.omegasuite.it/api/v1';
const headers = { Authorization: `Bearer ${process.env.TILLY_KEY}`, 'Content-Type': 'application/json' };

// Tutti i ticket cambiati da ieri, pagina dopo pagina
async function ticketCambiati(dal) {
  const tutti = [];
  let cursor = null;
  do {
    const q = new URLSearchParams({ sort: 'updated_asc', updated_after: dal, limit: '100' });
    if (cursor) q.set('cursor', cursor);
    const r = await fetch(`${API}/tickets?${q}`, { headers });
    if (r.status === 429) { await new Promise((ok) => setTimeout(ok, Number(r.headers.get('retry-after')) * 1000)); continue; }
    if (!r.ok) throw new Error((await r.json()).error.message);
    const pagina = await r.json();
    tutti.push(...pagina.data);
    cursor = pagina.next_cursor;
  } while (cursor);
  return tutti;
}

// Una nota interna su un ticket
await fetch(`${API}/tickets/1042/comments`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ body: 'Rimborso approvato dal magazzino.', public: false }),
});

# Python 3 con requests (pip install requests)
import os, requests

API = "https://tilly.omegasuite.it/api/v1"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['TILLY_KEY']}"

# Cerca un cliente per email e i suoi ticket
c = s.get(f"{API}/customers", params={"email": "marta@esempio.it"}).json()["data"]
if c:
    t = s.get(f"{API}/customers/{c[0]['id']}/tickets", params={"limit": 50}).json()
    for ticket in t["data"]:
        print(ticket["id"], ticket["status"], ticket["subject"])

# Risolvi un ticket
r = s.patch(f"{API}/tickets/1042", json={"status": "solved"})
if r.status_code == 422:
    print("Non si può ancora:", r.json()["error"]["message"])

POST /il-tuo-indirizzo HTTP/1.1
Content-Type: application/json
User-Agent: Tilly-Webhook/1.0
Tilly-Event: comment.created
Tilly-Event-Id: evt_Ab3dEf8hIj0kLm2n
Tilly-Delivery: 3381
Tilly-Attempt: 1
Tilly-Signature: t=1792138202,v1=5f0c4e…(64 caratteri esadecimali)

{
  "id": "evt_Ab3dEf8hIj0kLm2n",
  "type": "comment.created",
  "created_at": "2026-10-14T09:30:02.700Z",
  "account": { "id": 7, "name": "Assistenza Rinaldi" },
  "actor": { "type": "agent", "name": "Luca Bassi" },
  "data": {
    "ticket": { "id": 1042, "subject": "La fattura di settembre non torna", "status": "pending", … },
    "comment": { "id": 5121, "public": true, "text": "Le mando la nota di credito.", … }
  }
}

import crypto from 'node:crypto';
import express from 'express';

const app = express();
// Il corpo serve COSÌ COM'È ARRIVATO: rifatto da JSON.parse non torna più.
app.post('/webhook/tilly', express.text({ type: 'application/json' }), (req, res) => {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(req.get('tilly-signature') ?? '');
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return res.sendStatus(400);
  const atteso = crypto.createHmac('sha256', process.env.TILLY_WEBHOOK_SECRET)
    .update(`${m[1]}.${req.body}`).digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(m[2], 'hex'), Buffer.from(atteso, 'hex'))) return res.sendStatus(400);

  const evento = JSON.parse(req.body);
  // Lo stesso evento può arrivare due volte (un ritentativo dopo un tempo scaduto):
  // tieni da parte evento.id e salta quelli già visti.
  res.sendStatus(200); // rispondi subito, lavora dopo
});

import hmac, hashlib, time

def firma_valida(corpo: bytes, intestazione: str, segreto: str) -> bool:
    try:
        parti = dict(p.split("=", 1) for p in intestazione.split(","))
        t, v1 = parti["t"], parti["v1"]
    except (ValueError, KeyError):
        return False
    if abs(time.time() - int(t)) > 300:
        return False
    atteso = hmac.new(segreto.encode(), f"{t}.".encode() + corpo, hashlib.sha256).hexdigest()
    return hmac.compare_digest(atteso, v1)

<?php
$corpo = file_get_contents('php://input');
$intestazione = $_SERVER['HTTP_TILLY_SIGNATURE'] ?? '';
if (!preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $intestazione, $m) || abs(time() - (int)$m[1]) > 300) {
  http_response_code(400); exit;
}
$atteso = hash_hmac('sha256', $m[1] . '.' . $corpo, getenv('TILLY_WEBHOOK_SECRET'));
if (!hash_equals($atteso, $m[2])) { http_response_code(400); exit; }
$evento = json_decode($corpo, true);
http_response_code(200);

# Claude Code
claude mcp add --transport http tilly https://tilly.omegasuite.it/api/mcp \
  --header "Authorization: Bearer tly_…"

# Cursor (~/.cursor/mcp.json) e altri client con trasporto HTTP
{
  "mcpServers": {
    "tilly": {
      "url": "https://tilly.omegasuite.it/api/mcp",
      "headers": { "Authorization": "Bearer tly_…" }
    }
  }
}

# Claude Desktop (claude_desktop_config.json), con il ponte mcp-remote
{
  "mcpServers": {
    "tilly": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://tilly.omegasuite.it/api/mcp", "--header", "Authorization: Bearer tly_…"]
    }
  }
}