API REST, webhook e server MCP

Specifica di riferimento per sviluppatori e agenti AI. Ogni oggetto del CRM è una risorsa REST, ogni cambiamento è un evento webhook, ogni capacità è anche un tool MCP con gli stessi permessi dell'utente che lo autorizza.

Reference completa openapi.json

01 — Fondamenta

Convenzioni dell'API

Le regole valgono per tutte le risorse: impara una volta, usa ovunque.

Base URLhttps://nido.logicaltech.it/api/v1Tutte le risorse sono sotto /api/v1

AutenticazioneAuthorization: Bearer <token>Chiavi API (server) o OAuth 2.1 + PKCE (app, MCP)

VersionamentoNido-Version: 2026-09-01Versioni datate, breaking change solo in nuove date

Rate limit100 req/10 s per tokenHeader X-RateLimit-Remaining · 429 + Retry-After

Paginazione?limit=50&cursor=eyJvIjo1MH0Risposta: { data, next_cursor, has_more }

Filtri e ordinamento?filter[stage]=proposta&sort=-amountOperatori: eq, ne, gt, gte, lt, lte, in, contains

IdempotenzaIdempotency-Key: <uuid>Su POST/PATCH, valida 24 h

Errori{ error: { type, code, message } }400 · 401 · 403 · 404 · 409 · 422 · 429 · 5xx

curl

curl https://nido.logicaltech.it/api/v1/contacts?limit=2&filter[lifecycle_stage]=customer \
  -H "Authorization: Bearer nido_sk_live_…" \
  -H "Nido-Version: 2026-09-01"

crea-contatto.ts

const res = await fetch("https://nido.logicaltech.it/api/v1/contacts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NIDO_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ email: "[email protected]", first_name: "Anna" }),
})

02 — Endpoint

Risorse e metodi

Ogni endpoint indica lo scope OAuth richiesto. 177 endpoint in 25 gruppi, generati dallo stesso registry che serve l'API. Parametri ed esempi →

Utenti

GET/meUtente, workspace e permessi del token correnteautenticato

Contatti

GET/contactsElenca e filtra contatticontacts:read POST/contactsCrea (deduplica per email)contacts:write GET/contacts/facetsConteggi per fase e città (filtri)contacts:read POST/contacts/scan-cardLeggi un biglietto da visita (AI)contacts:write GET/contacts/duplicatesPossibili duplicaticontacts:read POST/contacts/mergeUnisci duplicaticontacts:write POST/contacts/batchAzioni di massa (owner, fase, tag, cestino)contacts:write GET/contacts/{id}Dettaglio con proprietàcontacts:read PATCH/contacts/{id}Aggiorna proprietàcontacts:write DELETE/contacts/{id}Sposta nel cestino (30 gg)contacts:delete POST/contacts/{id}/restoreRipristina dal cestinocontacts:delete GET/contacts/{id}/timelineAttività, email, noteactivities:read

Aziende

GET/companiesElenca aziendecompanies:read POST/companiesCrea aziendacompanies:write GET/companies/{id}Dettaglio aziendacompanies:read PATCH/companies/{id}Aggiornacompanies:write DELETE/companies/{id}Sposta nel cestino (30 gg)companies:delete GET/companies/{id}/timelineAttività dell'azienda e dei suoi contattiactivities:read

Deal & pipeline

