API e webhook

Con API e webhook i tuoi sistemi (ERP, data warehouse, backend del sito, strumenti di automazione) lavorano con il tuo workspace NextCRM:

• la REST API legge e modifica lead, contatti, attività e note, e legge funnel, invii dei moduli, campagne e membri del team;
• i webhook avvisano il tuo server non appena succede qualcosa, ad esempio un nuovo lead o un cambio di fase.

Nota: Solo gli Admin del workspace possono aprire Impostazioni > API e webhook. L'accesso API è incluso nei piani Business, Agency ed Enterprise. Negli altri piani le chiavi e gli endpoint esistenti restano visibili, ma non se ne possono creare di nuovi e le chiamate API vengono rifiutate.

Dove trovare ogni valore

Tutto proviene da NextCRM stesso; non serve alcun account di terze parti.

Valore	Dove trovarlo
Chiave API	Impostazioni > API e webhook > Crea chiave API. La chiave completa viene mostrata una sola volta; copiala nella tua integrazione (ad esempio n8n, Zapier, Make o il tuo codice) come token Bearer.
Segreto di firma	Mostrato una volta quando aggiungi un endpoint webhook, e di nuovo dopo Rinnova segreto. Salvalo sul server che riceve i webhook.
URL dell'endpoint	Proviene dal tuo sistema o strumento di automazione, ad esempio l'URL di produzione di un nodo Webhook di n8n. Deve usare https.

Ordine di configurazione: creare una chiave API con i permessi necessari > fare una prima chiamata > aggiungere un endpoint webhook con i suoi eventi > verificare la firma sul tuo server > inviare un evento di prova.

Creare una chiave API

1. Fai clic sulla scheda del tuo profilo in fondo alla barra laterale, scegli Impostazioni e apri la scheda API e webhook (apri API e webhook) e resta nella scheda Chiavi API.
2. Fai clic su Crea chiave API.
3. Inserisci un Nome che indichi dove viene usata la chiave, ad esempio "Sincronizzazione ERP".
4. In Permessi scegli Lettura e/o Scrittura per ogni area. Scegli solo ciò che serve davvero all'integrazione.
5. Se vuoi, imposta una scadenza in Scadenza (30, 90 o 365 giorni, oppure una data).
6. Fai clic su Crea chiave e copia subito la chiave con Copia.

Attenzione: La chiave viene mostrata una sola volta. NextCRM ne conserva solo un'impronta (hash), quindi nessuno - nemmeno il supporto - può mostrartela di nuovo. Se la perdi, revocala e creane una nuova.

L'elenco mostra ogni chiave con il suo prefisso (ad esempio ncrm_live_1a2b3c4d), i permessi, chi l'ha creata, l'ultimo utilizzo e la scadenza. Revoca blocca subito una chiave.

Cosa può fare una chiave

Una chiave agisce per il tuo workspace con i diritti di un Admin del workspace, limitati ai permessi scelti:

Permesso	Consente
Lead (lettura / scrittura)	Elencare e leggere lead; crearli, modificarli, spostarli in una fase, assegnarli, spostarli nel Cestino e ripristinarli
Contatti (lettura / scrittura)	Elencare, leggere, creare, modificare ed eliminare contatti
Attività (lettura / scrittura)	Elencare e leggere attività; crearle, modificarle, completarle e archiviarle
Funnel e fasi (lettura)	Leggere i funnel con le loro fasi
Invii dei moduli (lettura)	Leggere i moduli e i loro invii
Campagne (lettura)	Leggere le campagne e i loro risultati
Note e cronologia (lettura / scrittura)	Leggere le note e la cronologia di un lead; aggiungere note e registrare chiamate
Membri del team (lettura)	Leggere nomi, email e ruoli dei membri (per assegnare lead e attività)
Webhook (lettura / scrittura)	Leggere, registrare ed eliminare endpoint webhook

Valgono le stesse regole dell'app: limiti del piano (un nuovo lead oltre il limite di lead attivi finisce nella Posta in arrivo dei lead), il Cestino (i lead nel Cestino vanno ripristinati prima di modificarli; eliminare tramite API sposta sempre nel Cestino) e i dati non passano mai a un altro workspace. Ciò che possono fare solo le persone - gestire team, ruoli, fatturazione o chiavi API ed eliminare definitivamente - non è possibile con una chiave. Una chiave smette inoltre di funzionare quando chi l'ha creata non è più Admin del workspace.

Ogni modifica fatta con una chiave compare nella cronologia del lead come API key <nome>.

La prima chiamata

Invia la chiave nell'intestazione Authorization. L'URL di base è https://…/api/v1.

curl https://…/api/v1/leads?limit=10 \
  -H "Authorization: Bearer ncrm_live_..."

Creare un lead:

curl -X POST https://…/api/v1/leads \
  -H "Authorization: Bearer ncrm_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2a10-order-4711" \
  -d '{"first_name":"Ada","last_name":"Lovelace","email":"ada@example.com","value":12000}'

Il riferimento completo con tutti gli endpoint, i campi e un esempio curl si trova nella scheda Documentazione API, pubblicamente su https://…/api/v1/docs e come file OpenAPI 3.1 su https://…/api/v1/openapi.json.

