API - Documentazione tecnica per la gestione e l'invio delle LEAD

Questo Web Service permette ai clienti autorizzati di inviare richieste di preventivo per trasporto o logistica. Le richieste devono essere inviate in formato JSON con un token di autenticazione personale.

URL del WS

L'URL del servizio, insieme al token di autenticazione personale, verrà fornito al momento dell'attivazione dell'accesso al Web Service.

Metodo HTTP e Header obbligatori

Il Web Service accetta richieste POST con i seguenti header:

• Content-Type: application/json
• X-API-Key: {il tuo token personale}

Autenticazione

Ogni cliente riceve un token unico. Il WS verifica:

• Token presente nell'header X-API-Key
• Token attivo nel database

Se il token non è presente o non è valido, viene restituito un errore JSON:

{
"status": "error",
"error": "Token mancante"
}

oppure

{
  "status": "error",
  "error": "Token non presente nei nostri sistemi"
}

Struttura JSON per trasporti

Campi obbligatori:

• tipo_preventivo: deve essere "T"
• tipologia
  Valori ammessi

  Valori ammessi per il campo "tipologia" del preventivo per Trasporti:

  trasporto-eccezionale

  trasporto-bancali-epal

  trasporto-bilici-completi

  trasporto-collettame

  trasporto-centinato

  trasporto-macchinari-industriali

  trasporto-macchinari-per-edilizia

  trasporto-materiali-per-edilizia

  trasporto-materiale-pesante

  trasporto-mezzi-agricoli

  trasporto-di-materiali-e-attrezzature

  trasporto-mobili--complementi-e-accessori

  trasporto-adr-merci-pericolose

  trasporto-trattori-agricoli

  movimentazioni-industriali

  noleggio-autogru

  sollevamenti-eccezionali

  trasporto-autovetture

  trasporto-barche

  trasporto-bestiame

  trasporto-bisarca-auto

  trasporto-con-celle-frigorifere

  trasporto-container-internazionali

  trasporto-espresso-internazionale

  trasporto-espresso-nazionale

  trasporto-groupage-internazionale

  trasporto-merci-non-deperibili

  trasporto-prodotti-alimentari

  trasporto-refrigerato

  trasporto-veicoli-a-4-ruote
• frequenza_trasporto
  Valori ammessi

  Valori ammessi per il campo "frequenza_trasporto":

  solo-uno

  diversi-trasporti

  trasporti-periodici
• paese_ritiro
• localita_ritiro
• paese_consegna
• localita_consegna
• tipo_richiedente
• nome
• cognome
• azienda (se tipo_richiedente non è 'privato')
• email

Campi opzionali:

• peso (in Kg), larghezza (in cm), altezza (in cm), lunghezza (in cm)
• n_colli, note, note_interne, quando_trasporto, termine_ricezione_preventivi
• Dati richiedente: telefono

Esempio di invio CURL (trasporti)

curl -X POST https://www.preventivipertrasporti.it/services/ws_ppt_preventivi.php \
-H "Content-Type: application/json" \
-H "X-API-Key: b04b3b9a5452fa02f2d8ce8f15d72ec8b25cd3820754ed9fa857047da1a877aa" \
-d '{
  "tipo_preventivo": "T",
  "tipologia": "trasporto-eccezionale",
  "frequenza_trasporto": "solo-uno",
  "paese_ritiro": "Italia",
  "localita_ritiro": "Milano",
  "paese_consegna": "Spagna",
  "localita_consegna": "Madrid",
  "peso": "127",
  "larghezza": "50",
  "altezza": "51",
  "lunghezza": "52",
  "n_colli": "1",
  "note": "Test da WS",
  "note_interne": "Note visualizzabili sono in area riservata",
  "quando_trasporto": "20 dicembre 2025",
  "termine_ricezione_preventivi": "10 dicembre 2025",
  "tipo_richiedente": "azienda",
  "nome": "Mario",
  "cognome": "Rossi",
  "azienda": "Company S.p.a.",
  "telefono": "123456798",
  "email": "email@email.it"
}'

Risposta JSON

Successo:

{
  "status": "success",
  "message": "Dati ricevuti correttamente"
}

Errore campi obbligatori mancanti:

{
  "status": "error",
  "message": "Campi obbligatori mancanti: paese_ritiro, localita_ritiro"
}

Struttura JSON per logistica

Campi obbligatori:

• tipo_preventivo: deve essere "L"
• tipologia
  Valori ammessi

  Valori ammessi per il campo "tipologia" del preventivo per Logistica:

  logistica-merci-integrata

  altra-tipologia
• periodo_utilizzo_logistica
  Valori ammessi

  Valori ammessi per il campo "periodo_utilizzo_logistica":

  1-mese

  3-mesi

  4-mesi

  6-mesi

  1-anno

  2-anni

  3-anni

  5-anni

  10-anni

  per-sempre
• paese_logistica
• localita_logistica
• spazio_necessario
  Valori ammessi

  Valori ammessi per il campo "spazio_logistico":

  circa-100-metri-cubi

  circa-300-metri-cubi

  circa-400-metri-cubi

  circa-1000-metri-cubi

  circa-2000-metri-cubi

  circa-3000-metri-cubi

  circa-5000-metri-cubi

  circa-10000-metri-cubi

  circa-20000-metri-cubi

  circa-30000-metri-cubi

  circa-50000-metri-cubi

  circa-100000-metri-cubi

  oltre-100000-metri-cubi
• tipo_richiedente
• nome
• cognome
• azienda (se tipo_richiedente non è 'privato')
• email

Campi opzionali:

• note
• note_interne
• Dati richiedente: telefono

Esempio di invio CURL (logistica)

curl -X POST https://www.preventivipertrasporti.it/services/ws_ppt_preventivi.php \
-H "Content-Type: application/json" \
-H "X-API-Key: b04b3b9a5452fa02f2d8ce8f15d72ec8b25cd3820754ed9fa857047da1a877aa" \
-d '{
  "tipo_preventivo": "L",
  "tipologia": "logistica-merci-integrata",
  "periodo_utilizzo_logistica": "4-mesi",
  "paese_logistica": "Italia",
  "localita_logistica": "Milano",
  "spazio_necessario": "circa-5000-metri-cubi",
  "note": "Test Logistica",
  "note_interne": "Note visualizzabili sono in area riservata",
  "tipo_richiedente": "azienda",
  "nome": "Mario",
  "cognome": "Rossi",
  "azienda": "Company S.p.a.",
  "telefono": "123456798",
  "email": "email@email.it"
}'

Risposta JSON

Successo:

{
  "status": "success",
  "message": "Dati ricevuti correttamente"
}

Errore campi obbligatori mancanti:

{
  "status": "error",
  "message": "Campi obbligatori mancanti: periodo_utilizzo_logistica, paese_logistica"
}

Note di sicurezza

• Il token deve essere sempre trasmesso via HTTPS
• Ogni cliente ha un token unico e revocabile (all'attivazione del servizio ogni cliente riceverà un token univoco)
• Non salvare il token nei log pubblici
• Utilizzare solo richieste POST con Content-Type: application/json