GET/dealsElenca dealdeals:read POST/dealsCrea dealdeals:write GET/deals/summaryTotali per fase e previsione ponderatadeals:read GET/deals/goalAvanzamento obiettivo di venditadeals:read GET/productsCatalogo prodottideals:read GET/deals/{id}Dettaglio con prodotti e contattideals:read PATCH/deals/{id}Aggiorna / cambia fasedeals:write DELETE/deals/{id}Sposta nel cestino (30 gg)deals:delete POST/deals/{id}/wonChiudi come vintodeals:write POST/deals/{id}/lostChiudi come persodeals:write POST/deals/{id}/reopenRiapri deal chiusodeals:write POST/deals/{id}/line-itemsAggiungi prodottideals:write PATCH/deals/{id}/line-items/{item}Aggiorna quantità, prezzo o scontodeals:write DELETE/deals/{id}/line-items/{item}Rimuovi prodottodeals:write GET/deals/{id}/timelineAttività e cronologia del dealactivities:read GET/pipelinesPipeline e fasideals:read POST/pipelinesCrea pipelineschema:write GET/pipelines/{id}Dettaglio pipelinedeals:read PATCH/pipelines/{id}Rinomina o riordina le fasischema:write DELETE/pipelines/{id}Elimina pipeline vuotaschema:write POST/pipelines/{id}/stagesAggiungi faseschema:write PATCH/pipelines/{id}/stages/{stage}Aggiorna fase (nome, probabilità, posizione)schema:write DELETE/pipelines/{id}/stages/{stage}Elimina fase (con move_to se contiene deal)schema:write

Attività

GET/tasksElenca taskactivities:read GET/tasks/statsContatori task (aperti, in ritardo, oggi, chiamate in coda)activities:read POST/tasksCrea taskactivities:write GET/tasks/{id}Dettaglio taskactivities:read PATCH/tasks/{id}Aggiorna o completa taskactivities:write DELETE/tasks/{id}Elimina taskactivities:write POST/notesAggiungi nota a contatto, azienda o dealactivities:write POST/callsRegistra chiamata ed esitoactivities:write GET/calls/queueCoda chiamate di oggiactivities:read GET/meetingsElenca meetingactivities:read POST/meetingsFissa meetingactivities:write GET/meetings/{id}Dettaglio meeting con partecipantiactivities:read PATCH/meetings/{id}Modifica meetingactivities:write DELETE/meetings/{id}Annulla meetingactivities:write

Dashboard

GET/dashboardDati della Home: KPI, pipeline per fase, agenda e taskautenticato

Inbox

GET/email-accountsCaselle email collegate e provider disponibiliemails:read POST/email-accountsCollega una casella (Gmail, Outlook o IMAP/SMTP)emails:send DELETE/email-accounts/{id}Scollega una casellaemails:send POST/email-accounts/{id}/syncSincronizza oraemails:read GET/conversationsConversazioni dell'inbox condivisaemails:read GET/conversations/{id}Dettaglio conversazione con contatto e dealemails:read PATCH/conversations/{id}Assegna, chiudi, posticipa o segna come lettaemails:read GET/conversations/{id}/messagesMessaggi e note interne del threademails:read POST/conversations/{id}/messagesRispondi o aggiungi una nota internaemails:read GET/conversations/{id}/attachments/{attachment_id}Scarica allegatoemails:read POST/emails/sendInvia email tracciataemails:send POST/emails/draftsCrea bozza emailemails:send GET/templatesTemplate di rispostaemails:read POST/templatesCrea templateemails:send GET/templates/{id}Dettaglio templateemails:read PATCH/templates/{id}Modifica templateemails:send DELETE/templates/{id}Elimina templateemails:send POST/templates/{id}/renderCompila le variabili del templateemails:read

Proprietà

GET/properties/{object}Schema proprietàschema:read POST/properties/{object}Crea proprietà personalizzataschema:write PATCH/properties/{object}/{key}Aggiorna proprietàschema:write DELETE/properties/{object}/{key}Elimina proprietà e valorischema:write

Viste

GET/viewsViste salvate per oggettoautenticato POST/viewsCrea vistaautenticato PATCH/views/{id}Aggiorna vistaautenticato DELETE/views/{id}Elimina vistaautenticato

Ricerca

POST/searchRicerca globale full-textautenticato

Utenti e team

