1. Home
  2. iThink
  3. WordPress
  4. Bitrix24 API REST: webhook, limiti, batch e REST 3.0
WordPress

Bitrix24 API REST: webhook, limiti, batch e REST 3.0

Cavi di rete gialli collegati alle porte di uno switch
Immagine: blickpixel · Pixabay · Licenza dei contenuti Pixabay

Se devi far parlare un tuo sistema con Bitrix24, le Bitrix24 API REST sono la strada, e la documentazione ufficiale è in inglese e cambia in fretta. In questa guida metto in fila quello che serve a chi scrive il codice: come si crea un webhook in entrata, come si riceve un evento con un webhook in uscita, quali limiti rispettare, come usare le chiamate batch e che cosa è successo ai metodi classici come crm.deal.add. Le informazioni vengono dalla documentazione che ho letto a novembre 2026, con i link in fondo. Le pagine non riportano una data, quindi controlla sempre quella del metodo che stai usando.

Parlo anche per esperienza: nel connettore Ready2Bitrix scrivo su Bitrix24 con 26 metodi REST e con chiamate batch a lotti da 50. Se il lavoro lo vuoi affidare a me, la pagina del servizio è API REST e connettori su misura. Se invece sei tu a dover decidere se l'integrazione conviene, ti serve l'articolo gemello, l'integrazione tra Bitrix24 e WooCommerce, scritto per chi decide e non per chi programma.

Webhook o applicazione: da dove si parte con le Bitrix24 API REST?

Per collegare un sistema tuo a un solo portale Bitrix24 hai due vie. Il webhook è un indirizzo con una chiave segreta dentro: chi lo chiama agisce con i diritti dell'utente che lo ha creato. L'applicazione locale usa invece OAuth 2.0, con token che scadono e vanno rinnovati. Per la maggior parte delle integrazioni su un singolo portale il webhook basta ed è più semplice da mantenere. Ti servirà un'app quando vuoi un'autenticazione con token a scadenza, come vedremo in fondo.

Una nota sul piano: l'helpdesk italiano di Bitrix24, aggiornato il 30 ottobre 2026, dice che tutti gli utenti possono creare webhook in entrata e app personali, ma che webhook e applicazioni si creano solo con un piano a pagamento. Se stai provando su un portale gratuito e la voce non compare, parti da qui prima di cercare un bug.

Come si crea e si usa un webhook in entrata

Il webhook in entrata serve quando sei tu a chiamare Bitrix24: crei un contatto, aggiorni una trattativa, leggi un elenco.

Creazione

Vai in Developer resources (nel portale in italiano, Applicazioni > Developer resources), poi Casi d'uso comuni, Altro, Webhook in entrata. Nel generatore di richieste scegli il metodo e provi i parametri con Esegui. Poi, in «Assegna permessi», scegli i permessi (gli scope) e crei il webhook. Puoi anche impostare una data di scadenza.

Se la voce non c'è, serve un amministratore: in Impostazioni, Sicurezza, Integrazioni Bitrix24 c'è il campo «Chi può creare webhook in entrata». Tieni presente che alcuni metodi non sono disponibili via webhook.

L'indirizzo

Il formato è https://<portale>/rest/<id utente che ha creato il webhook>/<codice segreto>/<metodo>.json, e il .json finale è facoltativo. Le richieste valgono entro i permessi scelti e con i diritti di quell'utente. Quindi, se vuoi che il tuo sistema non possa toccare le fatture, non dargli lo scope delle fatture e, soprattutto, crea il webhook con un utente che ha diritti ridotti, non con l'amministratore.

Questa è una chiamata di esempio, con un indirizzo finto, che cerca i doppioni per email:

curl -s "https://tuo-portale.bitrix24.it/rest/1/xxxxxxxx/crm.duplicate.findbycomm.json" \
  --data-urlencode "type=EMAIL" \
  --data-urlencode "values[0]=mario.rossi@tuo-negozio.it" \
  --data-urlencode "entity_type=CONTACT"

