Usare la REST API di Reonic

Reonic offre una REST API pubblica che copre progetti residenziali, progetti commerciali, contatti, attività, team, file, appuntamenti, componenti, attività registrate, stato e pipeline, tag, note, pacchetti di pianificazione, modelli di pianificazione, modelli di offerta, modelli di checklist, fonti di lead, bacheche Kanban e colonne, contenuti wiki, fotogrammetria e monitoraggio ore.

Se un sistema che vuoi collegare ha già un'integrazione dedicata (HubSpot, Pipedrive, Lexoffice, Bexio, Hero, K2, Microsoft, Google, AroundHome, DAA, Wattfox, Bees & Bears, EOS, Photovate e altre ancora), usa quella. È già cablata e supportata. L'API serve per tutto il resto: sistemi fatti in casa, strumenti di BI, CRM di nicchia, dashboard personalizzate e ponti verso strumenti che non hanno un'integrazione dedicata. Per le automazioni no-code e il push degli eventi in uscita, vedi le guide su Zapier e sui webhook.

A chi è rivolto

Admin dell'installatore e admin del Workspace che costruiscono integrazioni su misura o esportano dati fuori da Reonic. I tuoi clienti finali (proprietari di casa, acquirenti commerciali) non vedono mai la superficie dell'API.

Prima di iniziare

• Ti servono diritti di admin nel tuo Workspace Reonic.
• L'API è disponibile su ogni Workspace. Se il pannello delle chiavi API non compare nelle tue impostazioni, contatta il supporto Reonic.
• Reonic tiene in funzione fianco a fianco una versione corrente dell'API e quella precedente, per un periodo di transizione. Se il tuo Workspace ha chiavi sulla versione più vecchia, la pagina Impostazioni > API / Developers > API mostra una scheda per ciascuna. Costruisci tutte le nuove integrazioni sulla versione corrente.
• Un host per gli script, uno strumento di BI o qualsiasi sistema in grado di mandare richieste HTTPS.

Trovare la pagina di impostazioni dell'API

La configurazione dell'API e dei webhook vive su una pagina di impostazioni separata rispetto all'elenco delle integrazioni dedicate.

1. Apri Impostazioni > API / Developers. È una pagina distinta da Impostazioni > Impostazioni aziendali > Integrazioni (la pagina delle integrazioni dedicate).
2. La categoria API / Developers contiene due pagine: API (creare e gestire le chiavi) e Webhooks (configurare i webhook in uscita e gli hook di Zapier).
3. Se il tuo Workspace ha chiavi sulla versione precedente dell'API, la pagina API mostra una scheda per la versione corrente (già selezionata) e una per quella precedente. I Workspace con chiavi solo sulla versione corrente vedono una sola pagina.
4. Se non vedi affatto la sezione delle chiavi API, contatta il supporto Reonic.

Creare una chiave API

Le chiavi API permettono ai tuoi script e ai sistemi esterni di autenticarsi verso Reonic.

1. Nella pagina API, fai clic su Crea nuovo per generare una chiave API.
2. Dai alla chiave un nome descrittivo che ti dica a cosa serve, per esempio una chiave in sola lettura per il magazzino o una chiave Zapier di produzione. Il nome compare nel registro delle attività, così distingui una chiave dall'altra.
3. Scegli l'ambito. Ce ne sono tre: Sola lettura (lettura su tutte le risorse), Lettura e scrittura (lettura e scrittura complete su tutte le risorse) e Solo creazione di lead (un ambito ristretto che può creare lead, progetti residenziali, contatti e note, ma nient'altro). Per un'integrazione normale scegli Sola lettura o Lettura e scrittura. Solo creazione di lead è pensato per le chiavi dei broker di lead in ingresso, che devono solo aggiungere lead.
4. Reonic genera la chiave e te la mostra al momento della creazione.
5. Copiala subito nel tuo gestore di segreti, poi salva. Se non hai più la chiave, creane una nuova e rimuovi la vecchia.

Dove trovare l'ID cliente

Il tuo ID cliente è l'identificativo del tuo Workspace. Per la maggior parte delle integrazioni non ti serve separatamente. Un numero ristretto di integrazioni partner, come alcune configurazioni di broker di lead in ingresso, richiede l'ID cliente come campo a sé. Chiedi al supporto Reonic conferma del tuo.