GET/usersUtenti e teamusers:read POST/users/invitationsInvita un membrousers:manage DELETE/users/invitations/{id}Annulla invitousers:manage PATCH/users/{id}Cambia ruolousers:manage DELETE/users/{id}Rimuovi dal workspaceusers:manage

Ruoli e permessi

GET/rolesRuoli e matrice permessiusers:read POST/rolesCrea ruolo personalizzatosettings:manage PATCH/roles/{name}Aggiorna permessi del ruolosettings:manage DELETE/roles/{name}Elimina ruolo personalizzatosettings:manage

Import

POST/importsCarica un CSV di contatticontacts:write GET/imports/{id}Stato e progresso dell'importcontacts:read POST/imports/{id}/startAvvia l'import in backgroundcontacts:write

Onboarding

GET/onboarding/statusChecklist «Configura Nido»autenticato PATCH/onboardingSalva settore, dimensione, obiettivi e avanzamento dell'onboardingautenticato

Report

GET/reportsReport predefinitireports:read GET/reports/{id}Esegui un reportreports:read GET/goalsObiettivi di venditareports:read POST/goalsCrea obiettivosettings:manage PATCH/goals/{id}Aggiorna obiettivosettings:manage DELETE/goals/{id}Elimina obiettivosettings:manage

Notifiche

GET/notificationsNotifiche dell'utenteautenticato POST/notifications/readSegna come letteautenticato GET/notifications/preferencesPreferenze notifiche pushautenticato PATCH/notifications/preferencesAggiorna preferenze notifiche pushautenticato

Workflow

GET/workflowsElenca workflowworkflows:read POST/workflowsCrea workflow (anche da modello)workflows:write GET/workflow-templatesModelli di workflowworkflows:read GET/workflows/{id}Dettaglio con trigger, passi e statisticheworkflows:read PATCH/workflows/{id}Aggiorna nome, trigger o passiworkflows:write DELETE/workflows/{id}Elimina workflow e cronologiaworkflows:write POST/workflows/{id}/publishPubblica e attivaworkflows:write POST/workflows/{id}/pauseMetti in pausaworkflows:write POST/workflows/{id}/enrollIscrivi un recordworkflows:write POST/workflows/{id}/testTesta su un record reale (nessun effetto esterno)workflows:write GET/workflows/{id}/runsCronologia esecuzioniworkflows:read GET/workflow-runs/{id}Dettaglio esecuzione con logworkflows:read POST/workflow-runs/{id}/retryRiprova un'esecuzione fallitaworkflows:write

Form

POST/forms/submissionsInvia un form (crea o aggiorna il contatto)contacts:write

Webhook

GET/event-typesCatalogo eventi (webhook e trigger)autenticato GET/eventsRegistro eventi recentiwebhooks:manage GET/webhooksElenca endpointwebhooks:manage POST/webhooksCrea endpoint + secretwebhooks:manage POST/webhooks/testInvia un evento di prova a un URLwebhooks:manage GET/webhooks/{id}Dettaglio endpointwebhooks:manage PATCH/webhooks/{id}Aggiorna, metti in pausa o riattivawebhooks:manage DELETE/webhooks/{id}Elimina endpointwebhooks:manage POST/webhooks/{id}/testInvia evento di provawebhooks:manage POST/webhooks/{id}/rotate-secretRuota il secret di firmawebhooks:manage GET/webhooks/{id}/deliveriesLog consegnewebhooks:manage POST/webhooks/{id}/retry-failedReinvia le consegne fallitewebhooks:manage GET/deliveries/{id}Dettaglio consegna (richiesta, risposta, tentativi)webhooks:manage POST/deliveries/{id}/retryReinvia consegnawebhooks:manage

Chiavi API

GET/api-keysElenca chiavi APIsettings:manage POST/api-keysCrea chiave (mostrata una sola volta)settings:manage DELETE/api-keys/{id}Revoca chiavesettings:manage

Integrazioni