Il metodo crm.duplicate.findbycomm accetta type EMAIL o PHONE, un elenco values di al massimo 20 elementi e un entity_type facoltativo (LEAD, CONTACT, COMPANY). Restituisce gli ID trovati e non è tra i metodi deprecati. Lo uso prima di creare un contatto, perché i filtri su email e telefono di crm.contact.list funzionano solo con corrispondenza esatta e un doppione per una virgola in più è facile da fare.

La chiave è un segreto

Un webhook con la chiave pubblicata viene bloccato e risponde INVALID_CREDENTIALS. Lo ripristini da Modifica copiando la nuova chiave. La chiave la vede solo chi ha creato il webhook, e se un amministratore modifica il webhook di un altro utente, la chiave viene reimpostata e l'amministratore ne diventa il proprietario. Non metterla nel codice che gira nel browser, non committarla in un repository, tienila in una variabile d'ambiente sul tuo server.

I due sensi. Verso Bitrix24 scrivi e leggi con il webhook in entrata; da Bitrix24 verso di te arrivano gli eventi del webhook in uscita, che il gestore verifica e mette in coda.

Come funziona il webhook in uscita e cosa arriva al tuo server

Il webhook in uscita è il contrario: Bitrix24 chiama te quando succede qualcosa. Lo crei da Developer resources, Casi d'uso comuni, Altro, Webhook in uscita. Indichi l'indirizzo del tuo gestore, che deve essere pubblico (localhost non funziona), e l'evento. Dopo il salvataggio Bitrix24 mostra un «Application token».

