REST API

PrimoCRM registra le proprie route REST sotto il namespace primocrm/v1 su rest_api_init. L’applicazione di amministrazione utilizza questi stessi endpoint, quindi tutto ciò che fa l’interfaccia utente è disponibile programmaticamente.

URL di base

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

Autenticazione

Ogni endpoint possiede un callback di autorizzazione che verifica una capability di WordPress, pertanto un chiamante deve essere autenticato e autorizzato.

• Dall’applicazione di amministrazione (stessa origine): le richieste vengono autenticate dalla sessione dell’utente connesso e da un nonce REST. WordPress invia il nonce nell’intestazione 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 API REST, 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 amministrativo. 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 durante l’utilizzo dell’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}	Ottiene un 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	Il log 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 pattern del controller.

Esempio di richiesta

Creazione di un contatto con autenticazione tramite application-password:

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

Le risposte riuscite restituiscono JSON. Gli errori restituiscono un corpo JSON con un message che puoi mostrare a una persona e uno stato HTTP che indica il problema riscontrato: 400 per input rifiutati dall’endpoint, 401 o 403 quando la richiesta non è autorizzata (utente non connesso o privo della capability), 404 quando l’elemento non esiste.

PrimoCRM non prevede limiti di piano né endpoint bloccati. Una route aggiunta da un altro plugin, come quelle di PrimoCRM Pro, esiste solo finché quel plugin è attivo; senza di esso la route restituisce 404. Il salvataggio di qualcosa che nessun elemento del sito fornisce, ad esempio un trigger di automazione il cui plugin non è installato o un provider di posta non registrato, viene rifiutato con un errore 400 e un messaggio esplicativo.

Attenzione

Tratta le API REST come qualsiasi area privilegiata. Concedi l’accesso alle API esclusivamente a utenti fidati, utilizza HTTPS e non esporre mai le credenziali nel codice lato client.