Con Connectif puoi registrare gli acquisti che i tuoi clienti effettuano nei tuoi negozi fisici per registrarli nella loro scheda contatto e disporre di uno storico unificato tra le loro azioni online e offline. In questo modo, potrai utilizzare queste informazioni per personalizzare le tue strategie utilizzando lo storico completo degli acquisti di ogni cliente, indipendentemente dal canale in cui sono stati effettuati.
In questo articolo imparerai come integrare gli acquisti da negozi fisici tramite l’API di Connectif affinché vengano registrati nella scheda di ogni contatto.
Per utilizzare l’integrazione tramite API, avrai bisogno di un esperto con conoscenze di programmazione. Se necessiti di maggiori informazioni, consulta la documentazione dell’API di Connectif.
Prima di iniziare
Per poter effettuare questa integrazione, dovrai avere coperti i seguenti aspetti:
- Email come chiave primaria: il contatto deve esistere nel tuo database Contatti di Connectif, con un’email associata come chiave primaria. Sebbene l’API supporti altri identificatori (come codice fiscale o telefono), usarli come identificatore principale provocherebbe la creazione di contatti duplicati.
- Catalogo e prodotti sincronizzati: tutti i prodotti inclusi nell’acquisto offline devono esistere nel tuo catalogo Connectif. Se un articolo viene venduto esclusivamente nei negozi fisici e non fa parte del sito web, dovrai crearlo in Connectif con lo stato Discontinuato per poter collegare la vendita offline.
- Informazioni sui prodotti: è consigliabile inviare le informazioni complete dei prodotti inclusi nell’acquisto, in particolare l’attributo categories. In questo modo potrai creare segmenti di prodotto e utilizzare queste informazioni nelle tue strategie automatizzate.
- Struttura rigorosa della richiesta: la richiesta può includere solo gli attributi supportati dal modello dell’API. Non è possibile inviare campi personalizzati o attributi aggiuntivi all’interno del JSON.
Scopri come funziona l’API di Connectif in questo articolo.
PASSO 1. Preparazione dei contatti in Connectif
(In questa sezione si spiega come preparare i tuoi contatti in Connectif affinché possano essere correttamente collegati all’acquisto offline).
Puoi aggiungere i contatti a Connectif tramite un’importazione da file o tramite l’API.
Quando registri un acquisto offline tramite API, Connectif assocerà le informazioni inviate ai contatti e prodotti esistenti. L’API non li creerà durante il processo, quindi dovrai verificare in anticipo che siano già creati in Connectif.
1. Verifica che il contatto esista già in Connectif con la sua email registrata. In caso contrario, crealo prima per poter collegare correttamente l’attività.
2. Nel campo di ricerca, inserisci l’email del contatto per verificarne l’esistenza. Se il contatto non esiste, dovrai crearlo per poter associare l’acquisto al suo storico.
Scopri come importare contatti in questo articolo.
PASSO 2. Preparazione dei prodotti in Connectif
(In questa sezione si spiega come preparare i tuoi prodotti in Connectif affinché possano essere correttamente collegati all’acquisto offline).
Puoi aggiungere i prodotti a Connectif tramite un’importazione da file o tramite l’API.
3. Accedi a "E-commerce > Catalogo" e clicca sul pulsante delle opzioni .
4. Se uno degli articoli associati all’acquisto offline non esiste in Connectif, crealo prima di importare l’acquisto, per farlo:
-
Clicca su Crea prodotto.
-
Completa, almeno, i campi obbligatori del prodotto (nome, ID, URL dettaglio e prezzo).
- Se il prodotto è venduto solo nei negozi fisici, assegnagli lo stato Discontinuato, in modo che l’acquisto offline possa essere registrato ma il prodotto non venga mostrato nel negozio online.
L’URL dettaglio è obbligatoria, anche se il prodotto non esiste sul sito web o è contrassegnato come Discontinuato. In questi casi, inserisci un URL che utilizzi lo stesso dominio registrato nel tuo negozio Connectif per evitare errori di validazione. Per esempio, se il dominio del tuo negozio è https://www.midominio.com, puoi utilizzare come URL dettaglio: https://www.midominio.com/prodotti/SKU-12345.
PASSO 3. Creazione della chiave API
5. Accedi a Impostazioni negozio nel menu laterale sinistro di Connectif.
6. Nella selezione delle schede, vai su "API e accessi IP" e clicca su API Keys.
7. Clicca sul pulsante Crea nuova API Key.
8. Nella sezione Acquisti del pannello di creazione, abilita i permessi per Leggere, Scrivere e Cancellare in modo massivo.
Se gestirai anche contatti e prodotti tramite API, abilita i permessi corrispondenti nelle sezioni Contatti e Prodotti.
9. Salva la chiave API e copiala per utilizzarla successivamente nel tuo script di automazione.
PASSO 4. Registrazione dell’acquisto tramite API
(In questa sezione si spiega come preparare l’invio delle informazioni dell’acquisto a Connectif tramite API).
Per registrare un acquisto offline, dovrai effettuare una richiesta HTTP POST che invierà le informazioni dell’acquisto a Connectif in formato JSON.
10. Crea lo script di automazione dal tuo sistema e includi in esso la API Key generata nel passo precedente.
11. Configura nello script una richiesta HTTP POST per registrare l’acquisto in Connectif: https://api.connectif.cloud/purchases/
Nella richiesta, indica:
- La API Key per autenticare la chiamata.
- Il tipo di contenuto application/json.
- Le informazioni dell’acquisto nel corpo della richiesta.
12. Crea le informazioni dell’acquisto da inviare e verifica che soddisfino le seguenti condizioni:
- Includi gli attributi obbligatori dell’acquisto: cartId, products, purchaseDate, purchaseId, totalPrice e totalQuantity.
- Identifica il contatto tramite contactEmail.
- Per ogni prodotto incluso in products, completa gli attributi obbligatori: name, price, productDetailUrl, productId, quantity e unitPrice.
- Per registrare l’acquisto come proveniente da un negozio fisico, configura sourceType con il valore point-of-sale e indica il negozio o filiale in sourceName.
- Assicurati che purchaseId sia l’identificatore unico dell’acquisto.
Scopri come elaborare la struttura completa della richiesta nella documentazione dell’API.
Esempio
Una volta creata, la richiesta avrà un aspetto simile a questo:
const apiKey = "TU_API_KEY";
const url = "https://api.connectif.cloud/purchases/";
const purchase = {
contactEmail: "cliente@esempio.com",
purchaseId: "POS-20260804-001",
cartId: "POS-20260804-001",
purchaseDate: "2026-08-04T15:30:00Z",
sourceType: "point-of-sale",
sourceName: "Negozio Centro",
products: [
{
productId: "SKU-12345",
name: "Scarpa Running",
categories: ["Calzature/Running"],
quantity: 2,
unitPrice: 39.95,
price: 79.90,
productDetailUrl: "https://www.midominio.com/prodotti/SKU-12345"
}
],
totalQuantity: 2,
totalPrice: 79.90
};
async function main() {
const response = await fetch(url, {
method: "POST",
headers: {
"Authorization": `apiKey ${apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify(purchase)
});
const result = await response.json();
console.log(result);
}
main();
Lo script registra un acquisto effettuato in un negozio fisico e lo associa al contatto indicato nell’attributo contactEmail. Gli attributi sourceType e sourceName identificano il punto vendita fisico e il nome della sede di origine.
Successo!
L’importazione degli acquisti dai negozi fisici è ora pronta.
Continua a imparare!
Per sfruttare tutto il potenziale del tuo account Connectif, ti consigliamo di continuare con i seguenti articoli:
- Integrazioni via API, per gestire eventi come registrazioni di acquisti o aggiunte di contatti.
- Integrazione personalizzata per inviare dati da Connectif, per inviare informazioni in tempo reale tramite Webhooks.
- Importazione di contatti, per importare manualmente contatti in Connectif.
- Esportazione di contatti e attività, per esportare contatti ed eventi da Connectif.