GET/integrationsCatalogo integrazioni e stato di collegamentoautenticato POST/integrations/{slug}/connectCollega (chiave del provider o incoming webhook)settings:manage POST/integrations/{slug}/testVerifica il collegamentosettings:manage DELETE/integrations/{slug}Scollegasettings:manage

Nido AI

GET/ai/settingsImpostazioni AI, stato del provider e utilizzo del meseai:use PATCH/ai/settingsAggiorna modalità, modello, limiti, conferme e policy dei toolai:manage GET/ai/credentialsChiavi AI salvate (mascherate)ai:manage POST/ai/credentialsSalva una chiave propria (verificata e cifrata)ai:manage DELETE/ai/credentials/{id}Elimina una chiave o scollega ChatGPTai:manage GET/ai/modelsModelli disponibili per la modalità attivaai:manage GET/ai/actionsAudit log AI (chiamate, tool, conferme)ai:use GET/ai/actions/statsAzioni AI del mese e richieste in attesaai:use GET/ai/actions/{id}Dettaglio di un'azione AIai:use POST/ai/actions/{id}/confirmApprova ed esegue una scrittura in attesa di confermaai:use POST/ai/actions/{id}/rejectRifiuta una scrittura in attesa di confermaai:use GET/ai/connectionsClient MCP/OAuth collegati al workspaceai:use DELETE/ai/connections/{client_id}Revoca subito l'accesso di un clientai:use POST/ai/summarizeRiassunto di un contatto, azienda o deal con prossima azioneai:use POST/ai/draft-replyBozza di risposta a una conversazione dell'inboxai:use POST/ai/workflow-draftWorkflow in bozza da una descrizione in italianoai:use GET/ai/conversationsConversazioni con il copilotaai:use GET/ai/conversations/{id}Messaggi di una conversazioneai:use DELETE/ai/conversations/{id}Elimina una conversazioneai:use

Workspace

GET/workspaceWorkspace e brandautenticato PATCH/workspaceAggiorna nome, logo, colore, fuso, valuta, linguasettings:manage POST/workspace/deleteElimina il workspaceorganization:delete GET/settings/securityImpostazioni di sicurezzasettings:manage PATCH/settings/security2FA obbligatoria, domini consentiti, durata sessionisettings:manage GET/audit-logAudit log del workspacesettings:manage

Privacy ed export

GET/exportsOggetti esportabilisettings:manage GET/exports/{object}Scarica i datisettings:manage GET/trashCestino (30 giorni)autenticato POST/trash/restoreRipristina dal cestinoautenticato

Fatturazione

GET/billingPiano, posti, utilizzo e crediti AIbilling:manage PATCH/billing/detailsDati di fatturazionebilling:manage GET/billing/invoicesFatture e note di creditobilling:manage POST/billing/ai-cardCollega una carta per Nido AI a consumobilling:manage PATCH/billing/ai-limitLimite di spesa mensile AIbilling:manage

03 — Modelli dati

Oggetti principali

Tutti gli oggetti condividono id con prefisso, timestamp ISO 8601, proprietà personalizzate in «properties» e associazioni esplicite.

Contact.json

{
  "id": "ct_29f1",
  "object": "contact",
  "email": "[email protected]",
  "first_name": "Marco",
  "last_name": "Ferraro",
  "lifecycle_stage": "opportunity",
  "owner_id": "usr_giulia",
  "lead_score": 92,
  "properties": {
    "lead_source": "fiera",
    "gdpr_newsletter": true
  },
  "associations": {
    "companies": ["co_4471"],
    "deals": ["deal_8841"]
  },
  "created_at": "2026-08-14T09:12:00Z",
  "updated_at": "2026-10-03T10:14:03Z"
}

Deal.json

