CRM con API: il tuo agente IA e i tuoi strumenti fanno follow-up dagli stessi record dei clienti

Customermates è un CRM con API: un’API REST aperta su ogni piano, da Starter a 12 € per utente al mese, e nell’edizione self-hosted gratuita. Ti autentichi con una chiave API nell’intestazione x-api-key, lo schema completo è un documento OpenAPI 3.1 su /api/v1/openapi e, sui piani a pagamento e in self-hosting, 16 eventi webhook avvisano i tuoi sistemi quando qualcosa cambia. Non esiste un piano per sviluppatori separato né un componente aggiuntivo a pagamento per l’API.

Customermates è un CRM open source nativo per l’IA, nato in Germania per piccoli team a contatto con i clienti. L’API interessa due tipi di lettori: uno sviluppatore che vuole sincronizzare il CRM con un altro sistema, e un team che vuole che un client IA come Claude o ChatGPT aggiorni i record. Il primo usa REST e webhook. Il secondo usa l’endpoint MCP, che poggia sugli stessi permessi.

Perché conta per il follow-up. Una risposta a un cliente salta quando i fatti che servono stanno in un altro sistema. Tramite MCP il tuo client IA, come Claude o ChatGPT, legge il record di un cliente e, su Customermates Cloud dal piano Pro, le conversazioni con lui, e può salvare una bozza di risposta da rivedere e inviare. Tramite REST e webhook i tuoi altri strumenti ricevono gli stessi record e vengono avvisati quando uno cambia.

Cosa copre l’API REST

L’API REST funziona su ogni lista del CRM. Un nuovo workspace parte senza liste: crei le liste che ti servono (contatti, organizzazioni, trattative o le tue) nel Modello dati, tramite l’API o MCP, oppure lasci che la configurazione con IA le crei nel cloud. Ogni rotta dei record è una POST verso un’azione con nome e un corpo JSON, quindi lo stesso codice funziona per trattative, contatti o una lista aggiunta la settimana scorsa.

Un record si indirizza con un riferimento, { "typeId": "...", "recordId": "..." }, non con il suo URL. L’URL di base è l’indirizzo da cui apri Customermates, nel cloud e sul tuo server. Altre rotte coprono gli utenti (/api/v1/users/me, /api/v1/users/search), i webhook e la posta in arrivo: thread, bozze, invio di e-mail e messaggi di chat, attività e calendari in sola lettura.

Alcuni dettagli fanno risparmiare tempo il primo giorno:

• I campi hanno ID stabili. /model/read restituisce il fieldId di ogni campo, gli ID delle opzioni di un campo a scelta singola come la Fase della trattativa e la revision dello schema. Gli ID restano gli stessi quando qualcuno rinomina una lista o un campo. I valori sono tipizzati, per esempio { "kind": "text", "value": "Acme" }.
• Le query usano un corpo JSON. /records/query accetta typeId, filters, sort, page e pageSize (fino a 500). I filtri usano la sintassi dei filtri condivisa con l’app e MCP.
• Le scritture sono protette. Una mutazione porta expectedRevision (la revisione dello schema), una idempotencyKey e la mutation stessa; aggiornamenti ed eliminazioni portano anche l’expectedVersion del record. Inviare di nuovo la stessa richiesta con la stessa chiave non la applica due volte.
• I collegamenti sono un’azione a parte. link e unlink accettano un relationId, un riferimento source e uno target. Un aggiornamento non rimuove mai i collegamenti che non hai menzionato.
• Le scritture di massa accettano fino a 100 record. updateMany applica una modifica a fino a 100 record in modo atomico e deleteMany ne sposta fino a 100 nel cestino, quindi una pulizia di 2.000 contatti si divide in 20 richieste.

Webhook: lascia che il CRM ti chiami

