API e MCP

Tre modi per collegarti

URL base: https://app.crmai.it. Tutte le richieste e le risposte sono JSON.

MCP

Endpoint: https://app.crmai.it/api/mcp (Streamable HTTP). Lo trovi già pronto da copiare in Impostazioni → Accesso AI (MCP).

Con OAuth: claude.ai, ChatGPT, Cursor

1. Nel client, aggiungi un connettore personalizzato e incolla l’URL.
2. Premi Connetti e accedi con il tuo account CrmAI.
3. Conferma con Autorizza. Il client opera con il tuo ruolo, nel tuo workspace.

Con token: Claude Code, Claude Desktop, agenti tuoi

Genera un token personale (vedi Token) e passalo come header Authorization: Bearer crmmcp_….

claude mcp add crmai "https://app.crmai.it/api/mcp?toolset=core" \
  --transport http \
  -H "Authorization: Bearer crmmcp_..." -s user

Toolset

Ogni tool pesa sul contesto dell’agente. Con ?toolset= scegli cosa caricare; i tool esclusi restano raggiungibili con find_crm_tools e call_crm_tool, senza ricollegarti.

• core: circa 30 tool di uso quotidiano (deal, contatti, aziende, attività, briefing). Consigliato.
• outreach: core + sequenze, inbox, WhatsApp, liste, prenotazioni, campagne.
• quotes: core + preventivi, listini, storico acquisti, fatturazione.
• admin: core + configurazione, import, merge, audit, memoria.
• all: tutto (default). Si combinano: ?toolset=outreach,quotes.

Per regole, esempi e formati di un tool l’agente chiama get_tool_guide: le descrizioni restano corte, la guida arriva solo quando serve.

Da MCP le scritture partono subito, senza conferma in UI. Il controllo sta altrove: ogni client rispetta ruolo e verticali del membro che si è collegato, e ogni modifica finisce nel registro con stato prima/dopo, annullabile.

Token

I token crmmcp_… si generano in Impostazioni → Controllo accessi → Token MCP (serve il ruolo owner o admin). Uno per membro: chi usa il token agisce con il ruolo e le verticali di quel membro, e nel registro compare il suo nome. Lo revochi in un clic e smette di funzionare subito.

Lo stesso token vale per MCP, webhook lead caldo e ingest conversazioni. Trattalo come una password: mai in codice lato browser.

Form lead sul tuo sito

Crea il form in Impostazioni → Form embeddabili: scegli campi, testo del consenso, lista e sequenza in cui far entrare il lead. Poi hai due strade.

Embed: due righe

<div data-crmai-form="FORM_ID"></div>
<script src="https://app.crmai.it/embed/form.js" async></script>

Il tuo form, la nostra API

POST /api/public/lead-forms/:id/submit. CORS aperto: si chiama direttamente dal browser.

curl -X POST https://app.crmai.it/api/public/lead-forms/FORM_ID/submit \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Giulia Rossi",
    "email": "giulia@studiorossi.it",
    "company": "Studio Rossi",
    "message": "Vorrei una demo",
    "consent": true,
    "attribution": { "utmSource": "linkedin", "utmCampaign": "autunno" }
  }'

{ "ok": true, "contactId": "…", "eventId": "…", "successMessage": "Grazie!" }

• consent: true è obbligatorio, e serve almeno email o phone.
• Campi opzionali: name, company, role, message; attribution accetta UTM, fbclid, fbp, fbc, referrer, landingUrl.
• Il lead diventa un contatto con fonte e consenso tracciati, ed entra nella lista e nella sequenza del form.
• Se sul form hai collegato il Pixel Meta, l’evento Lead parte anche lato server con lo stesso eventId, senza doppi conteggi.
• Limiti: 20 invii al minuto per IP, 60 al minuto per form.

Webhook lead caldo

Qualcuno ha scaricato una guida o compilato un form su un altro strumento? POST /api/webhooks/hot-lead crea il contatto (se non c’è) e una chiamata con priorità massima in cima alla giornata.

curl -X POST https://app.crmai.it/api/webhooks/hot-lead \
  -H "Authorization: Bearer crmmcp_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f1c…" \
  -d '{
    "prospectEmail": "marco@azienda.it",
    "prospectName": "Marco Bianchi",
    "prospectCompany": "Azienda Srl",
    "contentName": "Guida al preventivo perfetto",
    "contentType": "guida",
    "dueInHours": 4
  }'

• Obbligatori: contentName e uno tra prospectEmail o contactId.
• dueInHours: entro quando chiamare (default 24, massimo 720).
• Senza Idempotency-Key, lo stesso lead sullo stesso contenuto nella stessa ora non viene duplicato.

Ingest conversazioni

Porta in Inbox thread da email, LinkedIn o WhatsApp gestiti fuori da CrmAI. POST /api/conversations/ingest aggancia il contatto (per email, poi nome e azienda) e ferma le sequenze di chi ha risposto.

curl -X POST https://app.crmai.it/api/conversations/ingest \
  -H "Authorization: Bearer crmmcp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "externalThreadId": "393401234567",
    "participant": { "name": "Laura Verdi", "company": "Verdi & C." },
    "messages": [{
      "externalMessageId": "wamid.HBg…",
      "direction": "inbound",
      "body": "Ci vediamo giovedì per il preventivo?",
      "sentAt": "2026-10-08T09:12:00Z"
    }]
  }'

• channel: email, linkedin o whatsapp. Fino a 200 messaggi per chiamata.
• Idempotente: lo stesso externalMessageId non entra due volte, quindi puoi rimandare tutto il thread.
• Risposta: conversationId, contactId, messaggi inseriti e scartati come duplicati.

Prenotazioni

Ogni link di prenotazione ha una pagina pronta su https://app.crmai.it/b/:slug. Se vuoi il calendario dentro il tuo sito, usi le stesse due chiamate della pagina.

GET https://app.crmai.it/api/public/booking/SLUG/slots?from=2026-10-12&to=2026-10-18&tz=Europe/Rome

curl -X POST https://app.crmai.it/api/public/booking/SLUG/book \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2026-10-14T08:00:00.000Z",
    "name": "Paolo Neri",
    "email": "paolo@neri.it",
    "timezone": "Europe/Rome",
    "consent": true
  }'

• Gli slot tengono conto del tuo Google Calendar. Massimo 14 giorni per richiesta.
• La prenotazione crea contatto, evento con link Meet ed email di conferma; la risposta include manageUrl per spostare o cancellare.
• answers porta le risposte alle domande del link, se ne hai impostate.

Integrazioni native

Già collegate, senza scrivere codice:

Convenzioni

• Idempotenza: gli endpoint che scrivono accettano Idempotency-Key. Un retry con la stessa chiave restituisce la stessa risposta, senza duplicati.
• Errori: codice HTTP più un corpo JSON. Sui 400, data dice quali campi non vanno.
• Limiti: superata la soglia ricevi 429; dove presente, data.retryAfter dice quando riprovare.
• Anti-bot: form e prenotazioni hanno un campo trappola website. Lascialo vuoto o non inviarlo.

{ "statusCode": 400, "statusMessage": "Payload non valido", "data": { "fieldErrors": { … } } }