# API REST per CRM con webhook firmati | AiCrm

> CRM con API REST pubblica: crea e consulta i contatti con un’intestazione X-Api-Key, fino a 20 chiavi per integrazione e webhook in uscita firmati con HMAC-SHA256. Registrazione di lead dal tuo sito web senza duplicati.

- **Fonte (source):** https://aistohire.com/it/aicrm-crm-leggero-con-api-109/f/api-rest-crm-webhook-firmati
- **Piattaforma (platform):** AIstoHire
- **Lingua (language):** it

## In sintesi

- API REST pubblica con diverse API key e webhook firmati
- Registra i customer dal tuo sito web, dal tuo modulo o dal tuo backend con una chiamata HTTP, e ricevi ogni modifica sul tuo server firmata con HMAC-SHA256.
- Registrazione di customer con una sola chiamata
- Nessun duplicato per design
- Fino a 20 API key nominate

## API REST pubblica con diverse API key e webhook firmati

AiCrm, l'app CRM di AIsToHire, espone un'API REST pubblica sui tuoi customer. Con una API key nell'HTTP header `X-Api-Key` puoi creare, elencare, consultare, aggiornare ed eliminare customer, e aggiungere attività a ciascuno di essi, dal modulo del tuo sito web, dal tuo chatbot, da uno Zap, da uno script Python o dal tuo backend. Le risposte sono JSON nella forma `{ success, data }`, e il limite è di 100 richieste al minuto per API key.

La registrazione tramite API non duplica: se l'email che invii esiste già nel tuo database, AiCrm aggiorna la scheda esistente (completa il telefono, il nome o l'azienda mancanti, unisce i tag/label) e registra un nuovo invio nella sua timeline, restituendo HTTP 200; se è nuovo, lo crea e restituisce 201. Ogni customer che entra tramite API viene automaticamente etichettato come `api-lead`, conserva i tag/label che invii e salva il `subId` di origine, oltre al paese, all'IP e al browser da cui è arrivato.

Puoi avere fino a 20 API key con un nome proprio, oltre all'internal key dell'app. In questo modo, assegni una API key diversa a ogni integrazione —il sito web, il modulo della campagna di maggio, lo stagista, il fornitore— e la revochi singolarmente quando l'integrazione termina, senza intaccare le altre. Il valore completo di una API key viene mostrato una sola volta, al momento della creazione; in seguito, è visibile solo mascherato nell'elenco.

Nella direzione opposta, i webhook avvisano i tuoi sistemi. Configuri fino a 10 destinazioni, scegli a quali eventi si iscrive ciascuna (`customer.created`, `customer.updated`, `customer.deleted`, `activity.created`) e AiCrm effettua un POST alla tua URL con gli HTTP header `X-AiCrm-Event` e `X-AiCrm-Signature: sha256=…`, la signature HMAC-SHA256 del corpo con il segreto di quel webhook, affinché tu possa verificare che la consegna sia legittima. Al salvataggio dell'URL, una protezione anti-SSRF rifiuta localhost, 127.0.0.0/8, 10.x, 192.168.x, 172.16-31.x, ::1, 0.0.0.0 e i domini `.local` e `.internal`.

## Cosa include

- **Registrazione di customer con una sola chiamata** — un POST a `/api/apps/public/crm/customers` con l'email e i tag/label che desideri, e il lead è già classificato nel tuo CRM.
- **Nessun duplicato per design** — se l'email esiste già, la scheda viene aggiornata e il nuovo invio viene annotato nella sua timeline invece di creare una seconda scheda.
- **Fino a 20 API key nominate** — una per integrazione, revocabile separatamente. Se una chiave viene compromessa, elimini quella e nient'altro smette di funzionare.
- **Webhook firmati con HMAC-SHA256** — verifichi l'intestazione `X-AiCrm-Signature` con il tuo segreto e sai che la notifica proviene dal tuo CRM e non da una terza parte.
- **Protezione anti-SSRF inclusa** — l'app si rifiuta di consegnare webhook a localhost o a intervalli di rete privati, così il tuo CRM non può essere usato per sondare una rete interna.
- **CRUD completo, non solo aggiunte** — elencare con paginazione e filtri (ricerca, stato del ciclo di vita, tag/etichette, paese), consultare un cliente con la sua attività, aggiornarlo, eliminarlo e registrarvi attività.
- **Origine tracciata automaticamente** — ogni aggiunta tramite API salva il `subId` che invii più il paese, l'IP e il browser, e viene etichettata come `api-lead` per filtrarla successivamente nell'app.
- **Test senza congetture** — l'app include la documentazione degli endpoint con un esempio `curl` copiabile e un pulsante per inviare una consegna di prova a ogni webhook, con lo stato e l'ora dell'ultimo tentativo.

## Domande frequenti

### Come creo un cliente nel CRM dal mio sito web?

Effettui una richiesta POST a `/api/apps/public/crm/customers` con l'intestazione `X-Api-Key` e un JSON contenente almeno l'email o il telefono. Puoi inviare anche nome, telefono, azienda, paese, stato, note, tag e un `subId` per identificare la campagna o il modulo di origine. AiCrm restituisce 201 se lo crea e 200 se quel cliente esisteva già.

### Cosa succede se la stessa email viene inviata due volte tramite l'API?