Un webhook invia una POST JSON al tuo URL quando avviene un evento sottoscritto. Gli amministratori, e i membri il cui ruolo ha Accesso in lettura Tutti e Crea su API e webhook, ne aggiungono uno in Impostazioni → Webhook: URL, eventi, la lista sotto Record da con filtri facoltativi, un segreto facoltativo, intestazioni personalizzate facoltative e un modello del corpo facoltativo. Il riferimento sui webhook elenca ogni evento e payload.

• Eventi: 5 eventi sui record (record.created, record.updated, record.deleted quando un record passa nel cestino, record.restored e record.deletedPermanently) per qualsiasi lista tu scelga, comprese le tue, più 11 eventi della posta in arrivo e del calendario.
• Modifiche incluse: un payload record.updated porta il riferimento del record ed elenca ogni campo cambiato con il suo valore before e after. Una scrittura che non cambia nulla non invia alcun evento.
• Firme: con un segreto impostato, ogni consegna è firmata con HMAC-SHA256 sul corpo grezzo.
• Nuovi tentativi: un timeout, un errore di rete, un 5xx, 408, 425 o 429 viene ritentato automaticamente, fino a 10 tentativi in totale. Le altre risposte 4xx non vengono ritentate, perché una ripetizione fallirebbe allo stesso modo. Ogni consegna ha un timeout di 5 secondi.
• Registro delle consegne: Impostazioni → Log dei webhook mostra codice di stato e messaggio di risposta di ogni consegna, con un pulsante per reinviare.
• Modelli del corpo: un modello sostituisce la busta standard, così uno strumento di chat o un endpoint di automazione che si aspetta una propria forma JSON può ricevere le consegne senza intermediari.

Le consegne non sono rigorosamente ordinate. Due aggiornamenti dello stesso contatto a pochi millisecondi di distanza possono arrivare invertiti, quindi deduplica per id dell’evento, imposta il tuo gestore su typeId e recordId e usa il timestamp del payload e la versione del record.

Come fare la tua prima chiamata API

1. Crea una chiave

   Apri Impostazioni → Chiavi API e connettori, premi Aggiungi, scegli Chiave API standard, dalle un nome come ERP sync, produzione e copia la chiave. Viene mostrata una sola volta. La guida alle chiavi API tratta scadenza e rotazione.

2. Leggi lo schema

   Scarica /api/v1/openapi dall’indirizzo del tuo workspace e importalo in Postman, Insomnia o in un generatore di client. Poi invia POST /api/v1/model/discover con {"search":"deal"} per ottenere il typeId delle tue trattative, e POST /api/v1/model/read con {"typeIds":["<deal-type-id>"]} per vederne i campi, le opzioni della fase e la revision dello schema.

3. Interroga

   Invia POST /api/v1/records/query con l’intestazione x-api-key e un corpo come {"typeId":"<deal-type-id>","filters":[{"fieldId":"system:updatedAt","operator":"inLastDays","value":{"kind":"decimal","value":"7","currency":null}}],"page":1,"pageSize":25} per elencare le trattative modificate nell’ultima settimana.

4. Scrivi

   Sposta una trattativa in un’altra fase con POST /api/v1/records/mutate e {"expectedRevision":<revision>,"idempotencyKey":"move-acme-to-demo","mutation":{"action":"update","ref":{"typeId":"<deal-type-id>","recordId":"<deal-id>"},"expectedVersion":<version>,"fields":[{"fieldId":"<stage-field-id>","value":{"kind":"select","value":"<option-id>"}}]}}. Se il tuo utente può farlo nell’app, la chiave può farlo tramite l’API.

5. Iscriviti

   Aggiungi un webhook per Record aggiornato sulla lista Trattative con un segreto, puntalo al tuo endpoint e controlla la prima consegna nel Log dei webhook.

Una chiave sbagliata, scaduta o eliminata riceve HTTP 401. Una chiave il cui proprietario è stato impostato su Inattivo riceve 403.

Chiavi API e permessi

Le chiavi appartengono all’utente che le ha create e agiscono con il ruolo attuale di quell’utente. Non ci sono utenti API separati né ambiti per chiave, quindi una chiave non si può limitare alla sola lettura. Se un’integrazione deve solo leggere le trattative, crea la sua chiave sotto un membro il cui ruolo consente solo quello. In Customermates Cloud quel membro è una postazione a pagamento come le altre.