Chiave API e ID cliente a confronto

La chiave API è il segreto, come una password. Autentica ogni richiesta. L'ID cliente è l'identificativo del tuo Workspace, come un nome utente. Tieni privata la chiave API; l'ID cliente è il riferimento del tuo Workspace per i sistemi partner.

Autenticare le chiamate API

Reonic usa un header di autenticazione proprio invece dell'header Authorization standard. Il riferimento degli endpoint indica il nome esatto dell'header e mostra come impostarlo.

1. Nel tuo client HTTP, imposta l'header di autenticazione Reonic sul valore della tua chiave API.
2. Manda la richiesta all'endpoint pertinente.
3. Se la richiesta viene respinta come non autenticata, controlla di aver impostato l'header di autenticazione Reonic (non l'header Authorization standard) e di aver copiato la chiave per intero.

Trovare il riferimento degli endpoint

Il riferimento degli endpoint è una pagina di documentazione generata. È l'elenco autorevole di ogni endpoint, del suo percorso esatto, dei campi di richiesta e risposta e dell'header di autenticazione. I suoi endpoint si dividono in dieci grandi aree:

• People — utenti, team.
• Projects — progetti residenziali (la superficie residenziale per solare, pompa di calore e wallbox) e progetti commerciali (la pipeline commerciale).
• Working on a project — attività registrate, stato, tag, note, file, bacheche Kanban e colonne.
• Calendar — appuntamenti, feed del calendario.
• Catalog — componenti, produttori, pacchetti di pianificazione, modelli di pianificazione, modelli di offerta.
• Workspace setup — fonti di lead, modelli di checklist, integrazioni.
• Wiki — contenuti wiki.
• Services — appuntamenti di servizio.
• API helpers — endpoint di utilità.
• Guides — pagine della guida alla migrazione incorporate.

Fare la tua prima chiamata API

Prova il collegamento prima di costruirci sopra qualsiasi cosa.

1. Scegli un endpoint di lettura a basso rischio. Un elenco di progetti residenziali o di contatti è un buon punto di partenza. Il riferimento degli endpoint ti dà il percorso esatto.
2. Esegui la chiamata con la tua chiave API nell'header di autenticazione Reonic.
3. Reonic risponde con un payload JSON. Gli endpoint di elenco restituiscono un array di dati più un blocco di paginazione.
4. Verifica che la chiamata sia arrivata sotto Impostazioni > Impostazioni aziendali > Integrazioni con esito positivo.

Migrare alla versione corrente dell'API

Entrambe le versioni dell'API funzionano fianco a fianco durante la transizione, e quella precedente resta stabile. Pianifica la migrazione con anticipo, così le tue integrazioni sono sulla versione corrente ben prima che la precedente venga dismessa. Chiedi al supporto Reonic la data prevista di dismissione, così puoi organizzarti.

Il gruppo migration nel riferimento degli endpoint accompagna passo passo. In sintesi:

1. Crea una nuova chiave sulla versione corrente. Gli endpoint correnti si aspettano una chiave della versione corrente.
2. Gestisci gli elenchi paginati. Ogni risposta di elenco racchiude un array di dati più un blocco di paginazione. Aggiorna qualsiasi parser che dava per scontato un array nudo.
3. Usa le superfici dei progetti residenziali e dei progetti commerciali. Sostituiscono la vecchia superficie fatta di richieste e offerte: progetti residenziali per la linea solare, pompa di calore e wallbox, progetti commerciali per la linea commerciale.
4. Adeguati ai nomi di campo correnti. Alcuni nomi di campo sono diversi rispetto alla versione precedente, compresi i campi email, indirizzo e varianti. Il riferimento degli endpoint elenca i nomi correnti.
5. Adotta i limiti e il comportamento di caching correnti. Il riferimento degli endpoint descrive come chiedere una lettura fresca a ogni chiamata e come reagire quando ti viene chiesto di rallentare (vedi Gestire i limiti di frequenza e il caching).

