API Leadflow: invio dei lead

Introduzione

L'API è REST su HTTPS, con corpo e risposte JSON in UTF-8. Ogni chiamata è autenticata con una chiave API legata a un'azienda: i lead creati con una chiave appartengono a quell'azienda e prendono la provenienza associata alla chiave.

Autenticazione

La chiave API va inviata a ogni chiamata, in uno di questi modi (in ordine di preferenza):

Authorization: Bearer <CHIAVE>
X-Api-Key: <CHIAVE>
https://leadflow.deskpilotapp.cloud/service.php?action=lead_nuovo&token=<CHIAVE>

Il parametro token nella query è previsto solo per i sistemi che non permettono di impostare intestazioni. Una chiave mancante, errata o disattivata produce 401. La chiave consente solo la creazione di lead e la lettura delle provenienze della propria azienda.

Non includere la chiave nel codice eseguito dal browser: le chiamate vanno fatte dal tuo server.

POST lead_nuovo

Crea un lead. Se il lead esiste già (vedi Idempotenza e doppioni) non ne crea uno nuovo.

POST https://leadflow.deskpilotapp.cloud/service.php?action=lead_nuovo

Il lead creato entra nella coda delle chiamate dell'azienda senza un operatore assegnato.

Parametri

Obbligatori: nome, cognome o ragione_sociale (almeno uno) e cellulare, telefono_fisso o email (almeno uno). I campi sconosciuti vengono ignorati; i valori più lunghi del massimo vengono troncati.

Risposta

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "success": true,
  "data": { "esito": "inserito", "lead_id": 1234 },
  "error": null,
  "code": 200
}

HTTP/1.1 422 Unprocessable Entity

{"success": false, "data": null, "error": "Servono il nome (o la ragione sociale) e almeno un recapito", "code": 422}

Codici di stato

Idempotenza e doppioni

• Idempotenza: se invii id_esterno, una seconda richiesta con lo stesso valore e la stessa chiave non crea nulla e risponde gia_ricevuto con il lead_id originale. Usalo sempre se il tuo sistema può ritentare l'invio.
• Doppioni: se nell'azienda esiste già un lead con lo stesso cellulare (confrontato senza spazi, simboli e prefisso +39) o la stessa email, non viene creato un nuovo lead: la richiesta viene aggiunta allo storico del lead esistente e la risposta è doppione.

GET fonti

Restituisce le provenienze attive dell'azienda della chiave, utilizzabili nel campo fonte.

GET https://leadflow.deskpilotapp.cloud/service.php?action=fonti

{"success": true, "data": [{"id": 1, "nome": "Sito web"}, {"id": 2, "nome": "Portale"}], "error": null, "code": 200}

Esempi

cURL

curl -X POST 'https://leadflow.deskpilotapp.cloud/service.php?action=lead_nuovo' \
  -H 'Authorization: Bearer test_leadflow_b9f4a574b6d50d00a2cb00eb' \
  -H 'Content-Type: application/json' \
  -d '{
    "nome": "Mario",
    "cognome": "Rossi",
    "cellulare": "+39 333 1234567",
    "email": "mario.rossi@example.com",
    "provincia": "MI",
    "interesse": "Corso di grafica",
    "campagna": "Autunno 2026",
    "id_esterno": "ORD-1001"
  }'

PHP

$ch = curl_init('https://leadflow.deskpilotapp.cloud/service.php?action=lead_nuovo');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 15,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer test_leadflow_b9f4a574b6d50d00a2cb00eb', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'nome' => 'Mario', 'cognome' => 'Rossi', 'cellulare' => '3331234567',
        'interesse' => 'Corso di grafica', 'id_esterno' => 'ORD-1001',
    ]),
]);
$risposta = json_decode(curl_exec($ch), true);
$stato    = curl_getinfo($ch, CURLINFO_HTTP_CODE);

Node.js

const r = await fetch('https://leadflow.deskpilotapp.cloud/service.php?action=lead_nuovo', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer test_leadflow_b9f4a574b6d50d00a2cb00eb', 'Content-Type': 'application/json' },
  body: JSON.stringify({ nome: 'Mario', cognome: 'Rossi', email: 'mario.rossi@example.com', id_esterno: 'ORD-1001' })
});
const { success, data, error } = await r.json();

Python

import requests

r = requests.post(
    'https://leadflow.deskpilotapp.cloud/service.php?action=lead_nuovo',
    headers={'Authorization': 'Bearer test_leadflow_b9f4a574b6d50d00a2cb00eb'},
    json={'nome': 'Mario', 'cognome': 'Rossi', 'cellulare': '3331234567', 'id_esterno': 'ORD-1001'},
    timeout=15,
)
print(r.status_code, r.json())

Form-urlencoded con chiave nella query

curl -X POST 'https://leadflow.deskpilotapp.cloud/service.php?action=lead_nuovo&token=test_leadflow_b9f4a574b6d50d00a2cb00eb' \
  -d nome=Mario -d cognome=Rossi -d cellulare=3331234567

Ambiente di test

Chiave pubblica per le prove. I lead vengono creati in un'azienda dimostrativa con la provenienza «Test API» e cancellati automaticamente dopo 7 giorni. Non inviare dati personali reali.

test_leadflow_b9f4a574b6d50d00a2cb00eb

Note

• Tutte le chiamate devono usare HTTPS.
• I numeri di telefono vengono salvati come inviati; la ricerca dei doppioni li confronta in forma normalizzata.
• Nome e cognome scritti tutti in maiuscolo o tutti in minuscolo vengono normalizzati (es. MARIO → Mario).
• Ogni lead ricevuto, compresi quelli scartati per dati insufficienti, viene registrato con i dati inviati e l'indirizzo IP.
• Supporto all'integrazione: contattaci.