Non viene duplicato. AiCrm cerca l'email (o il telefono, se non invii l'email) e, se la trova, aggiorna la scheda esistente compilando i campi vuoti, unisce i nuovi tag con quelli già presenti e registra il nuovo invio nella sua timeline di attività. La risposta indica che il cliente esisteva già e restituisce il suo ID.

### Quante API key posso avere e posso revocarne una singola?

Puoi creare fino a 20 chiavi con nome proprio, oltre alla chiave interna dell'app, che non può essere eliminata. Ogni chiave viene eliminata in modo indipendente, così puoi darne una diversa a ogni integrazione e revocarla senza influenzare le altre. Il valore completo viene mostrato solo al momento della creazione; dopo appare mascherato nell'elenco. Tutte le chiavi condividono il limite di 100 richieste al minuto per chiave.

### Come verifico che un webhook provenga effettivamente dal mio CRM?

Ogni consegna include l'HTTP header `X-AiCrm-Signature: sha256=<firma>`, che è l'HMAC-SHA256 del corpo esatto della richiesta usando il segreto che l'app ti mostra al momento della creazione del webhook. Calcola quell'HMAC sul tuo server sul corpo ricevuto e confrontalo. Inoltre, viene inviato l'HTTP header `X-AiCrm-Event` con il nome dell'evento: `customer.created`, `customer.updated`, `customer.deleted` o `activity.created`.

### Cosa succede se il mio endpoint webhook è inattivo?

La consegna è best-effort: AiCrm attende fino a 5 secondi e, se fallisce, riprova dopo un secondo e mezzo. Non c'è una coda persistente di tentativi, quindi un lungo periodo di inattività del tuo server potrebbe farti perdere delle notifiche; in tal caso, riconcilia con una richiesta GET a `/api/apps/public/crm/customers`. L'app ti mostra lo lifecycle status e l'ora dell'ultimo tentativo di ogni webhook, e puoi avviare una consegna di prova quando vuoi.

- [AiCrm — CRM leggero con API per creare clienti da qualsiasi sistema](https://aistohire.com/it/aicrm-crm-leggero-con-api-109)

## Informazioni sulla piattaforma

**AiCrm — CRM leggero con API per creare clienti da qualsiasi sistema** — un'applicazione di AIstoHire. Disponibile su: https://aistohire.com/it/aicrm-crm-leggero-con-api-109/f/api-rest-crm-webhook-firmati

### Altre lingue

- `es`: https://aistohire.com/es/aicrm-crm-ligero-con-api-109/f/api-rest-crm-webhooks-firmados
- `en`: https://aistohire.com/aicrm-lightweight-crm-with-api-109/f/api-rest-crm-signed-webhooks
- `fr`: https://aistohire.com/fr/aicrm-crm-leger-avec-api-109/f/api-rest-crm-webhooks-signes
- `pt`: https://aistohire.com/pt/aicrm-crm-leve-com-api-109/f/api-rest-crm-webhooks-assinados
- `de`: https://aistohire.com/de/aicrm-leichtes-crm-mit-api-109/f/api-rest-crm-signierte-webhooks
- `bg`: https://aistohire.com/bg/aicrm-lesen-crm-s-api-za-upravlenie-na-klienti-i-liydove-109/f/rest-api-crm-podpisani-uebhukove
- `ja`: https://aistohire.com/ja/aicrm-lightweight-crm-with-api-109/f/crm-rest-api-signed-webhooks
- `nl`: https://aistohire.com/nl/aicrm-eenvoudige-crm-met-api-om-klanten-en-leads-te-beheren-109/f/rest-api-crm-ondertekende-webhooks
- `ko`: https://aistohire.com/ko/aicrm-api-gyeongnyang-crm-109/f/crm-rest-api-seomyeong-webhook
- `sv`: https://aistohire.com/sv/aicrm-enkelt-crm-med-api-for-att-hantera-kunder-och-leads-109/f/rest-api-crm-signerade-webhooks
- `da`: https://aistohire.com/da/aicrm-enkelt-crm-med-api-til-at-styre-kunder-og-leads-109/f/rest-api-crm-signerede-webhooks
- `ar`: https://aistohire.com/ar/aicrm-nzam-crm-bsit-ma-api-lidara-alamla-walamla-almhtmlin-109/f/crm-rest-api-webhooks
- `no`: https://aistohire.com/no/aicrm-enkelt-crm-med-api-for-a-styre-kunder-og-leads-109/f/rest-api-crm-signerte-webhooks
- `fi`: https://aistohire.com/fi/aicrm-yksinkertainen-crm-rajapinnalla-asiakkaille-ja-liideille-109/f/crm-rest-api-allekirjoitetut-webhookit
- `zh`: https://aistohire.com/zh/ai-crm-rest-api-webhooks-109/f/crm-rest-api-webhook
- `pl`: https://aistohire.com/pl/aicrm-prosty-crm-z-api-do-zarzadzania-klientami-i-leadami-109/f/api-rest-crm-podpisane-webhooki
- `he`: https://aistohire.com/he/aicrm-crm-pshot-am-api-lnihol-lkochot-vlidim-109/f/api-rest-crm-webhooks-chatumim
- `cs`: https://aistohire.com/cs/aicrm-jednoduche-crm-s-api-pro-spravu-klientu-a-leadu-109/f/rest-api-crm-podepsane-webhooky
- `id`: https://aistohire.com/id/aicrm-crm-sederhana-dengan-api-untuk-mengelola-pelanggan-dan-lead-109/f/api-rest-crm-webhook-bertanda-tangan
