Integrazione API in WordPress: collegare il sito al CRM senza appesantire il database

Il sito web e il CRM sono due sistemi che dovrebbero parlarsi, ma nella maggior parte delle aziende non lo fanno. Il form di contatto manda un'email che qualcuno ricopia a mano nel CRM. L'ordine WooCommerce non aggiorna il contatto. Il risultato: dati duplicati, lead persi, tempo sprecato. L'integrazione via API risolve il problema, ma fatta male può appesantire WordPress e rallentare tutto.

L'errore più comune è sincronizzare in modo sincrono: quando l'utente invia il form, WordPress chiama l'API del CRM e aspetta la risposta prima di mostrare la pagina di conferma. Se il CRM è lento, l'utente aspetta. Se il CRM è giù, il form fallisce. Il pattern corretto è asincrono: WordPress salva il dato e lo invia al CRM in background, senza bloccare l'utente.

Il pattern: webhook in uscita asincrono

Quando un evento succede su WordPress (nuovo lead, nuovo ordine, registrazione utente), invece di chiamare subito l'API esterna, si accoda un'azione. WordPress risponde all'utente immediatamente, e un processo separato invia i dati al CRM. Il modo più semplice in WordPress è usare wp_schedule_single_event o un hook asincrono:

<?php
// Quando un form viene inviato, accoda la sincronizzazione CRM
add_action( 'wp_planet_lead_created', function( $lead_data ) {
    // Salva il lead in una coda per invio asincrono
    wp_schedule_single_event( time(), 'wp_planet_sync_crm', array( $lead_data ) );
}, 10, 1 );

// Il processo che invia effettivamente al CRM (in background)
add_action( 'wp_planet_sync_crm', function( $lead_data ) {
    $response = wp_remote_post( 'https://api.crm-esterno.com/contacts', array(
        'headers' => array(
            'Authorization' => 'Bearer ' . CRM_API_TOKEN,
            'Content-Type'  => 'application/json',
        ),
        'body'    => wp_json_encode( $lead_data ),
        'timeout' => 15,
    ) );

    if ( is_wp_error( $response ) ) {
        error_log( 'CRM sync fallita per lead: ' . $lead_data['email'] );
        // Riprova più tardi o salva in una tabella di retry
    }
} );

Webhook in entrata: il CRM chiama WordPress

L'altra direzione: il CRM aggiorna lo stato di un lead e vuole notificare WordPress. Si espone un endpoint tramite la REST API di WordPress che il CRM può chiamare:

<?php
// Registra un endpoint REST che il CRM può chiamare
add_action( 'rest_api_init', function() {
    register_rest_route( 'wp-planet/v1', '/crm-webhook', array(
        'methods'  => 'POST',
        'callback' => 'wp_planet_handle_crm_webhook',
        'permission_callback' => 'wp_planet_verify_crm_signature',
    ) );
} );

function wp_planet_verify_crm_signature( $request ) {
    $signature = $request->get_header( 'x-crm-signature' );
    $body = $request->get_body();
    $expected = hash_hmac( 'sha256', $body, CRM_WEBHOOK_SECRET );
    if ( ! hash_equals( $expected, $signature ?? '' ) ) {
        return new WP_Error( 'invalid_signature', 'Firma non valida', array( 'status' => 401 ) );
    }
    return true;
}

Non duplicare i contatti

Il problema più fastidioso delle integrazioni CRM è la duplicazione: lo stesso lead entra due volte perché ha compilato il form due volte, o perché il webhook è arrivato due volte. La soluzione è usare un identificatore stabile (l'email, normalizzata in minuscolo) e fare un upsert invece di un insert puro: cerca prima il contatto esistente, aggiornalo se esiste, crealo se non esiste.

A livello di WordPress, conviene tenere un log minimale degli invii riusciti in una tabella custom leggera (lead_id, email, crm_contact_id, sync_status, timestamp), non i dati completi del lead. Il CRM è il sistema di verità per i dati del contatto; WordPress deve solo sapere se l'ha già sincronizzato. Questo tiene il database di WordPress leggero.

Tracciamento della provenienza

Un'integrazione utile passa anche i dati di tracciamento: UTM source, medium, campaign, la pagina di provenienza, il servizio richiesto. Questi dati permettono al CRM di attribuire correttamente il lead e di misurare quale canale produce contatti qualificati. Vanno catturati lato browser (nei campi nascosti del form) e passati nel payload dell'API, non ricostruiti lato server dove non sono disponibili.

Un'integrazione API ben fatta è invisibile per l'utente — il form risponde subito, i dati arrivano al CRM, niente si duplica — e misurabile per il business. È uno dei lavori di sviluppo personalizzato che produce più valore rispetto al costo, perché collega il sito agli strumenti che l'azienda usa davvero.