REST API

PrimoCRM registra le sue route REST sotto il namespace primocrm/v1 durante rest_api_init. L’app di amministrazione utilizza questi stessi endpoint, quindi tutto ciò che fa l’interfaccia utente è disponibile a livello di programmazione.

URL di base

https://yoursite.com/wp-json/primocrm/v1/

Autenticazione

Ogni endpoint dispone di un callback di autorizzazione che verifica una capability di WordPress, quindi chi effettua la chiamata deve essere autenticato e autorizzato.

• Dall’app di amministrazione (stessa origine): le richieste vengono autenticate dalla sessione dell’utente connesso e da un nonce REST. WordPress invia il nonce nell’header X-WP-Nonce. Questo processo è automatico per il codice in esecuzione all’interno di wp-admin.
• Da codice esterno: utilizza un metodo di autenticazione accettato da WordPress per le REST API, come le password per le applicazioni, insieme a un utente che possiede la capability richiesta. PrimoCRM Pro aggiunge chiavi API dedicate per l’accesso programmatico.

Gli endpoint che gestiscono impostazioni, invii o operazioni distruttive richiedono una capability di livello amministratore. Le operazioni di lettura e la gestione ordinaria dei contatti richiedono la capability di accesso al CRM.

Endpoint rappresentativi

L’elenco sottostante costituisce un campione rappresentativo e non esaustivo. Esplora l’insieme completo dalla scheda di rete del browser mentre utilizzi l’app di amministrazione, poiché l’interfaccia utente richiama le stesse route.

Contatti

Metodo	Percorso	Scopo
GET	/contacts	Elenca i contatti (supporta paginazione e filtri)
POST	/contacts	Crea un contatto
GET	/contacts/{id}	Ottieni un singolo contatto
PUT	/contacts/{id}	Aggiorna un contatto
DELETE	/contacts/{id}	Elimina un contatto
POST	/contacts/bulk-action	Applica un’azione di massa a molti contatti
POST	/contacts/bulk-delete	Elimina molti contatti
GET	/contacts/statuses	Elenca gli stati disponibili
GET	/contacts/{id}/activities	Registro delle attività di un contatto
GET	/contacts/{id}/emails	Email inviate a un contatto

Automazioni

Metodo	Percorso	Scopo
GET	/automations/triggers	Tutti i trigger registrati
GET	/automations/actions	Tutte le azioni registrate
GET	/automations/condition-options	Campi e operatori per il generatore di condizioni

Form e smart code

Metodo	Percorso	Scopo
GET	/forms/field-types	Tutti i tipi di campo dei form registrati
GET	/smart-codes	Il catalogo dei tag di personalizzazione

Campagne, sequenze, liste, tag, template, migrazione e impostazioni espongono ciascuno le proprie route sotto lo stesso namespace, seguendo lo stesso schema dei controller.

Esempio di richiesta

Creazione di un contatto con autenticazione tramite password per applicazioni:

curl -X POST https://yoursite.com/wp-json/primocrm/v1/contacts \
  -u "admin:APPLICATION_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com","first_name":"Ada","status":"subscribed"}'

Struttura della risposta e limitazioni

Le risposte riuscite restituiscono JSON. Quando una funzionalità Pro o un limite del piano blocca una richiesta, PrimoCRM restituisce un 403 il cui corpo include pro_lock: true, che l’app di amministrazione utilizza per mostrare l’invito all’aggiornamento. Gestisci questa struttura se richiami endpoint protetti da licenza Pro dal tuo codice.

Attenzione

Tratta le REST API come qualsiasi superficie privilegiata. Concedi l’accesso API solo a utenti di fiducia, utilizza HTTPS e non esporre mai le credenziali nel codice lato client.