Per ricreare oggetti che prima costruivi con i vecchi helper di duplicazione, usa l'endpoint di creazione standard. La versione corrente gestisce la duplicazione attraverso il normale flusso di creazione.

Paginare, filtrare ed estrarre i delta

Gli endpoint di elenco usano la paginazione per numero di pagina.

• Passa un numero di pagina e una dimensione di pagina per scorrere i risultati.
• La risposta include i link alla pagina successiva e a quella precedente. Seguili per scorrere l'insieme completo.
• Qualche endpoint pagina in modo diverso. Il riferimento degli endpoint segnala questi casi, tra cui una dimensione di pagina fissa sul monitoraggio ore, endpoint a risposta unica come team e tag, e una finestra temporale scorrevole sugli eventi del calendario.

Per le estrazioni delta (solo i record cambiati dall'ultima esecuzione), i progetti residenziali espongono un timestamp di ultima modifica che puoi usare come riferimento alto. Sugli altri endpoint, conserva il timestamp di modifica più alto della risposta precedente e riparti da lì. Il supporto ai filtri per le interrogazioni "cambiati da" varia da endpoint a endpoint. Se al tuo script serve il supporto ai delta, chiedi al supporto Reonic quali endpoint di elenco espongono il filtro.

Gestire i limiti di frequenza e il caching

L'API applica un limite di frequenza per Workspace, così nessuna singola integrazione sommerge i tuoi dati. Se mandi richieste più velocemente del limite, Reonic risponde chiedendoti di rallentare.

1. Quando ti viene chiesto di rallentare, arretra prima di riprovare. Il backoff esponenziale (2, 4, 8, 16 secondi) è uno schema sicuro.
2. Se il servizio segnala di essere temporaneamente non disponibile, arretra e riprova.
3. Per le estrazioni grandi, cadenza le chiamate e aggiungi una breve pausa tra una pagina e l'altra per restare sotto il limite.
4. Le letture ripetute vengono servite da una cache di breve durata. Quando ti servono i dati più aggiornati su una chiamata specifica, il riferimento degli endpoint mostra come chiedere una lettura fresca.

Gestire gli errori

Reonic restituisce errori HTTP strutturati che ricalcano la semantica standard 4xx e 5xx.

• Non autenticato — chiave mancante o non valida. Controlla di aver impostato l'header di autenticazione Reonic (non l'header Authorization standard) e di aver copiato la chiave per intero.
• Permesso negato — l'ambito della chiave non comprende l'operazione, oppure la risorsa è fuori da ciò che la chiave consente. Tratta le risposte 4xx come definitive; non riprovare.
• Non trovato — controlla l'ID.
• Richiesta di rallentare — stai mandando richieste troppo in fretta. Arretra e riprova.
• Errore del server (5xx) — segnalalo al supporto indicando il timestamp. Tratta i 5xx come transitori e riprova con il backoff.
• Temporaneamente non disponibile — arretra e riprova.

Compiti API più comuni

Sono gli schemi più richiesti. Prendili come punti di partenza. Il riferimento degli endpoint in linea elenca ogni endpoint e la forma esatta dei suoi campi; il tuo account manager può darti una mano se ti blocchi.

Creare una richiesta

Usa l'endpoint di creazione dei progetti residenziali per i lead solare, pompa di calore e wallbox, e l'endpoint di creazione dei progetti commerciali per la pipeline commerciale. L'endpoint restituisce l'ID del nuovo progetto.

Perché il lead finisca sulla mappa, a Reonic serve una posizione. Fornisci un indirizzo da far cercare a Reonic, oppure un insieme di coordinate che hai già risolto. Includi sempre il CAP e verifica le coordinate restituite se ti serve una precisione al metro.

Imposta lo stato del progetto al momento della creazione se vuoi uno stato iniziale specifico. Altrimenti la richiesta arriva sullo stato iniziale del Workspace.

Questo è anche l'endpoint con cui importare lead da un sistema senza integrazione dedicata, per esempio un modulo di contatto WordPress che scrive sul tuo endpoint dei progetti residenziali o dei contatti. La strada con meno codice è un ponte Zapier a partire dal modulo WordPress.

Modificare una richiesta dopo la creazione

