Venditore Digitale — API

Versione 1.0 · sola lettura · una chiave per azienda

Queste API espongono in lettura i dati del Venditore Digitale della tua azienda: contatti, venditori, opportunità, azioni e le tabelle che servono a interpretarli. Servono ad alimentare automazioni esterne — CRM, flussi di ricontatto, cruscotti.

Indirizzo e versione

https://europe-west1-app-venditore-digitale.cloudfunctions.net/api/1.0

Tutte le rotte sono in GET. Un metodo diverso risponde 405 No method.

Autenticazione

Ogni chiamata richiede l’header authorization con la API key della tua azienda.

authorization: LA-TUA-API-KEY

La chiave va passata nuda. Niente Bearer, niente ApiKey, nessun prefisso: il valore viene confrontato tale e quale, spazi compresi.

La chiave identifica l’azienda: ogni risposta contiene soltanto i dati di quell’azienda, e non esiste modo di leggere quelli di un’altra. La trovi nel backoffice, in Aziende → la tua azienda → Api, oppure la chiedi a PowerApp.

Trattala come una password: chi ce l’ha legge l’intera anagrafica contatti. Tienila fuori dal codice sorgente e da qualunque pagina pubblica.

Formato della risposta

Tutte le rotte rispondono con lo stesso involucro:

{
  "success": true,
  "message": "",
  "code": 200,
  "meta": 500,
  "data": [ ... ]
}

campo	significato
`success`	esito della chiamata
`message`	vuoto quando va bene, il motivo quando fallisce
`code`	ripete lo status HTTP
`meta`	quanti elementi ci sono in questa pagina
`data`	i dati

meta non è il totale. È il numero di elementi restituiti dalla chiamata che hai appena fatto. Un conteggio complessivo non è esposto da nessuna rotta: se ti serve, lo ottieni solo scorrendo tutte le pagine.

Errori

Gli errori usano lo stesso involucro con success: false. Lo status HTTP coincide sempre con il campo code.

HTTP	`message`	causa
405	No method	metodo diverso da GET
401	No authorization	header `authorization` assente o vuoto
400	No company found. Wrong Api Key	la chiave non corrisponde a nessuna azienda
400	No customerId · No projectId	manca un parametro obbligatorio
400	No customer found · No project found	l’id passato non esiste o non è della tua azienda
400	Group not found · Temperature not found	valore fuori dalla lista ammessa
500	—	errore imprevisto; la risposta contiene anche `"error": true`

Paginazione

La paginazione è a cursore, non per numero di pagina.

parametro	significato
`size`	quanti elementi per pagina. Default 500
`lastDocument`	l’`id` dell’ultimo elemento ricevuto: la pagina riparte da lì

# prima pagina
curl -H "authorization: LA-TUA-API-KEY" \
  ".../api/1.0/contacts?size=200"

# pagine successive: si passa l’id dell’ultimo elemento ricevuto
curl -H "authorization: LA-TUA-API-KEY" \
  ".../api/1.0/contacts?size=200&lastDocument=ID-ULTIMO-ELEMENTO"

Si continua finché data non torna vuoto.

size e lastDocument funzionano solo su quattro rotte: /contacts, /customers, /projects, /actions.
Su /origins e /sectors sono accettati ma ignorati: la risposta è sempre la lista completa. Su /groups, /states, /temperatures e /info non vengono nemmeno letti. Non scrivere cicli di paginazione su queste rotte.

GET/1.0/info

I dati anagrafici e di configurazione della tua azienda. Nessun parametro.

È anche la chiamata di prova: se risponde 200, la chiave è valida.

curl -H "authorization: LA-TUA-API-KEY" ".../api/1.0/info"

GET/1.0/customers

Gli utenti dell’azienda, cioè i venditori. Ordinati per data di inserimento decrescente, paginati.

È il punto di partenza: l’id di un customer serve a /projects e come filtro su /contacts.

parametro		significato
`size`	opz.	elementi per pagina (default 500)
`lastDocument`	opz.	cursore

GET/1.0/contacts

I contatti dell’azienda. È la rotta principale e l’unica con filtri veri. Nessun parametro è obbligatorio: la chiamata nuda funziona.

parametro		significato
`customerId`	opz.	solo i contatti di un venditore. Se l’id non è della tua azienda → `400 No customer found`
`group`	opz.	gruppo del contatto. Ammessi solo 0, 1, 2, 8 (vedi /groups); altri valori → `400 Group not found`
`temperature`	opz.	temperatura: 1, 2, 3 (vedi /temperatures)
`win`	opz.	`true` = solo le opportunità a punteggio pieno (100)
`startDate`	opz.	data minima, `GG-MM-AAAA` oppure `GG-MM-AAAA HH:mm`
`endDate`	opz.	data massima, stesso formato. La giornata indicata è inclusa per intero
`byUpdateDate`	opz.	su quale data agiscono i due filtri sopra: `true` (default) = ultima modifica, qualsiasi altro valore = data di creazione
`originId`	opz.	id di una provenienza (vedi /origins)
`sectorId`	opz.	id di un settore (vedi /sectors)
`projectName`	opz.	nome dell’opportunità corrente. Cerca per inizio di parola, non per sottostringa
`noGroupId`	opz.	esclude un gruppo. `noGroupId=5` toglie i cancellati
`size` · `lastDocument`	opz.	paginazione