Creare chiavi richiede Accesso in lettura Tutti e Crea sulla riga API e webhook di un ruolo. Un nuovo ruolo personalizzato parte senza, quindi di base solo gli amministratori creano chiavi. Lo stesso permesso apre anche ogni webhook del workspace, cosa da sapere prima di distribuirlo. Per fermare tutte le chiavi di chi se ne va, imposta il membro su Inattivo. Anche togliere dal suo ruolo Accesso in lettura Tutti su API e webhook ferma le sue chiavi.

MCP: l’API per i client IA

L’endpoint MCP su /api/v1/mcp dà a un client IA esterno 59 strumenti sugli stessi record, sulla posta in arrivo e sui webhook. Claude e ChatGPT si collegano tramite OAuth come connettore personalizzato; Claude Code, Codex, Cursor e Gemini usano una chiave API. Il client, il suo modello e il suo abbonamento restano tuoi. La ricerca semantica può comunque contare nell’uso di Mate in Customermates Cloud. La guida MCP elenca ogni strumento.

Mate, l’assistente dentro Customermates Cloud, è una funzione separata. Gira su crediti IA ospitati e non richiede alcuna chiave API. Le installazioni self-hosted hanno MCP ma non Mate.

Cosa non fa l’API

• Nessun PUT o PATCH sui record. Ogni modifica a un record è una POST a /api/v1/records/mutate.
• Nessun OR tra le regole di filtro. Le regole di filtro si combinano con AND. Per un OR, esegui due query o usa l’operatore in su un campo.
• Nessuna quota di richieste pubblicata. Un workspace molto carico risponde 429 con un’intestazione Retry-After. Dividi i lavori di massa in lotti da 100.
• Nessun endpoint di esportazione CSV e nessuna esportazione dell’intero account. L’app importa file Excel, CSV e JSON ed esporta XLSX e JSON, una lista alla volta. Qualsiasi cosa più grande passa da un tuo script API.
• Nessuna posta in arrivo né Mate in self-hosting. Le rotte REST dei record, i webhook e MCP funzionano lì; le rotte di messaggistica richiedono Customermates Cloud dal piano Pro in su.

Non è promesso alcun periodo di retrocompatibilità oltre il percorso /api/v1, quindi considera il documento OpenAPI attuale come il contratto e collauda rispetto a quello.

Come gli altri CRM misurano l’accesso all’API

Customermates pubblica questa pagina. Le cifre qui sotto vengono dalla documentazione di ciascun fornitore, verificate l’8 ottobre 2026; cambiano, quindi segui i link prima di pianificare su di esse.

Scegli HubSpot o Zoho CRM se vuoi un piano ospitato gratuito con accesso all’API e la tua integrazione rientra nei loro limiti di chiamate pubblicati. Scegli Pipedrive se un budget giornaliero che cresce con piano e postazioni si adatta al tuo volume. Scegli EspoCRM se vuoi un CRM open source self-hosted con utenti API separati e ruoli propri. Customermates si adatta a un piccolo team che vuole l’API dei record, i webhook e un endpoint MCP per i client IA al prezzo del CRM stesso, con un nucleo AGPL che può ospitare da solo. Non si adatta se ti servono ambiti per chiave o, in Customermates Cloud, un utente API che non occupi una postazione a pagamento.

Quanto costa

L’accesso all’API non ha sovrapprezzo. Un team di tre persone su Starter paga 36 € al mese e ottiene REST, webhook e MCP. Lo stesso team su Pro paga 87 € e aggiunge la posta in arrivo unificata e le sue rotte di messaggistica. Il self-hosting dell’edizione open source non costa nulla in licenze; il server lo gestisci tu. La fatturazione è mensile, vedi i prezzi. Se costruisci flussi in n8n, n8n è un prodotto separato con piani propri; la guida a n8n mostra la configurazione della richiesta HTTP.