Piattaforma sviluppatori
Un'API di conversione firmata, deep link tracciati e un postback S2S verso il tuo stack. Collega l'assicurazione viaggio HelloSafe in pochi giorni, senza diventare un assicuratore.
Percorsi di integrazione
Dal link tracciato attivabile in un pomeriggio all'API REST di preventivo: scegli il tuo livello di integrazione. Stessa copertura, stesse commissioni.
Un link tracciato per contenuto o campagna, con Sub-ID. Il modo più rapido per iniziare, zero codice.
Notifica ad Atlas quando una vendita attribuita viene confermata o cambia stato. Richiesta firmata HMAC, macchina a stati, idempotente.
Rimanda le conversioni dove le monitori: Impact, Partnerize, Awin, Voluum, RedTrack, Everflow o webhook BI.
Interroga, confronta e sottoscrivi polizze via API. Endpoint REST e ambiente sandbox, in beta privata.
Esponi HelloSafe come strumenti tipizzati che il tuo LLM può chiamare: cercare, confrontare, sottoscrivere. In beta privata.
L'API di conversione, in concreto
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.
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.
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.
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.
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
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
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
Ogni chiamante ha la propria chiave e il proprio secret. Nulla è condiviso, tutto è revocabile.
Un key_id e un secret di firma distinti per ogni integrazione. Revoca puntuale, senza impattare gli altri chiamanti.
La firma copre timestamp.body byte per byte. Qualsiasi alterazione del corpo invalida la richiesta.
Le richieste con timestamp oltre 5 minuti vengono rifiutate. Nessun riutilizzo di una richiesta intercettata.
pending verso validated o cancelled; validated verso cancelled solamente; cancelled è terminale. Rinviare lo stesso stato non ha effetto.
Prezzi
Nessun costo di attivazione, nessun abbonamento mensile, nessun costo per chiamata. HelloSafe incassa la propria quota dagli assicuratori; i tuoi ricavi arrivano solo dalle commissioni.
$0
Ottenere la tua chiave API, collegare la tua integrazione e testare nel nostro ambiente non costa nulla. Nessun NDA, nessun processo d'acquisto.
$0
L'API di conversione, i deep link e il postback S2S non hanno alcun costo per chiamata né alcun minimo mensile. Scali al ritmo dei tuoi viaggiatori.
50%
Incassi metà delle commissioni HelloSafe su ogni sottoscrizione e ogni rinnovo generati dalla tua integrazione, versate mensilmente.
Affidabilità e supporto
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%
Postback e link tracciati girano su Cloudflare Workers con failover automatico. Nessuna singola regione può far cadere il servizio.
300+
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
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
Idempotente per externalOrderId: puoi ripetere l'invio dopo un timeout senza doppio conteggio, e una richiesta intercettata non può essere rigiocata oltre cinque minuti.
Una status page pubblica è in programma. Nel frattempo, il tuo contatto per integrazione e incidenti è il team partner, raggiungibile dalla pagina contatti.
Accesso anticipato
Oltre alla conversione, queste funzionalità esistono in beta privata. Dicci cosa stai costruendo per unirti al programma.
Preventivi multi-assicuratore, confronto e sottoscrizione via API, con sandbox e documentazione OpenAPI.
Le prime 6 cifre di una carta restituiscono cosa copre già, per vendere solo il vuoto.
Strumenti tipizzati perché i tuoi agenti IA cerchino, confrontino e sottoscrivano, ancorati a dati reali.
Quello che i team chiedono prima di integrare.
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.
L'API di conversione (postback) è in produzione. L'API REST di preventivo e sottoscrizione esiste in beta privata: richiedi un accesso anticipato e ti apriamo una sandbox.
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.
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.
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.
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.
Un riferimento OpenAPI accompagna l'API REST di preventivo in beta privata. L'API di conversione, invece, è documentata dal suo contratto qui sopra: endpoint, header firmati, payload e codici di risposta.
Sì, in beta privata. Il server MCP espone preventivo, confronto e sottoscrizione come strumenti tipizzati che il tuo LLM o agente può chiamare.
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.
Una domanda tecnica o commerciale? Contattaci
Costruiamo insieme
Dicci cosa stai costruendo. Ti indichiamo il percorso più rapido (link, postback o API) e ti apriamo una chiave.