{
  "id": "deal_8841",
  "object": "deal",
  "name": "Rinnovo licenze 2027",
  "amount": 24000,
  "currency": "EUR",
  "pipeline_id": "pl_vendite_b2b",
  "stage": "negoziazione",
  "probability": 0.8,
  "close_date": "2026-10-12",
  "status": "open",
  "owner_id": "usr_giulia",
  "line_items": [
    { "sku": "NIDO-BIZ", "qty": 25,
      "unit_price": 840, "discount": 0.1 }
  ],
  "associations": {
    "contacts": ["ct_29f1", "ct_31aa"],
    "companies": ["co_4471"]
  }
}

Error.json

HTTP/1.1 422 Unprocessable Entity

{
  "error": {
    "type": "validation_error",
    "code": "invalid_property",
    "message": "La fase «firmato» non esiste
      nella pipeline vendite-b2b.",
    "param": "stage",
    "doc_url": "https://nido.logicaltech.it/developers/errors
      #invalid_property",
    "request_id": "req_9f2c11ab"
  }
}

04 — Webhook

Eventi e consegne

Ogni evento arriva come POST JSON firmato. Rispondi 2xx entro 10 s; in caso di errore riproviamo fino a 5 volte con backoff esponenziale (1 min → 5 min → 30 min → 2 h → 6 h).

Catalogo eventi

Contatticontact.createdcontact.updatedcontact.deletedcontact.merged

Aziendecompany.createdcompany.updatedcompany.deleted

Dealdeal.createddeal.updateddeal.stage_changeddeal.wondeal.lostdeal.deleted

Attivitàtask.createdtask.completedmeeting.bookedcall.loggednote.created

Comunicazioniemail.sentemail.openedemail.repliedconversation.assigned

Sistemaworkflow.run_failedform.submitteduser.invitedai.action_executed

deal.won · envelope

POST /tuo-endpoint
Content-Type: application/json
X-Nido-Event: deal.won
X-Nido-Delivery: dlv_7hq2k…
X-Nido-Signature: t=1791018734,
  v1=5f2a9c…c91e

{
  "id": "evt_01jb7q2k9x",
  "type": "deal.won",
  "api_version": "2026-09-01",
  "created_at": "2026-10-03T10:14:03Z",
  "workspace_id": "005683c9-…",
  "data": {
    "object": { …Deal },
    "previous": { "stage": "negoziazione" }
  }
}

verify.ts

import crypto from "node:crypto";

export function verify(req, secret) {
  const [t, v1] = req.headers["x-nido-signature"]
    .split(",").map((p) => p.split("=")[1]);

  // rifiuta richieste più vecchie di 5 min
  if (Date.now() / 1000 - Number(t) > 300)
    return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${req.rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(v1), Buffer.from(expected));
}

05 — MCP per AI

Server MCP di Nido

Il Model Context Protocol permette a Claude, ChatGPT, Cursor e ai tuoi agenti di leggere e aggiornare il CRM con tool tipizzati. Il server è remoto (streamable HTTP), autenticato via OAuth 2.1 e rispetta ruoli e permessi dell'utente che lo collega.

Client AIClaude, ChatGPT, Cursor, agenti custom (Agent SDK, n8n).ClaudeChatGPTCursor

nido.logicaltech.it/api/mcpServer MCP remoto. Espone tool, risorse e prompt; chiede conferma per le scritture.OAuth 2.1scopesHTTP

API v1Stesse regole di rate limit, validazione e idempotenza dell'API pubblica.v1idempotency

Dati CRM + auditOgni chiamata è registrata con utente, client, tool e risultato.audit_logUE

claude_desktop_config.json

{
  "mcpServers": {
    "nido": {
      "type": "http",
      "url": "https://nido.logicaltech.it/api/mcp",
      "oauth": {
        "scopes": [
          "contacts:read",
          "contacts:write",
          "deals:read",
          "deals:write",
          "activities:write"
        ]
      }
    }
  }
}

Collegare un client in 4 passi

1Impostazioni › AI & MCPCrea una connessione e scegli il client (Claude, ChatGPT, Cursor, personalizzato).