Regole per ogni integrazione

• Le risposte hanno la forma { "data": ..., "meta": { ... } }, gli errori { "error": { "code", "message", "details" } } con l'elenco dei campi per gli errori di validazione. Le date sono in ISO 8601, UTC.
• Paginazione: gli elenchi restituiscono meta.next_cursor; passalo come cursor per ottenere la pagina successiva (limit fino a 100).
• Idempotenza: invia un'intestazione Idempotency-Key con le richieste POST. Un nuovo tentativo con la stessa chiave restituisce il primo risultato invece di creare un duplicato (per 24 ore).
• Limiti di frequenza: 120 richieste al minuto per chiave e 600 per workspace. Oltre, l'API risponde 429 con l'intestazione Retry-After: attendi quei secondi.
• Manutenzione: durante un aggiornamento di NextCRM l'API risponde 503 MAINTENANCE con Retry-After. I webhook vengono trattenuti e consegnati dopo.
• Solo dal server: chiama l'API dal tuo server. I browser non possono chiamarla (niente CORS) e una chiave API non va mai inserita in un sito web o in un'app.

Webhook

1. Apri la scheda Webhook e fai clic su Aggiungi endpoint.
2. Inserisci l'URL dell'endpoint del tuo server. Deve iniziare con https:// ed essere raggiungibile da internet; gli indirizzi interni, privati e di metadati cloud vengono rifiutati.
3. Scegli gli Eventi desiderati e fai clic su Salva endpoint.
4. Copia il segreto di firma (mostrato una sola volta) e salvalo sul tuo server.
5. Fai clic su Invia evento di prova per verificare che il server risponda.

Eventi disponibili: lead.created, lead.updated, lead.stage_changed, lead.assigned, lead.trashed, lead.restored, task.created, task.completed, form.submitted, contact.created, contact.updated, campaign.sent, call.logged, nps.responded, customer.renewal_updated, customer.at_risk, booking.created, booking.rescheduled, booking.canceled, quote.sent, quote.accepted, quote.declined e automation.webhook.

Gli eventi dei preventivi riportano gli importi come numeri interi nell'unità più piccola della valuta (ad esempio centesimi): subtotal_minor è la somma delle righe dopo gli sconti di riga, discount_minor lo sconto sull'intero preventivo, tax_minor l'imposta e total_minor l'importo da pagare. Il total_minor di ogni riga è il suo importo dopo lo sconto di riga, prima dello sconto del preventivo e dell'imposta.

I lead creati da un'importazione di file inviano un lead.created per ogni lead importato al termine dell'importazione, con "context": { "source": "import", "import_batch_id": "..." } accanto a data.

Ogni consegna è un POST con l'evento in JSON (id, type, created_at, actor, data) e queste intestazioni: X-NextCRM-Event, X-NextCRM-Delivery, X-NextCRM-Timestamp e X-NextCRM-Signature.

Verificare la firma

X-NextCRM-Signature ha la forma t=1760860800,v1=5f2b.... Calcola l'HMAC-SHA256 di <t>.<corpo grezzo della richiesta> con il tuo segreto di firma e confrontalo con v1. Rifiuta le richieste con un timestamp più vecchio di 5 minuti.

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const t = Number(/(?:^|,)t=(\d+)/.exec(header)?.[1]);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return header.split(",").some((part) => part === `v1=${expected}`);
}

Nuovi tentativi, registro delle consegne e rinnovo

• Rispondi con un qualsiasi stato 2xx entro 10 secondi. Altrimenti NextCRM riprova con pause crescenti (1, 2, 4, ... minuti), fino a 8 tentativi.
• Il Registro delle consegne mostra ogni consegna con stato, tentativi e codice di risposta. Invia di nuovo rimette in coda una consegna.
• Dopo molti errori consecutivi l'endpoint viene disattivato automaticamente e tutti gli Admin del workspace ricevono una notifica. Correggi l'endpoint e fai clic su Attiva.
• Rinnova segreto crea un nuovo segreto di firma. Quello vecchio continua a firmare per 24 ore, così puoi passare al nuovo senza perdere eventi.

Lora e l'API

Lora può spiegare l'API, aprire questa pagina ed elencare i tuoi endpoint webhook. Non crea, mostra o revoca mai chiavi API e non vede mai un segreto di firma: queste operazioni le fai tu su questa pagina.

Risoluzione dei problemi

Risposta	Significato
401 INVALID_API_KEY, API_KEY_REVOKED, API_KEY_EXPIRED	La chiave è errata, revocata o scaduta. Creane una nuova.
403 INSUFFICIENT_SCOPE	La chiave non ha il permesso per questa chiamata. Crea una chiave con il permesso necessario.
403 API_KEY_OWNER_NOT_ADMIN	Chi ha creato la chiave non è più Admin del workspace. Un admin attuale deve creare una nuova chiave.
402 FEATURE_NOT_IN_PLAN	Il piano non include l'accesso API.
409 LEAD_IN_TRASH	Ripristina prima il lead (POST /leads/{id}/restore).
422 VALIDATION_FAILED	Campo e motivo sono in error.details.
429 RATE_LIMITED	Attendi i secondi di Retry-After, poi continua.