win non si disattiva con false. Qualsiasi valore diverso da true — compresi false, 0, no — è un filtro attivo che restituisce le opportunità con punteggio diverso da 100. Per non filtrare, ometti il parametro.

Una data scritta male non dà errore. Se startDate o endDate non sono nel formato atteso, il filtro viene ignorato in silenzio e ricevi tutti i record. Controlla il numero di risultati, non solo lo status.

originId e sectorId non sono validati: un id inesistente non dà errore, restituisce zero contatti.

Campi principali di un contatto

campo	significato
`id`	identificativo, e valore da usare come `lastDocument`
`name` · `surname` · `companyName`	nome, cognome, azienda
`email` · `phone` · `city`	recapiti
`stateId`	0 = Contatto, 1 = Cliente (vedi /states)
`group`	Attivi / Persi / Inattivi / Vinti
`score`	punteggio dell’opportunità corrente
`currentProject` · `currentProjectId`	l’opportunità in corso
`customerId`	il venditore a cui è assegnato
`sector` · `sectorTagId` · `originTagId`	settore e provenienza
`insertDate` · `updateDate`	creazione e ultima modifica
`comment`	note libere

GET/1.0/projects

Le opportunità correnti dei contatti assegnati a un venditore.

parametro		significato
`customerId`	OBBLIGATORIO	id del venditore, da /customers
`size` · `lastDocument`	opz.	paginazione

Senza customerId risponde 400 No customerId. È la causa più comune di errore su questa rotta: non è la chiave a essere sbagliata.

curl -H "authorization: LA-TUA-API-KEY" \
  ".../api/1.0/projects?customerId=ID-VENDITORE"

Qui lastDocument è l’id di un contatto, non di un’opportunità: la lista scorre i contatti del venditore.

GET/1.0/actions

Le azioni registrate su un’opportunità: email, messaggi, telefonate, social, eventi, incontri. Ordinate dalla più recente.

parametro		significato
`projectId`	OBBLIGATORIO	id dell’opportunità, da /projects
`size` · `lastDocument`	opz.	paginazione

Senza projectId risponde 400 No projectId.

GET/1.0/groups

I gruppi del contatto. Lista fissa, uguale per tutte le aziende. Nessun parametro.

id	etichetta
0	Attivi
1	Persi
2	Inattivi
8	Vinti

Sono anche gli unici valori accettati dal filtro group di /contacts.

GET/1.0/states

Lo stato del contatto. Lista fissa, nessun parametro.

id	etichetta
0	Contatto
1	Cliente

GET/1.0/temperatures

La temperatura, calcolata sul punteggio dell’opportunità corrente. Lista fissa, nessun parametro.

id	etichetta	punteggio
1	Freddi	fino a 33
2	Tiepidi	da 34 a 66
3	Caldi	oltre 66

La temperatura 0 non esiste. Passare ?temperature=0 a /contacts dà 400 Temperature not found. Per «tutte», ometti il parametro.

GET/1.0/origins

Le provenienze censite dalla tua azienda (passaparola, sito web, fiera…): sono i valori del campo originTagId dei contatti e gli id validi per il filtro originId.

Lista sempre completa, non paginata.

GET/1.0/sectors

I settori censiti dalla tua azienda: gli id validi per il filtro sectorId.

Lista sempre completa, non paginata.

Qui il nome del settore sta nel campo sector, non in name come nelle altre liste.

La catena delle chiamate

Tre rotte si concatenano: l’id di una serve alla successiva.

/1.0/customers                 →  id del venditore
        ↓
/1.0/projects?customerId=...   →  id dell’opportunità
        ↓
/1.0/actions?projectId=...     →  le azioni

Se salti un passaggio ottieni un 400 che dice quale parametro manca.

Ricette

I contatti che non hanno ancora comprato

Sono quelli nel gruppo Attivi con stato Contatto:

curl -H "authorization: LA-TUA-API-KEY" \
  ".../api/1.0/contacts?group=0&size=200"

Nella risposta tieni quelli con stateId = 0: chi ha stateId = 1 è già diventato cliente.

Chi si è mosso in un periodo

curl -H "authorization: LA-TUA-API-KEY" \
  ".../api/1.0/contacts?startDate=01-08-2026&endDate=31-08-2026"

Il filtro agisce sull’ultima modifica. Per i contatti creati nel periodo aggiungi &byUpdateDate=false.

Scaricare tutto, a pagine

ID=""
while :; do
  URL=".../api/1.0/contacts?size=500"
  [ -n "$ID" ] && URL="$URL&lastDocument=$ID"
  R=$(curl -s -H "authorization: LA-TUA-API-KEY" "$URL")
  N=$(echo "$R" | jq '.data | length')
  [ "$N" = "0" ] && break
  echo "$R" | jq -c '.data[]'
  ID=$(echo "$R" | jq -r '.data[-1].id')
done

Prima di segmentare per settore

Normalizza le maiuscole. Nel campo sector possono convivere grafie diverse dello stesso settore (per esempio Kit e kit): se raggruppi sul valore grezzo, lo stesso settore si spacca in due.