Aggiorna la maggior parte dei campi dopo la creazione, indirizzo compreso, con l'endpoint di aggiornamento del progetto residenziale o commerciale e l'ID del progetto.

Creare un'offerta a partire da un progetto

Un'offerta nell'API è il preventivo con prezzi, strutturato in varianti, agganciato a un progetto. Raccoglie una o più varianti (ognuna con il proprio elenco di componenti, la selezione dei pacchetti, i prezzi ed eventuali sconti o impostazioni di finanziamento) più i metadati a livello di offerta (stato, stato della firma, note e file allegati). È lo stesso costrutto che vedi nel Portal sotto la scheda Offerte di un progetto.

Il flusso consigliato:

1. Crea il progetto tramite l'API.
2. Prendi l'ID progetto dalla risposta.
3. Chiama l'endpoint di creazione dell'offerta con quell'ID progetto e la definizione della tua variante.
4. La risposta contiene l'ID della nuova offerta, che userai per gli aggiornamenti successivi.

Lascia lo stato dell'offerta non impostato alla creazione se vuoi che arrivi come bozza. Per convertire una richiesta in offerta, chiama l'endpoint di creazione dell'offerta con l'ID progetto: Reonic collega la nuova offerta al progetto di origine.

Impostare o aggiornare il prezzo di un'offerta tramite l'API

L'endpoint di aggiornamento dell'offerta accetta un prezzo a livello di variante, utile quando il tuo sistema di pricing esterno deve spingere un prezzo finale dentro Reonic. La forma esatta del campo dipende dalla variante. Controlla il riferimento degli endpoint oppure chiedi al supporto Reonic.

Aggiungere note o file a un'offerta

Ci sono endpoint dedicati per aggiungere una nota e per caricare un file. I file caricati (PDF, immagini) si allegano all'offerta, al progetto o al contatto che indichi.

Creare un contatto

Usa l'endpoint di creazione dei contatti. Le coordinate non servono quando crei un contatto; solo i progetti che compaiono sulla mappa hanno bisogno di una posizione.

Per le importazioni in blocco (migrare in Reonic un elenco di contatti esistente da un CSV, da un vecchio CRM o da un foglio di calcolo), cicla sui tuoi record e crea un contatto per chiamata, cadenzando le chiamate per restare sotto il limite di frequenza. Per migrazioni una tantum più grandi, esegui il ciclo dalla tua infrastruttura verso lo stesso endpoint. Ogni endpoint di creazione restituisce l'ID della nuova risorsa, quindi catturalo al momento della creazione.

Filtrare le attività registrate per tipo di elemento padre

L'endpoint delle attività registrate supporta un filtro per tipo di elemento padre, che restringe le attività a un tipo specifico di record padre: per esempio un progetto residenziale, un progetto commerciale, un pacchetto, un componente, un contatto, un lavoro di fotogrammetria o un utente. Controlla il riferimento degli endpoint per i valori esatti accettati.

Esportazione dei dati

La strada più pulita per l'esportazione in blocco è fare un list sull'endpoint pertinente con la paginazione e salvare la risposta. Obiettivi comuni:

• Offerte vinte — estrai tutte le offerte e filtra per stato, oppure estrai l'elenco con stato Vinto.
• Contatti — estrai i contatti con la paginazione e salvali in locale.
• Progetti commerciali — estrai i progetti commerciali.
• Appuntamenti — estrai gli appuntamenti dell'area calendario di Reonic. I calendari esterni Microsoft o Google estraili direttamente da quei servizi.
• Versioni dei componenti — estrai i componenti e raggruppali per componente padre dove esistono più versioni.
• Stato Kanban — estrai bacheche Kanban e colonne per fotografare i progetti sulle bacheche.
• Fonti di lead — estrai le fonti di lead per la tassonomia dei canali di lead configurata nel Workspace.

Per produrre un file Excel delle tue richieste, offerte, statistiche o dei dati grezzi, estrai l'endpoint di elenco pertinente e carica la risposta JSON in Excel, Google Sheets o nel tuo strumento di BI.

Usare la versione corrente dell'API per le integrazioni esterne

Costruisci sempre le integrazioni esterne sulla versione pubblica corrente dell'API, caricamento dei file compreso. È il contratto stabile e supportato per leggere e scrivere i tuoi dati da fuori il Portal.