2Scegli i permessiLettura, scrittura o per singolo tool. Le scritture possono richiedere conferma.

3Autorizza con OAuthIl client apre la pagina di consenso di Nido; nessuna chiave da copiare.

4Chiedi in linguaggio naturale«Quali deal chiudono questa settimana e cosa manca per firmarli?»

Tool	Cosa fa	Parametri principali	Tipo	Conferma utente
search_crm	Cerca nel CRM	query, types, limit	Lettura	— Configurabile
get_record	Leggi record	object, id, include	Lettura	— Configurabile
get_timeline	Cronologia attività	object, id, since, limit	Lettura	— Configurabile
list_deals	Elenca deal	pipeline, stage, owner, close_before	Lettura	— Configurabile
pipeline_summary	Riepilogo pipeline	pipeline, period	Lettura	— Configurabile
run_report	Esegui report	report_id, filters	Lettura	— Configurabile
create_contact	Crea contatto	email, first_name, last_name, company	Scrittura	— Configurabile
update_record	Aggiorna record	object, id, properties	Scrittura	Sempre
move_deal_stage	Sposta fase del deal	deal_id, stage, reason	Scrittura	Sempre
log_activity	Registra attività	object, id, type, body	Scrittura	— Configurabile
create_task	Crea task	title, due_at, owner_id, related	Scrittura	— Configurabile
draft_email	Prepara bozza email	to, subject, body, context_id	Lettura	— Configurabile
send_email	Invia email	draft_id	Scrittura	Sempre
enroll_in_workflow	Iscrivi a workflow	workflow_id, object, id	Scrittura	Sempre

Risorse

nido://contacts/{id}Scheda contatto in markdownnido://companies/{id}Azienda con deal e personenido://deals/{id}Deal, prodotti e cronologianido://pipelinesPipeline e fasi del workspacenido://reports/{id}Risultato di un report salvatonido://schema/{object}Proprietà disponibili e tipi

Prompt pronti

/prepara_meetingBrief di 1 pagina prima di una call: contesto, persone, rischi, domande/riassumi_accountStoria del cliente, valore, stato dei deal e prossimi passi/revisione_pipelineDeal fermi, a rischio o senza prossima attività/follow_upEmail di follow-up dopo un meeting registrato

Sicurezza e controllo

Permessi dell'utenteL'AI non vede né modifica più di chi l'ha collegata.Umano nel loopScritture sensibili richiedono conferma esplicita.Audit logClient, tool, parametri e risultato per ogni chiamata.Revoca immediataToken a scadenza, revocabili in un clic.Dati in UENessun addestramento su dati dei clienti.

Esempio reale

Da una domanda a tre azioni nel CRM.

Claude combina tool di lettura e scrittura. Lo spostamento di fase richiede conferma: l'utente approva dentro la chat e l'azione finisce nell'audit log di Nido.

Ferraro ha firmato. Chiudi il deal e ricordami il kickoff tra 3 giorni.

nido · search_crm{ "query": "Ferraro", "types": ["deal"] }1 risultato · deal_8841 Rinnovo licenze 2027

nido · move_deal_stage{ "deal_id": "deal_8841", "stage": "vinto" }Richiede conferma · Approva / Rifiuta

nido · create_task{ "title": "Kickoff Ferraro", "due_at": "2026-10-06", "deal_id": "deal_8841" }Task creato per Giulia Rinaldi

06 — Sicurezza

Scope e permessi

Gli stessi scope valgono per chiavi API, token OAuth e tool MCP. Un token non può mai superare i permessi del ruolo dell'utente che l'ha autorizzato.

contacts:readcontacts:writecontacts:deletecompanies:readcompanies:writecompanies:deletedeals:readdeals:writedeals:deleteactivities:readactivities:writeemails:reademails:sendworkflows:readworkflows:writewebhooks:manageschema:readusers:readreports:read