50
Viaggiatori per preventivo
Puoi tariffare da 1 a 50 persone in una sola chiamata. Oltre dieci viaggiatori subentra il prodotto gruppo: stesso prezzo a persona, qualunque sia l'età.
Piattaforma sviluppatori
L'API per distribuire l'assicurazione viaggio nel tuo prodotto
Un'API di conversione firmata, deep link tracciati e un postback S2S verso il tuo stack. Gratuita da integrare e gratuita per chiamata: sei pagato a commissione.
Che cosa c'è dietro l'API
Il catalogo
193
Paesi di residenza
Il viaggiatore ottiene un prezzo da qualunque paese parta.
193
Destinazioni
Tutte le destinazioni, zone a rischio comprese.
26
Lingue
Percorso, documenti e riepilogo nella lingua del viaggiatore.
33
Valute
Il prezzo appare nella valuta del viaggiatore.
28
Garanzie
Salute, assistenza, viaggio, bagagli, responsabilità, attività, expat. Massimali e franchigie nella risposta.
Quello che non devi costruire
Tre cose che non costruirai mai
Nessuna licenza da avere
HelloSafe è il distributore registrato e si fa carico della conformità. Tu integri l'esperienza, non la regolamentazione.
Nessuna integrazione per assicuratore
Una chiamata, l'intero catalogo. Le connessioni, gli aggiornamenti di prodotto e i documenti contrattuali restano da noi.
Nessun commerciale da chiamare
La chiave sandbox è a un clic dal tuo account. Senza revisione, senza carta, senza appuntamento.
Percorsi di integrazione
Cinque modi per collegare HelloSafe
Dal link tracciato attivabile in un pomeriggio all'API REST di preventivo: scegli il tuo livello di integrazione. Stessa copertura, stesse commissioni.
Deep link tracciati
Un link tracciato per contenuto o campagna, con Sub-ID. Il modo più rapido per iniziare, zero codice.
- Deep link per pagina e per offerta
- Sub-ID per campagna, contenuto o punto vendita
- Cookie di attribuzione a 90 giorni, last-click
API di postback di conversione
Notifica ad Atlas quando una vendita attribuita viene confermata o cambia stato. Richiesta firmata HMAC, macchina a stati, idempotente.
- Chiavi firmate per singolo chiamante (HMAC-SHA256)
- Stati pending, validated, cancelled
- Importo nativo: la commissione è calcolata lato server
Postback S2S verso il tuo stack
Rimanda le conversioni dove le monitori: Impact, Partnerize, Awin, Voluum, RedTrack, Everflow o webhook BI.
- Connettori S2S standard
- Webhook verso il tuo BI
- Esportazione CSV
API REST di tariffazione
Tariffa un viaggio su più assicuratori, genera il link di vendita tracciato e leggi ciò che la carta del viaggiatore lascia scoperto. Una sola chiave per tutto. Crea un account, la chiave di test è a un clic.
- Preventivi in tempo reale da più assicuratori
- Link di vendita tracciato, attribuzione inclusa
- Documentazione pubblica e specifica OpenAPI
Server MCP per agenti IA
Esponi HelloSafe come strumenti tipizzati che il tuo LLM può chiamare: cercare, confrontare, consegnare il link tracciato. In beta privata.
- Strumenti tipizzati per Claude, ChatGPT e agenti proprietari
- Risposte ancorate a dati reali
- Checkout agentico
Documentazione
Da leggere prima di sviluppare
La documentazione è pubblica e in inglese. Senza account e senza modulo: tutto ciò che l'API risponde è scritto.
Guida rapida
Chiave sandbox, richiesta firmata, prime offerte con prezzo. Node, cURL e PHP.
Guida rapida →Riferimento API
Endpoint, campi del viaggio, garanzie, codici di errore e quote.
Riferimento API →Specifica OpenAPI
Il contratto leggibile dalle macchine, per generare il tuo client.
Specifica OpenAPI →Stato dell'API
Verifica in diretta dell'API, impegni di disponibilità e registro degli incidenti.
Stato dell'API →L'API di conversione, in concreto
Dal postback alla commissione, in una richiesta firmata
L'API di conversione è in produzione oggi. Invii una vendita attribuita, Atlas la riconcilia con il link, converte in EUR e calcola la commissione dalla tua griglia.
- 01
Ottieni una chiave
Durante la fase di lancio, le chiavi vengono concesse su richiesta. Ricevi un key_id e un secret di firma specifici per la tua integrazione.
- 02
Firma la richiesta
Calcola HMAC-SHA256 del secret su timestamp.body, poi invia gli header x-atlas-key-id, x-atlas-timestamp e x-atlas-signature. La finestra anti-replay è di 5 minuti.
- 03
Invia la conversione
Invia ref ed externalOrderId, più l'importo lordo nella sua valuta nativa e lo stato. Atlas blocca il tasso di cambio, calcola la commissione e restituisce lo stato applicato.
postback.js
import { createHmac } from "node:crypto";
const secret = process.env.ATLAS_SIGNING_SECRET;
const body = JSON.stringify({
ref: "hs-acme-7f3k9",
externalOrderId: "ORDER-5821",
amount: 89.90,
currency: "USD",
status: "validated"
});
const ts = Math.floor(Date.now() / 1000).toString();
const signature = "v1=" + createHmac("sha256", secret)
.update(`${ts}.${body}`)
.digest("hex");
await fetch("https://atlas.hellosafe.com/api/postback/conversion", {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-atlas-key-id": "pbk_live_a1b2c3",
"x-atlas-timestamp": ts,
"x-atlas-signature": signature
},
body
});
// → 200 { ok: true, action: "inserted", status: "validated" }Postback firmato HMAC-SHA256. Risposta 200 con l'azione e lo stato applicati.
Riferimento del payload
Il corpo della richiesta
JSON. ref ed externalOrderId sono obbligatori; il resto è opzionale. Qualsiasi commissione inviata viene ignorata: fa fede il registro.
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
ref | string | Sì | Identificativo di attribuzione, nel formato partnerCode-shortCode. |
externalOrderId | string | Sì | Il tuo identificativo d'ordine. Funge da chiave di idempotenza lato Atlas. |
amount | number | No | Importo lordo della vendita, nella sua valuta nativa. |
currency | string (3) | No | Codice ISO 4217. Una valuta sconosciuta viene salvata come needs_fx e tariffata in seguito. |
status | enum | No | pending, validated o cancelled. Default: pending. |
subId | string | No | Sotto-identificativo di campagna o contenuto, per il tuo reporting. |
Codici di risposta
Cosa restituisce l'API
Codici HTTP espliciti. Le transizioni non consentite non vengono mai applicate in silenzio.
| Codice | Significato |
|---|---|
200 | Conversione registrata. action: inserted, updated, transitioned o unchanged. |
400 | Campi mancanti, ref non valido, o ref che non corrisponde al proprietario del link. |
401 | Firma, chiave o timestamp non validi (finestra di 5 minuti). |
404 | Nessun link trovato per questo ref. |
409 | Transizione di stato non consentita: la macchina a stati la rifiuta. |
422 | Importo oltre il massimale di sicurezza per conversione. |
Autenticazione e sicurezza
Firmato, isolato, tracciabile
Ogni chiamante ha la propria chiave e il proprio secret. Nulla è condiviso, tutto è revocabile.
Chiavi per chiamante
Un key_id e un secret di firma distinti per ogni integrazione. Revoca puntuale, senza impattare gli altri chiamanti.
Firma HMAC-SHA256
La firma copre timestamp.body byte per byte. Qualsiasi alterazione del corpo invalida la richiesta.
Protezione anti-replay
Le richieste con timestamp oltre 5 minuti vengono rifiutate. Nessun riutilizzo di una richiesta intercettata.
Macchina a stati idempotente
pending verso validated o cancelled; validated verso cancelled solamente; cancelled è terminale. Rinviare lo stesso stato non ha effetto.
Affidabilità e supporto
Progettato per restare online, risposte da persone reali
L'API di conversione e i link tracciati girano sulla rete edge di Cloudflare. Ecco su cosa puoi contare per disponibilità, ripresa e supporto.
99,9%
Disponibilità target
Postback e link tracciati girano su Cloudflare Workers con failover automatico. Nessuna singola regione può far cadere il servizio.
300+
Punti di presenza
Le richieste sono servite dal punto di presenza Cloudflare più vicino ai tuoi utenti; commissione e cambio vengono poi calcolati in asincrono, fuori dal percorso critico del tuo pagamento.
< 24h
Risposta del supporto
Il supporto via email risponde entro un giorno lavorativo, nei giorni lavorativi. Le tue domande di integrazione arrivano al team tecnico partner, non a una coda anonima.
5 min
Finestra di ripresa sicura
Idempotente per externalOrderId: puoi ripetere l'invio dopo un timeout senza doppio conteggio, e una richiesta intercettata non può essere rigiocata oltre cinque minuti.
La pagina di stato è pubblica: una verifica in diretta dell'API, i nostri impegni e ogni incidente dall'apertura. Il tuo referente per l'integrazione e gli incidenti resta il team partner, raggiungibile dalla pagina contatti. Stato dell'API →
Agenti IA
Il tuo agente chiama uno strumento, HelloSafe restituisce un prezzo vero
Il server MCP espone tariffazione, confronto e verifica della carta come strumenti tipizzati. Accesso su richiesta.
Server MCP
Nessuna integrazione per assicuratore, nessuna logica di tariffazione da scrivere, nessun impianto normativo. Il tuo copilota, il tuo chatbot o il tuo percorso di prenotazione chiama uno strumento e riceve un'offerta reale, con i suoi massimali e i suoi documenti. Raccontaci cosa stai costruendo.
Domande tecniche
Quello che i team chiedono prima di integrare.
Quanto costa l'API?
Niente. Non ci sono costi di attivazione, non c'è un abbonamento mensile e non c'è un costo per chiamata sull'API di conversione o sui deep link. Guadagni il 50% delle commissioni sulle vendite generate dalla tua integrazione: è l'unico flusso di denaro del programma.
C'è un'API REST di preventivo?
Sono entrambe online. L'API di conversione (postback) e l'API REST di tariffazione: crea un account, genera una chiave di test con un clic, poi richiedi la produzione quando la tua integrazione gira.
Come funziona l'autenticazione?
Con chiavi firmate, specifiche per ogni chiamante. Calcoli HMAC-SHA256 del secret su timestamp.body e lo invii in x-atlas-signature, con una finestra anti-replay di 5 minuti. Esiste un percorso Bearer legacy per la durata della migrazione dei chiamanti.
In quale valuta inviare l'importo?
L'importo lordo nella sua valuta nativa, insieme al codice valuta. Atlas blocca il tasso al momento dell'ingestione, converte in EUR (valuta contabile) e calcola la commissione dalla tua griglia. Qualsiasi commissione che invieresti viene ignorata.
Il postback è idempotente?
Sì. externalOrderId è la chiave: rinviare lo stesso stato non ha effetto, e la macchina a stati rifiuta le transizioni non consentite con un 409 invece di applicarle in silenzio.
Posso passare da Impact, Partnerize o Awin?
Sì. Esponiamo un postback S2S standard che si collega nativamente a Impact, Partnerize, Awin, Voluum, RedTrack ed Everflow, oppure un webhook verso il tuo BI.
Avete una specifica OpenAPI?
Sì, pubblicata su /openapi.json, in OpenAPI 3.1, con il riferimento completo su /platform/api/documentation. L'API di conversione è documentata dal contratto qui sopra: endpoint, header firmati, payload e codici di risposta.
Offrite supporto MCP?
Sì, in beta privata. Il server MCP espone preventivo, confronto e sottoscrizione come strumenti tipizzati che il tuo LLM o agente può chiamare.
Su quale disponibilità e quale supporto posso contare?
L'API di conversione e i link tracciati girano su Cloudflare Workers, distribuiti su oltre 300 punti di presenza con failover automatico, per una disponibilità target del 99,9%. Il supporto via email risponde entro un giorno lavorativo. Il postback è idempotente: qualsiasi timeout può essere rigiocato senza rischio. Una status page pubblica è in programma.
Serve una seconda chiave per il Coach?
No. Una sola chiave apre tutti gli endpoint: tariffazione, link tracciati e bilancio del Coach. La chiave di test generata dalla dashboard porta tutti e tre gli scope, quindi puoi provare l'intera API senza parlare con nessuno.
Una domanda tecnica o commerciale? Contattaci
Costruiamo insieme
Collega l'assicurazione viaggio al tuo prodotto
Crea il tuo account e genera la chiave di test con un clic: dati di esempio fissi, nessun assicuratore chiamato, niente da firmare. L'accesso in produzione è una revisione breve, una volta che la tua integrazione gira.