Fare da ponte verso strumenti senza integrazione dedicata

Per i sistemi che non sono nel catalogo delle integrazioni dedicate (Datev, Monday.com, Craftnote, sincronizzazione dei contatti di Office 365, Zoho CRM, invii massivi di email), costruisci sull'API per spingere i dati fuori a intervalli regolari, oppure collegali tramite Zapier.

• Datev — spingi le fatture fuori da Reonic tramite l'API e importale in Datev sul lato contabile, oppure usa Lexoffice o Sevdesk come ponte (entrambi hanno l'esportazione Datev nativa). La strada Lexoffice o Sevdesk è anche il modo per collegare un commercialista (Steuerbüro), che di solito ha già accesso a uno di questi strumenti.
• Sincronizzazione dei contatti di Office 365 — l'integrazione Microsoft si occupa dei calendari; i contatti sincronizzali con uno Zap su misura o con un'integrazione API verso il tuo endpoint dei contatti.
• Invii massivi di email — Reonic non è uno strumento di email marketing. Esporta i tuoi contatti tramite l'API e manda la campagna da una piattaforma dedicata (Mailchimp, Brevo, HubSpot Marketing).
• Zoho CRM — collegalo con un flusso Zapier (un trigger Zoho CRM new-lead che scrive sul tuo endpoint dei progetti residenziali o dei contatti), oppure scrivi nella tua infrastruttura uno script di sincronizzazione periodica da Zoho a Reonic. Entrambe le strade hanno bisogno dei campi indirizzo descritti sotto Creare una richiesta.
• Calendario Microsoft 365 / Google Workspace — hanno integrazioni dedicate sotto Impostazioni > Impostazioni aziendali > Integrazioni, non la strada dell'API. Configurale lì, poi estrai i calendari esterni Outlook o Google direttamente da quei servizi. L'API espone gli appuntamenti di Reonic.
• Broker di lead (AroundHome, DAA, Wattfox e altri) — hanno integrazioni dedicate sotto Impostazioni > Impostazioni aziendali > Integrazioni, quindi usa quelle invece dell'API generica. Per AroundHome, il customer ID è l'identificativo specifico dell'integrazione; controlla nel pannello di amministrazione di AroundHome il formato esatto. Ripiega sull'API o su Zapier solo per le fonti di lead fuori dal catalogo delle integrazioni dedicate.

Se vuoi un'integrazione dedicata per una fonte ad alto volume, parlane con il tuo account manager.

Dove vivono le integrazioni dedicate

Tutte le integrazioni dedicate vivono sotto Impostazioni > Impostazioni aziendali > Integrazioni (non sotto API / Developers), ognuna con la propria pagina di configurazione e le proprie credenziali per Workspace. Per il finanziamento Bees & Bears non ti serve una chiave API. Configura l'integrazione direttamente in Impostazioni > Impostazioni aziendali > Integrazioni e Reonic si occupa delle credenziali.

• HubSpot, Photovate, Hero, Sevdesk — vedi le rispettive pagine di configurazione sotto Impostazioni > Impostazioni aziendali > Integrazioni.
• Esportazione dell'offerta verso Photovate / K2 e collegamento dei componenti Photovate — pulsanti di esportazione dedicati sull'offerta firmata. Per le offerte che hanno bisogno dei dati K2 dopo la firma, fai clic sul pulsante di esportazione sulla riga della firma.
• Finanziamento (Bees & Bears, EOS) — Bees & Bears copre DE, AT, FR e BE; EOS copre il Brasile. Dopo che un cliente ha firmato un'offerta con un'opzione di finanziamento, usa il pulsante di esportazione verso il finanziamento sull'offerta firmata. Reonic manda al partner di finanziamento i dati dell'offerta, i dettagli del cliente e il PDF firmato. Se l'opzione di esportazione non compare, verifica con il tuo account manager che il tuo Workspace abbia l'integrazione di finanziamento attiva e che l'utente abbia il diritto Financing Provider.
• Sevdesk dopo un link scaduto — per trasferire a Sevdesk un'offerta firmata quando il link di firma originale è scaduto, apri una nuova richiesta di firma sulla stessa variante, carica il PDF firmato sulla nuova riga della firma, poi fai clic sul pulsante di esportazione verso Sevdesk su quella riga.
• SMTP — Reonic manda le email rivolte al cliente, come i link di firma e le notifiche di fattura. Per mandarle dal tuo dominio, configura un server SMTP in uscita personalizzato sotto Impostazioni > Impostazioni aziendali > Integrazioni > Server di posta SMTP.
• Campi del modulo di contatto e UTM — il modulo di contatto supporta un insieme limitato di campi aggiuntivi e di tag di fonte del lead. Il passaggio dei parametri UTM sui moduli incorporati è gestito dal codice di incorporamento; parla con il tuo account manager del tracciamento UTM per il modulo di contatto.