Per le trattative gli eventi sono onCrmDealAdd (creata), onCrmDealUpdate (modificata), onCrmDealDelete e onCrmDealMoveToCategory. Bitrix24 invia una richiesta POST application/x-www-form-urlencoded con questi campi: event, data (per il CRM l'ID sta in data[FIELDS][ID]), ts con il timestamp Unix e auth con domain, member_id e application_token.

Il corpo non contiene la trattativa completa, solo l'ID, quindi per i dati veri devi chiamare tu Bitrix24. Di solito il gestore legge i dati veri con una seconda chiamata, usando il webhook in entrata: la documentazione porta come esempio crm.item.get. Conviene farlo nel lavoro in coda e non dentro la risposta all'evento.

Verificare l'application token

Chiunque conosca l'indirizzo del tuo gestore può mandargli una richiesta. La documentazione sugli handler sicuri dice di confrontare auth[application_token] con il valore salvato e, se non coincidono, di rispondere 403 e interrompere l'elaborazione. Il token è un segreto: niente log, niente codice lato browser.

Ecco un gestore PHP minimo. Il token vero sta in una variabile d'ambiente, qui c'è solo il nome:

<?php
// gestore-bitrix24.php: riceve l'evento, verifica il token, mette l'ID in coda
$atteso = (string) getenv('B24_APPLICATION_TOKEN');
$ricevuto = (string) ($_POST['auth']['application_token'] ?? '');

if ($atteso === '' || !hash_equals($atteso, $ricevuto)) {
    http_response_code(403);
    exit;
}

$evento = (string) ($_POST['event'] ?? '');
$id = (int) ($_POST['data']['FIELDS']['ID'] ?? 0);

if ($id > 0) {
    $riga = json_encode(['evento' => $evento, 'id' => $id, 'ts' => (int) ($_POST['ts'] ?? 0)]);
    file_put_contents('/var/lib/tuo-negozio/coda-eventi.jsonl', $riga . "\n", FILE_APPEND | LOCK_EX);
}

http_response_code(200); // risposta subito: i dati si leggono dopo, dal lavoro in coda

Un file di testo come coda ti basta per provare; in produzione usa una tabella o un sistema di code vero. Conta il principio: verifichi, accodi, rispondi.

Nessun nuovo invio

Qui c'è la cosa che ti sorprenderà di più. Se il tuo gestore fallisce, il server delle code di Bitrix24 registra l'errore ma non rimanda l'evento. Gli eventi passano da una coda e possono arrivare con un piccolo ritardo. Con una modifica di massa arriva una chiamata per oggetto: mille trattative modificate sono mille chiamate al tuo gestore.

La documentazione non indica un timeout in secondi per il gestore, quindi non ho un numero da darti: la regola pratica è rispondere subito e lavorare dopo. E poiché un evento perso non torna, ti serve una riconciliazione periodica: un lavoro pianificato che legge da Bitrix24 le trattative modificate dall'ultimo controllo e recupera quello che gli eventi non hanno portato. È la stessa logica di code, nuovi tentativi e riconciliazione che descrivo nella pagina sui connettori API REST.

simulazione · gestore-bitrix24.log
[*] evento onCrmDealUpdate ricevuto, trattativa 4821
[✓] application_token verificato, ID messo in coda
[*] lavoro in coda: lettura dei dati della trattativa 4821
503 QUERY_LIMIT_EXCEEDED, attendo e riprovo
[✓] seconda chiamata riuscita, dati letti
[*] riconciliazione: 50 trattative da aggiornare
[✓] batch da 50 completato
Simulazione. Numeri, nomi e tempi sono di esempio: il comportamento è quello descritto nel testo.

Quali sono i limiti delle API e cosa fare con gli errori

La pagina dei limiti distingue due cose. La prima è la velocità, con un modello a «secchio che perde» (leaky bucket): il piano Enterprise ammette 5 richieste al secondo con soglia 250, gli altri piani 2 richieste al secondo con soglia 50. Se superi la soglia ricevi HTTP 503 con QUERY_LIMIT_EXCEEDED.

La seconda è il limite di risorse: Bitrix24 somma il tempo di esecuzione dei metodi su una finestra scorrevole di 10 minuti, fatta di 10 intervalli da un minuto. Se la superi, la chiamata successiva a quel metodo è bloccata per quell'app o quel webhook con HTTP 429 e OPERATION_TIME_LIMIT. Nel cloud la soglia la stabilisce la configurazione di Bitrix24 e la pagina non dà un numero, quindi non cercarne uno da copiare. Una singola richiesta REST nel cloud deve inoltre finire entro 60 secondi.

Nel tuo codice metti un limitatore di velocità lato tuo, per non arrivare ai 503; se un 503 arriva comunque, attendi e riprova con attese crescenti; con un 429 smetti di chiamare quel metodo per un po' e alleggerisci le richieste, perché il problema è il lavoro che chiedi, non il numero di chiamate.

Le chiamate batch: come raggruppare fino a 50 richieste

Il batch esegue più richieste in una sola chiamata. Il limite è 50 sottorichieste: oltre, la risposta è ERROR_BATCH_LENGTH_EXCEEDED. Il parametro cmd è obbligatorio e halt vale 0 o 1: con 1 il batch si ferma al primo errore, con 0 (il valore predefinito) prosegue. Dalla versione REST 24.0.0 i batch annidati sono vietati.

curl -s "https://tuo-portale.bitrix24.it/rest/1/xxxxxxxx/batch.json" \
  --data-urlencode "halt=0" \
  --data-urlencode "cmd[c1]=crm.contact.add?fields[NAME]=Mario&fields[LAST_NAME]=Rossi&fields[EMAIL][0][VALUE]=mario.rossi@tuo-negozio.it&fields[EMAIL][0][VALUE_TYPE]=WORK" \
  --data-urlencode "cmd[c2]=crm.contact.add?fields[NAME]=Laura&fields[LAST_NAME]=Bianchi&fields[EMAIL][0][VALUE]=laura.bianchi@tuo-negozio.it&fields[EMAIL][0][VALUE_TYPE]=WORK"

Ogni sottorichiesta ha una chiave (c1, c2) e ritrovi il suo esito nella risposta sotto la stessa chiave. Email e telefono in crm.contact.add sono array di VALUE e VALUE_TYPE, con tipi come WORK e HOME. Nei miei lavori il batch è lo strumento che ti consiglio per non finire contro il limite di velocità: cinquanta scritture in una chiamata pesano molto meno di cinquanta chiamate. Tieni presente che in REST 3.0 il formato del batch cambia, quindi rileggi la pagina prima di portare il tuo codice.

Paginazione e grandi volumi

Le liste restituiscono sempre 50 record per pagina. Il parametro start vale (N-1)*50, il campo next indica il valore da passare a start e compare solo se i risultati sono più di 50, mentre total dà il totale.

Per i volumi grandi non scorrere con start, e fai così: la documentazione consiglia di filtrare per ID maggiore dell'ultimo ricevuto, ordinare per ID e usare start uguale a -1, così Bitrix24 non calcola il totale. Per una sincronizzazione completa di un catalogo o di un archivio contatti è il modo che ti risparmia tempo di esecuzione, quindi guarda anche il limite di risorse della sezione precedente.

Metodi classici deprecati e REST 3.0: cosa cambia per il tuo codice

Qui la documentazione è cambiata. crm.deal.add, crm.deal.update, crm.deal.list, crm.contact.add e crm.contact.list sono ancora documentati ma segnati DEPRECATED: «lo sviluppo di questo metodo è stato fermato», e la pagina rimanda al metodo REST 3.0 con lo stesso nome. La panoramica delle trattative aggiunge che i metodi crm.deal.* restano solo per supportare le integrazioni esistenti.

Lo stesso vale per crm.item.add, che resta per i documenti CRM e B2E, e per crm.product.add, sostituito da catalog.product.add. Le righe prodotto di crm.deal.productrows.set hanno come alternativa REST 3.0 crm.deal.productrow.replace, con un'avvertenza: le righe esistenti che non passi al metodo vengono rimosse dalla trattativa.

REST 3.0 ha un indirizzo diverso, https://<portale>/rest/api/<id utente>/<codice webhook>/<metodo>. Le chiamate sono POST con un corpo JSON (la query string non viene letta), i campi sono in camelCase, le righe prodotto si aggiungono dopo con i metodi productrow, e l'intestazione Idempotency-Key serve a evitare i duplicati. La documentazione dice che le due versioni funzionano insieme e non si sostituiscono. Non indica da quando REST 3.0 è disponibile.

Per ora non ti mostro un esempio di corpo JSON di REST 3.0: la pagina di ogni metodo ha i suoi campi e non voglio darti nomi che non ho verificato. Quando scrivi il codice, verifica i nomi dei campi sulla pagina del metodo.

Che cosa fai, allora, se hai già un'integrazione con i metodi classici? Continua a funzionare, quindi non c'è un'urgenza. Per un'integrazione nuova, parti dai metodi REST 3.0 dove esistono e usa i classici solo dove la pagina del metodo non indica un'alternativa, per esempio crm.duplicate.findbycomm.

Quando serve un'applicazione locale con OAuth

Un'app locale funziona solo sul portale in cui la crei, e la scelta ti riguarda se vuoi eventi o token a scadenza. I tipi sono tre: statica, server con interfaccia, server senza interfaccia. L'app statica non riceve eventi: per reagire ai cambiamenti serve un'app server o un webhook in uscita.

Con OAuth 2.0 l'access_token dura un'ora (expires_in 3600) e il refresh_token 180 giorni. Ogni rinnovo restituisce una nuova coppia di token, e devi salvare quella nuova. Se il refresh token scade, l'app va reinstallata. Questo vuol dire che l'app ha un punto in più da sorvegliare: se il rinnovo fallisce per mesi senza che nessuno lo veda, l'integrazione si ferma. Per un connettore su un solo portale preferisco il webhook finché non serve altro.

Passo per passo: la tua prima integrazione con le Bitrix24 API REST

  1. Controlla il piano del portale e chi può creare webhook in entrata.
  2. Crea un utente dedicato con i diritti minimi e con quell'utente il webhook in entrata, scegliendo solo gli scope che servono.
  3. Prova il metodo dal generatore di richieste di Developer resources, poi riproduci la chiamata con curl.
  4. Conserva l'indirizzo del webhook in una variabile d'ambiente del tuo server.
  5. Prima di creare un contatto, cerca i doppioni con crm.duplicate.findbycomm e tieni un registro che lega il tuo codice all'ID in Bitrix24.
  6. Raggruppa le scritture in batch da 50 e metti un limitatore di velocità.
  7. Se ti servono gli eventi, crea il webhook in uscita, salva l'application token e scrivi il gestore che verifica, accoda e risponde.
  8. Aggiungi un lavoro periodico di riconciliazione, perché un evento non consegnato non torna.

Checklist prima di mettere in produzione

  • Il webhook è creato da un utente con diritti ridotti e ha solo gli scope necessari.
  • La chiave e l'application token stanno fuori dal codice e dai log.
  • Il gestore risponde 403 se il token non coincide.
  • Il gestore risponde subito e lascia la lettura dei dati a un lavoro in coda.
  • Una riconciliazione periodica recupera gli eventi persi.
  • Le tue richieste restano sotto le 2 al secondo (5 sul piano Enterprise) e i 503 hanno un nuovo tentativo con attesa.
  • I batch hanno al massimo 50 sottorichieste e non sono annidati.
  • Hai deciso che cosa fare quando un metodo che usi è segnato DEPRECATED.

Errori da evitare

  • Pubblicare la chiave del webhook. Un webhook con la chiave pubblicata viene bloccato e risponde INVALID_CREDENTIALS: ripristinarlo vuol dire cambiare la chiave in tutti i posti dove la usi.
  • Credere che un evento fallito venga rimandato. Non succede: serve la riconciliazione.
  • Leggere i dati nel gestore dell'evento. Se la lettura va in 503, il gestore resta aperto e l'evento è perso.
  • Usare crm.deal.productrows.set con un elenco parziale. Le righe non passate vengono rimosse dalla trattativa.
  • Scorrere centinaia di migliaia di record con start. Per i grandi volumi usa il filtro sull'ID e start a -1.
  • Annidare i batch. Dalla versione REST 24.0.0 non è permesso.
  • Creare il webhook con l'amministratore. Tutto ciò che il tuo sistema fa sarà fatto con i diritti dell'amministratore.

Consigli

Tratta Bitrix24 come un sistema che può rispondere con un errore e che a volte è più lento: scrivi il codice in modo che un 503 sia un caso normale, non un'eccezione. Registra ogni chiamata con il suo esito, senza scrivere nei log la chiave o il token, e tieni un registro che lega ogni tuo codice all'ID in Bitrix24: è quello che in Ready2Bitrix mi evita i doppioni.

Se parti adesso con un'integrazione nuova, leggi la pagina di ogni metodo prima di usarlo: se è segnato DEPRECATED ti dice qual è l'alternativa. E poiché la documentazione non è datata, annota la data in cui l'hai letta.

Domande frequenti

Che differenza c'è tra webhook in entrata e in uscita?

Il webhook in entrata è un indirizzo con una chiave che usi tu per chiamare Bitrix24, con i diritti dell'utente che lo ha creato. Per te è la porta d'ingresso. Il webhook in uscita funziona al contrario: Bitrix24 manda una richiesta POST al tuo indirizzo quando avviene un evento, per esempio la modifica di una trattativa.

Dove trovo l'URL del webhook e quali permessi servono?

In Developer resources, Casi d'uso comuni, Altro, Webhook in entrata. L'indirizzo ha la forma https://<portale>/rest/<id utente>/<codice segreto>/<metodo>.json. I permessi li scegli in «Assegna permessi»: dagli solo gli scope che il tuo sistema usa davvero.

Quali sono i limiti delle API e cosa faccio con gli errori?

Sul piano Enterprise 5 richieste al secondo con soglia 250, sugli altri piani 2 al secondo con soglia 50. Oltre la soglia arriva un 503 QUERY_LIMIT_EXCEEDED: attendi e riprova. Un 429 OPERATION_TIME_LIMIT indica che il tempo di esecuzione dei metodi ha superato il limite di risorse, e nel cloud la pagina non dà il numero.

Meglio crm.lead.add o i metodi nuovi?

Nella documentazione che ho letto a novembre 2026 sono segnati DEPRECATED i metodi delle trattative e dei contatti (crm.deal.*, crm.contact.add e crm.contact.list) e anche crm.item.add. La pagina di crm.lead.add rimanda a crm.item.add, che a sua volta rimanda a REST 3.0. Per trattative e contatti i metodi REST 3.0 hanno lo stesso nome e oggi convivono con i classici. Per un'integrazione nuova ti consiglio REST 3.0; controlla comunque la pagina del metodo che ti serve.

Webhook o applicazione OAuth?

Per un solo portale e un flusso semplice, a te basta il webhook. L'app locale ha senso quando ti serve l'autenticazione OAuth, con un access_token di un'ora e un refresh_token di 180 giorni da rinnovare. Se devi ricevere eventi, ti basta un webhook in uscita oppure un'app server.

Le API sono nel piano gratuito?

Secondo l'helpdesk italiano di Bitrix24, aggiornato il 30 ottobre 2026, webhook e applicazioni si creano solo con un piano a pagamento. Verifica sul tuo portale, perché i piani cambiano e la condizione che ti riguarda è quella attuale.

Considerazioni finali

Il punto che cambia il modo di scrivere il codice è uno: gli eventi non si rimandano, quindi ogni integrazione seria ha una coda e una riconciliazione. Il resto, limiti, batch e metodi deprecati, si gestisce con un po' di disciplina. Se vuoi che ti aiuti a costruire o a rivedere un connettore, guarda il servizio API REST e connettori su misura oppure scrivimi dai contatti con il portale, il sistema da collegare e i metodi che usi oggi. Per vedere un'integrazione già in funzione, leggi il progetto Ready2Bitrix; se ti interessa il lato eBay e magazzino, c'è la sincronizzazione tra WooCommerce ed eBay.

Fonti

Pagine lette a novembre 2026.

Condividi LinkedIn Facebook X WhatsApp Telegram Email
Cybersecurity per PMI

Quanto è esposta la tua azienda?

Un hacker etico certificato trova le falle prima di chi attacca e ti dice come chiuderle, partendo dalla più pericolosa.

Marketing & Google Ads

Le tue campagne stanno bruciando budget?

Raccontami obiettivi e numeri attuali: ti dico dove intervenire per primo.

Coding & debugging

Codice scritto con l’AI? Funziona oggi. Reggerà domani?

Audit del debito tecnico e della sicurezza di app e siti, debugging e code review.

iLife · crescita personale

Riprogramma la tua vita con il metodo di un hacker etico

Percorsi one-to-one per capire dove sei, scegliere la direzione e arrivarci con metodo.

Digital Agency

Dove sta frenando il tuo business?

Una consulenza per capire cosa sistemare prima: sicurezza, tecnologia, marketing o persone.

Continua a leggere

Tutti gli articoli del blog

Rocco Balzamà
Parli direttamente con me

Il prossimo passo?
Parliamone.

Raccontami cosa vuoi proteggere, costruire o far crescere. Ti aiuto a capire da dove partire.

Di cosa mi occupo

Da oltre trent'anni faccio tre cose. Cerco le falle della tua azienda prima che le trovi chi vuole entrare. Imposto il marketing perché i risultati si possano misurare. E aiuto persone e aziende a capire chi sono, prima ancora di decidere cosa vendere.

Da remoto e in presenzaLavoro da remoto tramite call e videocall. Quando il progetto lo richiede, intervengo anche in presenza.
Seguimi sui social
Certified Ethical HackerSicurezza informatica dal 1993
Gli strumenti con cui lavoro
  • Google Ads
  • Meta
  • WordPress
  • WooCommerce
  • Shopify
  • TikTok
Strumenti gratuiti