Trasferire offerte tra Workspace Reonic

Per spostare un'offerta tra Workspace Reonic:

1. Esporta il PDF dell'offerta dal Workspace di origine.
2. Ricrea il progetto e l'offerta nel Workspace di destinazione, tramite l'API oppure a mano nel Portal.
3. Allega il PDF esportato come file sull'offerta di destinazione.

Se diventa un'esigenza ricorrente, per esempio un gruppo in franchising che sposta offerte tra Workspace, parla con il tuo account manager di uno schema migliore.

Cosa sapere

• L'API è disponibile su ogni Workspace. Le chiavi compaiono nella pagina Impostazioni > API / Developers > API.
• Entrambe le versioni dell'API funzionano fianco a fianco durante la transizione. Costruisci le nuove integrazioni sulla versione corrente e migra prima che la precedente venga dismessa; chiedi al supporto Reonic la data prevista.
• Reonic usa un header di autenticazione proprio, non l'header Authorization standard. Molti client HTTP usano Authorization per impostazione predefinita; aggiungi invece l'header di autenticazione Reonic come header personalizzato. Il riferimento degli endpoint ne indica il nome.
• Il riferimento degli endpoint è il contratto autorevole. Elenca ogni endpoint, il suo percorso esatto, i campi di richiesta e risposta e l'header di autenticazione. Quando un campo o un percorso è diverso dalla versione precedente, il riferimento mostra il nome corrente.
• Gli errori di permesso emergono come errori HTTP strutturati. Tratta i 4xx come definitivi (non riprovare) e i 5xx come transitori (riprova con il backoff).
• Copia ogni chiave nel tuo gestore di segreti al momento della creazione. Se non hai più una chiave, creane una nuova e rimuovi la vecchia.
• L'ambito di una chiave API ha tre livelli — Sola lettura, Lettura e scrittura e Solo creazione di lead (un ambito ristretto che può creare solo progetti residenziali, contatti e note, pensato per le chiavi dei broker di lead in ingresso). Crea chiavi separate con nomi descrittivi, per chiarezza di audit.
• I limiti di frequenza si applicano per Workspace. Se mandi richieste troppo in fretta, Reonic ti chiede di rallentare; arretra e riprova. Tutte le chiavi di un Workspace condividono un unico budget.
• Le letture ripetute vengono servite da una cache di breve durata. Quando ti servono i dati più aggiornati su una chiamata specifica, il riferimento degli endpoint mostra come chiedere una lettura fresca.
• Rimuovere una chiave la rende inutilizzabile. Disattivare, ruotare o eliminare una chiave la mette fuori servizio.
• Ogni chiamata API finisce nel registro delle attività dell'integrazione con il tuo ID cliente, il metodo, lo stato e un timestamp, visibile sotto Impostazioni > Impostazioni aziendali > Integrazioni.
• Le attività registrate si filtrano per tipo di elemento padre. Restringile a un progetto residenziale, un progetto commerciale, un pacchetto, un componente, un contatto, un lavoro di fotogrammetria o un utente; controlla il riferimento degli endpoint per i valori esatti.
• I calendari esterni non passano dall'API. L'API espone gli appuntamenti di Reonic; Outlook o Google estraili direttamente da quei servizi.
• Fai le prove sul tuo Workspace con una richiesta di prova dal nome inequivocabile, e ripulisci dopo.

Ultimo aggiornamento il 12 ottobre 2026